← Back to branch summary

~ubuntu-branches/ubuntu/raring/scilab/raring-proposed

« back to all changes in this revision

Viewing changes to modules/development_tools/help/en_US/test_run.xml

  • Committer: Package Import Robot
  • Author(s): Sylvestre Ledru
  • Date: 2012-08-30 14:42:38 UTC
  • mfrom: (1.4.7)
  • Revision ID: package-import@ubuntu.com-20120830144238-c1y2og7dbm7m9nig
Tags: 5.4.0-beta-3-1~exp1
* New upstream release
* Update the scirenderer dep
* Get ride of libjhdf5-java dependency

Show diffs side-by-side

added added

removed removed

Lines of Context:
modules/development_tools/help/en_US/test_run.xml
12
12
 *
13
13
 -->
14
14
<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" version="5.0-subset Scilab" xml:id="test_run" xml:lang="en">
15
 
  <refnamediv>
16
 
    <refname>test_run</refname>
17
 
    <refpurpose>Launch tests</refpurpose>
18
 
  </refnamediv>
19
 
  <refsynopsisdiv>
20
 
    <title>Calling Sequence</title>
21
 
    <synopsis>
22
 
      status = test_run()
23
 
      status = test_run(module)
24
 
      status = test_run(module, test_name)
25
 
      status = test_run(module, test_name, options, exportToFile)
26
 
    </synopsis>
27
 
  </refsynopsisdiv>
28
 
  <refsection>
29
 
    <title>Arguments</title>
30
 
    <variablelist>
31
 
      <varlistentry>
32
 
        <term>module</term>
33
 
        <listitem>
34
 
          <para>A String array. This input argument must be</para>
35
 
          <itemizedlist>
36
 
            <listitem>
37
 
              <para>
38
 
                the name of an internal Scilab module ("core", "time", ...) or a sub-module (e.g. "optimization|neldermead").
39
 
              </para>
40
 
            </listitem>
41
 
            <listitem>
42
 
              <para>
43
 
                the name of an ATOMS module ("module_lycee", "nisp", ...). To be taken into account, the module must be loaded when test_run() is called.
44
 
              </para>
45
 
            </listitem>
46
 
            <listitem>
47
 
              <para>
48
 
                the absolute directory path of a module.
49
 
              </para>
50
 
            </listitem>
51
 
          </itemizedlist>
52
 
        </listitem>
53
 
      </varlistentry>
54
 
      <varlistentry>
55
 
        <term>test_name</term>
56
 
        <listitem>
57
 
          <para>A string array</para>
58
 
        </listitem>
59
 
      </varlistentry>
60
 
      <varlistentry>
61
 
        <term>options</term>
62
 
        <listitem>
63
 
          <para>A string array</para>
64
 
          <variablelist>
65
 
            <varlistentry>
66
 
              <term>no_check_ref</term>
67
 
              <listitem>
68
 
                <para>does not check if the .dia and .dia.ref are equal</para>
69
 
              </listitem>
70
 
            </varlistentry>
71
 
            <varlistentry>
72
 
              <term>no_check_error_output</term>
73
 
              <listitem>
74
 
                <para>The error output stream is not checked. This option can be used when Scilab complains about the localization being not available.</para>
75
 
              </listitem>
76
 
            </varlistentry>
77
 
            <varlistentry>
78
 
              <term>create_ref</term>
79
 
              <listitem>
80
 
                <para>create the .dia.ref file and does not check if the .dia and .dia.ref are equal</para>
81
 
              </listitem>
82
 
            </varlistentry>
83
 
            <varlistentry>
84
 
              <term>show_error</term>
85
 
              <listitem>
86
 
                <para>If an error occurs, show the last 10 lines of the execution</para>
87
 
              </listitem>
88
 
            </varlistentry>
89
 
            <varlistentry>
90
 
              <term>show_diff</term>
91
 
              <listitem>
92
 
                <para>
93
 
                  If a difference is found, show the result of the command <literal>diff -u</literal>
94
 
                </para>
95
 
              </listitem>
96
 
            </varlistentry>
97
 
            <varlistentry>
98
 
              <term>list</term>
99
 
              <listitem>
100
 
                <para>Does not perform the tests but displays a list of available tests</para>
