[doc] misc. patchs & small improvements
[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  * Copyright (C) 2012 - 2016 - Scilab Enterprises
7  * Copyright (C) 2018 - Samuel GOUGEON
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"
18           xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml"
19           xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
20           xmlns:scilab="http://www.scilab.org" xml:id="test_run" xml:lang="ja">
21     <refnamediv>
22         <refname>test_run</refname>
23         <refpurpose>テストを実行</refpurpose>
24     </refnamediv>
25     <refsynopsisdiv>
26         <title>呼び出し手順</title>
27         <synopsis>
28             status = test_run()
29             status = test_run(module)
30             status = test_run(module, test_name)
31             status = test_run(module, test_name, options, exportToFile)
32         </synopsis>
33     </refsynopsisdiv>
34     <refsection>
35         <title>引数</title>
36         <variablelist>
37             <varlistentry>
38                 <term>module</term>
39                 <listitem>
40                     <para>文字列の配列. この入力引数には以下のどれかを指定します</para>
41                     <itemizedlist>
42                         <listitem>
43                             <para>
44                                 Scilab内部モジュール名 ("core", "time", ...)またはサブモジュール名 (例: "optimization|neldermead").
45                             </para>
46                         </listitem>
47                         <listitem>
48                             <para>
49                                 ATOMSモジュールの名前("module_lycee", "nisp", ...).
50                                 処理を行うには,このモジュールはtest_run()をコールする前に
51                                 ロードしておく必要があります.
52                             </para>
53                         </listitem>
54                         <listitem>
55                             <para>
56                                 モジュールの絶対ディレクトリパス.
57                             </para>
58                         </listitem>
59                     </itemizedlist>
60                 </listitem>
61             </varlistentry>
62             <varlistentry>
63                 <term>test_name</term>
64                 <listitem>
65                     <para>
66                         A string array or <literal>[]</literal> or <literal>"[]"</literal>:
67                         The names of the tests to execute during this run. If <varname>test_name</varname>
68                         is <literal>[]</literal>, all tests found in the module or in the directory are executed.
69                     </para>
70                     <para>
71                         The wildcard * can be used, like in <literal>*sin</literal>,
72                         <literal>*sin</literal>, or <literal>*sin*</literal>.
73                     </para>
74                 </listitem>
75             </varlistentry>
76             <varlistentry>
77                 <term>options</term>
78                 <listitem>
79                     <para>文字列配列</para>
80                     <variablelist>
81                         <varlistentry>
82                             <term>no_check_ref</term>
83                             <listitem>
84                                 <para>the .dia と .dia.ref が等しい場合, チェックを行いません</para>
85                             </listitem>
86                         </varlistentry>
87                         <varlistentry>
88                             <term>no_check_error_output</term>
89                             <listitem>
90                                 <para>エラー出力ストリームはチェックされません.
91                                     Scilabがローカライズされたものが利用できないとエラーを発生する
92                                     場合,このオプションを利用できます.
93                                 </para>
94                             </listitem>
95                         </varlistentry>
96                         <varlistentry>
97                             <term>create_ref</term>
98                             <listitem>
99                                 <para>.dia.refファイルを作成し,
100                                     .dia と .dia.refが等しいかどうかをチェックしません.
101                                   This option is applied only to chosen tests not having the
102                                   <literal>&lt;-- NO CHECK REF --></literal> flag.
103                                 </para>
104                             </listitem>
105                         </varlistentry>
106                         <varlistentry>
107                             <term>show_error</term>
108                             <listitem>
109                                 <para>エラーが発生した場合直近の10行分の実行行を表示します
110                                 </para>
111                             </listitem>
112                         </varlistentry>
113                         <varlistentry>
114                             <term>show_diff</term>
115                             <listitem>
116                                 <para>
117                                     差異がみつかった場合,<literal>diff -u</literal>コマンドの結果を
118                                     表示します.
119                                 </para>
120                             </listitem>
121                         </varlistentry>
122                         <varlistentry>
123                             <term>list</term>
124                             <listitem>
125                                 <para>
126                                     テストを実行しませんが,
127                                     利用可能なテストの一覧を表示します
128                                 </para>
129                             </listitem>
130                         </varlistentry>
131                         <varlistentry>
132                             <term>help</term>
133                             <listitem>
134                                 <para>
135                                     このコマンドの使用方法に関するいくつかの例を表示します
136                                 </para>
137                             </listitem>
138                         </varlistentry>
139                         <varlistentry>
140                             <term>mode_nw</term>
141                             <listitem>
142                                 <para>実行時に "-nw" オプションを追加します</para>
143                             </listitem>
144                         </varlistentry>
145                         <varlistentry>
146                             <term>mode_nwni</term>
147                             <listitem>
148                                 <para>実行時に "-nwni"オプションを追加します</para>
149                             </listitem>
150                         </varlistentry>
151                         <varlistentry>
152                             <term>mode_nwni_profiling</term>
153                             <listitem>
154                                 <para>Add the "-nwni -profiling" option to the launch for detect valgrind error (Linux only)</para>
155                             </listitem>
156                         </varlistentry>
157                         <varlistentry>
158                             <term>nonreg_tests</term>
159                             <listitem>
160                                 <para>回帰的でないテストのみを実行し,
161                                     ユニットテストをスキップします
162                                 </para>
163                             </listitem>
164                         </varlistentry>
165                         <varlistentry>
166                             <term>unit_tests</term>
167                             <listitem>
168                                 <para>
169                                     ユニットテストのみを実行し,回帰的でないテストをスキップします
170                                 </para>
171                             </listitem>
172                         </varlistentry>
173                         <varlistentry>
174                             <term>skip_tests</term>
175                             <listitem>
176                                 <para>テストをスキップします</para>
177                             </listitem>
178                         </varlistentry>
179                         <varlistentry>
180                             <term>enable_lt</term>
181                             <listitem>
182                                 <para>テストの長時間実行を許可します</para>
183                             </listitem>
184                         </varlistentry>
185                         <varlistentry>
186                             <term>short_summary</term>
187                             <listitem>
188                                 <para>
189                                     実行後に統計または実行時間を表示しません
190                                     (実行回数,成功/失敗/スキップしたテストの回数のみを1行に表示します).
191                                 </para>
192                             </listitem>
193                         </varlistentry>
194                     </variablelist>
195                 </listitem>
196             </varlistentry>
197             <varlistentry>
198                 <term>exportToFile</term>
199                 <listitem>
200                     <para>
201                         テストの結果をXMLファイルにエクスポートします.
202                         このファイルはXUnit形式となります.
203                         このオプションの使用により,
204                         <literal>show_diff</literal> および <literal>show_error</literal>
205                         が有効となることに注意してください.
206                     </para>
207                     <para>
208                         <varname>exportToFile</varname>で指定したファイルが既に存在する場合,
209                         新規結果は既存のファイルに追加されます.
210                     </para>
211                 </listitem>
212             </varlistentry>
213             <varlistentry>
214                 <term>status</term>
215                 <listitem>
216                     <para>
217                         論理値で,エラーが検出されなかった場合に %t,
218                         エラーが検出された場合に %f を返します.
219                     </para>
220                 </listitem>
221             </varlistentry>
222         </variablelist>
223     </refsection>
224     <refsection>
225         <title>説明</title>
226         <para>
227             ユニットテストおよび非回帰テストライブラリで
228             .tstファイルを探して実行し,成功/失敗に関するレポートを表示します.
229             .tst ファイルはディレクトリ SCI+"/modules/*/tests/unit_tests"
230             およびSCI+"/modules/*/tests/nonreg_tests"で探されます.
231             テストが実行される度に, .diaファイルが生成され,
232             実行された全コマンドとコンソールに表示されたメッセージのリストが
233             出力されます.
234             スクリプトが実行された後, この.dia ファイルは,
235             .tst ファイルと同じディレクトリに置かれた.dia.refファイルで
236             と比較されます.
237             2つのファイルが異なる場合,そのテストは失敗となります.
238         </para>
239         <para>
240             テストの処理を制御できるように.tstファイルに特殊なタグを挿入できます.
241             これらのタグはScilabコメントとして記述します.
242         </para>
243         <para>以下に利用可能なタグを示します:</para>
244         <itemizedlist>
245             <listitem>
246                 <para>
247                     &lt;-- INTERACTIVE TEST --&gt;
248                     このテストは対話的なものであるため,スキップされます.
249                 </para>
250             </listitem>
251             <listitem>
252                 <para>
253                     &lt;-- LONG TIME EXECUTION --&gt;
254                     このテストは長い時間を要するためスキップされます.
255                     このテストを有効にするには,以下のオプションを指定してtest_runを
256                     コールします: "enable_lt"
257                 </para>
258             </listitem>
259             <listitem>
260                 <para>
261                     &lt;-- NOT FIXED --&gt;
262                     このテストは,既知ではあるが,未修正のバグであるため,スキップされます.
263                 </para>
264             </listitem>
265             <listitem>
266                 <para>
267                     &lt;-- TEST WITH GRAPHIC --&gt;
268                     This test will be executed with scilab -nw. (default mode)
269                 </para>
270             </listitem>
271             <listitem>
272                 <para>
273                     &lt;-- NO TRY CATCH --&gt;
274                 </para>
275             </listitem>
276             <listitem>
277                 <para>
278                     &lt;-- NO CHECK ERROR OUTPUT --&gt;
279                     エラー出力ファイルはチェックされません
280                 </para>
281             </listitem>
282             <listitem>
283                 <para>
284                     &lt;-- NO CHECK REF --&gt;
285                     .dia および.dia.refファイルの比較が行われません.
286                 </para>
287             </listitem>
288             <listitem>
289                 <para>
290                     &lt;-- ENGLISH IMPOSED --&gt;
291                     このテストは-l en_USオプションを指定した場合のみ実行されます.
292                 </para>
293             </listitem>
294             <listitem>
295                 <para>
296                     &lt;-- FRENCH IMPOSED --&gt;
297                     このテストは-l fr_FRオプションを指定した場合のみ実行されます.
298                 </para>
299             </listitem>
300             <listitem>
301                 <para>
302                     &lt;-- CLI SHELL MODE --&gt;
303                     (was &lt;-- JVM NOT MANDATORY --&gt; and is obsolete)
304                     This test will be executed with scilab -nwni.
305                     All tests without this, will not be executed in "mode_mwni".
306                 </para>
307             </listitem>
308             <listitem>
309                 <para>
310                     &lt;-- WINDOWS ONLY --&gt;
311                     オペレーティング・システムがWindowsでない場合, このテストはスキップされます.
312                 </para>
313             </listitem>
314             <listitem>
315                 <para>
316                     &lt;-- UNIX ONLY --&gt;
317                     オペレーティング・システムがUnix OSでない場合, このテストはスキップされます.
318                 </para>
319             </listitem>
320             <listitem>
321                 <para>
322                     &lt;-- LINUX ONLY --&gt;
323                     オペレーティング・システムがGNU/Linuxでない場合, このテストはスキップされます.
324                 </para>
325             </listitem>
326             <listitem>
327                 <para>
328                     &lt;-- MACOSX ONLY --&gt;
329                     オペレーティング・システムがMac OS Xでない場合, このテストはスキップされます.
330                 </para>
331             </listitem>
332             <listitem>
333                 <para>
334                     &lt;-- XCOS TEST --&gt;
335                     このテストは全ての必要なXcosライブラリを実行します.
336                     このテストはnwモードで実行されます.
337                 </para>
338             </listitem>
339         </itemizedlist>
340         <para>
341             各テストは"host"コマンドで生成された別のプロセスで実行されます.
342             これにより,テストにより不安定な環境となる場合でも,
343             カレントのコマンドの実行を継続できます.
344             また,テストは他のテストと独立して実行可能となります.
345         </para>
346     </refsection>
347     <refsection>
348         <title>プラットフォーム毎のテスト</title>
349         <para>
350             テストの出力が実行されるプラットフォームに依存している場合があります.
351             この場合,<literal>.ref</literal>を全てのプラットフォーム用で同じとならず,
352             いくつかのプラットフォームではユニットテストが失敗する可能性があります.
353             この場合,
354             デフォルトの<literal>.ref</literal>と共に
355             各プラットフォーム用の<literal>.ref</literal>を作成することができます.
356         </para>
357         <para>
358             プラットフォーム毎の <literal>.ref</literal>には以下のような拡張子の
359             どれかを付ける必要があります.
360         </para>
361         <itemizedlist>
362             <listitem>
363                 <para>
364                     <literal>.unix.dia.ref</literal>はUnixプラットフォーム用,
365                 </para>
366             </listitem>
367             <listitem>
368                 <para>
369                     <literal>.linux.dia.ref</literal>はGNU/Linuxプラットフォーム用,
370                 </para>
371             </listitem>
372             <listitem>
373                 <para>
374                     <literal>.win.dia.ref</literal>はWindowsプラットフォーム用,
375                 </para>
376             </listitem>
377             <listitem>
378                 <para>
379                     <literal>.macosx.dia.ref</literal>はMac OS Xプラットフォーム用.
380                 </para>
381             </listitem>
382         </itemizedlist>
383         <para>
384             アルゴリズムは以下のようになります.
385             まず, <literal>.ref</literal> が探されます.
386             このファイルが存在しない場合,
387             現在のプラットフォームに応じた以下の
388             プラットフォーム毎の<literal>.ref</literal>ファイルが実行されます.
389         </para>
390         <itemizedlist>
391             <listitem>
392                 <para>
393                     Windowsプラットフォームの場合: <literal>.win.dia.ref</literal>,
394                 </para>
395             </listitem>
396             <listitem>
397                 <para>
398                     Max OS X プラットフォームの場合: <literal>.unix.dia.ref</literal>, <literal>.macosx.dia.ref</literal>,
399                 </para>
400             </listitem>
401             <listitem>
402                 <para>
403                     GNU/Linuxプラットフォームの場合: <literal>.unix.dia.ref</literal>, <literal>.linux.dia.ref</literal>.
404                 </para>
405             </listitem>
406         </itemizedlist>
407     </refsection>
408     <refsection>
409         <title>例</title>
410         <programlisting role="example"><![CDATA[
411 // 全てのテストを実行
412 // =============================================
413 // test_run();
414 // test_run([]);
415 // test_run([],[]);
416 // test_run("[]","[]");
417 // test_run [] [];
418
419 // 1つまたは複数のモジュールをテスト
420 // =============================================
421 // 1つのモジュールをテスト
422 test_run('time');
423
424 // 複数のモジュールをテスト
425 test_run(['time','string']);
426
427 // サブモジュールをテスト
428 test_run('optimization|neldermead');
429
430 // パスで指定したモジュールを参照
431 test_run(SCI+'/modules/core');
432
433 // 指定したテストを実行
434 // =============================================
435 // テストを1つ指定
436 test_run('time','datenum');
437
438 // 複数のテストを指定
439 test_run('time',['datenum';'calendar']);
440
441 // いくつかのテストをスキップ
442 // =============================================
443 test_run('time',['datenum';'calendar'],'skip_tests');
444
445 // オプション
446 // =============================================
447 // .dia と .dia.ref が等しいかどうかをチェックしません
448 test_run('time','datenum','no_check_ref');
449
450 // .dia.refファイルを作成しますが,.diaと.dia.refが等しいかどうかをチェックしません
451 test_run([],[],'create_ref');
452
453 // テストを実行しないが,利用可能なテストの一覧を表示します
454 test_run([],[],'list');
455
456 // このコマンドの使用法に関するいくつかの例を表示します
457 test_run([],[],'help');
458
459 // 非回帰テストのみを実行し,ユニットテストをスキップします
460 test_run([],[],'nonreg_test');
461
462 // ユニットテストのみを実行し,非回帰テストをスキップします
463 test_run([],[],'unit_test');
464
465 // エラー出力 (std err)をチェックしません
466 test_run('boolean','bug_2799','no_check_error_output');
467
468 // 複数のオプションを同時に指定
469 test_run([],[],['no_check_ref','mode_nw']);
470 // Console mode
471 test_run time [] no_check_ref //tests time module with no_check_ref option
472  ]]></programlisting>
473         <programlisting role="example"><![CDATA[
474 //  (パスで指定した)外部モジュールのユニットテストを実行
475 test_run('SCI/contrib/toolbox_skeleton')
476  ]]></programlisting>
477         <programlisting role="example"><![CDATA[
478 // XML Xunitファイルにエクスポート
479 test_run('boolean',[],[],TMPDIR+"/boolean_test_run.xml");
480 test_run('time','datenum',[],TMPDIR+"/time_datenum_test_run.xml");
481  ]]></programlisting>
482         <para>
483             <emphasis role="bold">Selections with wildcard *:</emphasis>
484         </para>
485         <programlisting role="example"><![CDATA[
486 test_run elementary_functions *space
487 test_run elementary_functions dec2*
488 test_run string *ascii*
489  ]]></programlisting>
490     <screen><![CDATA[
491 --> test_run elementary_functions *space
492    TMPDIR = C:\MyPath\AppData\Local\Temp\SCI_TMP_3668_1147
493
494    001/002 - [elementary_functions] logspace....................passed
495    002/002 - [elementary_functions] linspace....................passed
496    --------------------------------------------------------------------------
497    Summary
498 ../..
499
500 --> test_run elementary_functions dec2*
501    TMPDIR = C:\MyPath\AppData\Local\Temp\SCI_TMP_3668_1147
502
503    001/004 - [elementary_functions] dec2oct.....................passed
504    002/004 - [elementary_functions] dec2hex.....................passed
505    003/004 - [elementary_functions] dec2bin.....................passed
506    004/004 - [elementary_functions] dec2base....................passed
507    --------------------------------------------------------------------------
508    Summary
509 ../..
510
511 --> test_run string *ascii*
512    TMPDIR = C:\MyPath\AppData\Local\Temp\SCI_TMP_3668_1147
513
514    001/003 - [string] isascii...................................passed
515    002/003 - [string] asciimat..................................passed
516    003/003 - [string] ascii.....................................passed
517    --------------------------------------------------------------------------
518    Summary
519 ../..
520 ]]></screen>
521     </refsection>
522     <refsection>
523         <title>内部設計</title>
524         <para>
525             テストは,
526             テストファイルが置かれたディレクトリではなく,
527             テンポラリディレクトリで実行されます.
528             .tstファイルはテンポラリディレクトリにコピーされた後,
529             テストが実行され,.dia.ref が元の位置にコピーされます.
530         </para>
531         <para>
532             .tstスクリプトはそのまま実行されません.
533             かわりに,テンポラリディレクトリにコピーされる際に
534             ヘッダとフッタが.tstの先頭と終端に挿入されます.
535             この修正の理由は,出力メッセージを.diaファイルにリダイレクトし,
536             テストが実行された後に,ユーザがログファイルを取得できるように
537             するためです.
538         </para>
539         <para>
540             An execution timeout delay (watchdog timer) is setup to 5 minutes
541             for each regular test. To ignore this timeout use the long-time
542             execution (<literal>LONG TIME EXECUTION</literal>) flag.
543         </para>
544     </refsection>
545     <refsection role="see also">
546         <title>参照</title>
547         <simplelist type="inline">
548             <member>
549                 <link linkend="debug">debug</link>
550             </member>
551             <member>
552                 <link linkend="covStart">covStart</link>
553             </member>
554             <member>
555                 <link linkend="profile">profile</link>
556             </member>
557             <member>
558                 <link linkend="slint">slint</link>
559             </member>
560             <member>
561                 <ulink url="https://msdn.microsoft.com/en-us/library/windows/desktop/ms681382.aspx">
562                   List of MS Windows exit codes
563                 </ulink>
564             </member>
565         </simplelist>
566     </refsection>
567     <refsection>
568         <title>履歴</title>
569         <revhistory>
570             <revision>
571                 <revnumber>5.4.0</revnumber>
572                 <revdescription>test_runは以下のステータスを返します:
573                     <itemizedlist><listitem>
574                             エラーが検出されなかった場合に %t を返します
575                         </listitem>
576                         <listitem>
577                             エラーが検出された場合に %f を返します
578                         </listitem>
579                     </itemizedlist>
580                     <para>
581                         <literal>show_diff</literal> および <literal>show_error</literal> が
582                         新しいオプションとして追加されました
583                     </para>
584                     <para>
585                         <literal>CLI SHELL MODE</literal> タグが追加されました.
586                         <literal>JVM NOT MANDATORY</literal> (まだサポート中)を置き換えます
587                     </para>
588                     <para>
589                         <literal>test_run</literal> は外部モジュールでも動作します.
590                     </para>
591                     <para>
592                         XMLファイルにエクスポートする4番目の引数が追加されました
593                     </para>
594                 </revdescription>
595             </revision>
596             <revision>
597                 <revnumber>5.5.0</revnumber>
598                 <revdescription>32/64bits separation available</revdescription>
599             </revision>
600             <revision>
601                 <revnumber>6.0.0</revnumber>
602                 <revdescription>
603                     <para>profiling mode added to profile execution with valgrind (Linux only)</para>
604                     <para>
605                         timeout delay (watchdog timer) set to 5 minutes for single tests without <literal>LONG TIME EXECUTION</literal>
606                     </para>
607                 </revdescription>
608             </revision>
609             <revision>
610                 <revnumber>6.0.2</revnumber>
611                 <revdescription>
612                     <para>Tests names with the * wildcard like sin*, *sin, or *sin* are now allowed</para>
613                 </revdescription>
614             </revision>
615         </revhistory>
616     </refsection>
617 </refentry>