MOdox is documentation test ("doctest") framework for Matlab and GNU Octave.
- Runs on both the Matlab and GNU Octave platforms.
- Can be used directly with continuous integration services, such as coveralls.io and Shippable.
- Extends MOxUnit, a unit test framework for Matlab and GNU Octave.
- Is distributed under the MIT license, a permissive free software license.
- Working installation of MOxUnit.
evalcfunction. This functon is generally available in Matlab. Older versions of Octave without
evalccan compile the
evalc.ccfile from in the "externals" directory. This can be done by running
make build-octavefrom the shell, or in Octave by running
externalsdirectory and then adding that directory to the search path. The
evalc.ccimplementation is Copyright 2015 Oliver Heimlich, distributed under the GPL v3+ license.
Using the shell (requires a Unix-like operating system such as GNU/Linux or Apple OSX):
git clone https://github.com/MOdox/MOdox.git cd MOdox make install
This will add the MOdox directory to the Matlab and/or GNU Octave search path. If both Matlab and GNU Octave are available on your machine, it will install MOdox for both.
Download the zip archive from the MOdox website.
Start Matlab or GNU Octave.
On the Matlab or GNU Octave prompt,
MOdoxroot directory, then run:
cd MOdox % cd to MOdox subdirectory addpath(pwd) % add the current directory to the Matlab/GNU Octave path savepath % save the path
Writing documentation tests
Documentation tests can be defined in the help section of a Matlab / Octave .m file. The help section of a function "foo" is the text shown when running "help foo".
Documentation tests must be placed in an example section starting with a header that consists of exactly one of the strings "Example", "Examples", "Example:" or "Examples:" (optionally surrounded by whitespace). Subsequent lines, if indented (by being prefixed by more whitespace than the example header), are used to construct documentation tests. The examples section ends when the indentation is back to the original level. Multiple test sections can be defined by separating them by whitespace. Each tests contains one or more Matlab epxressions, and one or more lines containing expected output. Expected output is prefixed by "%||"; this ensures that documentation tests can be run by using copy-pasting code fragments. If a potential test section does not have expected output, then it is ignored (and not used to construct a test).
In the following example, a file "foo.m" defines two documentation tests:
function foo() % This function illustrates a documentation test defined for MOdox. % Other than that it does absolutely nothing % % Examples: % a=2; % disp(a) % % Expected output is prefixed by '%||' as in the following line: % %|| 2 % % % % The test continues because no interruption through whitespace, % % as the previous line used a '%' comment character; % % thus the 'a' variable is still in the namespace and can be % % accessed. % b=3+a; % disp(a+[3 4]) % %|| [5 6] % % % A new test starts here because the previous line was white-space % % only. Thus the 'a' and 'b' variables are not present here anymore. % % The following expression raises an error because the 'b' variable % % is not defined (and does not carry over from the previous test). % % Because the expected output indicates an error as well, % % the test passes % disp(b) % %|| error('Some error') % % % A set of expressions is ignored if there is no expected output % % (that is, no lines starting with '%||'). % % Thus, the following expression is not part of any test, % % and therefore does not raise an error. % error('this is never executed) % % % % tests end here because test indentation has ended
Running documentation tests
Tests can be run using the
modox function. For example, to run the documentation test defined above (in file foo.m):
modox accepts as input arguments both single .m files and directories with m files. If no .m files or directories are given, it runs tests on all .m files in the current directory.
Use with travis-ci and Shippable
MOdox can be used with the Travis-ci and Shippable services for continuous integration testing. This is achieved by setting up a
travis.yml file. For an example in the related MOxUnit project, see the [MOxUnit travis.yml] file.
- Because GNU Octave 3.8 and 4.0 do not support
classdefsyntax, 'old-style' object-oriented syntax is used for the class definitions.
- Expressions with the "for" keyword are not supported in Octave because
evalcdoes not seem to support it
- It is possible to indicate that an expression throws an exception, but not which exception.
- Thanks to Oliver Heimlich for the evalc implementation for GNU Octave.
Nikolaas N. Oosterhof, n.n.oosterhof gmail com.
(The MIT License)
Copyright (c) 2017 Nikolaas N. Oosterhof
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.