101
 
              </listitem>
102
 
            </varlistentry>
103
 
            <varlistentry>
104
 
              <term>help</term>
105
 
              <listitem>
106
 
                <para>display some examples about how to use this command</para>
107
 
              </listitem>
108
 
            </varlistentry>
109
 
            <varlistentry>
110
 
              <term>mode_nw</term>
111
 
              <listitem>
112
 
                <para>Add the "-nw" option to the launch</para>
113
 
              </listitem>
114
 
            </varlistentry>
115
 
            <varlistentry>
116
 
              <term>mode_nwni</term>
117
 
              <listitem>
118
 
                <para>Add the "-nwni" option to the launch</para>
119
 
              </listitem>
120
 
            </varlistentry>
121
 
            <varlistentry>
122
 
              <term>nonreg_test</term>
123
 
              <listitem>
124
 
                <para>runs only the non-regression tests, skipping unit tests</para>
125
 
              </listitem>
126
 
            </varlistentry>
127
 
            <varlistentry>
128
 
              <term>unit_test</term>
129
 
              <listitem>
130
 
                <para>Runs only the unit tests, skipping non-regression tests</para>
131
 
              </listitem>
132
 
            </varlistentry>
133
 
            <varlistentry>
134
 
              <term>skip_tests</term>
135
 
              <listitem>
136
 
                <para>Skip the tests</para>
137
 
              </listitem>
138
 
            </varlistentry>
139
 
            <varlistentry>
140
 
              <term>enable_lt</term>
141
 
              <listitem>
142
 
                <para>Enable long-time execution tests</para>
143
 
              </listitem>
144
 
            </varlistentry>
145
 
            <varlistentry>
146
 
              <term>short_summary</term>
147
 
              <listitem>
148
 
                <para>Does not display statistics nor execution time after execution (only number of executed, passed, failed and skipped tests will be displayed on a single line).</para>
149
 
              </listitem>
150
 
            </varlistentry>
151
 
          </variablelist>
152
 
        </listitem>
153
 
      </varlistentry>
154
 
      <varlistentry>
155
 
        <term>exportToFile</term>
156
 
        <listitem>
157
 
          <para>
158
 
            Export to a XML file the result of the test. This file follows the specification of the XUnit format.
159
 
            Note that the usage of this option enables <literal>show_diff</literal> and <literal>show_error</literal>.
160
 
          </para>
161
 
          <para>
162
 
            If the file pointed by <varname>exportToFile</varname> already exists, the new result will be added to the existing file.
163
 
          </para>
164
 
        </listitem>
165
 
      </varlistentry>
166
 
      <varlistentry>
167
 
        <term>status</term>
168
 
        <listitem>
169
 
          <para>
170
 
            Boolean value
171
 
            Returns %t if no error has been detected
172
 
            Returns %f if any error has been detected
173
 
          </para>
174
 
        </listitem>
175
 
      </varlistentry>
176
 
    </variablelist>
177
 
  </refsection>
178
 
  <refsection>
179
 
    <title>Description</title>
180
 
    <para>
181
 
      Search for .tst files in the unit test and non-regression test library
182
 
      execute them, and display a report about success of failures.
183
 
      The .tst files are searched in directories SCI+"/modules/*/tests/unit_tests"
184
 
      and SCI+"/modules/*/tests/nonreg_tests".
185
 
      Whenever a test is executed, a .dia file is generated which contains
186
 
      the full list of commands executed along with message which appears in the
187
 
      console. When the script is done, the .dia file is compared with
188
 
      the .dia.ref file which is expected to be in the same directory
189
 
      as the .tst file. If the two file are different, the test fails.
190
 
    </para>
191
 
    <para>
192
 
      Special tags may be inserted in the .tst file, which help to
193
 
      control the processing of the corresponding test. These tags
194
 
      are expected to be found in Scilab comments.
195
 
    </para>
196
 
    <para>These are the available tags:</para>
197
 
    <itemizedlist>
198
 
      <listitem>
199
 
        <para>
200
 
          &lt;-- INTERACTIVE TEST --&gt;
201
 
          This test will be skipped because it is interactive.
202
 
        </para>
203
 
      </listitem>
