unitizer
SectionThe 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.
unitizer_sect(title = NULL, expr = expression(), details = character(),
compare = new("testFuns"))
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. unitizer_sect(expr=...)
)
test expression(s), most commonly a call to {}
with
several calls inside (see examples)
character more detailed description of what the purpose of the section is; currently this doesn't do anything.
a function or a testFuns
object
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.
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.
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
.
# NOT RUN {
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
)
# }
Run the code above in your browser using DataLab