Doctest - embed testable examples in your function's help comments

Put a usage example in the help of your function, then test it to make sure it still works over time
1.1K Downloads
Updated 28 Sep 2010

View License

Unit testing is great, but it can seem like overkill to make a whole new file for every test you want to run. Doctest allows you to embed tests in the documentation of your function (or class or method), so that they're in the same file as the code they test. They can also be valuable demonstrations of how to call your code.

Say you have a function that adds 3 to any numbers you give it. Let's add a doctest:

function sum = add3(value)
% adds 3 to a number
%
% add3(value)
% returns (value + 3)
%
% Examples:
%
% >> add3(7)
%
% ans =
%
% 10
%
% >> add3([2 4])
%
% ans =
%
% 5 7
if ~ isnumeric(value)
error('add3(value) requires value to be a number');
end

sum = value + 3;

Put that in "add3.m".
Now we can run "doctest add3", and we'll get this:

TAP version 13
1..3
ok 1 - "add3(7)"
ok 2 - "add3([2 4])"

This tells you that your examples work correctly. Now, if you accidentally change the function so that it adds 10^30 instead of 3, the next time you run your tests you'll quickly find the problem. Yay testing!

Other features --- wildcard support for output that *should* change --- test functions, classes, and methods --- handles exceptions, see if you correctly catch an error --- uses a standard output format ( http://testanything.org/ ) --- easy to write examples, just cut+paste from command window

This function is inspired by the Python doctest module: http://docs.python.org/library/doctest.html

The newest version can always be obtained at http://bitbucket.org/tgs/doctest-for-matlab/src , where there is also a bug tracker if you have any issues. Contributions are also welcome!

Cite As

Thomas Smith (2024). Doctest - embed testable examples in your function's help comments (https://www.mathworks.com/matlabcentral/fileexchange/28862-doctest-embed-testable-examples-in-your-function-s-help-comments), MATLAB Central File Exchange. Retrieved .

MATLAB Release Compatibility
Created with R2010a
Compatible with any release
Platform Compatibility
Windows macOS Linux
Categories
Find more on Testing Frameworks in Help Center and MATLAB Answers

Community Treasure Hunt

Find the treasures in MATLAB Central and discover how the community can help you!

Start Hunting!
Version Published Release Notes
1.1.0.0

Added a note that the bug tracker is available, and invited to contribute

1.0.0.0