204
 
      <listitem>
205
 
        <para>
206
 
          &lt;-- LONG TIME EXECUTION --&gt;
207
 
          This test will be skipped because it needs long-time duration. To enable
208
 
          the test, call test_run with the following option: "enable_lt"
209
 
        </para>
210
 
      </listitem>
211
 
      <listitem>
212
 
        <para>
213
 
          &lt;-- NOT FIXED --&gt;
214
 
          This test will be skipped because it is a known, but unfixed bug.
215
 
        </para>
216
 
      </listitem>
217
 
      <listitem>
218
 
        <para>
219
 
          &lt;-- TEST WITH GRAPHIC --&gt;
220
 
          This test will not be executed if the option "mode_nwni" is used.
221
 
        </para>
222
 
      </listitem>
223
 
      <listitem>
224
 
        <para>
225
 
          &lt;-- NO TRY CATCH --&gt;
226
 
        </para>
227
 
      </listitem>
228
 
      <listitem>
229
 
        <para>
230
 
          &lt;-- NO CHECK ERROR OUTPUT --&gt;
231
 
          The error output file is not checked
232
 
        </para>
233
 
      </listitem>
234
 
      <listitem>
235
 
        <para>
236
 
          &lt;-- NO CHECK REF --&gt;
237
 
          The .dia and the .dia.ref files are not compared.
238
 
        </para>
239
 
      </listitem>
240
 
      <listitem>
241
 
        <para>
242
 
          &lt;-- ENGLISH IMPOSED --&gt;
243
 
          This test will be executed with the -l en_US option.
244
 
        </para>
245
 
      </listitem>
246
 
      <listitem>
247
 
        <para>
248
 
          &lt;-- FRENCH IMPOSED --&gt;
249
 
          This test will be executed with the -l fr_FR option.
250
 
        </para>
251
 
      </listitem>
252
 
      <listitem>
253
 
        <para>
254
 
          &lt;-- CLI SHELL MODE --&gt;
255
 
          (was: &lt;-- JVM NOT MANDATORY --&gt;)
256
 
          This test will be executed with scilab-cli (nwni mode) by default.
257
 
        </para>
258
 
      </listitem>
259
 
      <listitem>
260
 
        <para>
261
 
          &lt;-- WINDOWS ONLY --&gt;
262
 
          If the operating system isn't Windows, the test is skipped.
263
 
        </para>
264
 
      </listitem>
265
 
      <listitem>
266
 
        <para>
267
 
          &lt;-- UNIX ONLY --&gt;
268
 
          If the operating system isn't an Unix OS, the test is skipped.
269
 
        </para>
270
 
      </listitem>
271
 
      <listitem>
272
 
        <para>
273
 
          &lt;-- LINUX ONLY --&gt;
274
 
          If the operating system isn't GNU/Linux, the test is skipped.
275
 
        </para>
276
 
      </listitem>
277
 
      <listitem>
278
 
        <para>
279
 
          &lt;-- MACOSX ONLY --&gt;
280
 
          If the operating system isn't Mac OS X, the test is skipped.
281
 
        </para>
282
 
      </listitem>
283
 
      <listitem>
284
 
        <para>
285
 
          &lt;-- XCOS TEST --&gt;
286
 
          This test will launch all the necessary Xcos libs. This test
287
 
          will be launched in nw mode.
288
 
        </para>
289
 
      </listitem>
290
 
    </itemizedlist>
291
 
    <para>
292
 
      Each test is executed in a separated process, created with the "host" command.
293
 
      That enables the current command to continue, even if the test as
294
 
      created an unstable environment. It also enables the tests to be
295
 
      independent from one another.
296
 
    </para>
297
 
  </refsection>
298
 
  <refsection>
299
 
    <title>Platform-specific tests</title>
300
 
    <para>
301
 
      It may happen that the output of a test depends on the platform on which it is
302
 
      executed. In this case, the <literal>.ref</literal> file cannot be correct for
303
 
      all platforms and unit tests may fail for some platform. In this case, we can
304
 
      create a default <literal>.ref</literal> and create additionnal <literal>.ref</literal>
305
 
      file for each platform.
306
 
    </para>
307
 
    <para>
