test_run テストを実行

## 呼び出し手順

                status = test_run()
                status = test_run(module)
                status = test_run(module, test_name)
                status = test_run(module, test_name, options, exportToFile)

## 引数

module

  文字列の配列. この入力引数には以下のどれかを指定します

  - Scilab内部モジュール名 ("core", "time", ...)またはサブモジュール名 (例: "optimization|neldermead").

  - ATOMSモジュールの名前("module_lycee", "nisp", ...). 処理を行うには,このモジュールはtest_run()をコールする前に ロードしておく必要があります. See `atomsGetLoaded()(:,1)` and atomsLoad(…).

  - absolute or relative path to the root directory of an external module containing test/unit_tests or test/nonreg_tests.

  - `[]` or `"[]"` to run tests of all internal Scilab modules.

test_name

  A string array or `[]` or `"[]"`: The names of the tests to execute during this run. If `test_name` is `[]`, all tests found in the module or in the directory are executed.

  The wildcard * can be used, like in `*sin`, `*sin`, or `*sin*`.

options

  文字列配列

  no_check_ref

    the .dia と .dia.ref が等しい場合, チェックを行いません

  no_check_error_output

    エラー出力ストリームはチェックされません. Scilabがローカライズされたものが利用できないとエラーを発生する 場合,このオプションを利用できます.

  create_ref

    .dia.refファイルを作成し, .dia と .dia.refが等しいかどうかをチェックしません. This option is applied only to chosen tests not having the `<-- NO CHECK REF -->` flag.

  show_error

    エラーが発生した場合直近の10行分の実行行を表示します

  show_diff

    差異がみつかった場合,`diff -u`コマンドの結果を 表示します.

  list

    テストを実行しませんが, 利用可能なテストの一覧を表示します

  help

    このコマンドの使用方法に関するいくつかの例を表示します

  mode_nw

    実行時に "-nw" オプションを追加します

  mode_nwni

    実行時に "-nwni"オプションを追加します

  mode_nwni_profiling

    Add the "-nwni -profiling" option to the launch for detect valgrind error (Linux only)

  nonreg_tests

    回帰的でないテストのみを実行し, ユニットテストをスキップします

  unit_tests

    ユニットテストのみを実行し,回帰的でないテストをスキップします

  skip_tests

    テストをスキップします

  enable_lt

    テストの長時間実行を許可します

  short_summary

    実行後に統計または実行時間を表示しません (実行回数,成功/失敗/スキップしたテストの回数のみを1行に表示します).

exportToFile

  テストの結果をXMLファイルにエクスポートします. このファイルはXUnit形式となります. このオプションの使用により, `show_diff` および `show_error` が有効となることに注意してください.

  `exportToFile`で指定したファイルが既に存在する場合, 新規結果は既存のファイルに追加されます.

status

  論理値で,エラーが検出されなかった場合に %t, エラーが検出された場合に %f を返します.

## 説明

ユニットテストおよび非回帰テストライブラリで .tstファイルを探して実行し,成功/失敗に関するレポートを表示します. .tst ファイルはディレクトリ SCI+"/modules/*/tests/unit_tests" およびSCI+"/modules/*/tests/nonreg_tests"で探されます. テストが実行される度に, .diaファイルが生成され, 実行された全コマンドとコンソールに表示されたメッセージのリストが 出力されます. スクリプトが実行された後, この.dia ファイルは, .tst ファイルと同じディレクトリに置かれた.dia.refファイルで と比較されます. 2つのファイルが異なる場合,そのテストは失敗となります.

テストの処理を制御できるように.tstファイルに特殊なタグを挿入できます. これらのタグはScilabコメントとして記述します.

以下に利用可能なタグを示します:

- <-- INTERACTIVE TEST --> このテストは対話的なものであるため,スキップされます.

- <-- LONG TIME EXECUTION --> このテストは長い時間を要するためスキップされます. このテストを有効にするには,以下のオプションを指定してtest_runを コールします: "enable_lt"

