octave: doc/interpreter/testfun.txi annotate

annotate doc/interpreter/testfun.txi @ 16190:7fe4ea72ba4d stable

doc: Update 'test' and "fail" documentation With thanks to Iain Cunningham <iain.cunningham@eese.co.uk> * testfun.txi: Add more examples on how to use fail, assert, error, and xtest. * fail.m: Explain more the kind of input that fail needs and how it behaves.

author	Jordi Gutiérrez Hermoso <jordigh@octave.org>
date	Mon, 04 Mar 2013 16:47:22 -0500
parents	72c96de7a403
children	70c47da7e02b

rev	line source
14138 72c96de7a403 maint: update copyright notices for 2012 John W. Eaton <jwe@octave.org> parents: 14093 diff changeset	1 @c Copyright (C) 2005-2012 David Bateman
11523 fd0a3ac60b0e update copyright notices John W. Eaton <jwe@octave.org> parents: 10846 diff changeset	2 @c Copyright (C) 2002-2005 Paul Kienzle
7018 fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7001 diff changeset	3 @c
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7001 diff changeset	4 @c This file is part of Octave.
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7001 diff changeset	5 @c
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7001 diff changeset	6 @c Octave is free software; you can redistribute it and/or modify it
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7001 diff changeset	7 @c under the terms of the GNU General Public License as published by the
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7001 diff changeset	8 @c Free Software Foundation; either version 3 of the License, or (at
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7001 diff changeset	9 @c your option) any later version.
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7001 diff changeset	10 @c
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7001 diff changeset	11 @c Octave is distributed in the hope that it will be useful, but WITHOUT
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7001 diff changeset	12 @c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7001 diff changeset	13 @c FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7001 diff changeset	14 @c for more details.
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7001 diff changeset	15 @c
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7001 diff changeset	16 @c You should have received a copy of the GNU General Public License
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7001 diff changeset	17 @c along with Octave; see the file COPYING. If not, see
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7001 diff changeset	18 @c <http://www.gnu.org/licenses/>.
5582 6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	19
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	20 @node Test and Demo Functions
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	21 @appendix Test and Demo Functions
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	22 @cindex test functions
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	23
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	24 Octave includes a number of functions to allow the integration of testing
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	25 and demonstration code in the source code of the functions themselves.
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	26
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	27 @menu
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	28 * Test Functions::
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	29 * Demonstration Functions::
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	30 @end menu
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	31
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	32 @node Test Functions
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	33 @section Test Functions
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	34
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	35 @DOCSTRING(test)
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	36
14051 f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	37 @code{test} scans the named script file looking for lines which start
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	38 with the identifier @samp{%!}. The prefix is stripped off and the rest
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	39 of the line is processed through the Octave interpreter. If the code
5582 6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	40 generates an error, then the test is said to fail.
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	41
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	42 Since @code{eval()} will stop at the first error it encounters, you must
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	43 divide your tests up into blocks, with anything in a separate
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	44 block evaluated separately. Blocks are introduced by the keyword
14051 f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	45 @code{test} immediately following @samp{%!}. For example:
5582 6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	46
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	47 @example
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	48 @group
14051 f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	49 %!test error ("this test fails!");
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	50 %!test "test doesn't fail. it doesn't generate an error";
5582 6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	51 @end group
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	52 @end example
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	53
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	54 When a test fails, you will see something like:
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	55
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	56 @example
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	57 @group
14051 f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	58 ***** test error ("this test fails!")
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	59 !!!!! test failed
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	60 this test fails!
5582 6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	61 @end group
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	62 @end example
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	63
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	64 Generally, to test if something works, you want to assert that it
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	65 produces a correct value. A real test might look something like
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	66
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	67 @example
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	68 @group
14051 f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	69 %!test
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	70 %! @var{a} = [1, 2, 3; 4, 5, 6]; B = [1; 2];
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	71 %! expect = [ @var{a} ; 2*@var{a} ];
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	72 %! get = kron (@var{b}, @var{a});
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	73 %! if (any (size (expect) != size (get)))
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	74 %! error ("wrong size: expected %d,%d but got %d,%d",
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	75 %! size(expect), size(get));
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	76 %! elseif (any (any (expect != get)))
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	77 %! error ("didn't get what was expected.");
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	78 %! endif
5582 6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	79 @end group
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	80 @end example
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	81
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	82 To make the process easier, use the @code{assert} function. For example,
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	83 with @code{assert} the previous test is reduced to:
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	84
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	85 @example
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	86 @group
14051 f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	87 %!test
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	88 %! @var{a} = [1, 2, 3; 4, 5, 6]; @var{b} = [1; 2];
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	89 %! assert (kron (@var{b}, @var{a}), [ @var{a}; 2*@var{a} ]);
5582 6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	90 @end group
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	91 @end example
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	92
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	93 @code{assert} can accept a tolerance so that you can compare results
9080 ec41eabf4499 Cleanup documentation files dynamic.texi, testfun.texi, tips.texi Rik <rdrider0-list@yahoo.com> parents: 8920 diff changeset	94 absolutely or relatively. For example, the following all succeed:
5582 6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	95
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	96 @example
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	97 @group
14051 f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	98 %!test assert (1+eps, 1, 2*eps) # absolute error
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	99 %!test assert (100+100eps, 100, -2eps) # relative error
5582 6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	100 @end group
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	101 @end example
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	102
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	103 You can also do the comparison yourself, but still have assert
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	104 generate the error:
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	105
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	106 @example
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	107 @group
14051 f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	108 %!test assert (isempty ([]))
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	109 %!test assert ([1, 2; 3, 4] > 0)
5582 6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	110 @end group
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	111 @end example
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	112
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	113 Because @code{assert} is so frequently used alone in a test block, there
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	114 is a shorthand form:
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	115
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	116 @example
14051 f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	117 %!assert (@dots{})
5582 6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	118 @end example
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	119
10846 a4f482e66b65 Grammarcheck more of the documentation. Rik <octave@nomad.inbox5.com> parents: 10828 diff changeset	120 @noindent
5582 6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	121 which is equivalent to:
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	122
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	123 @example
14051 f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	124 %!test assert (@dots{})
5582 6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	125 @end example
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	126
14051 f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	127 Occasionally a block of tests will depend on having optional
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	128 functionality in Octave. Before testing such blocks the availability of
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	129 the required functionality must be checked. A @code{%!testif HAVE_XXX}
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	130 block will only be run if Octave was compiled with functionality
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	131 @samp{HAVE_XXX}. For example, the sparse single value decomposition,
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	132 @code{svds()}, depends on having the @sc{arpack} library. All of the tests
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	133 for @code{svds} begin with
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	134
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	135 @example
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	136 %!testif HAVE_ARPACK
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	137 @end example
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	138
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	139 @noindent
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	140 Review @file{config.h} or @code{octave_config_info ("DEFS")} to see some
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	141 of the possible values to check.
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	142
6728 a25173d58101 [project @ 2007-06-14 21:10:48 by jwe] jwe parents: 5582 diff changeset	143 Sometimes during development there is a test that should work but is
a25173d58101 [project @ 2007-06-14 21:10:48 by jwe] jwe parents: 5582 diff changeset	144 known to fail. You still want to leave the test in because when the
a25173d58101 [project @ 2007-06-14 21:10:48 by jwe] jwe parents: 5582 diff changeset	145 final code is ready the test should pass, but you may not be able to
7001 8b0cfeb06365 [project @ 2007-10-10 18:02:59 by jwe] jwe parents: 6731 diff changeset	146 fix it immediately. To avoid unnecessary bug reports for these known
6728 a25173d58101 [project @ 2007-06-14 21:10:48 by jwe] jwe parents: 5582 diff changeset	147 failures, mark the block with @code{xtest} rather than @code{test}:
a25173d58101 [project @ 2007-06-14 21:10:48 by jwe] jwe parents: 5582 diff changeset	148
a25173d58101 [project @ 2007-06-14 21:10:48 by jwe] jwe parents: 5582 diff changeset	149 @example
9080 ec41eabf4499 Cleanup documentation files dynamic.texi, testfun.texi, tips.texi Rik <rdrider0-list@yahoo.com> parents: 8920 diff changeset	150 @group
14051 f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	151 %!xtest assert (1==0)
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	152 %!xtest fail ("success=1", "error")
9080 ec41eabf4499 Cleanup documentation files dynamic.texi, testfun.texi, tips.texi Rik <rdrider0-list@yahoo.com> parents: 8920 diff changeset	153 @end group
6728 a25173d58101 [project @ 2007-06-14 21:10:48 by jwe] jwe parents: 5582 diff changeset	154 @end example
a25173d58101 [project @ 2007-06-14 21:10:48 by jwe] jwe parents: 5582 diff changeset	155
14051 f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	156 @noindent
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	157 In this case, the test will run and any failure will be reported.
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	158 However, testing is not aborted and subsequent test blocks will be
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	159 processed normally. Another use of @code{xtest} is for statistical
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	160 tests which should pass most of the time but are known to fail
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	161 occasionally.
6728 a25173d58101 [project @ 2007-06-14 21:10:48 by jwe] jwe parents: 5582 diff changeset	162
5582 6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	163 Each block is evaluated in its own function environment, which means
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	164 that variables defined in one block are not automatically shared
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	165 with other blocks. If you do want to share variables, then you
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	166 must declare them as @code{shared} before you use them. For example, the
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	167 following declares the variable @var{a}, gives it an initial value (default
14051 f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	168 is empty), and then uses it in several subsequent tests.
5582 6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	169
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	170 @example
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	171 @group
14051 f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	172 %!shared @var{a}
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	173 %! @var{a} = [1, 2, 3; 4, 5, 6];
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	174 %!assert (kron ([1; 2], @var{a}), [ @var{a}; 2*@var{a} ]);
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	175 %!assert (kron ([1, 2], @var{a}), [ @var{a}, 2*@var{a} ]);
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	176 %!assert (kron ([1,2; 3,4], @var{a}), [ @var{a},2@var{a}; 3@var{a},4*@var{a} ]);
5582 6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	177 @end group
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	178 @end example
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	179
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	180 You can share several variables at the same time:
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	181
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	182 @example
14051 f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	183 %!shared @var{a}, @var{b}
5582 6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	184 @end example
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	185
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	186 You can also share test functions:
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	187
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	188 @example
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	189 @group
14051 f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	190 %!function @var{a} = fn (@var{b})
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	191 %! @var{a} = 2*@var{b};
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	192 %!endfunction
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	193 %!assert (fn(2), 4);
5582 6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	194 @end group
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	195 @end example
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	196
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	197 Note that all previous variables and values are lost when a new
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	198 shared block is declared.
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	199
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	200 Error and warning blocks are like test blocks, but they only succeed
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	201 if the code generates an error. You can check the text of the error
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	202 is correct using an optional regular expression @code{<pattern>}.
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	203 For example:
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	204
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	205 @example
14051 f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	206 %!error <passes!> error ("this test passes!");
5582 6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	207 @end example
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	208
10846 a4f482e66b65 Grammarcheck more of the documentation. Rik <octave@nomad.inbox5.com> parents: 10828 diff changeset	209 If the code doesn't generate an error, the test fails. For example:
5582 6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	210
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	211 @example
14051 f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	212 %!error "this is an error because it succeeds.";
5582 6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	213 @end example
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	214
10846 a4f482e66b65 Grammarcheck more of the documentation. Rik <octave@nomad.inbox5.com> parents: 10828 diff changeset	215 @noindent
5582 6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	216 produces
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	217
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	218 @example
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	219 @group
14051 f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	220 ***** error "this is an error because it succeeds.";
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	221 !!!!! test failed: no error
5582 6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	222 @end group
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	223 @end example
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	224
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	225 It is important to automate the tests as much as possible, however
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	226 some tests require user interaction. These can be isolated into
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	227 demo blocks, which if you are in batch mode, are only run when
14051 f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	228 called with @code{demo} or the @code{verbose} option to @code{test}.
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	229 The code is displayed before it is executed. For example,
5582 6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	230
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	231 @example
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	232 @group
14051 f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	233 %!demo
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	234 %! @var{t} = [0:0.01:2*pi]; @var{x} = sin (@var{t});
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	235 %! plot (@var{t}, @var{x});
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	236 %! # you should now see a sine wave in your figure window
5582 6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	237 @end group
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	238 @end example
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	239
10846 a4f482e66b65 Grammarcheck more of the documentation. Rik <octave@nomad.inbox5.com> parents: 10828 diff changeset	240 @noindent
5582 6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	241 produces
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	242
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	243 @example
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	244 @group
14051 f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	245 funcname example 1:
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	246 @var{t} = [0:0.01:2*pi]; @var{x} = sin (@var{t});
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	247 plot (@var{t}, @var{x});
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	248 # you should now see a sine wave in your figure window
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	249
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	250 Press <enter> to continue:
5582 6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	251 @end group
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	252 @end example
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	253
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	254 Note that demo blocks cannot use any shared variables. This is so
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	255 that they can be executed by themselves, ignoring all other tests.
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	256
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	257 If you want to temporarily disable a test block, put @code{#} in place
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	258 of the block type. This creates a comment block which is echoed
14051 f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	259 in the log file but not executed. For example:
5582 6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	260
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	261 @example
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	262 @group
14051 f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	263 %!#demo
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	264 %! @var{t} = [0:0.01:2*pi]; @var{x} = sin (@var{t});
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	265 %! plot (@var{t}, @var{x});
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	266 %! # you should now see a sine wave in your figure window
5582 6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	267 @end group
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	268 @end example
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	269
16190 7fe4ea72ba4d doc: Update 'test' and "fail" documentation Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14138 diff changeset	270 @noindent
7fe4ea72ba4d doc: Update 'test' and "fail" documentation Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14138 diff changeset	271 The following trivial code snippet provides examples for the use of
7fe4ea72ba4d doc: Update 'test' and "fail" documentation Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14138 diff changeset	272 fail, assert, error and xtest:
7fe4ea72ba4d doc: Update 'test' and "fail" documentation Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14138 diff changeset	273
7fe4ea72ba4d doc: Update 'test' and "fail" documentation Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14138 diff changeset	274 @example
7fe4ea72ba4d doc: Update 'test' and "fail" documentation Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14138 diff changeset	275 @group
7fe4ea72ba4d doc: Update 'test' and "fail" documentation Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14138 diff changeset	276 function output = must_be_zero (@var{input})
7fe4ea72ba4d doc: Update 'test' and "fail" documentation Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14138 diff changeset	277 if (@var{input} != 0)
7fe4ea72ba4d doc: Update 'test' and "fail" documentation Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14138 diff changeset	278 error ("Non-zero input!")
7fe4ea72ba4d doc: Update 'test' and "fail" documentation Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14138 diff changeset	279 endif
7fe4ea72ba4d doc: Update 'test' and "fail" documentation Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14138 diff changeset	280 output = input;
7fe4ea72ba4d doc: Update 'test' and "fail" documentation Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14138 diff changeset	281 endfunction
7fe4ea72ba4d doc: Update 'test' and "fail" documentation Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14138 diff changeset	282
7fe4ea72ba4d doc: Update 'test' and "fail" documentation Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14138 diff changeset	283 %!fail ("must_be_zero (1)");
7fe4ea72ba4d doc: Update 'test' and "fail" documentation Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14138 diff changeset	284 %!assert (must_be_zero (0), 0);
7fe4ea72ba4d doc: Update 'test' and "fail" documentation Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14138 diff changeset	285 %!error <Non-zero> must_be_zero (1);
7fe4ea72ba4d doc: Update 'test' and "fail" documentation Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14138 diff changeset	286 %!xtest error ("This code generates an error");
7fe4ea72ba4d doc: Update 'test' and "fail" documentation Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14138 diff changeset	287 @end group
7fe4ea72ba4d doc: Update 'test' and "fail" documentation Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14138 diff changeset	288 @end example
7fe4ea72ba4d doc: Update 'test' and "fail" documentation Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14138 diff changeset	289
7fe4ea72ba4d doc: Update 'test' and "fail" documentation Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14138 diff changeset	290 @noindent
7fe4ea72ba4d doc: Update 'test' and "fail" documentation Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14138 diff changeset	291 When putting this a file @file{must_be_zero.m}, and running the test, we see
7fe4ea72ba4d doc: Update 'test' and "fail" documentation Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14138 diff changeset	292
7fe4ea72ba4d doc: Update 'test' and "fail" documentation Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14138 diff changeset	293 @example
7fe4ea72ba4d doc: Update 'test' and "fail" documentation Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14138 diff changeset	294 @group
7fe4ea72ba4d doc: Update 'test' and "fail" documentation Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14138 diff changeset	295 test must_be_zero verbose
7fe4ea72ba4d doc: Update 'test' and "fail" documentation Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14138 diff changeset	296
7fe4ea72ba4d doc: Update 'test' and "fail" documentation Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14138 diff changeset	297 @result{}
7fe4ea72ba4d doc: Update 'test' and "fail" documentation Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14138 diff changeset	298 >>>>> /path/to/must_be_zero.m
7fe4ea72ba4d doc: Update 'test' and "fail" documentation Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14138 diff changeset	299 ***** fail ("must_be_zero (1)");
7fe4ea72ba4d doc: Update 'test' and "fail" documentation Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14138 diff changeset	300 ***** assert (must_be_zero (0), 0);
7fe4ea72ba4d doc: Update 'test' and "fail" documentation Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14138 diff changeset	301 ***** error <Non-zero> must_be_zero (1);
7fe4ea72ba4d doc: Update 'test' and "fail" documentation Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14138 diff changeset	302 ***** xtest error ("This code generates an error");
7fe4ea72ba4d doc: Update 'test' and "fail" documentation Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14138 diff changeset	303 !!!!! known failure
7fe4ea72ba4d doc: Update 'test' and "fail" documentation Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14138 diff changeset	304 This code generates an error
7fe4ea72ba4d doc: Update 'test' and "fail" documentation Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14138 diff changeset	305 PASSES 4 out of 4 tests (1 expected failures)
7fe4ea72ba4d doc: Update 'test' and "fail" documentation Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14138 diff changeset	306 @end group
7fe4ea72ba4d doc: Update 'test' and "fail" documentation Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14138 diff changeset	307 @end example
7fe4ea72ba4d doc: Update 'test' and "fail" documentation Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14138 diff changeset	308
14051 f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	309 @subsubheading Block type summary:
5582 6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	310
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	311 @table @code
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	312 @item %!test
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	313 check that entire block is correct
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10496 diff changeset	314
14051 f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	315 @item %!testif HAVE_XXX
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	316 check block only if Octave was compiled with feature HAVE_XXX.
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	317
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	318 @item %!xtest
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	319 check block, report a test failure but do not abort testing.
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	320
5582 6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	321 @item %!error
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	322 check for correct error message
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10496 diff changeset	323
5582 6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	324 @item %!warning
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	325 check for correct warning message
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10496 diff changeset	326
5582 6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	327 @item %!demo
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	328 demo only executes in interactive mode
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10496 diff changeset	329
5582 6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	330 @item %!#
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	331 comment: ignore everything within the block
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10496 diff changeset	332
5582 6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	333 @item %!shared x,y,z
13920 9cf8bd0e13d2 doc: Document %!endfunction keyword Rik <octave@nomad.inbox5.com> parents: 11523 diff changeset	334 declare variables for use in multiple tests
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10496 diff changeset	335
5582 6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	336 @item %!function
13920 9cf8bd0e13d2 doc: Document %!endfunction keyword Rik <octave@nomad.inbox5.com> parents: 11523 diff changeset	337 define a function for use in multiple tests
9cf8bd0e13d2 doc: Document %!endfunction keyword Rik <octave@nomad.inbox5.com> parents: 11523 diff changeset	338
9cf8bd0e13d2 doc: Document %!endfunction keyword Rik <octave@nomad.inbox5.com> parents: 11523 diff changeset	339 @item %!endfunction
9cf8bd0e13d2 doc: Document %!endfunction keyword Rik <octave@nomad.inbox5.com> parents: 11523 diff changeset	340 close a function definition
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10496 diff changeset	341
5582 6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	342 @item %!assert (x, y, tol)
13920 9cf8bd0e13d2 doc: Document %!endfunction keyword Rik <octave@nomad.inbox5.com> parents: 11523 diff changeset	343 shorthand for @code{%!test assert (x, y, tol)}
5582 6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	344 @end table
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	345
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	346 You can also create test scripts for builtins and your own C++
14051 f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	347 functions. To do so put a file with the bare function name (no .m
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	348 extension) in a directory in the load path and it will be discovered by
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	349 the @code{test} function. Alternatively, you can embed tests directly in your
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	350 C++ code:
5582 6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	351
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	352 @example
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	353 @group
14093 050bc580cb60 doc: Various docstring improvements before 3.6.0 release. Rik <octave@nomad.inbox5.com> parents: 14051 diff changeset	354 /*
14051 f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	355 %!test disp ("this is a test")
14093 050bc580cb60 doc: Various docstring improvements before 3.6.0 release. Rik <octave@nomad.inbox5.com> parents: 14051 diff changeset	356 */
5582 6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	357 @end group
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	358 @end example
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	359
10846 a4f482e66b65 Grammarcheck more of the documentation. Rik <octave@nomad.inbox5.com> parents: 10828 diff changeset	360 @noindent
5582 6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	361 or
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	362
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	363 @example
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	364 @group
14093 050bc580cb60 doc: Various docstring improvements before 3.6.0 release. Rik <octave@nomad.inbox5.com> parents: 14051 diff changeset	365 #if 0
14051 f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	366 %!test disp ("this is a test")
14093 050bc580cb60 doc: Various docstring improvements before 3.6.0 release. Rik <octave@nomad.inbox5.com> parents: 14051 diff changeset	367 #endif
5582 6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	368 @end group
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	369 @end example
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	370
10846 a4f482e66b65 Grammarcheck more of the documentation. Rik <octave@nomad.inbox5.com> parents: 10828 diff changeset	371 @noindent
14051 f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	372 However, in this case the raw source code will need to be on the load
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	373 path and the user will have to remember to type
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	374 @code{test ("funcname.cc")}.
5582 6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	375
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	376 @DOCSTRING(assert)
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	377
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	378 @DOCSTRING(fail)
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	379
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	380 @node Demonstration Functions
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	381 @section Demonstration Functions
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	382
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	383 @DOCSTRING(demo)
6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	384
14051 f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	385 @DOCSTRING(example)
f07f7dd0d4df doc: Update documentation chapter on test functions Rik <octave@nomad.inbox5.com> parents: 13920 diff changeset	386
8817 03b7f618ab3d include docstrings for new functions in the manual John W. Eaton <jwe@octave.org> parents: 8481 diff changeset	387 @DOCSTRING(rundemos)
03b7f618ab3d include docstrings for new functions in the manual John W. Eaton <jwe@octave.org> parents: 8481 diff changeset	388
10496 3b77db443cc0 scripts/testfun/runtests.m: new function John W. Eaton <jwe@octave.org> parents: 9080 diff changeset	389 @DOCSTRING(runtests)
3b77db443cc0 scripts/testfun/runtests.m: new function John W. Eaton <jwe@octave.org> parents: 9080 diff changeset	390
5582 6bf56668b01a [project @ 2005-12-15 01:08:20 by jwe] jwe parents: diff changeset	391 @DOCSTRING(speed)

Mercurial > octave

annotate doc/interpreter/testfun.txi @ 16190:7fe4ea72ba4d stable