308
 
      The various platform-specific <literal>.ref</literal> files must have one of the following extensions.
309
 
    </para>
310
 
    <itemizedlist>
311
 
      <listitem>
312
 
        <para>
313
 
          <literal>.unix.dia.ref</literal> for Unix platform,
314
 
        </para>
315
 
      </listitem>
316
 
      <listitem>
317
 
        <para>
318
 
          <literal>.linux.dia.ref</literal> for GNU/Linux platform,
319
 
        </para>
320
 
      </listitem>
321
 
      <listitem>
322
 
        <para>
323
 
          <literal>.win.dia.ref</literal> for Windows platform,
324
 
        </para>
325
 
      </listitem>
326
 
      <listitem>
327
 
        <para>
328
 
          <literal>.macosx.dia.ref</literal> for Mac OS X platform.
329
 
        </para>
330
 
      </listitem>
331
 
    </itemizedlist>
332
 
    <para>
333
 
      The algorithm is the following.
334
 
      First, the <literal>.ref</literal> is considered. If this file does not exist,
335
 
      the platform-specific <literal>.ref</literal> file is examined depending on the current platform.
336
 
    </para>
337
 
    <itemizedlist>
338
 
      <listitem>
339
 
        <para>
340
 
          on Windows platforms: <literal>.win.dia.ref</literal>,
341
 
        </para>
342
 
      </listitem>
343
 
      <listitem>
344
 
        <para>
345
 
          on Max OS X platforms: <literal>.unix.dia.ref</literal>, <literal>.macosx.dia.ref</literal>,
346
 
        </para>
347
 
      </listitem>
348
 
      <listitem>
349
 
        <para>
350
 
          on GNU/Linux platforms: <literal>.unix.dia.ref</literal>, <literal>.linux.dia.ref</literal>.
351
 
        </para>
352
 
      </listitem>
353
 
    </itemizedlist>
354
 
  </refsection>
355
 
  <refsection>
356
 
    <title>Examples</title>