- <-- NOT FIXED --> このテストは,既知ではあるが,未修正のバグであるため,スキップされます.

- <-- TEST WITH GRAPHIC --> This test will be executed with scilab -nw. (default mode)

- <-- NO TRY CATCH -->

- <-- NO CHECK ERROR OUTPUT --> エラー出力ファイルはチェックされません

- <-- NO CHECK REF --> .dia および.dia.refファイルの比較が行われません.

- <-- ENGLISH IMPOSED --> このテストは-l en_USオプションを指定した場合のみ実行されます.

- <-- FRENCH IMPOSED --> このテストは-l fr_FRオプションを指定した場合のみ実行されます.

- <-- CLI SHELL MODE --> This test will be executed with scilab -nwni.

- <-- WINDOWS ONLY --> オペレーティング・システムがWindowsでない場合, このテストはスキップされます.

- <-- UNIX ONLY --> オペレーティング・システムがUnix OSでない場合, このテストはスキップされます.

- <-- LINUX ONLY --> オペレーティング・システムがGNU/Linuxでない場合, このテストはスキップされます.

- <-- MACOSX ONLY --> オペレーティング・システムがMac OS Xでない場合, このテストはスキップされます.

- <-- XCOS TEST --> このテストは全ての必要なXcosライブラリを実行します. このテストはnwモードで実行されます.

各テストは"host"コマンドで生成された別のプロセスで実行されます. これにより,テストにより不安定な環境となる場合でも, カレントのコマンドの実行を継続できます. また,テストは他のテストと独立して実行可能となります.

## プラットフォーム毎のテスト

テストの出力が実行されるプラットフォームに依存している場合があります. この場合,`.ref`を全てのプラットフォーム用で同じとならず, いくつかのプラットフォームではユニットテストが失敗する可能性があります. この場合, デフォルトの`.ref`と共に 各プラットフォーム用の`.ref`を作成することができます.

プラットフォーム毎の `.ref`には以下のような拡張子の どれかを付ける必要があります.

- `.unix.dia.ref`はUnixプラットフォーム用,

- `.linux.dia.ref`はGNU/Linuxプラットフォーム用,

- `.win.dia.ref`はWindowsプラットフォーム用,

- `.macosx.dia.ref`はMac OS Xプラットフォーム用.

アルゴリズムは以下のようになります. まず, `.ref` が探されます. このファイルが存在しない場合, 現在のプラットフォームに応じた以下の プラットフォーム毎の`.ref`ファイルが実行されます.

- Windowsプラットフォームの場合: `.win.dia.ref`,

- Max OS X プラットフォームの場合: `.unix.dia.ref`, `.macosx.dia.ref`,

- GNU/Linuxプラットフォームの場合: `.unix.dia.ref`, `.linux.dia.ref`.

## 例

    // 全てのテストを実行
    // =============================================
    // test_run();
    // test_run([]);
    // test_run([],[]);
    // test_run("[]","[]");
    // test_run [] [];

    // 1つまたは複数のモジュールをテスト
    // =============================================
    // 1つのモジュールをテスト
    test_run('time');

    // 複数のモジュールをテスト
    test_run(['time','string']);

    // サブモジュールをテスト
    test_run('optimization|neldermead');

    // パスで指定したモジュールを参照
    test_run(SCI+'/modules/core');

    // 指定したテストを実行
    // =============================================
    // テストを1つ指定
    test_run('time','datenum');

    // 複数のテストを指定
    test_run('time',['datenum';'calendar']);

    // いくつかのテストをスキップ
    // =============================================
    test_run('time',['datenum';'calendar'],'skip_tests');

    // オプション
    // =============================================
    // .dia と .dia.ref が等しいかどうかをチェックしません
    test_run('time','datenum','no_check_ref');

    // .dia.refファイルを作成しますが,.diaと.dia.refが等しいかどうかをチェックしません
    test_run([],[],'create_ref');

    // テストを実行しないが,利用可能なテストの一覧を表示します
    test_run([],[],'list');

    // このコマンドの使用法に関するいくつかの例を表示します
    test_run([],[],'help');

    // 非回帰テストのみを実行し,ユニットテストをスキップします
    test_run([],[],'nonreg_test');

    // ユニットテストのみを実行し,非回帰テストをスキップします
    test_run([],[],'unit_test');

    // エラー出力 (std err)をチェックしません
    test_run('boolean','bug_2799','no_check_error_output');

    // 複数のオプションを同時に指定
    test_run([],[],['no_check_ref','mode_nw']);
    // Console mode
    test_run time [] no_check_ref //tests time module with no_check_ref option

    //  (パスで指定した)外部モジュールのユニットテストを実行
    test_run('SCI/contrib/toolbox_skeleton')

    // XML Xunitファイルにエクスポート
    test_run('boolean',[],[],TMPDIR+"/boolean_test_run.xml");
    test_run('time','datenum',[],TMPDIR+"/time_datenum_test_run.xml");

