The artefacts.yaml File

Tags:

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

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

設定例

以下はnav2サンプルリポジトリから取得した artefacts.yaml設定ファイルの例です。この設定では、それぞれbasic と nav2 という名前の2つのジョブがあります。

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

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
          ros_testfile: "src/sam_bot_nav2_gz/test/test_bringup.launch.py"

  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
          ros_testfile: "src/sam_bot_nav2_gz/test/test_reach_goal.launch.py"
        - name: follow_waypoints
          ros_testfile: "src/sam_bot_nav2_gz/test/test_follow_waypoints.launch.py"

簡単に要約すると：

最初のジョブ 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を参照

ジョブ

jobs:

  <job_name>:
    type: test
    package:
       ...
    runtime:
       ...
    timeout: 5 #minutes
    scenarios:
       ...

各ジョブには以下のプロパティがあります：

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

パッケージ

  • custom 任意のプロジェクトのデフォルトビルドフローをカスタマイズするために使用できます。詳細は Packaging for Cloud Simulation を参照してください

  • docker テスト環境の構築時に artefacts が使用する Dockerfile を提供するために使用できます。詳細は Packaging with Docker を参照してください

ランタイム

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

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

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

シナリオ定義

ページ上部の例を参照すると：

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
        ros_testfile: "src/sam_bot_nav2_gz/test/test_reach_goal.launch.py"
    - name: follow_waypoints
        ros_testfile: "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 を参照してください

シナリオ

  • name シナリオの名前

  • output_dirs オプション Artefacts クライアントがダッシュボードにアップロードするアーティファクトを探すパスのリスト。サポートされるタイプには .html ファイル ( plotly で作成でき、インタラクティブな図として表示されます）やビデオ（クロスプラットフォーム互換性のために 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’ フレームワークの場合、パラメータ名は環境変数として設定されます（パラメータ名が文字、数字、アンダースコアのみであることを確認してください）。

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

フレームワーク固有のシナリオプロパティ

framework: ros2:* の場合:

  • ros_testfile ROS2 の場合： launch_test ファイルへのパス、通常は .py ファイル

framework: null (実験的)の場合：

  • run テストを開始するために使用されるコマンド文字列 (subprocess.run(command, shell=True)を介して実行されます)
最終更新 09.10.2025: Toolkit config updates (#50) (3138ef8)