<html lang="en">
<head>
<title>Test Functions - Untitled</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="Untitled">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="Test-and-Demo-Functions.html#Test-and-Demo-Functions" title="Test and Demo Functions">
<link rel="next" href="Demonstration-Functions.html#Demonstration-Functions" title="Demonstration Functions">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
pre.display { font-family:inherit }
pre.format { font-family:inherit }
pre.smalldisplay { font-family:inherit; font-size:smaller }
pre.smallformat { font-family:inherit; font-size:smaller }
pre.smallexample { font-size:smaller }
pre.smalllisp { font-size:smaller }
span.sc { font-variant:small-caps }
span.roman { font-family:serif; font-weight:normal; }
span.sansserif { font-family:sans-serif; font-weight:normal; }
--></style>
</head>
<body>
<div class="node">
<a name="Test-Functions"></a>
<p>
Next: <a rel="next" accesskey="n" href="Demonstration-Functions.html#Demonstration-Functions">Demonstration Functions</a>,
Up: <a rel="up" accesskey="u" href="Test-and-Demo-Functions.html#Test-and-Demo-Functions">Test and Demo Functions</a>
<hr>
</div>
<h3 class="section">B.1 Test Functions</h3>
<!-- ./testfun/test.m -->
<p><a name="doc_002dtest"></a>
<div class="defun">
— Function File: <b>test</b><var> name<a name="index-test-2485"></a></var><br>
— Function File: <b>test</b><var> name quiet|normal|verbose<a name="index-test-2486"></a></var><br>
— Function File: <b>test</b> (<var>'name', 'quiet|normal|verbose', fid</var>)<var><a name="index-test-2487"></a></var><br>
— Function File: <b>test</b> ([]<var>, 'explain', fid</var>)<var><a name="index-test-2488"></a></var><br>
— Function File: <var>success</var> = <b>test</b> (<var><small class="dots">...</small></var>)<var><a name="index-test-2489"></a></var><br>
— Function File: [<var>n</var>, <var>max</var>] = <b>test</b> (<var><small class="dots">...</small></var>)<var><a name="index-test-2490"></a></var><br>
— Function File: [<var>code</var>, <var>idx</var>] = <b>test</b> (<var>'name','grabdemo'</var>)<var><a name="index-test-2491"></a></var><br>
<blockquote>
<p>Perform tests from the first file in the loadpath matching <var>name</var>.
<code>test</code> can be called as a command or as a function. Called with
a single argument <var>name</var>, the tests are run interactively and stop
after the first error is encountered.
<p>With a second argument the tests which are performed and the amount of
output is selected.
<dl>
<dt>'quiet'<dd> Don't report all the tests as they happen, just the errors.
<br><dt>'normal'<dd>Report all tests as they happen, but don't do tests which require
user interaction.
<br><dt>'verbose'<dd>Do tests which require user interaction.
</dl>
<p>The argument <var>fid</var> can be used to allow batch processing. Errors
can be written to the already open file defined by <var>fid</var>, and
hopefully when Octave crashes this file will tell you what was happening
when it did. You can use <code>stdout</code> if you want to see the results as
they happen. You can also give a file name rather than an <var>fid</var>, in
which case the contents of the file will be replaced with the log from
the current test.
<p>Called with a single output argument <var>success</var>, <code>test</code> returns
true if all of the tests were successful. Called with two output arguments
<var>n</var> and <var>max</var>, the number of successful tests and the total number
of tests in the file <var>name</var> are returned.
<p>If the second argument is the string 'grabdemo', the contents of the demo
blocks are extracted but not executed. Code for all code blocks is
concatenated and returned as <var>code</var> with <var>idx</var> being a vector of
positions of the ends of the demo blocks.
<p>If the second argument is 'explain', then <var>name</var> is ignored and an
explanation of the line markers used is written to the file <var>fid</var>.
<!-- Texinfo @sp should work but in practice produces ugly results for HTML. -->
<!-- A simple blank line produces the correct behavior. -->
<!-- @sp 1 -->
<p class="noindent"><strong>See also:</strong> <a href="doc_002derror.html#doc_002derror">error</a>, <a href="doc_002dassert.html#doc_002dassert">assert</a>, <a href="doc_002dfail.html#doc_002dfail">fail</a>, <a href="doc_002ddemo.html#doc_002ddemo">demo</a>, <a href="doc_002dexample.html#doc_002dexample">example</a>.
</p></blockquote></div>
<p><code>test</code> scans the named script file looking for lines which
start with <code>%!</code>. The prefix is stripped off and the rest of the
line is processed through the Octave interpreter. If the code
generates an error, then the test is said to fail.
<p>Since <code>eval()</code> will stop at the first error it encounters, you must
divide your tests up into blocks, with anything in a separate
block evaluated separately. Blocks are introduced by the keyword
<code>test</code> immediately following the <code>%!</code>. For example,
<pre class="example"> %!test error ("this test fails!");
%!test "test doesn't fail. it doesn't generate an error";
</pre>
<p>When a test fails, you will see something like:
<pre class="example"> ***** test error ('this test fails!')
!!!!! test failed
this test fails!
</pre>
<p>Generally, to test if something works, you want to assert that it
produces a correct value. A real test might look something like
<pre class="example"> %!test
%! <var>a</var> = [1, 2, 3; 4, 5, 6]; B = [1; 2];
%! expect = [ <var>a</var> ; 2*<var>a</var> ];
%! get = kron (<var>b</var>, <var>a</var>);
%! if (any(size(expect) != size(get)))
%! error ("wrong size: expected %d,%d but got %d,%d",
%! size(expect), size(get));
%! elseif (any(any(expect!=get)))
%! error ("didn't get what was expected.");
%! endif
</pre>
<p>To make the process easier, use the <code>assert</code> function. For example,
with <code>assert</code> the previous test is reduced to:
<pre class="example"> %!test
%! <var>a</var> = [1, 2, 3; 4, 5, 6]; <var>b</var> = [1; 2];
%! assert (kron (<var>b</var>, <var>a</var>), [ <var>a</var>; 2*<var>a</var> ]);
</pre>
<p><code>assert</code> can accept a tolerance so that you can compare results
absolutely or relatively. For example, the following all succeed:
<pre class="example"> %!test assert (1+eps, 1, 2*eps) # absolute error
%!test assert (100+100*eps, 100, -2*eps) # relative error
</pre>
<p>You can also do the comparison yourself, but still have assert
generate the error:
<pre class="example"> %!test assert (isempty([]))
%!test assert ([ 1,2; 3,4 ] > 0)
</pre>
<p>Because <code>assert</code> is so frequently used alone in a test block, there
is a shorthand form:
<pre class="example"> %!assert (...)
</pre>
<p>which is equivalent to:
<pre class="example"> %!test assert (...)
</pre>
<p>Sometimes during development there is a test that should work but is
known to fail. You still want to leave the test in because when the
final code is ready the test should pass, but you may not be able to
fix it immediately. To avoid unnecessary bug reports for these known
failures, mark the block with <code>xtest</code> rather than <code>test</code>:
<pre class="example"> %!xtest assert (1==0)
%!xtest fail ('success=1','error'))
</pre>
<p>Another use of <code>xtest</code> is for statistical tests which should
pass most of the time but are known to fail occasionally.
<p>Each block is evaluated in its own function environment, which means
that variables defined in one block are not automatically shared
with other blocks. If you do want to share variables, then you
must declare them as <code>shared</code> before you use them. For example, the
following declares the variable <var>a</var>, gives it an initial value (default
is empty), then uses it in several subsequent tests.
<pre class="example"> %!shared <var>a</var>
%! <var>a</var> = [1, 2, 3; 4, 5, 6];
%!assert (kron ([1; 2], <var>a</var>), [ <var>a</var>; 2*<var>a</var> ]);
%!assert (kron ([1, 2], <var>a</var>), [ <var>a</var>, 2*<var>a</var> ]);
%!assert (kron ([1,2; 3,4], <var>a</var>), [ <var>a</var>,2*<var>a</var>; 3*<var>a</var>,4*<var>a</var> ]);
</pre>
<p>You can share several variables at the same time:
<pre class="example"> %!shared <var>a</var>, <var>b</var>
</pre>
<p>You can also share test functions:
<pre class="example"> %!function <var>a</var> = fn(<var>b</var>)
%! <var>a</var> = 2*<var>b</var>;
%!assert (<var>a</var>(2),4);
</pre>
<p>Note that all previous variables and values are lost when a new
shared block is declared.
<p>Error and warning blocks are like test blocks, but they only succeed
if the code generates an error. You can check the text of the error
is correct using an optional regular expression <code><pattern></code>.
For example:
<pre class="example"> %!error <passes!> error('this test passes!');
</pre>
<p>If the code doesn't generate an error, the test fails. For example,
<pre class="example"> %!error "this is an error because it succeeds.";
</pre>
<p>produces
<pre class="example"> ***** error "this is an error because it succeeds.";
!!!!! test failed: no error
</pre>
<p>It is important to automate the tests as much as possible, however
some tests require user interaction. These can be isolated into
demo blocks, which if you are in batch mode, are only run when
called with <code>demo</code> or <code>verbose</code>. The code is displayed before
it is executed. For example,
<pre class="example"> %!demo
%! <var>t</var>=[0:0.01:2*pi]; <var>x</var>=sin(<var>t</var>);
%! plot(<var>t</var>,<var>x</var>);
%! you should now see a sine wave in your figure window
</pre>
<p>produces
<pre class="example"> > <var>t</var>=[0:0.01:2*pi]; <var>x</var>=sin(<var>t</var>);
> plot(<var>t</var>,<var>x</var>);
> you should now see a sine wave in your figure window
Press <enter> to continue:
</pre>
<p>Note that demo blocks cannot use any shared variables. This is so
that they can be executed by themselves, ignoring all other tests.
<p>If you want to temporarily disable a test block, put <code>#</code> in place
of the block type. This creates a comment block which is echoed
in the log file, but is not executed. For example:
<pre class="example"> %!#demo
%! <var>t</var>=[0:0.01:2*pi]; <var>x</var>=sin(<var>t</var>);
%! plot(<var>t</var>,<var>x</var>);
%! you should now see a sine wave in your figure window
</pre>
<p>Block type summary:
<dl>
<dt><code>%!test</code><dd>check that entire block is correct
<br><dt><code>%!error</code><dd>check for correct error message
<br><dt><code>%!warning</code><dd>check for correct warning message
<br><dt><code>%!demo</code><dd>demo only executes in interactive mode
<br><dt><code>%!#</code><dd>comment: ignore everything within the block
<br><dt><code>%!shared x,y,z</code><dd>declares variables for use in multiple tests
<br><dt><code>%!function</code><dd>defines a function value for a shared variable
<br><dt><code>%!assert (x, y, tol)</code><dd>shorthand for %!test assert (x, y, tol)
</dl>
<p>You can also create test scripts for builtins and your own C++
functions. Just put a file of the function name on your path without
any extension and it will be picked up by the test procedure. You
can even embed tests directly in your C++ code:
<pre class="example"> #if 0
%!test disp('this is a test')
#endif
</pre>
<p>or
<pre class="example"> /*
%!test disp('this is a test')
*/
</pre>
<p>but then the code will have to be on the load path and the user
will have to remember to type test('name.cc'). Conversely, you
can separate the tests from normal Octave script files by putting
them in plain files with no extension rather than in script files.
<!-- DO I WANT TO INCLUDE THE EDITOR SPECIFIC STATEMENT BELOW??? -->
<!-- Don't forget to tell emacs that the plain text file you are using -->
<!-- is actually octave code, using something like: -->
<!-- *-octave-*- -->
<!-- ./testfun/assert.m -->
<p><a name="doc_002dassert"></a>
<div class="defun">
— Function File: <b>assert</b> (<var>cond</var>)<var><a name="index-assert-2492"></a></var><br>
— Function File: <b>assert</b> (<var>cond, errmsg, <small class="dots">...</small></var>)<var><a name="index-assert-2493"></a></var><br>
— Function File: <b>assert</b> (<var>cond, msg_id, errmsg, <small class="dots">...</small></var>)<var><a name="index-assert-2494"></a></var><br>
— Function File: <b>assert</b> (<var>observed,expected</var>)<var><a name="index-assert-2495"></a></var><br>
— Function File: <b>assert</b> (<var>observed,expected,tol</var>)<var><a name="index-assert-2496"></a></var><br>
<blockquote>
<p>Produces an error if the condition is not met. <code>assert</code> can be
called in three different ways.
<dl>
<dt><code>assert (</code><var>cond</var><code>)</code><dt><code>assert (</code><var>cond</var><code>, </code><var>errmsg</var><code>, ...)</code><dt><code>assert (</code><var>cond</var><code>, </code><var>msg_id</var><code>, </code><var>errmsg</var><code>, ...)</code><dd>Called with a single argument <var>cond</var>, <code>assert</code> produces an
error if <var>cond</var> is zero. If called with a single argument a
generic error message. With more than one argument, the additional
arguments are passed to the <code>error</code> function.
<br><dt><code>assert (</code><var>observed</var><code>, </code><var>expected</var><code>)</code><dd>Produce an error if observed is not the same as expected. Note that
observed and expected can be strings, scalars, vectors, matrices,
lists or structures.
<br><dt><code>assert(</code><var>observed</var><code>, </code><var>expected</var><code>, </code><var>tol</var><code>)</code><dd>Accept a tolerance when comparing numbers.
If <var>tol</var> is positive use it as an absolute tolerance, will produce an error if
<code>abs(</code><var>observed</var><code> - </code><var>expected</var><code>) > abs(</code><var>tol</var><code>)</code>.
If <var>tol</var> is negative use it as a relative tolerance, will produce an error if
<code>abs(</code><var>observed</var><code> - </code><var>expected</var><code>) > abs(</code><var>tol</var><code> * </code><var>expected</var><code>)</code>.
If <var>expected</var> is zero <var>tol</var> will always be used as an absolute tolerance.
</dl>
<!-- Texinfo @sp should work but in practice produces ugly results for HTML. -->
<!-- A simple blank line produces the correct behavior. -->
<!-- @sp 1 -->
<p class="noindent"><strong>See also:</strong> <a href="doc_002dtest.html#doc_002dtest">test</a>.
</p></blockquote></div>
<!-- ./testfun/fail.m -->
<p><a name="doc_002dfail"></a>
<div class="defun">
— Function File: <b>fail</b> (<var>code,pattern</var>)<var><a name="index-fail-2497"></a></var><br>
— Function File: <b>fail</b> (<var>code,'warning',pattern</var>)<var><a name="index-fail-2498"></a></var><br>
<blockquote>
<p>Return true if <var>code</var> fails with an error message matching
<var>pattern</var>, otherwise produce an error. Note that <var>code</var>
is a string and if <var>code</var> runs successfully, the error produced is:
<pre class="example"> expected error but got none
</pre>
<p>If the code fails with a different error, the message produced is:
<pre class="example"> expected <pattern>
but got <text of actual error>
</pre>
<p>The angle brackets are not part of the output.
<p>Called with three arguments, the behavior is similar to
<code>fail(</code><var>code</var><code>, </code><var>pattern</var><code>)</code>, but produces an error if no
warning is given during code execution or if the code fails.
</blockquote></div>
</body></html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
3e60ff9d4d6f58c8fbd17208f14089fa
>
files
>
410
