Menu
▾
▴
Tree [af39bc] v0.2.0 / History
| File | Date | Author | Commit |
|---|---|---|---|
| doc | 2011-03-30 |
Michael Walter
|
[ebc996] Updated README to reflect changes. |
| LICENSE.txt | 2011-03-24 |
Michael Walter
|
[a62287] Initial commit (forked from https://bitbucket.o... |
| README.html | 2011-03-30 |
Michael Walter
|
[ebc996] Updated README to reflect changes. |
| README.rst | 2011-03-30 |
Michael Walter
|
[ebc996] Updated README to reflect changes. |
| doctest.m | 2015-03-31 |
Colin B. Macdonald
|
[3650c7] record extraction errors correctly |
| doctest_compare.m | 2011-03-24 |
Michael Walter
|
[a62287] Initial commit (forked from https://bitbucket.o... |
| doctest_run.m | 2015-03-23 |
Colin B. Macdonald
|
[9e0afa] Different fix for Octave and exceptions |
Read Me
<!DOCTYPE html
PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<!--
This HTML was auto-generated from MATLAB code.
To make changes, update the MATLAB code and republish this document.
--><title>README</title><meta name="generator" content="MATLAB 7.11"><link rel="schema.DC" href="http://purl.org/dc/elements/1.1/"><meta name="DC.date" content="2011-03-25"><meta name="DC.source" content="README.m"><style type="text/css">
body {
background-color: white;
margin:10px;
}
h1 {
color: #990000;
font-size: x-large;
}
h2 {
color: #990000;
font-size: medium;
}
/* Make the text shrink to fit narrow windows, but not stretch too far in
wide windows. */
p,h1,h2,div.content div {
max-width: 600px;
/* Hack for IE6 */
width: auto !important; width: 600px;
}
pre.codeinput {
background: #EEEEEE;
padding: 10px;
}
@media print {
pre.codeinput {word-wrap:break-word; width:100%;}
}
span.keyword {color: #0000FF}
span.comment {color: #228B22}
span.string {color: #A020F0}
span.untermstring {color: #B20000}
span.syscmd {color: #B28C00}
pre.codeoutput {
color: #666666;
padding: 10px;
}
pre.error {
color: red;
}
p.footer {
text-align: right;
font-size: xx-small;
font-weight: lighter;
font-style: italic;
color: gray;
}
</style></head><body><div class="content"><h2>Contents</h2><div><ul><li><a href="#1">DOCTEST - Run examples embedded in documentation</a></li><li><a href="#2">Example output</a></li><li><a href="#3">Failure</a></li><li><a href="#4">Defining your expectations</a></li><li><a href="#5">Expecting an error</a></li><li><a href="#6">Limitations</a></li></ul></div><h2>DOCTEST - Run examples embedded in documentation<a name="1"></a></h2><p>With doctest, you can put an example of using your function, right in the m-file help. Then, that same example can be used like a unit test, to make sure the function still does what the docs say it does.</p><p>Here's a trivial function and its documentation:</p><pre class="codeoutput">
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
%
% >> add3('hi')
% ??? Error using ==> add3 ***
% add3(value) requires value to be a number
%
%
% TWO blank lines before the prose description of the function continues
%
if ~ isnumeric(value)
error('add3(value) requires value to be a number');
end
sum = value + 3;
</pre><h2>Example output<a name="2"></a></h2><p>Now we'll run</p><p>doctest add3</p><p>Here's the output we get:</p><pre class="codeoutput">add3: OK
</pre><h2>Failure<a name="3"></a></h2><p>Here's an example of what happens when something changes and your test fails.</p><p>Normally, the failure report would include a link to somewhere near the doctest that failed, but that doesn't format properly in published m-files.</p><pre class="codeoutput">
% Has a doctest that should fail.
%
% >> 3 + 3
%
% ans =
%
% 5
%
-------------
should_fail: 1 ERRORS
>> 3 + 3
expected: ans = 5
got : ans = 6
</pre><h2>Defining your expectations<a name="4"></a></h2><p>Each time doctest runs a test, it's running a line of code and checking that the output is what you say it should be. It knows something is an example because it's a line in help('your_function') that starts with '>>'. It knows what you think the output should be by starting on the line after >> and looking for the next >>, two blank lines, or the end of the documentation.</p><p>If the output of some function will change each time you call it, for instance if it includes a random number or a stack trace, you can put '***' (three asterisks) where the changing element should be. This acts as a wildcard, and will match anything. See the example below.</p><p>Here are some examples of formatting, both ones that work and ones that don't.</p><pre class="codeoutput">
% formatting examples
%
% >> 1 + 1 % should work fine
%
% ans =
%
% 2
%
% >> 1 + 1 % comparisons collapse all whitespace, so this passes
% ans = 2
%
% >> 1 + 1; % expects no output, since >> is on the next line
% >> for I = 1:3 % when code spans multiple lines, prefix every subsequent line with '..'
% .. disp(I)
% .. end
% 1
%
% 2
%
% 3
%
% >> for I = 1:3; disp(I); end % this also works
% 1
%
% 2
%
% 3
%
% >> 1 + 4 % FAILS: there aren't 2 blank lines before the prose
%
% ans =
%
% 5
%
% Blah blah blah oops! This prose started too soon!
%
%
% Sometimes you have output that changes each time you run a function
% >> dicomuid % FAILS: no wildcard on changing output
%
% ans =
%
% 1.3.6.1.4.1.9590.100.1.1.944807727511025110.343357080818013
%
%
% You can use *** as a wildcard to match this!
% >> dicomuid % passes
%
% ans =
%
% 1.3.6.1.4.1.***
%
%
% I guess that's it!
-------------
formatting: 2 ERRORS
>> 1 + 4 % FAILS: there aren't 2 blank lines before the prose
expected: ans = 5 Blah blah blah oops! This prose started too soon!
got : ans = 5
>> dicomuid % FAILS: no wildcard on changing output
expected: ans = 1.3.6.1.4.1.9590.100.1.1.944807727511025110.343357080818013
got : ans = 1.3.6.1.4.1.9590.100.1.2.127512981121022604124941919250705271702
</pre><h2>Expecting an error<a name="5"></a></h2><p>doctest can deal with errors, a little bit. You might want this to test that your function correctly detects that it is being given invalid parameters. But if your example will emit other output BEFORE the error message, the current version can't deal with that. For more info see Issue #4 on the bitbucket site (below). Warnings are different from errors, and they work fine.</p><pre class="codeoutput">
% Errors and doctest - demonstrates a current limitation of doctest
%
% This one works fine.
%
% >> not_a_real_function(42)
% ??? Undefined function or method 'not_a_real_function' for input
% arguments of type 'double'.
%
%
% This one breaks.
%
% >> disp('if at first you don''t succeed...'); error('nevermind')
% if at first you don't succeed...
% ??? nevermind
-------------
errors: 1 ERRORS
>> disp('if at first you don''t succeed...'); error('nevermind')
expected: if at first you don't succeed... ??? nevermind
got : ??? nevermind
</pre><h2>Limitations<a name="6"></a></h2><p>All adjascent white space is collapsed into a single space before comparison, so right now doctest can't detect a failure that's purely a whitespace difference.</p><p>I haven't found a good way of isolating the variables that you define in the tests from the variables used to run the test. So, don't run CLEAR in your doctest, and don't expect WHO/WHOS to work right, and don't mess with any variables that start with DOCTEST__. :-/</p><p>When you're working on writing/debugging a Matlab class, you might need to run 'clear classes' to get correct results from doctests (this is a general problem with developing classes in Matlab).</p><p>The latest version from the original author, Thomas Smith, is available at <a href="http://bitbucket.org/tgs/doctest-for-matlab/src">http://bitbucket.org/tgs/doctest-for-matlab/src</a></p><p>The bugtracker is also there, let me know if you encounter any problems!</p><p> This version, created by Michael Walter for multiline and Octave support (among other things), is available at <a href="http://github.com/catch22/doctest-for-matlab">http://github.com/catch22/doctest-for-matlab</a></p><p class="footer"><br>
Published with MATLAB® 7.11<br></p></div><!--
##### SOURCE BEGIN #####
%% DOCTEST - Run examples embedded in documentation
%
% With doctest, you can put an example of using your function, right in the
% m-file help. Then, that same example can be used like a unit test, to
% make sure the function still does what the docs say it does.
%
% Here's a trivial function and its documentation:
%
type add3
%% Example output
%
% Now we'll run
%
% doctest add3
%
% Here's the output we get:
%
doctest add3
%% Failure
% Here's an example of what happens when something changes and your test
% fails.
%
% Normally, the failure report would include a link to somewhere near the
% doctest that failed, but that doesn't format properly in published
% m-files.
%
type should_fail
disp REPLACE_WITH_DASH_DASHREPLACE_WITH_DASH_DASHREPLACE_WITH_DASH_DASHREPLACE_WITH_DASH_DASHREPLACE_WITH_DASH_DASHREPLACE_WITH_DASH_DASH-
doctest('should_fail', 'CreateLinks', 0) % the links don't work in publish()
%% Defining your expectations
%
% Each time doctest runs a test, it's running a line of code and checking
% that the output is what you say it should be. It knows something is an
% example because it's a line in help('your_function') that starts with
% '>>'. It knows what you think the output should be by starting on the
% line after >> and looking for the next >>, two blank lines, or the end of
% the documentation.
%
% If the output of some function will change each time you call it, for
% instance if it includes a random number or a stack trace, you can put
% '***' (three asterisks) where the changing element should be. This acts
% as a wildcard, and will match anything. See the example below.
%
% Here are some examples of formatting, both ones that work and ones that
% don't.
%
type formatting
disp REPLACE_WITH_DASH_DASHREPLACE_WITH_DASH_DASHREPLACE_WITH_DASH_DASHREPLACE_WITH_DASH_DASHREPLACE_WITH_DASH_DASHREPLACE_WITH_DASH_DASH-
doctest('formatting', 'CreateLinks', 0)
%% Expecting an error
%
% doctest can deal with errors, a little bit. You might want this to test
% that your function correctly detects that it is being given invalid
% parameters. But if your example will emit other output BEFORE the error
% message, the current version can't deal with that. For more info see
% Issue #4 on the bitbucket site (below). Warnings are different from
% errors, and they work fine.
type errors
disp REPLACE_WITH_DASH_DASHREPLACE_WITH_DASH_DASHREPLACE_WITH_DASH_DASHREPLACE_WITH_DASH_DASHREPLACE_WITH_DASH_DASHREPLACE_WITH_DASH_DASH-
doctest('errors', 'CreateLinks', 0)
%% Limitations
%
% All adjascent white space is collapsed into a single space before
% comparison, so right now doctest can't detect a failure that's purely a
% whitespace difference.
%
% I haven't found a good way of isolating the variables that you define in
% the tests from the variables used to run the test. So, don't run CLEAR
% in your doctest, and don't expect WHO/WHOS to work right, and don't mess
% with any variables that start with DOCTEST__. :-/
%
% When you're working on writing/debugging a Matlab class, you might need
% to run 'clear classes' to get correct results from doctests (this is a
% general problem with developing classes in Matlab).
%
% The latest version from the original author, Thomas Smith, is available
% at http://bitbucket.org/tgs/doctest-for-matlab/src
%
% The bugtracker is also there, let me know if you encounter any problems!
%
% This version, patched by Michael Walter for multiline support, is available
% at http://github.com/catch22/doctest-for-matlab
##### SOURCE END #####
--></body></html>
