これは、このセクションの複数ページの印刷可能なビューです。 印刷するには、ここをクリックしてください.

このページの通常のビューに戻る.

設定構文

テストを実行するには、プロジェクト内に artefacts.yaml ファイルが必要です。

設定ガイド

1 - The artefacts.yaml File

テストを実行するには、プロジェクトのルートに 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)を介して実行されます)

2 - ROS1プロジェクト向け非推奨設定

デフォルトでは、ファイル名は artefacts.yaml であることが想定されています。

設定

version オプション アーティファクトYAML形式の仕様バージョン。

project 関連プロジェクトの名前。結果の追跡と認証に使用されます。

jobs ジョブ名と Job 定義のマッピング、Jobを参照。

ジョブ

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

type デフォルトは test

timeout オプション ジョブが timed out とマークされるまでの時間。

runtime ランタイムプロパティを含む、 Runtimeを参照。

scenarios1つのジョブに複数のシナリオを含めることができます。通常、特定の環境にリンクされたテストスイートです。 Scenario definitionを参照。

シナリオ定義

defaults すべてのシナリオに共通するデフォルト設定を含みます。シナリオによって上書きされない限り適用されます。

scenarios Scenarioのリストを含みます。 Scenarioを参照。

パッケージ

Artefacts Cloud Simulationのみ

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

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

ランタイム

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

frameworkソフトウェアフレームワーク。サポートされる値： ros1:noetic、 ros2:humble、 ros2:galactic、 null

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

注意: 多くの場合、ローカルで実行する際にはアーティファクトCLIは上記にリストされていないフレームワーク/シミュレータとも互換性がありますが、アーティファクトクラウドシミュレーションで実行する場合は、package ブロックとcustom commandsのセット、または、dockerfileを提供する必要があります。

pre_launch オプション (現在は framework: ros1:noeticでのみ実装) 各テストを起動する前に実行されるbashコマンド。シミュレータとテストが起動される前に完了する必要があるセットアップを実行するために使用します。注意：スクリプトへの絶対パスが必要な場合、環境変数 USER_REPO_PATH がリポジトリのルートを指します。 pre_launch コマンドの例： source $USER_REPO_PATH/simulator/scripts/sim_setup.bash

params: オプション (現在は framework: ros1:noeticでのみ実装) .yaml file (/tmp/runtime_params.yaml)にダンプされるパラメータのリスト。実行時に、このファイルはユーザースクリプト(pre_launch`キーで指定されたものなど)で読み取ることができます。使用例：シミュレータセットアップスクリプトのパラメータ化。

シナリオ

name シナリオの名前

output_dirs オプション ArtefactsクライアントがDashboardにアップロードするアーティファクトを探すパスのリスト。 サポートされる形式には.htmlファイル ( plotly で作成可能で、インタラクティブな図として表示されます) と動画（クロスプラットフォーム互換性のためにh264/mp4を推奨）が含まれます。

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

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

  • ROS1フレームワークでは、パラメータ名はフォワードスラッシュで区切られた文字列 (例 test/nested_ns/param1)である必要があります。各フォワードスラッシュはネストされた名前空間に対応します。これらはyamlファイル
  • (/tmp/scenario_params.yaml) にダンプされ、テスト中に実行時にROS1 rosparamサーバーにロードされます。ノードの動作を制御するために使用できます。
  • ROS2フレームワークでは、パラメータ名は node_name/parameter_name (単一のフォワードスラッシュで区切られた)規則に従う必要があります。これらはyamlファイル (/tmp/scenario_params.yaml) にフォーマットされ、テスト中に実行時にロードされます (参照)。ノードの動作を制御するために使用できます。
  • 「その他」のフレームワークでは、パラメータ名は.yamlファイル (/tmp/scenario_params.yaml)にダンプされ、.jsonファイル (/tmp/scenario_params.json) 、環境変数として設定されます（パラメータ名が文字、数字、アンダースコアのみであることを確認してください）。

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

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

  • framework: ros1:noetic の場合:

ros_testpackage テストファイルを含むROSパッケージの名前。 (ROS2ではまだ実装されていません)

ros_testfile ROS1の場合： ros_testpackage/launch 内にあるXML起動ファイルの名前。ユーザーテックスタック（任意のROSノードのコレクション）+テストのロジックを含むテストノードを指定します (rostest 互換)。 .launch または .testである必要があります。

rosbag_postprocess オプション、現在ROS1でのみ実装 ros_testpackage/src 内にあるスクリプトの名前。テスト終了後に実行される追加の計算を指定します。拡張子は通常.pyです。このスクリプトは2つの引数を取る必要があります： --bag_path（テスト中に作成されたrosbag）と --out_folder（スクリプトによって作成されたすべての出力を保存するパス）。その後、Artefactはこのフォルダ内のすべてのファイルをDashboardにアップロードします。サポートされるファイル形式は output_dirs と同じです。さらに、rosbag_postprocessスクリプトが metrics.json ファイルをキー/値のペアで出力する場合、それらもDashboardでテーブルとしてレンダリングされます。

subscriptions オプション、現在ROS1でのみ実装 関心のあるROSトピックをマッピングするキー/値のペア。現在のところ、 rosbag_record: subscriptions を指定する際にのみ使用されます。

rosbag_record オプション、現在ROS1でのみ実装 デフォルトは noneです。 none の場合、rosbag記録はオフになります。 allの場合、すべてのROSトピックが記録されます。 subscriptions の場合、上記の subscriptions キー/値ペアで定義された関心のあるトピックのみが記録されます。文字列のリストが渡された場合、記録するトピックのリストとして解釈され 正規表現がサポートされています。

  • framework: nullの場合:

run テストを開始するために使用されるコマンド文字列 ( subprocess.run(command, shell=True)経由で実行されます)