Mercurial > octave
annotate doc/interpreter/testfun.txi @ 13920:9cf8bd0e13d2
doc: Document %!endfunction keyword
* testfun.txi: Document %!endfunction keyword
author | Rik <octave@nomad.inbox5.com> |
---|---|
date | Tue, 22 Nov 2011 20:42:08 -0800 |
parents | fd0a3ac60b0e |
children | f07f7dd0d4df |
rev | line source |
---|---|
11523 | 1 @c Copyright (C) 2005-2011 David Bateman |
2 @c Copyright (C) 2002-2005 Paul Kienzle | |
7018 | 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 | |
9080
ec41eabf4499
Cleanup documentation files dynamic.texi, testfun.texi, tips.texi
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
38 start with @code{%!}. The prefix is stripped off and the rest of the |
ec41eabf4499
Cleanup documentation files dynamic.texi, testfun.texi, tips.texi
Rik <rdrider0-list@yahoo.com>
parents:
8920
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 | |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10496
diff
changeset
|
45 @code{test} immediately following the @code{%!}. For example: |
5582 | 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 | |
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 | 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 | |
10846
a4f482e66b65
Grammarcheck more of the documentation.
Rik <octave@nomad.inbox5.com>
parents:
10828
diff
changeset
|
120 @noindent |
5582 | 121 which is equivalent to: |
122 | |
123 @example | |
124 %!test assert (@dots{}) | |
125 @end example | |
126 | |
6728 | 127 Sometimes during development there is a test that should work but is |
128 known to fail. You still want to leave the test in because when the | |
129 final code is ready the test should pass, but you may not be able to | |
7001 | 130 fix it immediately. To avoid unnecessary bug reports for these known |
6728 | 131 failures, mark the block with @code{xtest} rather than @code{test}: |
132 | |
133 @example | |
9080
ec41eabf4499
Cleanup documentation files dynamic.texi, testfun.texi, tips.texi
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
134 @group |
6731 | 135 %!xtest assert (1==0) |
136 %!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
|
137 @end group |
6728 | 138 @end example |
139 | |
140 Another use of @code{xtest} is for statistical tests which should | |
141 pass most of the time but are known to fail occasionally. | |
142 | |
5582 | 143 Each block is evaluated in its own function environment, which means |
144 that variables defined in one block are not automatically shared | |
145 with other blocks. If you do want to share variables, then you | |
146 must declare them as @code{shared} before you use them. For example, the | |
147 following declares the variable @var{a}, gives it an initial value (default | |
148 is empty), then uses it in several subsequent tests. | |
149 | |
150 @example | |
151 @group | |
152 %!shared @var{a} | |
153 %! @var{a} = [1, 2, 3; 4, 5, 6]; | |
154 %!assert (kron ([1; 2], @var{a}), [ @var{a}; 2*@var{a} ]); | |
155 %!assert (kron ([1, 2], @var{a}), [ @var{a}, 2*@var{a} ]); | |
156 %!assert (kron ([1,2; 3,4], @var{a}), [ @var{a},2*@var{a}; 3*@var{a},4*@var{a} ]); | |
157 @end group | |
158 @end example | |
159 | |
160 You can share several variables at the same time: | |
161 | |
162 @example | |
163 %!shared @var{a}, @var{b} | |
164 @end example | |
165 | |
166 You can also share test functions: | |
167 | |
168 @example | |
169 @group | |
13920
9cf8bd0e13d2
doc: Document %!endfunction keyword
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
170 %!function @var{a} = fn (@var{b}) |
5582 | 171 %! @var{a} = 2*@var{b}; |
13920
9cf8bd0e13d2
doc: Document %!endfunction keyword
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
172 %!endfunction |
9cf8bd0e13d2
doc: Document %!endfunction keyword
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
173 %!assert (@var{fn}(2), 4); |
5582 | 174 @end group |
175 @end example | |
176 | |
177 Note that all previous variables and values are lost when a new | |
178 shared block is declared. | |
179 | |
180 Error and warning blocks are like test blocks, but they only succeed | |
181 if the code generates an error. You can check the text of the error | |
182 is correct using an optional regular expression @code{<pattern>}. | |
183 For example: | |
184 | |
185 @example | |
186 %!error <passes!> error('this test passes!'); | |
187 @end example | |
188 | |
10846
a4f482e66b65
Grammarcheck more of the documentation.
Rik <octave@nomad.inbox5.com>
parents:
10828
diff
changeset
|
189 If the code doesn't generate an error, the test fails. For example: |
5582 | 190 |
191 @example | |
192 %!error "this is an error because it succeeds."; | |
193 @end example | |
194 | |
10846
a4f482e66b65
Grammarcheck more of the documentation.
Rik <octave@nomad.inbox5.com>
parents:
10828
diff
changeset
|
195 @noindent |
5582 | 196 produces |
197 | |
198 @example | |
199 @group | |
200 ***** error "this is an error because it succeeds."; | |
201 !!!!! test failed: no error | |
202 @end group | |
203 @end example | |
204 | |
205 It is important to automate the tests as much as possible, however | |
206 some tests require user interaction. These can be isolated into | |
207 demo blocks, which if you are in batch mode, are only run when | |
9080
ec41eabf4499
Cleanup documentation files dynamic.texi, testfun.texi, tips.texi
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
208 called with @code{demo} or @code{verbose}. The code is displayed before |
ec41eabf4499
Cleanup documentation files dynamic.texi, testfun.texi, tips.texi
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
209 it is executed. For example, |
5582 | 210 |
211 @example | |
212 @group | |
213 %!demo | |
214 %! @var{t}=[0:0.01:2*pi]; @var{x}=sin(@var{t}); | |
215 %! plot(@var{t},@var{x}); | |
216 %! you should now see a sine wave in your figure window | |
217 @end group | |
218 @end example | |
219 | |
10846
a4f482e66b65
Grammarcheck more of the documentation.
Rik <octave@nomad.inbox5.com>
parents:
10828
diff
changeset
|
220 @noindent |
5582 | 221 produces |
222 | |
223 @example | |
224 @group | |
225 > @var{t}=[0:0.01:2*pi]; @var{x}=sin(@var{t}); | |
226 > plot(@var{t},@var{x}); | |
227 > you should now see a sine wave in your figure window | |
228 Press <enter> to continue: | |
229 @end group | |
230 @end example | |
231 | |
232 Note that demo blocks cannot use any shared variables. This is so | |
233 that they can be executed by themselves, ignoring all other tests. | |
234 | |
235 If you want to temporarily disable a test block, put @code{#} in place | |
236 of the block type. This creates a comment block which is echoed | |
237 in the log file, but is not executed. For example: | |
238 | |
239 @example | |
240 @group | |
241 %!#demo | |
242 %! @var{t}=[0:0.01:2*pi]; @var{x}=sin(@var{t}); | |
243 %! plot(@var{t},@var{x}); | |
244 %! you should now see a sine wave in your figure window | |
245 @end group | |
246 @end example | |
247 | |
248 Block type summary: | |
249 | |
250 @table @code | |
251 @item %!test | |
252 check that entire block is correct | |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10496
diff
changeset
|
253 |
5582 | 254 @item %!error |
255 check for correct error message | |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10496
diff
changeset
|
256 |
5582 | 257 @item %!warning |
258 check for correct warning message | |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10496
diff
changeset
|
259 |
5582 | 260 @item %!demo |
261 demo only executes in interactive mode | |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10496
diff
changeset
|
262 |
5582 | 263 @item %!# |
264 comment: ignore everything within the block | |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10496
diff
changeset
|
265 |
5582 | 266 @item %!shared x,y,z |
13920
9cf8bd0e13d2
doc: Document %!endfunction keyword
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
267 declare variables for use in multiple tests |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10496
diff
changeset
|
268 |
5582 | 269 @item %!function |
13920
9cf8bd0e13d2
doc: Document %!endfunction keyword
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
270 define a function for use in multiple tests |
9cf8bd0e13d2
doc: Document %!endfunction keyword
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
271 |
9cf8bd0e13d2
doc: Document %!endfunction keyword
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
272 @item %!endfunction |
9cf8bd0e13d2
doc: Document %!endfunction keyword
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
273 close a function definition |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10496
diff
changeset
|
274 |
5582 | 275 @item %!assert (x, y, tol) |
13920
9cf8bd0e13d2
doc: Document %!endfunction keyword
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
276 shorthand for @code{%!test assert (x, y, tol)} |
5582 | 277 @end table |
278 | |
279 You can also create test scripts for builtins and your own C++ | |
9080
ec41eabf4499
Cleanup documentation files dynamic.texi, testfun.texi, tips.texi
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
280 functions. Just put a file of the function name on your path without |
5582 | 281 any extension and it will be picked up by the test procedure. You |
282 can even embed tests directly in your C++ code: | |
283 | |
284 @example | |
285 @group | |
286 #if 0 | |
287 %!test disp('this is a test') | |
288 #endif | |
289 @end group | |
290 @end example | |
291 | |
10846
a4f482e66b65
Grammarcheck more of the documentation.
Rik <octave@nomad.inbox5.com>
parents:
10828
diff
changeset
|
292 @noindent |
5582 | 293 or |
294 | |
295 @example | |
296 @group | |
297 /* | |
298 %!test disp('this is a test') | |
299 */ | |
300 @end group | |
301 @end example | |
302 | |
10846
a4f482e66b65
Grammarcheck more of the documentation.
Rik <octave@nomad.inbox5.com>
parents:
10828
diff
changeset
|
303 @noindent |
5582 | 304 but then the code will have to be on the load path and the user |
305 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
|
306 can separate the tests from normal Octave script files by putting |
5582 | 307 them in plain files with no extension rather than in script files. |
308 @c DO I WANT TO INCLUDE THE EDITOR SPECIFIC STATEMENT BELOW??? | |
309 @c Don't forget to tell emacs that the plain text file you are using | |
310 @c is actually octave code, using something like: | |
311 @c -*-octave-*- | |
312 | |
313 @DOCSTRING(assert) | |
314 | |
315 @DOCSTRING(fail) | |
316 | |
317 @node Demonstration Functions | |
318 @section Demonstration Functions | |
319 | |
320 @DOCSTRING(demo) | |
321 | |
8817
03b7f618ab3d
include docstrings for new functions in the manual
John W. Eaton <jwe@octave.org>
parents:
8481
diff
changeset
|
322 @DOCSTRING(rundemos) |
03b7f618ab3d
include docstrings for new functions in the manual
John W. Eaton <jwe@octave.org>
parents:
8481
diff
changeset
|
323 |
10496
3b77db443cc0
scripts/testfun/runtests.m: new function
John W. Eaton <jwe@octave.org>
parents:
9080
diff
changeset
|
324 @DOCSTRING(runtests) |
3b77db443cc0
scripts/testfun/runtests.m: new function
John W. Eaton <jwe@octave.org>
parents:
9080
diff
changeset
|
325 |
5582 | 326 @DOCSTRING(example) |
327 | |
328 @DOCSTRING(speed) |