Scilab cli: add a "--timeout delay" argument
[scilab.git] / scilab / modules / development_tools / help / ja_JP / test_run.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) INRIA
5  * Copyright (C) 2009-2011 - DIGITEO - Michael Baudin
6  *
7  * Copyright (C) 2012 - 2016 - Scilab Enterprises
8  *
9  * This file is hereby licensed under the terms of the GNU GPL v2.0,
10  * pursuant to article 5.3.4 of the CeCILL v.2.1.
11  * This file was originally licensed under the terms of the CeCILL v2.1,
12  * and continues to be available under such terms.
13  * For more information, see the COPYING file which you should have received
14  * along with this program.
15  *
16  -->
17 <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" xmlns:scilab="http://www.scilab.org" xml:id="test_run" xml:lang="ja">
18     <refnamediv>
19         <refname>test_run</refname>
20         <refpurpose>テストを実行</refpurpose>
21     </refnamediv>
22     <refsynopsisdiv>
23         <title>呼び出し手順</title>
24         <synopsis>
25             status = test_run()
26             status = test_run(module)
27             status = test_run(module, test_name)
28             status = test_run(module, test_name, options, exportToFile)
29         </synopsis>
30     </refsynopsisdiv>
31     <refsection>
32         <title>引数</title>
33         <variablelist>
34             <varlistentry>
35                 <term>module</term>
36                 <listitem>
37                     <para>文字列の配列. この入力引数には以下のどれかを指定します</para>
38                     <itemizedlist>
39                         <listitem>
40                             <para>
41                                 Scilab内部モジュール名 ("core", "time", ...)またはサブモジュール名 (例: "optimization|neldermead").
42                             </para>
43                         </listitem>
44                         <listitem>
45                             <para>
46                                 ATOMSモジュールの名前("module_lycee", "nisp", ...).
47                                 処理を行うには,このモジュールはtest_run()をコールする前に
48                                 ロードしておく必要があります.
49                             </para>
50                         </listitem>
51                         <listitem>
52                             <para>
53                                 モジュールの絶対ディレクトリパス.
54                             </para>
55                         </listitem>
56                     </itemizedlist>
57                 </listitem>
58             </varlistentry>
59             <varlistentry>
60                 <term>test_name</term>
61                 <listitem>
62                     <para>文字列配列</para>
63                 </listitem>
64             </varlistentry>
65             <varlistentry>
66                 <term>options</term>
67                 <listitem>
68                     <para>文字列配列</para>
69                     <variablelist>
70                         <varlistentry>
71                             <term>no_check_ref</term>
72                             <listitem>
73                                 <para>the .dia と .dia.ref が等しい場合, チェックを行いません</para>
74                             </listitem>
75                         </varlistentry>
76                         <varlistentry>
77                             <term>no_check_error_output</term>
78                             <listitem>
79                                 <para>エラー出力ストリームはチェックされません.
80                                     Scilabがローカライズされたものが利用できないとエラーを発生する
81                                     場合,このオプションを利用できます.
82                                 </para>
83                             </listitem>
84                         </varlistentry>
85                         <varlistentry>
86                             <term>create_ref</term>
87                             <listitem>
88                                 <para>.dia.refファイルを作成し,
89                                     .dia と .dia.refが等しいかどうかをチェックしません.
90                                 </para>
91                             </listitem>
92                         </varlistentry>
93                         <varlistentry>
94                             <term>show_error</term>
95                             <listitem>
96                                 <para>エラーが発生した場合直近の10行分の実行行を表示します
97                                 </para>
98                             </listitem>
99                         </varlistentry>
100                         <varlistentry>
101                             <term>show_diff</term>
102                             <listitem>
103                                 <para>
104                                     差異がみつかった場合,<literal>diff -u</literal>コマンドの結果を
105                                     表示します.
106                                 </para>
107                             </listitem>
108                         </varlistentry>
109                         <varlistentry>
110                             <term>list</term>
111                             <listitem>
112                                 <para>
113                                     テストを実行しませんが,
114                                     利用可能なテストの一覧を表示します
115                                 </para>
116                             </listitem>
117                         </varlistentry>
118                         <varlistentry>
119                             <term>help</term>
120                             <listitem>
121                                 <para>
122                                     このコマンドの使用方法に関するいくつかの例を表示します
123                                 </para>
124                             </listitem>
125                         </varlistentry>
126                         <varlistentry>
127                             <term>mode_nw</term>
128                             <listitem>
129                                 <para>実行時に "-nw" オプションを追加します</para>
130                             </listitem>
131                         </varlistentry>
132                         <varlistentry>
133                             <term>mode_nwni</term>
134                             <listitem>
135                                 <para>実行時に "-nwni"オプションを追加します</para>
136                             </listitem>
137                         </varlistentry>
138                         <varlistentry>
139                             <term>mode_nwni_profiling</term>
140                             <listitem>
141                                 <para>Add the "-nwni -profiling" option to the launch for detect valgrind error (Linux only)</para>
142                             </listitem>
143                         </varlistentry>
144                         <varlistentry>
145                             <term>nonreg_tests</term>
146                             <listitem>
147                                 <para>回帰的でないテストのみを実行し,
148                                     ユニットテストをスキップします
149                                 </para>
150                             </listitem>
151                         </varlistentry>
152                         <varlistentry>
153                             <term>unit_tests</term>
154                             <listitem>
155                                 <para>
156                                     ユニットテストのみを実行し,回帰的でないテストをスキップします
157                                 </para>
158                             </listitem>
159                         </varlistentry>
160                         <varlistentry>
161                             <term>skip_tests</term>
162                             <listitem>
163                                 <para>テストをスキップします</para>
164                             </listitem>
165                         </varlistentry>
166                         <varlistentry>
167                             <term>enable_lt</term>
168                             <listitem>
169                                 <para>テストの長時間実行を許可します</para>
170                             </listitem>
171                         </varlistentry>
172                         <varlistentry>
173                             <term>short_summary</term>
174                             <listitem>
175                                 <para>
176                                     実行後に統計または実行時間を表示しません
177                                     (実行回数,成功/失敗/スキップしたテストの回数のみを1行に表示します).
178                                 </para>
179                             </listitem>
180                         </varlistentry>
181                     </variablelist>
182                 </listitem>
183             </varlistentry>
184             <varlistentry>
185                 <term>exportToFile</term>
186                 <listitem>
187                     <para>
188                         テストの結果をXMLファイルにエクスポートします.
189                         このファイルはXUnit形式となります.
190                         このオプションの使用により,
191                         <literal>show_diff</literal> および <literal>show_error</literal>
192                         が有効となることに注意してください.
193                     </para>
194                     <para>
195                         <varname>exportToFile</varname>で指定したファイルが既に存在する場合,
196                         新規結果は既存のファイルに追加されます.
197                     </para>
198                 </listitem>
199             </varlistentry>
200             <varlistentry>
201                 <term>status</term>
202                 <listitem>
203                     <para>
204                         論理値で,エラーが検出されなかった場合に %t,
205                         エラーが検出された場合に %f を返します.
206                     </para>
207                 </listitem>
208             </varlistentry>
209         </variablelist>
210     </refsection>
211     <refsection>
212         <title>説明</title>
213         <para>
214             ユニットテストおよび非回帰テストライブラリで
215             .tstファイルを探して実行し,成功/失敗に関するレポートを表示します.
216             .tst ファイルはディレクトリ SCI+"/modules/*/tests/unit_tests"
217             およびSCI+"/modules/*/tests/nonreg_tests"で探されます.
218             テストが実行される度に, .diaファイルが生成され,
219             実行された全コマンドとコンソールに表示されたメッセージのリストが
220             出力されます.
221             スクリプトが実行された後, この.dia ファイルは,
222             .tst ファイルと同じディレクトリに置かれた.dia.refファイルで
223             と比較されます.
224             2つのファイルが異なる場合,そのテストは失敗となります.
225         </para>
226         <para>
227             テストの処理を制御できるように.tstファイルに特殊なタグを挿入できます.
228             これらのタグはScilabコメントとして記述します.
229         </para>
230         <para>以下に利用可能なタグを示します:</para>
231         <itemizedlist>
232             <listitem>
233                 <para>
234                     &lt;-- INTERACTIVE TEST --&gt;
235                     このテストは対話的なものであるため,スキップされます.
236                 </para>
237             </listitem>
238             <listitem>
239                 <para>
240                     &lt;-- LONG TIME EXECUTION --&gt;
241                     このテストは長い時間を要するためスキップされます.
242                     このテストを有効にするには,以下のオプションを指定してtest_runを
243                     コールします: "enable_lt"
244                 </para>
245             </listitem>
246             <listitem>
247                 <para>
248                     &lt;-- NOT FIXED --&gt;
249                     このテストは,既知ではあるが,未修正のバグであるため,スキップされます.
250                 </para>
251             </listitem>
252             <listitem>
253                 <para>
254                     &lt;-- TEST WITH GRAPHIC --&gt;
255                     This test will be executed with scilab -nw. (default mode)
256                 </para>
257             </listitem>
258             <listitem>
259                 <para>
260                     &lt;-- NO TRY CATCH --&gt;
261                 </para>
262             </listitem>
263             <listitem>
264                 <para>
265                     &lt;-- NO CHECK ERROR OUTPUT --&gt;
266                     エラー出力ファイルはチェックされません
267                 </para>
268             </listitem>
269             <listitem>
270                 <para>
271                     &lt;-- NO CHECK REF --&gt;
272                     .dia および.dia.refファイルの比較が行われません.
273                 </para>
274             </listitem>
275             <listitem>
276                 <para>
277                     &lt;-- ENGLISH IMPOSED --&gt;
278                     このテストは-l en_USオプションを指定した場合のみ実行されます.
279                 </para>
280             </listitem>
281             <listitem>
282                 <para>
283                     &lt;-- FRENCH IMPOSED --&gt;
284                     このテストは-l fr_FRオプションを指定した場合のみ実行されます.
285                 </para>
286             </listitem>
287             <listitem>
288                 <para>
289                     &lt;-- CLI SHELL MODE --&gt;
290                     (was &lt;-- JVM NOT MANDATORY --&gt; and is obsolete)
291                     This test will be executed with scilab -nwni.
292                     All tests without this, will not be executed in "mode_mwni".
293                 </para>
294             </listitem>
295             <listitem>
296                 <para>
297                     &lt;-- WINDOWS ONLY --&gt;
298                     オペレーティング・システムがWindowsでない場合, このテストはスキップされます.
299                 </para>
300             </listitem>
301             <listitem>
302                 <para>
303                     &lt;-- UNIX ONLY --&gt;
304                     オペレーティング・システムがUnix OSでない場合, このテストはスキップされます.
305                 </para>
306             </listitem>
307             <listitem>
308                 <para>
309                     &lt;-- LINUX ONLY --&gt;
310                     オペレーティング・システムがGNU/Linuxでない場合, このテストはスキップされます.
311                 </para>
312             </listitem>
313             <listitem>
314                 <para>
315                     &lt;-- MACOSX ONLY --&gt;
316                     オペレーティング・システムがMac OS Xでない場合, このテストはスキップされます.
317                 </para>
318             </listitem>
319             <listitem>
320                 <para>
321                     &lt;-- XCOS TEST --&gt;
322                     このテストは全ての必要なXcosライブラリを実行します.
323                     このテストはnwモードで実行されます.
324                 </para>
325             </listitem>
326         </itemizedlist>
327         <para>
328             各テストは"host"コマンドで生成された別のプロセスで実行されます.
329             これにより,テストにより不安定な環境となる場合でも,
330             カレントのコマンドの実行を継続できます.
331             また,テストは他のテストと独立して実行可能となります.
332         </para>
333     </refsection>
334     <refsection>
335         <title>プラットフォーム毎のテスト</title>
336         <para>
337             テストの出力が実行されるプラットフォームに依存している場合があります.
338             この場合,<literal>.ref</literal>を全てのプラットフォーム用で同じとならず,
339             いくつかのプラットフォームではユニットテストが失敗する可能性があります.
340             この場合,
341             デフォルトの<literal>.ref</literal>と共に
342             各プラットフォーム用の<literal>.ref</literal>を作成することができます.
343         </para>
344         <para>
345             プラットフォーム毎の <literal>.ref</literal>には以下のような拡張子の
346             どれかを付ける必要があります.
347         </para>
348         <itemizedlist>
349             <listitem>
350                 <para>
351                     <literal>.unix.dia.ref</literal>はUnixプラットフォーム用,
352                 </para>
353             </listitem>
354             <listitem>
355                 <para>
356                     <literal>.linux.dia.ref</literal>はGNU/Linuxプラットフォーム用,
357                 </para>
358             </listitem>
359             <listitem>
360                 <para>
361                     <literal>.win.dia.ref</literal>はWindowsプラットフォーム用,
362                 </para>
363             </listitem>
364             <listitem>
365                 <para>
366                     <literal>.macosx.dia.ref</literal>はMac OS Xプラットフォーム用.
367                 </para>
368             </listitem>
369         </itemizedlist>
370         <para>
371             アルゴリズムは以下のようになります.
372             まず, <literal>.ref</literal> が探されます.
373             このファイルが存在しない場合,
374             現在のプラットフォームに応じた以下の
375             プラットフォーム毎の<literal>.ref</literal>ファイルが実行されます.
376         </para>
377         <itemizedlist>
378             <listitem>
379                 <para>
380                     Windowsプラットフォームの場合: <literal>.win.dia.ref</literal>,
381                 </para>
382             </listitem>
383             <listitem>
384                 <para>
385                     Max OS X プラットフォームの場合: <literal>.unix.dia.ref</literal>, <literal>.macosx.dia.ref</literal>,
386                 </para>
387             </listitem>
388             <listitem>
389                 <para>
390                     GNU/Linuxプラットフォームの場合: <literal>.unix.dia.ref</literal>, <literal>.linux.dia.ref</literal>.
391                 </para>
392             </listitem>
393         </itemizedlist>
394     </refsection>
395     <refsection>
396         <title>例</title>
397         <programlisting role="example"><![CDATA[
398 // 全てのテストを実行
399 // =============================================
400 // test_run();
401 // test_run([]);
402 // test_run([],[]);
403 // test_run("[]","[]");
404 // test_run [] [];
405 // 1つまたは複数のモジュールをテスト
406 // =============================================
407 // 1つのモジュールをテスト
408 test_run('time');
409 // 複数のモジュールをテスト
410 test_run(['time','string']);
411 // サブモジュールをテスト
412 test_run('optimization|neldermead');
413 // パスで指定したモジュールを参照
414 test_run(SCI+'/modules/core');
415 // 指定したテストを実行
416 // =============================================
417 // テストを1つ指定
418 test_run('time','datenum');
419 // 複数のテストを指定
420 test_run('time',['datenum';'calendar']);
421 // いくつかのテストをスキップ
422 // =============================================
423 test_run('time',['datenum';'calendar'],'skip_tests');
424 // オプション
425 // =============================================
426 // .dia と .dia.ref が等しいかどうかをチェックしません
427 test_run('time','datenum','no_check_ref');
428 // .dia.refファイルを作成しますが,.diaと.dia.refが等しいかどうかをチェックしません
429 test_run([],[],'create_ref');
430 // テストを実行しないが,利用可能なテストの一覧を表示します
431 test_run([],[],'list');
432 // このコマンドの使用法に関するいくつかの例を表示します
433 test_run([],[],'help');
434 // 非回帰テストのみを実行し,ユニットテストをスキップします
435 test_run([],[],'nonreg_test');
436 // ユニットテストのみを実行し,非回帰テストをスキップします
437 test_run([],[],'unit_test');
438 // エラー出力 (std err)をチェックしません
439 test_run('boolean','bug_2799','no_check_error_output');
440 // 複数のオプションを同時に指定
441 test_run([],[],['no_check_ref','mode_nw']);
442 // Console mode
443 test_run time [] no_check_ref //tests time module with no_check_ref option
444  ]]></programlisting>
445         <programlisting role="example"><![CDATA[
446 //  (パスで指定した)外部モジュールのユニットテストを実行
447 test_run('SCI/contrib/toolbox_skeleton')
448  ]]></programlisting>
449         <programlisting role="example"><![CDATA[
450 // XML Xunitファイルにエクスポート
451 test_run('boolean',[],[],TMPDIR+"/boolean_test_run.xml");
452 test_run('time','datenum',[],TMPDIR+"/time_datenum_test_run.xml");
453  ]]></programlisting>
454     </refsection>
455     <refsection>
456         <title>内部設計</title>
457         <para>
458             テストは,
459             テストファイルが置かれたディレクトリではなく,
460             テンポラリディレクトリで実行されます.
461             .tstファイルはテンポラリディレクトリにコピーされた後,
462             テストが実行され,.dia.ref が元の位置にコピーされます.
463         </para>
464         <para>
465             .tstスクリプトはそのまま実行されません.
466             かわりに,テンポラリディレクトリにコピーされる際に
467             ヘッダとフッタが.tstの先頭と終端に挿入されます.
468             この修正の理由は,出力メッセージを.diaファイルにリダイレクトし,
469             テストが実行された後に,ユーザがログファイルを取得できるように
470             するためです.
471         </para>
472         <para>
473             An execution timeout delay (watchdog timer) is setup to 5 minutes
474             for each regular test. To ignore this timeout use the long-time
475             execution (<literal>LONG TIME EXECUTION</literal>) flag.
476         </para>
477     </refsection>
478     <refsection>
479         <title>履歴</title>
480         <revhistory>
481             <revision>
482                 <revnumber>5.4.0</revnumber>
483                 <revdescription>test_runは以下のステータスを返します:
484                     <itemizedlist><listitem>
485                             エラーが検出されなかった場合に %t を返します
486                         </listitem>
487                         <listitem>
488                             エラーが検出された場合に %f を返します
489                         </listitem>
490                     </itemizedlist>
491                     <para>
492                         <literal>show_diff</literal> および <literal>show_error</literal> が
493                         新しいオプションとして追加されました
494                     </para>
495                     <para>
496                         <literal>CLI SHELL MODE</literal> タグが追加されました.
497                         <literal>JVM NOT MANDATORY</literal> (まだサポート中)を置き換えます
498                     </para>
499                     <para>
500                         <literal>test_run</literal> は外部モジュールでも動作します.
501                     </para>
502                     <para>
503                         XMLファイルにエクスポートする4番目の引数が追加されました
504                     </para>
505                 </revdescription>
506                 <revnumber>5.5.0</revnumber>
507                 <revdescription>32/64bits separation available</revdescription>
508                 <revnumber>6.0.0</revnumber>
509                 <revdescription>
510                     <para>profiling mode added to profile execution with valgrind (Linux only)</para>
511                     <para>
512                         timeout delay (watchdog timer) set to 5 minutes for single tests without <literal>LONG TIME EXECUTION</literal>
513                     </para>
514                 </revdescription>
515             </revision>
516         </revhistory>
517     </refsection>
518 </refentry>