Mercurial > octave-antonio
annotate doc/interpreter/testfun.txi @ 8817:03b7f618ab3d
include docstrings for new functions in the manual
| author | John W. Eaton <jwe@octave.org> |
|---|---|
| date | Thu, 19 Feb 2009 15:39:19 -0500 |
| parents | 00df69d7e698 |
| children | eb63fbe60fab |
| rev | line source |
|---|---|
| 7018 | 1 @c Copyright (C) 2005, 2007 David Bateman |
| 2 @c Copyright (C) 2002, 2003, 2004, 2005 Paul Kienzle | |
| 3 @c | |
| 4 @c This file is part of Octave. | |
| 5 @c | |
| 6 @c Octave is free software; you can redistribute it and/or modify it | |
| 7 @c under the terms of the GNU General Public License as published by the | |
| 8 @c Free Software Foundation; either version 3 of the License, or (at | |
| 9 @c your option) any later version. | |
| 10 @c | |
| 11 @c Octave is distributed in the hope that it will be useful, but WITHOUT | |
| 12 @c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | |
| 13 @c FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License | |
| 14 @c for more details. | |
| 15 @c | |
| 16 @c You should have received a copy of the GNU General Public License | |
| 17 @c along with Octave; see the file COPYING. If not, see | |
| 18 @c <http://www.gnu.org/licenses/>. | |
| 5582 | 19 |
| 20 @node Test and Demo Functions | |
| 21 @appendix Test and Demo Functions | |
| 22 @cindex test functions | |
| 23 | |
| 24 Octave includes a number of functions to allow the integration of testing | |
| 25 and demonstration code in the source code of the functions themselves. | |
| 26 | |
| 27 @menu | |
| 28 * Test Functions:: | |
| 29 * Demonstration Functions:: | |
| 30 @end menu | |
| 31 | |
| 32 @node Test Functions | |
| 33 @section Test Functions | |
| 34 | |
| 35 @DOCSTRING(test) | |
| 36 | |
| 37 @code{test} scans the named script file looking for lines which | |
| 38 start with @code{%!}. The prefix is stripped off and the rest of the | |
|
8481
00df69d7e698
[docs] capitalize Octave consistently
Brian Gough <bjg@gnu.org>
parents:
7081
diff
changeset
|
39 line is processed through the Octave interpreter. If the code |
| 5582 | 40 generates an error, then the test is said to fail. |
| 41 | |
| 42 Since @code{eval()} will stop at the first error it encounters, you must | |
| 43 divide your tests up into blocks, with anything in a separate | |
| 44 block evaluated separately. Blocks are introduced by the keyword | |
| 45 @code{test} immediately following the @code{%!}. For example, | |
| 46 | |
| 47 @example | |
| 48 @group | |
| 6728 | 49 %!test error ("this test fails!"); |
| 7081 | 50 %!test "test doesn't fail. it doesn't generate an error"; |
| 5582 | 51 @end group |
| 52 @end example | |
| 53 | |
| 54 When a test fails, you will see something like: | |
| 55 | |
| 56 @example | |
| 57 @group | |
| 6728 | 58 ***** test error ('this test fails!') |
| 5582 | 59 !!!!! test failed |
| 60 this test fails! | |
| 61 @end group | |
| 62 @end example | |
| 63 | |
| 64 Generally, to test if something works, you want to assert that it | |
| 65 produces a correct value. A real test might look something like | |
| 66 | |
| 67 @example | |
| 68 @group | |
| 69 %!test | |
| 70 %! @var{a} = [1, 2, 3; 4, 5, 6]; B = [1; 2]; | |
| 71 %! expect = [ @var{a} ; 2*@var{a} ]; | |
| 72 %! get = kron (@var{b}, @var{a}); | |
| 73 %! if (any(size(expect) != size(get))) | |
| 74 %! error ("wrong size: expected %d,%d but got %d,%d", | |
| 75 %! size(expect), size(get)); | |
| 76 %! elseif (any(any(expect!=get))) | |
| 77 %! error ("didn't get what was expected."); | |
| 78 %! endif | |
| 79 @end group | |
| 80 @end example | |
| 81 | |
| 82 To make the process easier, use the @code{assert} function. For example, | |
| 83 with @code{assert} the previous test is reduced to: | |
| 84 | |
| 85 @example | |
| 86 @group | |
| 87 %!test | |
| 88 %! @var{a} = [1, 2, 3; 4, 5, 6]; @var{b} = [1; 2]; | |
| 89 %! assert (kron (@var{b}, @var{a}), [ @var{a}; 2*@var{a} ]); | |
| 90 @end group | |
| 91 @end example | |
| 92 | |
| 93 @code{assert} can accept a tolerance so that you can compare results | |
| 94 absolutely or relatively. For example, the following all succeed: | |
| 95 | |
| 96 @example | |
| 97 @group | |
| 98 %!test assert (1+eps, 1, 2*eps) # absolute error | |
| 99 %!test assert (100+100*eps, 100, -2*eps) # relative error | |
| 100 @end group | |
| 101 @end example | |
| 102 | |
| 103 You can also do the comparison yourself, but still have assert | |
| 104 generate the error: | |
| 105 | |
| 106 @example | |
| 107 @group | |
| 108 %!test assert (isempty([])) | |
| 109 %!test assert ([ 1,2; 3,4 ] > 0) | |
| 110 @end group | |
| 111 @end example | |
| 112 | |
| 113 Because @code{assert} is so frequently used alone in a test block, there | |
| 114 is a shorthand form: | |
| 115 | |
| 116 @example | |
| 117 %!assert (@dots{}) | |
| 118 @end example | |
| 119 | |
| 120 which is equivalent to: | |
| 121 | |
| 122 @example | |
| 123 %!test assert (@dots{}) | |
| 124 @end example | |
| 125 | |
| 6728 | 126 Sometimes during development there is a test that should work but is |
| 127 known to fail. You still want to leave the test in because when the | |
| 128 final code is ready the test should pass, but you may not be able to | |
| 7001 | 129 fix it immediately. To avoid unnecessary bug reports for these known |
| 6728 | 130 failures, mark the block with @code{xtest} rather than @code{test}: |
| 131 | |
| 132 @example | |
| 6731 | 133 %!xtest assert (1==0) |
| 134 %!xtest fail ('success=1','error')) | |
| 6728 | 135 @end example |
| 136 | |
| 137 Another use of @code{xtest} is for statistical tests which should | |
| 138 pass most of the time but are known to fail occasionally. | |
| 139 | |
| 5582 | 140 Each block is evaluated in its own function environment, which means |
| 141 that variables defined in one block are not automatically shared | |
| 142 with other blocks. If you do want to share variables, then you | |
| 143 must declare them as @code{shared} before you use them. For example, the | |
| 144 following declares the variable @var{a}, gives it an initial value (default | |
| 145 is empty), then uses it in several subsequent tests. | |
| 146 | |
| 147 @example | |
| 148 @group | |
| 149 %!shared @var{a} | |
| 150 %! @var{a} = [1, 2, 3; 4, 5, 6]; | |
| 151 %!assert (kron ([1; 2], @var{a}), [ @var{a}; 2*@var{a} ]); | |
| 152 %!assert (kron ([1, 2], @var{a}), [ @var{a}, 2*@var{a} ]); | |
| 153 %!assert (kron ([1,2; 3,4], @var{a}), [ @var{a},2*@var{a}; 3*@var{a},4*@var{a} ]); | |
| 154 @end group | |
| 155 @end example | |
| 156 | |
| 157 You can share several variables at the same time: | |
| 158 | |
| 159 @example | |
| 160 %!shared @var{a}, @var{b} | |
| 161 @end example | |
| 162 | |
| 163 You can also share test functions: | |
| 164 | |
| 165 @example | |
| 166 @group | |
| 167 %!function @var{a} = fn(@var{b}) | |
| 168 %! @var{a} = 2*@var{b}; | |
| 169 %!assert (@var{a}(2),4); | |
| 170 @end group | |
| 171 @end example | |
| 172 | |
| 173 Note that all previous variables and values are lost when a new | |
| 174 shared block is declared. | |
| 175 | |
| 176 Error and warning blocks are like test blocks, but they only succeed | |
| 177 if the code generates an error. You can check the text of the error | |
| 178 is correct using an optional regular expression @code{<pattern>}. | |
| 179 For example: | |
| 180 | |
| 181 @example | |
| 182 %!error <passes!> error('this test passes!'); | |
| 183 @end example | |
| 184 | |
| 185 If the code doesn't generate an error, the test fails. For example, | |
| 186 | |
| 187 @example | |
| 188 %!error "this is an error because it succeeds."; | |
| 189 @end example | |
| 190 | |
| 191 produces | |
| 192 | |
| 193 @example | |
| 194 @group | |
| 195 ***** error "this is an error because it succeeds."; | |
| 196 !!!!! test failed: no error | |
| 197 @end group | |
| 198 @end example | |
| 199 | |
| 200 It is important to automate the tests as much as possible, however | |
| 201 some tests require user interaction. These can be isolated into | |
| 202 demo blocks, which if you are in batch mode, are only run when | |
| 203 called with @code{demo} or @code{verbose}. The code is displayed before | |
| 204 it is executed. For example, | |
| 205 | |
| 206 @example | |
| 207 @group | |
| 208 %!demo | |
| 209 %! @var{t}=[0:0.01:2*pi]; @var{x}=sin(@var{t}); | |
| 210 %! plot(@var{t},@var{x}); | |
| 211 %! you should now see a sine wave in your figure window | |
| 212 @end group | |
| 213 @end example | |
| 214 | |
| 215 produces | |
| 216 | |
| 217 @example | |
| 218 @group | |
| 219 > @var{t}=[0:0.01:2*pi]; @var{x}=sin(@var{t}); | |
| 220 > plot(@var{t},@var{x}); | |
| 221 > you should now see a sine wave in your figure window | |
| 222 Press <enter> to continue: | |
| 223 @end group | |
| 224 @end example | |
| 225 | |
| 226 Note that demo blocks cannot use any shared variables. This is so | |
| 227 that they can be executed by themselves, ignoring all other tests. | |
| 228 | |
| 229 If you want to temporarily disable a test block, put @code{#} in place | |
| 230 of the block type. This creates a comment block which is echoed | |
| 231 in the log file, but is not executed. For example: | |
| 232 | |
| 233 @example | |
| 234 @group | |
| 235 %!#demo | |
| 236 %! @var{t}=[0:0.01:2*pi]; @var{x}=sin(@var{t}); | |
| 237 %! plot(@var{t},@var{x}); | |
| 238 %! you should now see a sine wave in your figure window | |
| 239 @end group | |
| 240 @end example | |
| 241 | |
| 242 Block type summary: | |
| 243 | |
| 244 @table @code | |
| 245 @item %!test | |
| 246 check that entire block is correct | |
| 247 @item %!error | |
| 248 check for correct error message | |
| 249 @item %!warning | |
| 250 check for correct warning message | |
| 251 @item %!demo | |
| 252 demo only executes in interactive mode | |
| 253 @item %!# | |
| 254 comment: ignore everything within the block | |
| 255 @item %!shared x,y,z | |
| 256 declares variables for use in multiple tests | |
| 257 @item %!function | |
| 258 defines a function value for a shared variable | |
| 259 @item %!assert (x, y, tol) | |
| 260 shorthand for %!test assert (x, y, tol) | |
| 261 @end table | |
| 262 | |
| 263 You can also create test scripts for builtins and your own C++ | |
| 264 functions. Just put a file of the function name on your path without | |
| 265 any extension and it will be picked up by the test procedure. You | |
| 266 can even embed tests directly in your C++ code: | |
| 267 | |
| 268 @example | |
| 269 @group | |
| 270 #if 0 | |
| 271 %!test disp('this is a test') | |
| 272 #endif | |
| 273 @end group | |
| 274 @end example | |
| 275 | |
| 276 or | |
| 277 | |
| 278 @example | |
| 279 @group | |
| 280 /* | |
| 281 %!test disp('this is a test') | |
| 282 */ | |
| 283 @end group | |
| 284 @end example | |
| 285 | |
| 286 but then the code will have to be on the load path and the user | |
| 287 will have to remember to type test('name.cc'). Conversely, you | |
|
8481
00df69d7e698
[docs] capitalize Octave consistently
Brian Gough <bjg@gnu.org>
parents:
7081
diff
changeset
|
288 can separate the tests from normal Octave script files by putting |
| 5582 | 289 them in plain files with no extension rather than in script files. |
| 290 @c DO I WANT TO INCLUDE THE EDITOR SPECIFIC STATEMENT BELOW??? | |
| 291 @c Don't forget to tell emacs that the plain text file you are using | |
| 292 @c is actually octave code, using something like: | |
| 293 @c -*-octave-*- | |
| 294 | |
| 295 @DOCSTRING(assert) | |
| 296 | |
| 297 @DOCSTRING(fail) | |
| 298 | |
| 299 @node Demonstration Functions | |
| 300 @section Demonstration Functions | |
| 301 | |
| 302 @DOCSTRING(demo) | |
| 303 | |
|
8817
03b7f618ab3d
include docstrings for new functions in the manual
John W. Eaton <jwe@octave.org>
parents:
8481
diff
changeset
|
304 @DOCSTRING(rundemos) |
|
03b7f618ab3d
include docstrings for new functions in the manual
John W. Eaton <jwe@octave.org>
parents:
8481
diff
changeset
|
305 |
| 5582 | 306 @DOCSTRING(example) |
| 307 | |
| 308 @DOCSTRING(speed) |