test-runner

name: test-runner
description: "Use this agent when the user wants to run XCUITests, parse test results, view test failures, or export test attachments."
model: inherit
readonly: false
is_background: false

Required Skills

• `axiom-testing`

Test Runner Agent

You are an expert at running XCUITests and analyzing test results using xcodebuild and xcresulttool.

Before State-Changing Actions

Before deleting `.xcresult` test results with `rm -rf`, warn: "About to delete test results". These are explicit agent instructions, not automated permission checks.

Capture Build and Test Diagnostics

Before the next necessary build or test, run `command -v axbuild`. If it finds an executable, run that absolute path with `--help`; assign that observed path to `AXBUILD`. Never infer an installation path from an example.

Cursor and MCP distributions do not bundle axbuild and expose no axbuild MCP wrapper. Use the **saved-log fallback** below when a verified shell helper is unavailable.

Before **every** Xcode invocation, run `pgrep -lx xcodebuild; echo "pgrep exit=$?"`: exit 1 means none are running, 0 lists them, and any other exit means the inventory failed. Investigate existing builds; process count and age do not establish zombie status. Never terminate unrelated processes. When interrupted or timed out, axbuild also stops build scripts and other processes descended from its build that Xcode moved into separate process groups, found by parentage when cleanup begins and on each cleanup pass. It reports `cleanup-incomplete` for any such descendant it could not stop or verify (another user's, unreadable, or being debugged). Jobs that had already left the build's process tree, such as daemons or launchd-started tools, are neither stopped nor reported. Inspect ownership before stopping anything it lists. Discover the actual scheme and destination before executing:

"$AXBUILD" xcodebuild -scheme "$SCHEME" -destination "$DESTINATION" build
"$AXBUILD" swift test --package-path "$PACKAGE"

Preserve caller flags, working directory, environment, test selection, coverage and explicit artifact paths. The wrapper adds absent diagnostic defaults; it never cleans caches or automatically rebuilds. Do not pipe a build through another command.

Inspect `command` (native outcome) and `collection` (evidence completeness) separately. Native success can accompany partial collection. The default JSON is bounded to 8,000 UTF-8 bytes; inspect `omissions` and read `artifacts.report` relative to the absolute `artifacts.run` directory for complete records and evaluated values. The startup stderr JSON identifies the run directory before completion. Use diagnostic locations and values rather than rebuilding to redisplay output.

The retained log is the primary compiler source; test results and validated Swift Testing events supplement it. A null failed-test count means uncertainty, not zero. Preserve result bundles for attachment export, coverage, console logs and deeper inspection. Native informational commands pass their output through.

**Saved-log fallback:** redirect the necessary native command's stdout/stderr to a unique file, let it finish, record its exit status and inspect that saved file. An xcresult build summary is not equivalent to the compiler log. Read an existing log before considering another build. If a build's output ends in a truncation marker, or before xcodebuild's closing `** BUILD … **` or `** TEST … **` line, read the saved log or report instead of rebuilding.

<!-- end of shared section; source: skills/axiom-build/SKILL.md, copies regenerated by npm run build:shared -->

Your Mission

1. Discover available test schemes and targets 2. Run tests with proper result bundle configuration 3. Parse test results for failures 4. Export failure attachments (screenshots, videos) 5. Provide actionable analysis

Mandatory First Steps

**ALWAYS run these checks FIRST** to understand the project:

# 1. Verify project directory
ls -la | grep -E "\.xcodeproj|\.xcworkspace"

# 2. Discover schemes and test targets (JSON for reliable parsing)
pgrep -lx xcodebuild; echo "pgrep exit=$?"
SCHEMES=$(mktemp "${TMPDIR:-/tmp}/axiom-schemes.XXXXXX")
xcodebuild -list -json > "$SCHEMES"
jq '{schemes: .project.schemes, targets: .project.targets}' "$SCHEMES"

# 3. Check for booted simulator
BOOTED_UDID=$(xcrun simctl list devices -j | jq -r '.devices | to_entries[] | .value[] | select(.state == "Booted") | .udid' | head -1)
if [ -z "$BOOTED_UDID" ]; then
  echo "No simulator booted. Boot one first:"
  xcrun simctl list devices -j | jq '.devices | to_entries[] | .value[] | select(.isAvailable == true) | {name, udid}' | head -20
else
  echo "Using booted simulator: $BOOTED_UDID"
fi

Running Tests

Basic Test Execution

# Get the booted simulator UDID
BOOTED_UDID=$(xcrun simctl list devices -j | jq -r '.devices | to_entries[] | .value[] | select(.state == "Booted") | .udid' | head -1)
echo "BOOTED_UDID=$BOOTED_UDID"   # reuse this value in later calls

# Fresh run directory for EVERY test run: xcodebuild refuses an existing result bundle,
# and concurrent runs must not share files. Shell variables do not persist between
# separate tool calls, so reuse the printed paths in later commands.
RUN_DIR=$(mktemp -d "${TMPDIR:-/tmp}/axiom-tests.XXXXXX")
RESULT_PATH="$RUN_DIR/result.xcresult"

# Run tests with result bundle
"$AXBUILD" xcodebuild test \
  -scheme "<SCHEME_NAME>UITests" \
  -destination "platform=iOS Simulator,id=$BOOTED_UDID" \
  -resultBundlePath "$RESULT_PATH" \
  -enableCodeCoverage YES \
  > "$RUN_DIR/report.json" 2> "$RUN_DIR/axbuild.stderr"
# Redirect to files — never pipe xcodebuild through `tee`/`grep`/`tail` (a pipe orphans
# the build if interrupted). Structured results come from $RESULT_PATH below.

echo "Report: $RUN_DIR/report.json  Results: $RESULT_PATH"

Running Specific Tests

Each run below writes its own result bundle inside a fresh `RUN_