hsb-test

HSB QA テストランナー

ユーザーが HSB ボードと開発キットに対して QA テスト計画を実行したい場合に、このスキルを使用します。このスキルはテスト文書（ローカルファイルまたはウェブリンク）を読み込み、ユーザー固有のハードウェア構成で自動実行できるテストに絞り込んだうえで、各テストを実行して合否を評価し、包括的な結果レポートを作成します。

このスキルは、開発キットのセットアップ（SSH、デモコンテナのビルド、ホストの設定、ボードの接続）が完了していることを前提としています。セットアップが完了していない場合は、まず /hsb-setup を実行するかどうかをユーザーに確認します。

このワークフローでは、デモコンテナ内でテストアプリケーションを実行します。ユーザーが明示的に実行を指示した場合に限り、実行してください。

開始前 — 必須の確認事項（この順に実行）

確認事項 1 — 環境変数を読み取ります。 ほかのことを行う前に、次の変数を確認し、解決された値をユーザーに表示します。

SSH_TARGET      Remote devkit login (e.g. [email protected]). Ask the user if not set.
REMOTE_ROOT     Remote working directory (e.g. /home/nvidia). Ask the user if not set.
REMOTE_SUDO     sudo / sudo -n / "" — default to "sudo" if not set.
REMOTE_SSH_OPTS Additional SSH options (optional).
HSB_PLATFORM    Platform hint (optional).

SSH_TARGET と REMOTE_ROOT は必須です。いずれかが設定されていない場合は停止し、ユーザーに値を確認してください。

確認事項 2 — フェーズ計画を提示し、テスト文書を確認して、承認を得ます。 次の操作を行う前に：

1. フェーズ計画を表示します。

HSB Test — Phase Plan
  Phase 0: Verify devkit SSH, board ping, and demo container availability
  Phase 1: Obtain test document, confirm setup, build executable test plan
  Phase 2: Execute tests, record pass/fail, analyze failures
  Phase 3: Produce test results report (with option to save)
  Phase 4: Clean up test artifacts

2. ユーザーがテスト文書のパスまたは URL を提示していない場合は、停止して提示を求めてください。ユーザーが提示するまで、Phase 0 もその他のフェーズも開始しないでください：Please provide the path or URL to your test document:。ユーザーがすでに特定のテスト（例：「接続確認のみ」）を指定している場合は、実行するフェーズとスキップするフェーズを伝え、テストをユーザーのプラットフォーム／ボード／センサー構成に合わせて絞り込み、自動実行可能か手動かに分類することを説明します。

3. 明示的に Shall I proceed with Phase 0? [Y/n] と尋ねます。ユーザーが確認するまで Phase 0 を開始しないでください。

このスキルで必ず行うこと

1. 開発キットに SSH で接続できること、HSB ボードが接続され応答すること、デモコンテナが利用可能であることを確認します。現在の FPGA バージョンとボードの識別情報を読み取ります。すでに設定済みの環境変数を使うか、ユーザーに確認して、センサー／カメラの種類、HSB 開発キット、および使用するリリースリポジトリを確認します。セットアップが完了していない場合は、開発キットを準備するために /hsb-setup を実行するかどうかをユーザーに確認します。
2. ユーザーからテスト計画文書（ファイルパスまたは URL）を受け取ります。Phase 0 で収集したユーザーのセットアップ情報（リポジトリの場所、HSB バージョン、プラットフォーム、ボードの種類、センサー）を確認します。テスト計画とリポジトリの examples/ ディレクトリを調べ、自動実行できるテストを判断します。手動テストと追加機材が必要なテストはスキップします。実行可能なテスト計画を提示し、ユーザーの承認を得ます。
3. 各テストケースを順番に実行します。テストごとに、アプリケーションを実行し、テスト計画の基準に照らして合否を評価し、結果を記録します。失敗した場合はログを分析し、修正方法を提案したうえで、次のテストを実行する前にユーザーの判断を確認します。
4. テストごとの合否、発生した問題、適用した修正を含む、構造化されたテスト結果レポートを作成します。レポートの保存を提案します。
5. テスト成果物（コンテナ、一時ファイル、セッション状態）をすべてクリーンアップします。

Linux／Windows 対応のラッパー変数

ほかの HSB スキルと同じ環境変数を使用します。

• SSH_TARGET：リモートログイン先（例：nvidia@agx-thor-host）
• REMOTE_ROOT：リモートの作業ディレクトリ
• REMOTE_SUDO：特権コマンド
• REMOTE_SSH_OPTS：追加の SSH オプション
• HSB_PLATFORM：任意のプラットフォームヒント

