Test S-PLUS Functions and Expressions

DESCRIPTION:

Expressions are parsed and evaluated from the connection file. Each expression should evaluate to a logical TRUE. Otherwise, do.test() prints the expression and its value.

USAGE:

do.test(file, verbose=F, strict=F, local=F, check)

ARGUMENTS:

file
a file or connection supplying S-PLUS code to test.
verbose
logical flag. If TRUE, the tested expression and its value are printed along with the results of the test.
strict
logical flag. If TRUE, any validity failures cause an error; that is, you get to debug after the first failed assertion.
local
logical flag controlling where the evaluation takes place: by default ( local=FALSE), in the top-level frame (results are left around in the working data). A more realistic efficiency test is to give local=TRUE, causing do.test()to create an evaluation frame.
check
an unevaluated S-PLUS expression. If checkis supplied, do.testevaluates this expression (it should be given via Quote()) between each parse and evaluation. This is for when you need to check some global information.

DETAILS:

A test file typically contains a sequence of expressions to test different aspects of a function or set of functions, including testing that each input argument is handled appropriately, error handling, the output has the expected structure, correct output under a number of combinations of inputs, and error handling (warning and stop invoked when appropriate and with appropriate messages). Each expression may contain multiple lines grouped using {}, where early lines may do computations and the last line checks for expected results, usually using .

Some expressions may be included that aren't intended to test anything by finishing them with TRUE, e.g. to read data: {read.table("data.txt"); TRUE} or to remove objects at the end of a test file: {rm(a, b, x, y); TRUE}.

We recommend including comments inside expressions to indicate the purpose of each test; then if errors occur the comments are printed too.

To compare just numbers, not names or matrix dimensions, functions and are useful.

To exclude certain components or attributes from the comparison the function all.equal.excluding is useful. This is defined in the examples below.

Each test should run silently if everything is working correctly; there should be nothing printed. can be used to intercept warning statements.

VALUE:

The indices of the expressions that did not evaluate to TRUE, returned with the invisible attribute set.

SEE ALSO:

, , , , , , , , .

EXAMPLES:

# Create a simple test file and run it;
# one test should and one fail:
cat("{ all.equal(24/8, 3) }\n", file="do.test.example.t")
cat("all.equal(log(10), 3)\n", file="do.test.example.t", append=TRUE)
do.test("do.test.example.t")
unlink("do.test.example.t")
# Output is:
## ------- Test file: do.test.example.t ---------
## all.equal(log(10), 3)
## [1] "Mean relative difference: 0.3028834"