| unitizer_sect {unitizer} | R Documentation |
Define a unitizer Section
Description
The purpose of unitizer sections is to allow the user to tag a
group of test expressions with meta information as well as to modify
how tests are determined to pass or fail.
Usage
unitizer_sect(
title = NULL,
expr = expression(),
details = character(),
compare = new("testFuns")
)
Arguments
title |
character 1 length title for the section, can be omitted
though if you do omit it you will have to refer to the subsequent
arguments by name (i.e. |
expr |
test expression(s), most commonly a call to |
details |
character more detailed description of what the purpose of the section is; currently this doesn't do anything. |
compare |
a function or a |
Tested Data
unitizer tracks the following:
value: the return value of the test
conditions: any conditions emitted by the test (e.g. warnings or errors)
output: screen output
message: stderr output
aborted: whether the test issued an 'abort' restart (e.g. by calling 'stop' directly or indirectly)
In the future stdout produced by the test expression itself may be captured separately from that produced by print/showing of the return value, but at this point the two are combined.
Each of the components of the test data can be tested, although by default
only value and condition are checked. Testing output is
potentially duplicative of testing value, since most often
value is printed to screen and the screen output of the value closely
correlates to the actual value. In some cases it is useful to explicitly
test the output, such as when testing print or show
methods.
Comparison Functions
The comparison function should accept at least two parameters, and
require no more than two. For each test component, the comparison function
will be passed the reference data as the first argument, and the newly
evaluated data as the second. The function should return TRUE if the
compared test components are considered equivalent, or FALSE. Instead of
FALSE, the function may also return a character vector describing the
mismatch, as all.equal does.
WARNING: Comparison functions that set and/or unset sink
can potentially cause problems. If for whatever reason you must really sink
and unsink output streams, please take extreme care to restore the streams to
the state they were in when the comparison function was called.
Any output to stdout or stderr is captured and only checked at
the end of the unitizer process with the expectation that there will
be no such output.
value and conditions are compared with all_eq,
which is a wrapper to all.equal except that it returns FALSE
instead of a descriptive string on failure. This is because unitizer
will run diffObj on the test data components that do
not match and including the all.equal output would be redundant.
If a comparison function signals a condition (e.g. throws a warning) the test will not be evaluated, so make sure that your function does not signal conditions unless it is genuinely failing.
If you wish to provide custom comparison functions you may do so by passing
an appropriately initialized testFuns object as the
value to the compare parameter to unitizer_sect
(see examples).
Make sure your comparison functions are available to unitize.
Comparisons will be evaluated in the environment of the test. By default
unitize runs tests in environments that are not children to
the global environment, so functions defined there will not be automatically
available. You can either specify the function in the test file before the
section that uses it, or change the base environment tests are evaluated in
with unitize(..., par.env), or make sure that the package that
contains your function is loaded within the test script.
Nested Sections
It is possible to have nested sections, but titles, etc. are ignored. The
only effect of nested sections is to allow you to change the comparison
functions for a portion of the outermost unitizer_sect.
Note
if you want to modify the functions used to compare conditions,
keep in mind that the conditions are stored in conditionList
objects so your function must loop through the lists and compare conditions
pairwise. By default unitizer uses the all.equal method for S4
class conditionList.
untizer does not account for sections when matching new and
reference tests. All tests will be displayed as per the section they belong
to in the newest version of the test file, irrespective of what section they
were in when the tests were last run.
Calls to unitizer_sect should be at the top level of your test
script, or nested within other unitizer_sects (see "Nested Sections").
Do not expect code like (untizer_sect(..., ...)) or
{unitizer_sect(..., ...)} or fun(unitizer_sect(..., ...)) to
work.
See Also
Examples
unitizer_sect("Switch to `all.equal` instead of `all_eq`",
{
fun(6L)
fun("hello")
},
compare=testFuns(value=all.equal, conditions=all.equal)
)
unitizer_sect("Use identical for ALL test data, including stdout, etc.",
{
fun(6L)
fun("hello")
},
compare=identical
)