これらが設定されている場合は、ユーザーに設定値を通知し、再確認せずに使用してください。

Phase 0 の前に、解決されたリモート実行設定を表示します。

必須の対話パターン

セッションでの初回実行（事前の検証なし）

有効なセッション状態が存在しない場合は、フェーズ計画全体を表示します。

• Phase 0：ボードへの接続、デモコンテナの準備状況、ユーザー設定（リリースリポジトリ、プラットフォーム、センサー／カメラ）を確認します
• Phase 1：テスト計画を取得し、設定を確認して、実行可能なテストリストを作成します
• Phase 2：テストごとに合否を評価しながら、テスト計画を実行します
• Phase 3：テスト結果レポートを生成します（保存するオプションあり）
• Phase 4：クリーンアップします

その後、フェーズを1つずつ実行します。

同一セッションでの2回目以降の実行（高速パス）

セッション状態ファイル（/tmp/.claude_hsb_test_session/state.sh）が存在し、かつ _SESSION_VERIFIED=true を含む場合、このスキルは接続、ハードウェア、リリースリポジトリ、プラットフォーム、センサー／カメラがすでに検証済みであるため、Phase 0 と Phase 1 の設定確認をスキップします。代わりに、ユーザーにその旨を伝え、テスト計画の確認に直接進みます。

Session already verified — skipping connectivity checks.
  SSH target: $SSH_TARGET
  Release repo: /home/work/holoscan-sensor-bridge (HSB vX.X.X)
  Platform: AGX Thor
  Board: HSB Lattice | FPGA: XXXX
  Sensors: Dual IMX274

Proceeding directly to test plan intake.

その後、以下を実行します。

• Phase 1（テスト計画の確認とテストリストの作成 — 設定確認はスキップします）
• Phase 2：テスト計画を実行します
• Phase 3：テスト結果レポートを作成します
• Phase 4：クリーンアップします

Phase 0 を最初から再実行する場合

次の場合は高速パスを無視して、Phase 0 を再実行する必要があります。

1. 新しいセッション：リモートホストにセッション状態ファイルが存在しない場合、または新しい Claude Code セッションが開始された場合。
2. 接続の喪失を示唆する実行失敗：Phase 2 が、ボードまたは開発キットに到達できないことを示す症状（ping の失敗、SSH のタイムアウト、コンテナの起動失敗、No such device エラー）を伴って失敗した場合は、セッション状態から _SESSION_VERIFIED を削除し、再試行する前に Phase 0 を再実行します。
3. ユーザーから明示的な要求があった場合：ユーザーが「再検証」「最初からやり直す」「最初から実行」と指示した場合、または /hsb-test --full を実行した場合は、Phase 0 を最初から実行します。

確認プロトコルの詳細については、以下の## フェーズゲートを参照してください。

何かが失敗した場合、生のログをそのまま出力するだけにしないでください。以下を要約します。

• 失敗したコマンドの正確な内容
• 考えられる根本原因
• 推奨する安全な対処方法
• 問題が進行を妨げるかどうか

フェーズの詳細

フェーズごとの手順については、references/phase-details.mdを参照してください。

実行ルール

SSH heredoc パターン

他の HSB スキルと同じ、永続的な SSH セッションモデルを使用します。各フェーズは、1つの SSH heredoc ブロックとして実行します。

ssh -o BatchMode=yes $REMOTE_SSH_OPTS $SSH_TARGET bash -s <<'REMOTE'
set -e

# restore state from previous phase
source /tmp/.claude_hsb_test_session/state.sh 2>/dev/null || true
cd "${_CLAUDE_CWD:-__REMOTE_ROOT__}"

# phase commands
echo "=== Phase N: description ==="
command1
command2

# save state for next phase (preserves _SESSION_VERIFIED if already set)
_PREV_VERIFIED="${_SESSION_VERIFIED:-}"
mkdir -p /tmp/.claude_hsb_test_session
{
  echo "export _CLAUDE_CWD=\"$(pwd)\""
  echo "export PATH=\"$PATH\""
  echo "export REPO_DIR=\"$REPO_DIR\""
  echo "export VERSION=\"$VERSION\""
  echo "export HSB_PLATFORM=\"$HSB_PLATFORM\""
  echo "export BOARD_TYPE=\"$BOARD_TYPE\""
  echo "export SENSORS=\"$SENSORS\""
  echo "export FPGA_VERSION=\"$FPGA_VERSION\""
  echo "export TEST_PLAN_SOURCE=\"$TEST_PLAN_SOURCE\""
  [ "$_PREV_VERIFIED" = "true" ] && echo "export _SESSION_VERIFIED=true"
} > /tmp/.claude_hsb_test_session/state.sh
REMOTE