Selections with wildcard *:

    test_run elementary_functions *space
    test_run elementary_functions dec2*
    test_run string *ascii*

    --> test_run elementary_functions *space
       TMPDIR = C:\MyPath\AppData\Local\Temp\SCI_TMP_3668_1147

       001/002 - [elementary_functions] logspace....................passed
       002/002 - [elementary_functions] linspace....................passed
       --------------------------------------------------------------------------
       Summary
    ../..

    --> test_run elementary_functions dec2*
       TMPDIR = C:\MyPath\AppData\Local\Temp\SCI_TMP_3668_1147

       001/004 - [elementary_functions] dec2oct.....................passed
       002/004 - [elementary_functions] dec2hex.....................passed
       003/004 - [elementary_functions] dec2bin.....................passed
       004/004 - [elementary_functions] dec2base....................passed
       --------------------------------------------------------------------------
       Summary
    ../..

    --> test_run string *ascii*
       TMPDIR = C:\MyPath\AppData\Local\Temp\SCI_TMP_3668_1147

       001/003 - [string] isascii...................................passed
       002/003 - [string] asciimat..................................passed
       003/003 - [string] ascii.....................................passed
       --------------------------------------------------------------------------
       Summary
    ../..

## 内部設計

テストは, テストファイルが置かれたディレクトリではなく, テンポラリディレクトリで実行されます. .tstファイルはテンポラリディレクトリにコピーされた後, テストが実行され,.dia.ref が元の位置にコピーされます.

.tstスクリプトはそのまま実行されません. かわりに,テンポラリディレクトリにコピーされる際に ヘッダとフッタが.tstの先頭と終端に挿入されます. この修正の理由は,出力メッセージを.diaファイルにリダイレクトし, テストが実行された後に,ユーザがログファイルを取得できるように するためです.

An execution timeout delay (watchdog timer) is setup to 5 minutes for each regular test. To ignore this timeout use the long-time execution (`LONG TIME EXECUTION`) flag.

## 参照

- atomsTest
- debug
- covStart
- profile
- slint
- List of MS Windows exit codes

## 履歴

5.4.0 test_runは以下のステータスを返します:

- エラーが検出されなかった場合に %t を返します
- エラーが検出された場合に %f を返します

`show_diff` および `show_error` が 新しいオプションとして追加されました

`CLI SHELL MODE` タグが追加されました. `JVM NOT MANDATORY` (まだサポート中)を置き換えます

`test_run` は外部モジュールでも動作します.

XMLファイルにエクスポートする4番目の引数が追加されました

5.5.0 32/64bits separation available
6.0.0

profiling mode added to profile execution with valgrind (Linux only)

timeout delay (watchdog timer) set to 5 minutes for single tests without `LONG TIME EXECUTION`

6.0.2

Tests names with the * wildcard like sin*, *sin, or *sin* are now allowed

2023.0.0

Tag `JVM NOT MANDATORY` removed.