# The artefacts.yaml File

Site [llms.txt](/ja/llms.txt)

---

テストを実行するには、プロジェクトのルートに `artefacts.yaml` ファイルを設定する必要があります。このファイルでの設定により、artefacts は以下のことが可能になります：

* 対応する組織とプロジェクトを artefacts ダッシュボードに接続する
* 特定のジョブに関する詳細を提供する：
    * ジョブ名
    * プロジェクトのビルド方法 ( `run --in-container` または `run-remote`を使用する場合)
    * ジョブの実行に必要なフレームワークとシミュレーター
    * 収集するメトリクス
    * 使用するパラメータ
    * 使用する起動ファイル

## 設定例

以下は[nav2サンプルリポジトリ](https://github.com/art-e-fact/navigation2_ignition_gazebo_example)から取得した `artefacts.yaml`設定ファイルの例です。この設定では、それぞれ`basic` と `nav2` という名前の2つのジョブがあります。

各セクションについては、このページで詳しく説明します。

```yaml
version: 0.1.0

project: artefacts/navigation2-ignition-example

jobs:

  basic: # Only checks that things are loading
    type: test
    package:
      docker:
        build:
          dockerfile: ./Dockerfile
    runtime:
      simulator: gazebo:fortress
      framework: ros2:humble
    timeout: 5 #minutes
    scenarios:
      defaults: # Global to all scenarios, and overriden in specific scenarios.
        output_dirs: ["output"]
      settings:
        - name: bringup
          pytest_file: "src/sam_bot_nav2_gz/test/test_bringup.py" # when using pytest or ros2 launch_pytest

  nav2:
    type: test
    package:
      docker:
        build:
          dockerfile: ./Dockerfile
    runtime:
      simulator: gazebo:fortress
      framework: ros2:humble
    timeout: 5 #minutes
    scenarios:
      defaults: # Global to all scenarios, and overriden in specific scenarios.
        output_dirs: ["output"]
        metrics:
          - /odometry_error
          - /distance_from_start_gt
          - /distance_from_start_est
        params:
          launch/world: ["bookstore.sdf", "empty.sdf"]
      settings:
        - name: reach_goal
          pytest_file: "src/sam_bot_nav2_gz/test/test_reach_goal.py" # when using pytest or ros2 launch_pytest
        - name: follow_waypoints
          launch_test_file: "src/sam_bot_nav2_gz/test/test_follow_waypoints.launch.py" # when using ros2 launch_test
```

簡単に要約すると：

最初のジョブ `basic`:

* プロジェクトリポジトリのルートにある `Dockerfile` という名前の Dockerfile を使用してビルドされます
* ros2 humble 上で実行され、シミュレーターとして gazebo (ignition) fortress を使用します
* テストが5分以内に完了しない場合、タイムアウトします
* テスト完了後、 `output` ディレクトリ内のすべてのものを Artefacts ダッシュボードにアップロードします
* `test_bringup.launch.py` 起動ファイルを使用して1つのテスト（「シナリオ」）を実行します

2番目のジョブ  `nav2`:

* プロジェクトリポジトリのルートにある `Dockerfile` という名前の Dockerfile を使用してビルドされます
* ros2 humble 上で実行され、シミュレーターとして gazebo (ignition) fortress を使用します
* テストが5分以内に完了しない場合、タイムアウトします
* テスト完了後、 `output` ディレクトリ内のすべてのものを Artefacts ダッシュボードにアップロードします
* リストされた3つの `metrics` を Artefacts ダッシュボードに表示します
* 2つのパラメータ（2つの異なるワールドファイル）があり、この場合は ros の `launch_arguments` として使用されます
* 2つのシナリオで合計 **4** つのテストを実行します： `reach_goal` は `test_reach_goal` 起動ファイルを使用して2回 ( `params`にリストされている各ワールドに1回ずつ)実行され, `follow_waypoints` は `test_follow_waypoints` 起動ファイルを使用して2回（再び各ワールドに1回ずつ）実行されます

## 設定の詳細

* `version` *オプション* artefacts yaml フォーマット仕様のバージョン
* `project` 関連プロジェクトの名前。  `<organization>/<project>`  の形式である必要があります
* `jobs` ジョブ名から `Job` 定義へのマッピング、 [Job](#job)を参照

### ジョブ

```yaml
jobs:

  <job_name>:
    type: test
    package:
       ...
    runtime:
       ...
    timeout: 5 #minutes
    scenarios:
       ...
```
各ジョブには以下のプロパティがあります：

* ジョブの名前 
* `type` デフォルトは `test`
* `package` *オプション* コンテナ内で実行する場合 (`run --in-container` または `run-remote`)のジョブのビルド方法を設定する際に使用します。 [Package](#package)を参照
* `runtime` ランタイムプロパティ（フレームワークとシミュレーター）を含みます。 [Runtime](#runtime)を参照
* `timeout` *オプション* ジョブが `timed out`とマークされるまでの時間
* `scenarios` 1つのジョブは複数のシナリオを含むことができ、通常は特定の環境にリンクされたテストスイートです。 [Scenario definition](#scenarios-definition)を参照

### パッケージ

> [!NB] _Artefacts Cloud Simulation で実行する場合に使用されます_

* `custom` 任意のプロジェクトのデフォルトビルドフローをカスタマイズするために使用できます。詳細は [Packaging for Cloud Simulation](user-guide/cloud-simulation.md#packaging-for-cloud-simulation) を参照してください

* `docker` テスト環境の構築時に artefacts が使用する Dockerfile を提供するために使用できます。詳細は [Packaging with Docker](user-guide/docker-package.md) を参照してください

### ランタイム

テスト環境の準備とフックに使用されます

* `framework` ソフトウェアフレームワーク。サポートされる値： `ros2:humble`, `ros2:galactic`, `ros2:jazzy`, `null` (実験的)

* `simulator` シミュレーションエンジン。サポートされる値： `turtlesim`, `gazebo:fortress`, `gazebo:harmonic`

> [!NOTE]
> 多くの場合、artefacts CLI はローカルで実行する際に上記にリストされていないフレームワーク/シミュレーターとも互換性があります。ただし、artefacts クラウドシミュレーションで実行する場合は、 `package` ブロックと、 [カスタムコマンド](user-guide/cloud-simulation.md#customizing-packaging-for-cloud-simulation), または [dockerfile](user-guide/docker-package.md#specifying-a-dockerfile-or-docker-image)のいずれかを提供する必要があります。

### シナリオ定義

ページ上部の例を参照すると：
```yaml
scenarios:
  defaults: # Global to all scenarios, and overriden in specific scenarios.
    output_dirs: ["output"]
    metrics:
      - /odometry_error
      - /distance_from_start_gt
      - /distance_from_start_est
    params:
      launch/world: ["bookstore.sdf", "empty.sdf"]
  settings:
    - name: reach_goal
        pytest_file: "src/sam_bot_nav2_gz/test/test_reach_goal.py"
    - name: follow_waypoints
        launch_test_file: "src/sam_bot_nav2_gz/test/test_follow_waypoints.launch.py"
```
* `defaults` すべてのシナリオに共通するデフォルト設定を含み、シナリオで `settings`が上書きされない限り適用されます。例では `output_dirs`, `metrics`, および `params` 設定が両方のシナリオ `reach_goal` と `follow_waypoints` で共有されます

* `settings`  `scenario` のリストを含み、 `defaults` からの設定が上書きされます。利用可能な設定については下記の [Scenario](#scenario) を参照してください

#### シナリオ

* `name` シナリオの名前

* `pytest_file` / `launch_test_file` / `run` のいずれか

    * `pytest_file` (`pytest` または ROS2 `launch_pytest` テストフレームワークを使用する場合): テストファイルへのパス。
    * `launch_test_file` (ROS2 `launch_test` テストフレームワークを使用する場合): テストファイルへのパス (通常は xxx.launch.py)
    * `run` テストを開始するためのコマンド文字列 (`subprocess.run(command, shell=True)` で実行されます)。通常はパワーユーザー向けです。

> [!NOTE]
> `run` を使用する場合、可能な限りテスト結果を `output_dirs` に保存された `tests_junit.xml` という名前の JUnit XML ファイルに出力してください。そうしないと、ダッシュボードが最終的なテスト結果のステータス (`pass` / `fail` / `error`) を正しく表示できません。

* `output_dirs` *オプション* Artefacts クライアントがダッシュボードにアップロードするアーティファクトを探すパスのリスト。サポートされるタイプには .html ファイル ( [plotly](https://plotly.com/python/interactive-html-export/) で作成でき、インタラクティブな図として表示されます）やビデオ（クロスプラットフォーム互換性のために h264/mp4 を推奨します）が含まれます。

* `launch_arguments` *オプション* ROS のみ。起動ファイルに渡す引数の `name: value` ペアの辞書。通常、ヘッドレスで実行するかどうか、rosbag を記録するかどうかなど、実行動作を設定するために使用されます。

* `params` シナリオに設定するパラメータのリスト。各パラメータに対して値のリストまたは単一の値を指定できます。パラメータの組み合わせごとにシナリオのバリエーションが自動的に実行されます（グリッド戦略）。すべてのテスト結果は同じダッシュボードエントリにアップロードされます。

    * ROS2 フレームワークの場合、パラメータ名は `node_name/parameter_name` 単一のフォワードスラッシュで区切られた）の規則に従う必要があり、環境変数`ARTEFACTS_SCENARIO_PARAMS_FILE`を通じて利用可能であるとともに、artefacts ツールキットからアクセスできます。これらはノードの動作を制御するために使用できます。ドット記法を使用したネストされたパラメータがサポートされています (例： `node_name/parameter_name.subparameter_name`).

    * (実験的に) 'null' フレームワークの場合、パラメータ名は環境変数として設定されます（パラメータ名が文字、数字、アンダースコアのみであることを確認してください）。

> [!NOTE]
> また、 `params` セクションで ros 起動引数をリストすることもできます。その場合、 `<node_name>` を `launch` に置き換え、artefactsツールキットの[`get_artefacts_param`](/artefacts-toolkit/config/#get_artefacts_param) ヘルパー関数を介してアクセスします。


* `metrics` *オプション*  テストメトリクスを指定します。json ファイルを受け入れます：キーと値のペアはメトリック名/メトリック値として使用されます。ROS プロジェクトは代わりにトピックのリストを受け入れることもでき、実行中のトピックの最新の値が記録値になります。