heredoc を作成する際は、__REMOTE_ROOT__ を $REMOTE_ROOT のリテラル値に置き換えてください。

テストでのコンテナの使用

テストコマンドはデモコンテナ内で実行します。タイムアウトを適用するため、名前付きコンテナとウォッチドッグを使用するデタッチドパターンを使ってください。

テストごとのデフォルトのタイムアウト：120秒（2分）。以下で上書きできます。

• スキルの呼び出し時に指定する --timeout N（すべてのテストに適用）
• テスト計画で指定するテストごとのタイムアウト

各テストコンテナの実行後のクリーンアップ

テストを実行するたびに、コンテナを停止して削除してください。クリーンアップのパターンについては、references/phase-details.mdを参照してください。

セッションの終了処理

Phase 4 で処理されます。Phase 4 の前にワークフローが中断された場合：

docker ps --filter "name=hsb_test_" --format '{{.Names}}' | xargs -r docker stop -t 2 2>/dev/null || true
ssh -o BatchMode=yes $REMOTE_SSH_OPTS $SSH_TARGET "rm -rf /tmp/.claude_hsb_test_session"

フェーズゲート — フェーズ間のユーザー確認

各フェーズ（Phase 0～3）の完了後、次のフェーズを開始する前に必ずユーザーに確認を求めてください。

例外：--y（自動承認モード）が有効な場合、フェーズゲートはスキップされます。「自動承認モード（--y）」セクションを参照してください。

例外：Phase 4（クリーンアップ）は、ゲートを設けず Phase 3 の後に自動的に実行します。

Proceed to Phase <N+1> (<phase description>)? [Y/n]

ユーザー応答の処理

このスキルのすべてのプロンプトでは、明示的な入力が必要です。空欄や Enter キーのみの入力を選択として扱わず、ユーザーに再入力を求めてください。

• "y"、"yes"、"Y"、"ok"、"go"、"continue"、"next" → 次のフェーズに進みます。
• "n"、"no"、"stop"、"abort" → 実行を停止します。次を出力します：

  QA testing paused after Phase N.
  You can resume by re-invoking the skill.
  

  その後、セッションの終了処理を実行します。
• その他のテキスト → 現在のフェーズに関する質問または指示として扱います。回答した後、再度入力を求めてください。
• "retry" → 現在のフェーズを再実行し、概要を再度表示した後、再入力を求めてください。

例外

• フェーズ 4（クリーンアップ）は最終フェーズです。フェーズ 3 の完了後、またはユーザーが別のテスト計画の実行を断った後に自動で実行されます。
• フェーズが失敗し、復旧できない場合は、処理を停止して明確に報告し、その後クリーンアップを実行してください。

組み込みヘルプ（--help）

$ARGUMENTS に --help または -h が含まれる場合は、次を出力して停止します：

HSB QA Test Runner Skill

USAGE
  /hsb-test [OPTIONS]

OPTIONS
  --help, -h        Show this help message and exit
  --verbose         Show full raw command output for every phase
  --y               Auto-approve all phase gates and skip interactive
                    debugging on test failures. Not recommended — a
                    confirmation warning is shown before proceeding.
                    All output is saved to a timestamped log file.
  --timeout N       Set per-test runtime in seconds (default: 120s).
                    Tests stop after N seconds or when pass/fail can
                    be determined, whichever comes first.
  --full            Force full verification from Phase 0, even if the
                    session was already verified

ENVIRONMENT VARIABLES (set before invoking the skill)
  SSH_TARGET        Remote login target (e.g. [email protected])
  REMOTE_ROOT       Remote working directory
  REMOTE_SUDO       Privilege escalation: 'sudo', 'sudo -n', or ''
  REMOTE_SSH_OPTS   Additional SSH options
  HSB_PLATFORM      Platform hint

WORKFLOW PHASES
  Phase 0   Verify board connectivity, demo container readiness,
            and user setup (release repo, platform, sensor/camera)
            (skipped on repeat runs in the same session)
  Phase 1   Obtain test plan, confirm setup, build executable test list
            (setup confirmation skipped on repeat runs)
  Phase 2   Execute test plan with per-test pass/fail evaluation
  Phase 3   Generate and optionally save test results report
  Phase 4   Cleanup (automatic)

EXAMPLES
  /hsb-test
  /hsb-test --verbose
  /hsb-test --timeout 60
  /hsb-test --y
  /hsb-test --y --timeout 60
  /hsb-test --full
  /hsb-test --help

