Navigation

Operators and Keywords

Function List:

C++ API

: test name
: test name quiet|normal|verbose
: test ("name", "quiet|normal|verbose", fid)
: test ("name", "quiet|normal|verbose", fname)
: success = test (…)
: [n, nmax, nxfail, nskip] = test (…)
: [code, idx] = test ("name", "grabdemo")
: test ([], "explain", fid)
: test ([], "explain", fname)

Perform built-in self-tests from the first file in the loadpath matching name.

test can be called in either command or functional form. The exact operation of test is determined by a combination of mode (interactive or batch), reporting level ("quiet", "normal", "verbose"), and whether a logfile or summary output variable is used.

The default mode when test is called from the command line is interactive. In this mode, tests will be run until the first error is encountered, or all tests complete successfully. In batch mode, all tests are run regardless of any failures, and the results are collected for reporting. Tests which require user interaction, i.e., demo blocks, are never run in batch mode.

Batch mode is enabled by either 1) specifying a logfile using the third argument fname or fid, or 2) requesting an output argument such as success, n, etc.

The optional second argument determines the amount of output to generate and which types of tests to run. The default value is "normal". Requesting an output argument will suppress printing the final summary message and any intermediate warnings, unless verbose reporting is enabled.

"quiet"

Print a summary message when all tests pass, or print an error with the results of the first bad test when a failure occurs. Don’t run tests which require user interaction.

"normal"

Display warning messages about skipped tests or failing xtests during test execution. Print a summary message when all tests pass, or print an error with the results of the first bad test when a failure occurs. Don’t run tests which require user interaction.

"verbose"

Display tests before execution. Print all warning messages. In interactive mode, run all tests including those which require user interaction.

The optional third input argument specifies a logfile where results of the tests should be written. The logfile may be a character string (fname) or an open file descriptor ID (fid). To enable batch processing, but still print the results to the screen, use stdout for fid.

When called with just a single output argument success, test returns true if all of the tests were successful. If called with more than one output argument then the number of successful tests (n), the total number of tests in the file (nmax), the number of xtest failures (nxfail), and the number of skipped tests (nskip) are returned.

Example 

test sind
⇒
PASSES 5 out of 5 tests

[n, nmax] = test ("sind")
⇒
n =  5
nmax =  5

Additional Calling Syntaxes

If the second argument is the string "grabdemo", the contents of any built-in demo blocks are extracted but not executed. The text for all code blocks is concatenated and returned as code with idx being a vector of positions of the ends of each demo block. For an easier way to extract demo blocks from files, See ‘example’.

If the second argument is "explain" then name is ignored and an explanation of the line markers used in test output reports is written to the file specified by fname or fid.

See also: assert, fail, demo, example, error.

Demonstration 1

The following code

 toeplitz ([1,2,3,4],[1,5,6])

Produces the following output

ans =

   1   5   6
   2   1   5
   3   2   1
   4   3   2

Demonstration 2

The following code

                      # multiline demo block
 t = [0:0.01:2*pi]; x = sin (t);
 plot (t,x);
 % you should now see a sine wave in your figure window

Produces the following figure

ans =

   1   5   6
   2   1   5
   3   2   1
   4   3   2

Figure 1

Demonstration 3

The following code

 a=3                  # single line demo blocks work too

Produces the following output

a =  3

Figure 1

Package: octave