nvidia-holoscan/holoscan-sensor-bridge/hsb-test

HSB QA Test Runner

Use this skill when the user wants to execute a QA test plan against an HSB board and devkit. The skill reads a test document (local file or web link), filters tests to those that can run automatically on the user's specific hardware setup, executes each test with pass/fail evaluation, and produces a comprehensive results report.

This skill assumes the devkit is already set up (SSH, demo container built, host configured, board connected). If setup is not complete, it will offer to invoke /hsb-setup first.

This workflow runs test applications inside the demo container. Only run it when the user explicitly invokes it.

Before you start — required gates (do these first, in order)

Gate 1 — Read environment variables. Before doing anything else, check these variables and print their resolved values to the user:

SSH_TARGET      Remote devkit login (e.g. nvidia@192.168.1.50). 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 and REMOTE_ROOT are required. Stop and ask the user for them if either is missing.

Gate 2 — Present the phase plan, ask for the test document, and get confirmation. Before taking any action:

1. Show the phase plan:

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

1. If the user has not provided a test document path or URL, STOP and ask for it — do not proceed to Phase 0 or any phase until the user provides it: Please provide the path or URL to your test document:. If the user has already specified specific tests (e.g., "connectivity checks only"), state which phases will run and which will be skipped, and note that tests will be filtered to the user's platform/board/sensor configuration and classified as automatable vs. manual.

1. Ask explicitly: Shall I proceed with Phase 0? [Y/n] — do not start Phase 0 until the user confirms.

What this skill must do

1. Verify that the devkit is reachable over SSH, the HSB board is connected and responsive, and the demo container is available. Read the current FPGA version and board identity. Verify the type of sensor/camera and hsb devkit and release repo used either from already set environment variables or from prompting the user. If the setup is not ready, offer to invoke /hsb-setup to prepare the devkit.
2. Obtain a test plan document from the user (file path or URL). Confirm the user's setup details collected in Phase 0 (repo location, HSB version, platform, board type, sensors). Study the test plan and the repository's examples/ directory to determine which tests can run automatically. Skip manual tests and tests requiring additional equipment. Present the executable test plan for user approval.
3. Execute each test case in sequence. For each test: run the application, evaluate pass/fail against the criteria in the test plan, log the result. On failure, analyze logs, suggest fixes, and let the user decide how to proceed before running the next test.
4. Produce a structured test results report with per-test pass/fail status, issues encountered, and fixes applied. Offer to save the report.
5. Clean up all test artifacts (containers, temporary files, session state).

Linux/Windows-friendly wrapper variables

Reuse the same environment variables from the other HSB skills:

• SSH_TARGET for the remote login target (e.g. nvidia@agx-thor-host)
• REMOTE_ROOT for the remote working directory
• REMOTE_SUDO for privileged commands
• REMOTE_SSH_OPTS for additional SSH options
• HSB_PLATFORM as an optional platform hint

If these are set, notify the user of these settings and use them without re-asking.

Before Phase 0, print the resolved remote execution settings.

Mandatory interaction pattern

First run in a session (no prior verification)

When no valid session state exists, show the full phase plan:

• Phase 0: Verify board connectivity, demo container readiness, and user setup (release repo, platform, sensor/camera)
• Phase 1: Obtain test plan, confirm setup, build executable test list
• Phase 2: Execute test plan with per-test pass/fail evaluation
• Phase 3: Generate test results report (with option to save)
• Phase 4: Cleanup

Then execute one phase at a time.

Subsequent runs in the same session (fast path)

When the session state file (/tmp/.claude_hsb_test_session/state.sh) exists and contains _SESSION_VERIFIED=true, the skill skips Phase 0 and Phase 1 setup confirmation because connectivity, hardware, release repo, platform, and sensor/camera were already verified. Instead, inform the user and jump directly to test plan intake:

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.

Then execute:

• Phase 1 (test plan intake and test list building — setup confirmation is skipped)
• Phase 2: Execute test plan
• Phase 3: Test results report
• Phase 4: Cleanup

When to re-run Phase 0 from the beginning

Phase 0 must be re-run (ignoring the fast path) when:

1. New session: No session state file exists on the remote host, or a new Claude Code session is started.
2. Execution failure suggesting connectivity loss: If Phase 2 fails with symptoms indicating the board or devkit is unreachable (ping failure, SSH timeout, container launch failure, No such device errors), clear _SESSION_VERIFIED from the session state and re-run Phase 0 before retrying.
3. User explicitly requests it: If the user says "re-verify", "start over", "run from the beginning", or invokes /hsb-test --full, run Phase 0 from scratch.

See ## Phase gate below for the full confirmation protocol.

If something fails, do not just dump raw logs. Summarize:

• the exact command that failed
• the likely root cause
• what safe action you recommend
• whether the issue is blocking

Phase details

See references/phase-details.md for full step-by-step phase instructions.

Execution rules

SSH heredoc pattern

Use the same persistent SSH session model as the other HSB skills. Each phase runs as a single SSH heredoc block:

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

Replace __REMOTE_ROOT__ with the literal value of $REMOTE_ROOT when composing the heredoc.

Container usage for tests

Test commands run inside the demo container. Use the detached pattern with a named container and a watchdog for timeout enforcement.

Default timeout per test: 120 seconds (2 minutes). Overridden by:

• --timeout N on the skill invocation (applies to all tests)
• Per-test timeout specified in the test plan

Cleanup after each test container

After every test run, stop and remove the container. See references/phase-details.md for the cleanup pattern.

Session teardown

Handled by Phase 4. If the workflow is aborted before 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 gate — user confirmation between phases

After completing each phase (Phases 0–3), always prompt the user for confirmation before starting the next phase.

Exception: When --y (auto-approve mode) is active, phase gates are skipped. See "Auto-approve mode (--y)" section.

Exception: Phase 4 (cleanup) runs automatically after Phase 3 without a gate.

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

User response handling

All prompts in this skill require explicit typed responses. Never treat a blank or Enter-only input as a selection — re-prompt the user instead.

• "y", "yes", "Y", "ok", "go", "continue", "next" → proceed to the next phase.
• "n", "no", "stop", "abort" → stop execution. Print:

`` QA testing paused after Phase N. You can resume by re-invoking the skill. `` Then run session teardown.

• Any other text → treat as a question or instruction about the current phase. Answer it, then re-prompt.
• "retry" → re-execute the current phase, show summary again, then re-prompt.

Exceptions

• Phase 4 (cleanup) is the final phase — it runs automatically after Phase 3 completes or after the user declines to run another test plan.
• If a phase FAILs and cannot be recovered, stop and report clearly, then run cleanup.

Built-in help (--help)

If $ARGUMENTS contains --help or -h, print the following and stop:

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. ubuntu@10.0.0.1)
  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

Invocation examples