357
 
    <programlisting role="example"><![CDATA[ 
 
15
    <refnamediv>
 
16
        <refname>test_run</refname>
 
17
        <refpurpose>Launch tests</refpurpose>
 
18
    </refnamediv>
 
19
    <refsynopsisdiv>
 
20
        <title>Calling Sequence</title>
 
21
        <synopsis>
 
22
            status = test_run()
 
23
            status = test_run(module)
 
24
            status = test_run(module, test_name)
 
25
            status = test_run(module, test_name, options, exportToFile)
 
26
        </synopsis>
 
27
    </refsynopsisdiv>
 
28
    <refsection>
 
29
        <title>Arguments</title>
 
30
        <variablelist>
 
31
            <varlistentry>
 
32
                <term>module</term>
 
33
                <listitem>
 
34
                    <para>A String array. This input argument must be</para>
 
35
                    <itemizedlist>
 
36
                        <listitem>
 
37
                            <para>
 
38
                                the name of an internal Scilab module ("core", "time", ...) or a sub-module (e.g. "optimization|neldermead").
 
39
                            </para>
 
40
                        </listitem>
 
41
                        <listitem>
 
42
                            <para>
 
43
                                the name of an ATOMS module ("module_lycee", "nisp", ...). To be taken into account, the module must be loaded when test_run() is called.
 
44
                            </para>
 
45
                        </listitem>
 
46
                        <listitem>
 
47
                            <para>
 
48
                                the absolute directory path of a module.
 
49
                            </para>
 
50
                        </listitem>
 
51
                    </itemizedlist>
 
52
                </listitem>
 
53
            </varlistentry>
 
54
            <varlistentry>
 
55
                <term>test_name</term>
 
56
                <listitem>
 
57
                    <para>A string array</para>
 
58
                </listitem>
 
59
            </varlistentry>
 
60
            <varlistentry>
 
61
                <term>options</term>
 
62
                <listitem>
 
63
                    <para>A string array</para>
 
64
                    <variablelist>
 
65
                        <varlistentry>
 
66
                            <term>no_check_ref</term>
 
67
                            <listitem>
 
68
                                <para>does not check if the .dia and .dia.ref are equal</para>
 
69
                            </listitem>
 
70
                        </varlistentry>
 
71
                        <varlistentry>
 
72
                            <term>no_check_error_output</term>
 
73
                            <listitem>
 
74
                                <para>The error output stream is not checked. This option can be used when Scilab complains about the localization being not available.</para>
 
75
                            </listitem>
 
76
                        </varlistentry>
 
77
                        <varlistentry>
 
78
                            <term>create_ref</term>
 
79
                            <listitem>
 
80
                                <para>create the .dia.ref file and does not check if the .dia and .dia.ref are equal</para>
 
81
                            </listitem>
 
82
                        </varlistentry>
 
83
                        <varlistentry>
 
84
                            <term>show_error</term>
 
85
                            <listitem>
 
86
                                <para>If an error occurs, show the last 10 lines of the execution</para>
 
87
                            </listitem>
 
88
                        </varlistentry>
 
89
                        <varlistentry>
 
90
                            <term>show_diff</term>
 
91
                            <listitem>
 
92
                                <para>
 
93
                                    If a difference is found, show the result of the command <literal>diff -u</literal>
 
94
                                </para>
 
95
                            </listitem>
 
96
                        </varlistentry>
 
97
                        <varlistentry>
 
98
                            <term>list</term>
 
99
                            <listitem>
 
100
                                <para>Does not perform the tests but displays a list of available tests</para>
 
101
                            </listitem>
 
102
                        </varlistentry>
 
103
                        <varlistentry>
 
104
                            <term>help</term>
 
105
                            <listitem>
 
106
                                <para>display some examples about how to use this command</para>
 
107
                            </listitem>
 
108
                        </varlistentry>
 
109
                        <varlistentry>
 
110
                            <term>mode_nw</term>
 
111
                            <listitem>
 
112
                                <para>Add the "-nw" option to the launch</para>
 
113
                            </listitem>
 
114
                        </varlistentry>
 
115
                        <varlistentry>
 
116
                            <term>mode_nwni</term>
 
117
                            <listitem>
 
118
                                <para>Add the "-nwni" option to the launch</para>
 
119
                            </listitem>
 
120
                        </varlistentry>
 
121
                        <varlistentry>
 
122
                            <term>nonreg_test</term>
 
123
                            <listitem>
 
124
                                <para>runs only the non-regression tests, skipping unit tests</para>
 
125
                            </listitem>
 
126
                        </varlistentry>
 
127
                        <varlistentry>
 
128
                            <term>unit_test</term>
 
129
                            <listitem>
 
130
                                <para>Runs only the unit tests, skipping non-regression tests</para>
 
131
                            </listitem>
 
132
                        </varlistentry>
 
133
                        <varlistentry>
 
134
                            <term>skip_tests</term>
 
135
                            <listitem>
 
136
                                <para>Skip the tests</para>
 
137
                            </listitem>
 
138
                        </varlistentry>
 
139
                        <varlistentry>
 
140
                            <term>enable_lt</term>
 
141
                            <listitem>
 
142
                                <para>Enable long-time execution tests</para>
 
143
                            </listitem>
 
144
                        </varlistentry>
 
145
                        <varlistentry>
 
146
                            <term>short_summary</term>
 
147
                            <listitem>
 
148
                                <para>Does not display statistics nor execution time after execution (only number of executed, passed, failed and skipped tests will be displayed on a single line).</para>
 
149
                            </listitem>
 
150
                        </varlistentry>
 
151
                    </variablelist>
 
152
                </listitem>
 
153
            </varlistentry>
 
154
            <varlistentry>
 
155
                <term>exportToFile</term>
 
156
                <listitem>
 
157
                    <para>
 
158
                        Export to a XML file the result of the test. This file follows the specification of the XUnit format.
 
159
                        Note that the usage of this option enables <literal>show_diff</literal> and <literal>show_error</literal>.
 
160
                    </para>
 
161
                    <para>
 
162
                        If the file pointed by <varname>exportToFile</varname> already exists, the new result will be added to the existing file.
 
163
                    </para>
 
164
                </listitem>
 
165
            </varlistentry>
 
166
            <varlistentry>
 
167
                <term>status</term>
 
168
                <listitem>
 
169
                    <para>
 
170
                        Boolean value
 
171
                        Returns %t if no error has been detected
 
172
                        Returns %f if any error has been detected
 
173
                    </para>
 
174
                </listitem>
 
175
            </varlistentry>
 
176
        </variablelist>
 
177
    </refsection>
 
178
    <refsection>
 
179
        <title>Description</title>
 
180
        <para>
 
181
            Search for .tst files in the unit test and non-regression test library
 
182
            execute them, and display a report about success of failures.
 
183
            The .tst files are searched in directories SCI+"/modules/*/tests/unit_tests"
 
184
            and SCI+"/modules/*/tests/nonreg_tests".
 
185
            Whenever a test is executed, a .dia file is generated which contains
 
186
            the full list of commands executed along with message which appears in the
 
187
            console. When the script is done, the .dia file is compared with
 
188
            the .dia.ref file which is expected to be in the same directory
 
189
            as the .tst file. If the two file are different, the test fails.
 
190
        </para>
 
191
        <para>
 
192
            Special tags may be inserted in the .tst file, which help to
 
193
            control the processing of the corresponding test. These tags
 
194
            are expected to be found in Scilab comments.
 
195
        </para>
 
196
        <para>These are the available tags:</para>
 
197
        <itemizedlist>
 
198
            <listitem>
 
199
                <para>
 
200
                    &lt;-- INTERACTIVE TEST --&gt;
 
201
                    This test will be skipped because it is interactive.
 
202
                </para>
 
203
            </listitem>
 
204
            <listitem>
 
205
                <para>
 
206
                    &lt;-- LONG TIME EXECUTION --&gt;
 
207
                    This test will be skipped because it needs long-time duration. To enable
 
208
                    the test, call test_run with the following option: "enable_lt"
 
209
                </para>
 
210
            </listitem>
 
211
            <listitem>
 
212
                <para>
 
213
                    &lt;-- NOT FIXED --&gt;
 
214
                    This test will be skipped because it is a known, but unfixed bug.
 
215
                </para>
 
216
            </listitem>
 
217
            <listitem>
 
218
                <para>
 
219
                    &lt;-- TEST WITH GRAPHIC --&gt;
 
220
                    This test will not be executed if the option "mode_nwni" is used.
 
221
                </para>
 
222
            </listitem>
 
223
            <listitem>
 
224
                <para>
 
225
                    &lt;-- NO TRY CATCH --&gt;
 
226
                </para>
 
227
            </listitem>
 
228
            <listitem>
 
229
                <para>
 
230
                    &lt;-- NO CHECK ERROR OUTPUT --&gt;
 
231
                    The error output file is not checked
 
232
                </para>
 
233
            </listitem>
 
234
            <listitem>
 
235
                <para>
 
236
                    &lt;-- NO CHECK REF --&gt;
 
237
                    The .dia and the .dia.ref files are not compared.
 
238
                </para>
 
239
            </listitem>
 
240
            <listitem>
 
241
                <para>
 
242
                    &lt;-- ENGLISH IMPOSED --&gt;
 
243
                    This test will be executed with the -l en_US option.
 
244
                </para>
 
245
            </listitem>
 
246
            <listitem>
 
247
                <para>
 
248
                    &lt;-- FRENCH IMPOSED --&gt;
 
249
                    This test will be executed with the -l fr_FR option.
 
250
                </para>
 
251
            </listitem>
 
252
            <listitem>
 
253
                <para>
 
254
                    &lt;-- CLI SHELL MODE --&gt;
 
255
                    (was: &lt;-- JVM NOT MANDATORY --&gt;)
 
256
                    This test will be executed with scilab-cli (nwni mode) by default.
 
257
                </para>
 
258
            </listitem>
 
259
            <listitem>
 
260
                <para>
 
261
                    &lt;-- WINDOWS ONLY --&gt;
 
262
                    If the operating system isn't Windows, the test is skipped.
 
263
                </para>
 
264
            </listitem>
 
265
            <listitem>
 
266
                <para>
 
267
                    &lt;-- UNIX ONLY --&gt;
 
268
                    If the operating system isn't an Unix OS, the test is skipped.
 
269
                </para>
 
270
            </listitem>
 
271
            <listitem>
 
272
                <para>
 
273
                    &lt;-- LINUX ONLY --&gt;
 
274
                    If the operating system isn't GNU/Linux, the test is skipped.
 
275
                </para>
 
276
            </listitem>
 
277
            <listitem>
 
278
                <para>
 
279
                    &lt;-- MACOSX ONLY --&gt;
 
280
                    If the operating system isn't Mac OS X, the test is skipped.
 
281
                </para>
 
282
            </listitem>
 
283
            <listitem>
 
284
                <para>
 
285
                    &lt;-- XCOS TEST --&gt;
 
286
                    This test will launch all the necessary Xcos libs. This test
 
287
                    will be launched in nw mode.
 
288
                </para>
 
289
            </listitem>
 
290
        </itemizedlist>
 
291
        <para>
 
292
            Each test is executed in a separated process, created with the "host" command.
 
293
            That enables the current command to continue, even if the test as
 
294
            created an unstable environment. It also enables the tests to be
 
295
            independent from one another.
 
296
        </para>
 
297
    </refsection>
 
298
    <refsection>
 
299
        <title>Platform-specific tests</title>
 
300
        <para>
 
301
            It may happen that the output of a test depends on the platform on which it is
 
302
            executed. In this case, the <literal>.ref</literal> file cannot be correct for
 
303
            all platforms and unit tests may fail for some platform. In this case, we can
 
304
            create a default <literal>.ref</literal> and create additionnal <literal>.ref</literal>
 
305
            file for each platform.
 
306
        </para>
 
307
        <para>
 
308
            The various platform-specific <literal>.ref</literal> files must have one of the following extensions.
 
309
        </para>
 
310
        <itemizedlist>
 
311
            <listitem>
 
312
                <para>
 
313
                    <literal>.unix.dia.ref</literal> for Unix platform,
 
314
                </para>
 
315
            </listitem>
 
316
            <listitem>
 
317
                <para>
 
318
                    <literal>.linux.dia.ref</literal> for GNU/Linux platform,
 
319
                </para>
 
320
            </listitem>
 
321
            <listitem>
 
322
                <para>
 
323
                    <literal>.win.dia.ref</literal> for Windows platform,
 
324
                </para>
 
325
            </listitem>
 
326
            <listitem>
 
327
                <para>
 
328
                    <literal>.macosx.dia.ref</literal> for Mac OS X platform.
 
329
                </para>
 
330
            </listitem>
 
331
        </itemizedlist>
 
332
        <para>
 
333
            The algorithm is the following.
 
334
            First, the <literal>.ref</literal> is considered. If this file does not exist,
 
335
            the platform-specific <literal>.ref</literal> file is examined depending on the current platform.
 
336
        </para>
 
337
        <itemizedlist>
 
338
            <listitem>
 
339
                <para>
 
340
                    on Windows platforms: <literal>.win.dia.ref</literal>,
 
341
                </para>
 
342
            </listitem>
 
343
            <listitem>
 
344
                <para>
 
345
                    on Max OS X platforms: <literal>.unix.dia.ref</literal>, <literal>.macosx.dia.ref</literal>,
 
346
                </para>
 
347
            </listitem>
 
348
            <listitem>
 
349
                <para>
 
350
                    on GNU/Linux platforms: <literal>.unix.dia.ref</literal>, <literal>.linux.dia.ref</literal>.
 
351
                </para>
 
352
            </listitem>
 
353
        </itemizedlist>
 
354
    </refsection>
 
355
    <refsection>
 
356
        <title>Examples</title>
 
357
        <programlisting role="example"><![CDATA[ 
358
358
// Launch all tests
359
359
// =============================================
360
360
 
418
418
// Combine several options
419
419
test_run([],[],['no_check_ref','mode_nw']);
420
420
 ]]></programlisting>
421
 
    
422
 
    <programlisting role="example"><![CDATA[
 
421
        
 
422
        <programlisting role="example"><![CDATA[
423
423
// Run unitary tests of an external module (with his path)
424
424
test_run('SCI/contrib/toolbox_skeleton')
425
425
 ]]></programlisting>
426
 
    
427
 
    <programlisting role="example"><![CDATA[ 
 
426
        
 
427
        <programlisting role="example"><![CDATA[ 
428
428
// Export to a XML Xunit file
429
429
test_run('boolean',[],[],TMPDIR+"/boolean_test_run.xml");
430
430
test_run('time','datenum',[],TMPDIR+"/time_datenum_test_run.xml");
431
431
 ]]></programlisting>
432
 
  </refsection>
433
 
  <refsection>
434
 
    <title>Internal Design</title>
435
 
    <para>
436
 
      The tests are performed in the temporary directory, not in the directory
437
 
      which originaly contain the tests files.
438
 
      The .tst file is copied into the temporary directory, the test is performed
439
 
      and the .dia.ref is copied back into the original location.
440
 
    </para>
441
 
    <para>
442
 
      The .tst script is not run as is. Instead, a header and a footer are
443
 
      inserted at the beginning and at the end of the .tst at the time
444
 
      the script is copied into the temporary directory.
445
 
      The role of this modification is to redirect the output messages
446
 
      into the .dia file, so that the user can have a log file once the test
447
 
      is performed.
448
 
    </para>
449
 
  </refsection>
450
 
  <refsection>
451
 
    <title>History</title>
452
 
    <revhistory>
453
 
      <revision>
454
 
        <revnumber>5.4.0</revnumber>
455
 
        <revdescription>test_run returns a status:
456
 
          <itemizedlist><listitem>
457
 
              Returns %t if no error has been detected
458
 
            </listitem>
459
 
            <listitem>
460
 
              Returns %f if any error has been detected
461
 
            </listitem>
462
 
          </itemizedlist>
463
 
          <para>
464
 
            <literal>show_diff</literal> and <literal>show_error</literal> added as new options
465
 
          </para>
466
 
          <para>
467
 
            <literal>CLI SHELL MODE</literal> tag is added. Replaces <literal>JVM NOT MANDATORY</literal> (still supported)
468
 
          </para>
469
 
          <para>
470
 
            <literal>test_run</literal> can work on an external module.
471
 
          </para>
472
 
          
473
 
          <para>
474
 
            Fourth argument added to export to a XML file
475
 
          </para>
476
 
        </revdescription>
477
 
      </revision>
478
 
    </revhistory>
479
 
  </refsection>
 
432
    </refsection>
 
433
    <refsection>
 
434
        <title>Internal Design</title>
 
435
        <para>
 
436
            The tests are performed in the temporary directory, not in the directory
 
437
            which originaly contain the tests files.
 
438
            The .tst file is copied into the temporary directory, the test is performed
 
439
            and the .dia.ref is copied back into the original location.
 
440
        </para>
 
441
        <para>
 
442
            The .tst script is not run as is. Instead, a header and a footer are
 
443
            inserted at the beginning and at the end of the .tst at the time
 
444
            the script is copied into the temporary directory.
 
445
            The role of this modification is to redirect the output messages
 
446
            into the .dia file, so that the user can have a log file once the test
 
447
            is performed.
 
448
        </para>
 
449
    </refsection>
 
450
    <refsection>
 
451
        <title>History</title>
 
452
        <revhistory>
 
453
            <revision>
 
454
                <revnumber>5.4.0</revnumber>
 
455
                <revdescription>test_run returns a status:
 
456
                    <itemizedlist><listitem>
 
457
                            Returns %t if no error has been detected
 
458
                        </listitem>
 
459
                        <listitem>
 
460
                            Returns %f if any error has been detected
 
461
                        </listitem>
 
462
                    </itemizedlist>
 
463
                    <para>
 
464
                        <literal>show_diff</literal> and <literal>show_error</literal> added as new options
 
465
                    </para>
 
466
                    <para>
 
467
                        <literal>CLI SHELL MODE</literal> tag is added. Replaces <literal>JVM NOT MANDATORY</literal> (still supported)
 
468
                    </para>
 
469
                    <para>
 
470
                        <literal>test_run</literal> can work on an external module.
 
471
                    </para>
 
472
                    
 
473
                    <para>
 
474
                        Fourth argument added to export to a XML file
 
475
                    </para>
 
476
                </revdescription>
 
477
            </revision>
 
478
        </revhistory>
 
479
    </refsection>
480
480
</refentry>