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