: doctest target ¶

: doctest target -nonrecursive ¶

: success = doctest (target, …) ¶

: [numpass, numtests, summary] = doctest (…) ¶

Run examples embedded in documentation.

Doctest finds and runs code found in target, which can be a:

• function;
• class;
• Texinfo file;
• .oct/.mex compiled code;
• directory/folder (pass -nonrecursive to skip subfolders);
• cell array of such items.

When called with a single return value, return whether all tests have succeeded (success).

When called with two or more return values, return the number of tests passed (numpass), the total number of tests (numtests) and a structure summary with various fields.

Doctest finds example blocks, executes the code and verifies that the results match the expected output. For example, running doctest doctest will execute this code:

>> 1 + 3
ans =
     4

If there’s no output, just put the next line right after the one with no output. If the line does produce output (for instance, an error), this will be recorded as a test failure.

>> x = 3 + 4;
>> x
x =
   7

Wildcards You can use a wildcard to match unpredictable output:

>> disp(datestr(now, 'yyyy-mm-dd'))
2...

Expecting an error Doctest can deal with errors, to some extent. For instance, this case is handled correctly:

>> not_a_real_function(42)
error: ...ndefined ...

Note use of wildcards here; MATLAB spells this Undefined, while Octave uses undefined. Writing error: is optional. Currently errors do not work if the code emits other output before the error message. Warnings are different; they work fine.

Multiple lines of code Code spanning multiple lines can be entered by prefixing all subsequent lines with .., e.g.,

>> for i = 1:3
..   i
.. end
i = 1
i = 2
i = 3

(But note this is not required when writing texinfo documentation, see below).

Shortcuts You can optionally omit ans = when the output is unassigned. But actual variable names (such as x = ) must be included. Leading and trailing whitespace on each line of output will be discarded which gives some freedom to, e.g., indent the code output as you wish.

Directives You can skip certain tests by marking them with a special comment. This can be used, for example, for a test not expected to pass or to avoid opening a figure window during automated testing.

>> a = 6         % doctest: +SKIP
b = 42
>> plot(...)     % doctest: +SKIP

These special comments act as directives for modifying test behaviour. You can also mark tests that you expect to fail:

>> a = 6         % doctest: +XFAIL
b = 42

Both the +SKIP and the +XFAIL directives have conditional variants (e.g., +SKIP_IF and +SKIP_UNLESS) that control test execution and expectations based on runtime conditions, such as the platform, operating systems, or installed packages:

>> license       % doctest: +XFAIL_IF(DOCTEST_MATLAB)
ans = GNU General Public License

Doctest provides the default flags DOCTEST_OCTAVE and DOCTEST_MATLAB, but you can call functions and access arbitrary variables (including those defined by previous tests).

By default, all adjacent white space is collapsed into a single space before comparison. A stricter mode where “internal whitespace” must match is available:

>> fprintf('a   b\nc   d\n')
a b
c d

>> fprintf('a   b\nc   d\n')    % doctest: -NORMALIZE_WHITESPACE
a   b
c   d

To disable the ... wildcard, use the -ELLIPSIS directive.

Numerical Format Tests are run using default formatting:

>> 6/5
ans = 1.2000

If your test changes the global state (e.g., format or chdir), you may need to undo your changes afterwards. In this example, we followup with format to reset to the default five digits:

>> format long
>> 355/113
ans = 3.14159292035...
>> format

Diary Style When the m-file contains plaintext documentation, doctest finds tests by searching for lines that begin with >>. It then finds the expected output by searching for the next >> or two blank lines.

Octave/Texinfo Style If your m-file contains Texinfo markup, then doctest finds code in @example … @end example blocks. Note:

• The two-blank-lines convention is not required.
• The use of >> is neither required nor recommended as Octave documentation conventionally indicates output with @result{} and @print{}. Ambiguities are resolving by assuming output is indented further than input.

A typical Texinfo-style doctest looks like:

a = 5;
b = a + 1
  ⇒ b = 6
disp("hello\nthere")
  -| hello
  -| there

The two styles are not mutually exclusive: this documentation is written in Texinfo using a hybrid approach.

Support for non-ASCII characters If you encounter file encoding issues on Octave, see ‘dir_encoding’ and ‘__mfile_encoding__’. For example, this file itself is encoded in utf-8 and declares this by installing a .oct-config file. Matlab users might want to try feature('DefaultCharacterSet', 'UTF-8').

See also: test.

Package: doctest