呼び出し例

• /hsb-test
• /hsb-test --verbose
• /hsb-test --timeout 60
• /hsb-test --timeout 60 --verbose
• /hsb-test --y
• /hsb-test --y --timeout 60
• /hsb-test --full
• /hsb-test --full --verbose
• /hsb-test --help

詳細モード（--verbose）

このスキルは --verbose フラグに対応しています：

フラグの検出

$ARGUMENTS（スラッシュコマンドの後のテキスト）に、次のいずれかが含まれているか確認します：--help / -h、--verbose、--y、--timeout N、または --full（大文字と小文字は区別しません）。以降の解析を行う前に、すべてのフラグ（およびその値）を引数から削除してください。

--full が指定されている場合は、キャッシュされたセッション状態を無視し、フェーズ 0 を最初から実行してください。

詳細モード（有効時）

• すべての SSH コマンドの生出力を完全に表示します
• テストアプリケーションの出力をすべてインラインで表示します（stdout/stderr のすべて）
• 詳細なフェーズステータスブロックを表示します

簡潔モード（デフォルト、--verbose なし）

• 各フェーズの後に箇条書きの概要を表示します
• コマンドの生出力は表示しません
• テスト出力の主要な行（起動、エラー、合否の表示）は表示しますが、すべての行は表示しません
• 問題は 4 行形式（症状、原因、解決策、ブロックの有無）で表示します

自動承認モード（--y）

このスキルは --y フラグに対応しており、すべてのフェーズゲートをスキップして、フェーズ間のユーザー確認を待たずにワークフロー全体を最初から最後まで実行します。QA テストでは推奨されません。

確認の警告

--y が検出された場合は、警告を表示してユーザーに確認を求めます：

⚠  WARNING: Auto-approve mode (--y) is enabled.

This is NOT RECOMMENDED for QA testing. All phase gates will be skipped
and the entire test plan will execute without pausing for your
confirmation between phases or tests.

You will not be able to review intermediate results, intervene on
failures, or abort between tests. All output will be saved to a
timestamped log file.

NOTE: In auto-approve mode, you must still provide the test plan in
Phase 1. Failed tests are logged but not interactively debugged —
testing continues to the next test automatically.

Type 'yes' to confirm auto-approve mode, or anything else to cancel:

• ユーザーが "yes"（完全一致、大文字と小文字は区別しません）と応答した場合 → 自動承認モードを有効にします。
• それ以外の応答の場合 → 自動承認モードをキャンセルし、対話形式で実行します。

--y が有効な場合の動作

1. フェーズ間のフェーズゲートはスキップされます。
2. テスト計画の承認はスキップされ、生成されたテスト計画が自動的に実行されます。
3. テストに失敗しても一時停止せず、失敗を記録し、次のテストケースに自動的に進みます。
4. テスト間のプロンプトはスキップされ、確認なしでテストを連続して実行します。
5. デフォルトのタイムアウトが適用され、各テストは 120 秒で実行されます。--timeout N が指定されている場合は、その値が適用されます。
6. ログファイル：開始時に $REMOTE_ROOT/ または現在のディレクトリに hsb-test-log-YYYY-MM-DD-HHMMSS.md として作成されます。
7. フェーズの概要は引き続きリアルタイムで表示されます。
8. 接続に関するブロッキングエラーが発生した場合は、引き続きワークフローを停止し、再検証を実行します。

他のフラグとの組み合わせ

• --y --verbose：すべての生出力を表示する自動承認モード。
• --y --timeout N：テストごとにカスタムのタイムアウトを設定する自動承認モード。
• --y --full：フェーズ 0 から完全な検証を強制実行する自動承認モード。

タイムアウトの処理（--timeout）

このスキルは --timeout N フラグに対応しています。N は各テストの実行時間を秒数で指定します。

動作

• 設定した場合：各テストは最大 N 秒間実行された後、停止します。合否は、その時間内に収集された出力に基づいて判定されます。
• 設定しない場合：各テストはデフォルトで最大 120 秒（2 分間）実行されるか、出力から合否を判定できるようになるまで実行されます。いずれか早い方が適用されます。
• テストごとの上書き：テスト計画で特定のテストのタイムアウトが指定されている場合、その値はデフォルト値と --timeout フラグの両方より優先されます。

検証

• N は正の整数である必要があります。
• 最小値：5 秒
• 最大値：3600 秒（1 時間）
• 無効な場合は、エラーを表示し、有効なタイムアウトを指定するようユーザーに求めます。