unitizer_sect: Define a 'unitizer' Section

In unitizer: Interactive R Unit Tests

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.

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

testFuns, all_eq

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
)

unitizer documentation built on Oct. 8, 2023, 5:06 p.m.