[English Version](./README.md)

テストの実行方法
-----------------

[ctest][ctest]を使います。
FrontISTRプロジェクト自体を[cmake][cmake]で次の様にビルドしたと想定します

```
git clone https://gitlab.com/FrontISTR-Commons/FrontISTR
cd FrontISTR   # このディレクトリの事を以降 FRONTISTR_HOME と呼びます
cmake . -Bbuild
cmake --build build/ -j $(nproc)
```

これで `${FRONTISTR_HOME}/build` 以下に `fistr1` 等の実行バイナリが生成されています。
この状態で

```
cd build/
ctest
```

これで全てのテストが実行されます。

### テストのラベル

テストはラベルによって管理されていて、並列化について以下のラベルが存在します

| label | OpenMP | MPI |
|:------|:------:|:---:|
|serial | OFF    | OFF |
|openmp | ON     | OFF |
|mpi    | OFF    | ON  |
|hybrid | ON     | ON  |

これらのラベルが付いたテストだけを実行するには例えば

```
ctest -L mpi
```

の様に `-L` (`--label-regex`) を付けて実行します。

テストには並列化に関するものの他に以下に説明するように `target` によるものがあります。
テストは下記の節で説明されているように [cmake][cmake] によって自動的に追加されますが、
例えば `${FRONTISTR_HOME}/tests/analysis/eigen/exK/` ディレクトリにあるテストには
`${FRONTISTR_HOME}/tests/` からの相対パスをそのまま文字列として用いて `analysis/eigen/exK` というラベルを付けます
このディレクトリにあるテストだけを実行するには次の様にします

```
ctest -L analysis/eigen/exK
```

また `-L` は部分マッチで選択出きるので、

```
ctest -L analysis
```

とすれば `${FRONTISTR_HOME}/tests/analysis` 以下の全てのテストを実行します。
　
### 出力の調整

`ctest` の一般的な使い方として、

```
ctest -V
```

は全ての出力を表示、

```
ctest --output-on-failure
```

は失敗したテストの結果のみ出力を表示します。詳しくは `ctest -h` を確認してください。
　
テストの追加方法
-----------------

テストは [cmake][cmake] が `${FRONTISTR_HOME}/tests/` ディレクトリ以下にあるメッシュデータ(`*.msh`)を自動的に走査して、
発見したものを自動的に登録します。
このテストは信頼できるリファレンスと現在のソースコードに基づく `fistr1` での計算結果を比較して、
それが十分に小さいかどうかを判定します。

したがって、テストを新たに追加するには

1. `${FRONTISTR_HOME}/tests` 以下に新たにディレクトリを追加し
2. `*.msh` ファイル、`*.cnt` ファイルを追加し
3. `${FRONTISTR_HOME}/tests/create_reference.sh` でリファレンスデータを生成し
4. 計算結果が妥当かどうかを手動で確認する

というプロセスを経ます。

`create_reference.sh` の実行には`${FRONTISTR_HOME}/build/fistr/fistr1`をデフォルトで利用しますので事前にビルドが必要です。
`create_reference_docker.sh` の実行にはFrontISTRの公式リリースのコンテナイメージを用いるので
[Docker][docker] の実行権限が必要です。


[cmake]: https://cmake.org/cmake/help/latest/manual/cmake.1.html
[ctest]: https://cmake.org/cmake/help/latest/manual/ctest.1.html
[docker]: https://www.docker.com/

[Japanese Version](./README.ja.md)

Run test
---------

Use [ctest][ctest].
We assume here that FrontISTR project is built by [cmake][cmake]:

```
git clone https://gitlab.com/FrontISTR-Commons/FrontISTR
cd FrontISTR   # we call here as FRONTISTR_HOME
cmake . -Bbuild
cmake --build build/ -j $(nproc)
```

Then `fistr1` and other executables are built in `${FRONTISTR_HOME}/build`.
You can run test on this directory:

```
cd build/
ctest
```

### Labels of tests

Tests are managed by ctest's label. There are 4 labels about parallelization:

| label | OpenMP | MPI |
|:------|:------:|:---:|
|serial | OFF    | OFF |
|openmp | ON     | OFF |
|mpi    | OFF    | ON  |
|hybrid | ON     | ON  |

To execute labeled tests, please run [ctest][ctest] with `-L` (`--label-regex`) flag:

```
ctest -L mpi
```

In addition to these parallelization labels, there are labels for "target".
As described below, [cmake][cmake] seeks tests in this directory,
and put a label `analysis/eigen/exK` to tests for `${FRONTISTR_HOME}/tests/analysis/eigen/exK` for example.
To run tests on this directory, please use this label:

```
ctest -L analysis/eigen/exK
```

Because `-L` flag can select by partial match,

```
ctest -L analysis
```

will executes all tests in `${FRONTISTR_HOME}/tests/analysis`

### Configure test output

As a general technique of [ctest][ctest],

```
ctest -V
```

displays all output of test processes, and

```
ctest --output-on-failure
```

displays the output of failed tests. See `ctest -h` for detail.

Add test
---------

[cmake][cmake] seeks mesh data (`*.msh`) from `${FRONTISTR_HOME}/tests/`, and then registers it as a test target.
This target compares the result of `fistr1` of current build with reference build,
and tests the difference is enough small.
In order to append a new test, you should

1. Create a directory under `${FRONTISTR_HOME}/tests`
2. Put `*.msh` and `*.cnt` files
3. Generate reference result by `${FRONTISTR_HOME}/tests/create_reference.sh`
4. and Confirm this result is correct by your eye

Be sure that because `create_reference.sh` uses executable binary `${FRONTISTR_HOME}/build/fistr/fistr1` by default, you have to build it in advance.
Be sure that because `create_reference_docker.sh` uses official release image, you need the authority for execution of [Docker][docker].

[cmake]: https://cmake.org/cmake/help/latest/manual/cmake.1.html
[ctest]: https://cmake.org/cmake/help/latest/manual/ctest.1.html
[docker]: https://www.docker.com/