unitizer (version 1.4.6)

unitizer_sect: 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. unitizer_sect(expr=...))

expr

test expression(s), most commonly a call to {} with several calls inside (see examples)

details

character more detailed description of what the purpose of the section is; currently this doesn't do anything.

compare

a function or a testFuns object

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.

See Also

testFuns, all_eq

Examples

# 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
)
# }