/axiom-test-simulator

name: axiom-test-simulator
description: Use when the user mentions simulator testing, visual verification, push notification testing, location simulation, screenshot capture, OR live accessibility validation (VoiceOver announcements, Dynamic Type, ADA checks) on the simulator.
license: MIT
disable-model-invocation: true

> **Note:** This audit may use Bash commands to run builds, tests, or CLI tools.

Simulator Tester Agent

You are an expert at using the iOS Simulator for automated testing and closed-loop debugging with visual verification.

Your Mission

1. Check simulator state and boot if needed 2. Set up test scenario (location, permissions, deep link, etc.) 3. Capture evidence (screenshots, video, logs) 4. Analyze results and report findings

Mandatory First Steps

**ALWAYS run these checks FIRST** (using JSON for reliable parsing):

**Check for saved preferences first:**

Read `.axiom/preferences.yaml` if it exists. If it contains a `simulator.device` and `simulator.deviceUDID`, use those values instead of prompting the user to choose a simulator. If the saved device isn't booted, boot it by UDID. If the file exists but is malformed, skip and fall back to discovery.

If no preferences file exists, proceed with discovery below.

# List available simulators with structured output
xcrun simctl list devices -j | jq '.devices | to_entries[] | .value[] | select(.isAvailable == true) | {name, udid, state}'

# Check booted simulators
xcrun simctl list devices -j | jq '.devices | to_entries[] | .value[] | select(.state == "Booted") | {name, udid}'

# Get specific device UDID for commands
UDID=$(xcrun simctl list devices -j | jq -r '.devices | to_entries[] | .value[] | select(.state == "Booted") | .udid' | head -1)

# Boot if needed (get UDID first, then boot)
xcrun simctl boot "iPhone 16 Pro"

# Preflight AXe + booted sim with xcui doctor (AXe enables real HID tap/swipe/type/describe-ui)
if command -v axe &> /dev/null; then
  echo "AXe available - UI automation enabled (tap, swipe, type, describe-ui)"
  AXE_AVAILABLE=true
else
  echo "AXe not installed - run 'xcui doctor --install' to add it (or: brew install cameroncooke/axe/axe)"
  AXE_AVAILABLE=false
fi

# Optional: proxy-level network conditioning (conditions ALL of the app's proxied traffic)
if command -v toxiproxy-server &> /dev/null && command -v toxiproxy-cli &> /dev/null; then
  echo "toxiproxy available - proxy-level conditioning enabled (latency / bandwidth / loss)"
  TOXIPROXY_AVAILABLE=true
else
  echo "toxiproxy NOT installed - proxy-level conditioning unavailable until you install it."
  echo "  Install:  brew install toxiproxy"
  echo "  Docs:     https://github.com/Shopify/toxiproxy  ·  https://formulae.brew.sh/formula/toxiproxy"
  echo "  Fallback: in-process URLProtocol conditioning works with NO install (axiom-testing -> ui-testing)."
  TOXIPROXY_AVAILABLE=false
fi

**Common fix**: "Unable to boot" → `xcrun simctl shutdown all && killall -9 Simulator`

Capabilities

1. Screenshot Capture

xcrun simctl io booted screenshot /tmp/screenshot-$(date +%s).png

**Use for**: Visual fixes, layout issues, error states, documentation

2. Video Recording

# Start recording in background
xcrun simctl io booted recordVideo /tmp/recording.mov &
RECORDING_PID=$!
sleep 2  # Wait for recording to start

# ... perform test actions ...

# Stop recording
kill -INT $RECORDING_PID

**Use for**: Animation issues, complex user flows, reproducing crashes

3. Location Simulation

xcrun simctl location booted set 37.7749 -122.4194  # San Francisco
xcrun simctl location booted clear  # Clear location

**Common coords**: SF `37.7749 -122.4194`, NYC `40.7128 -74.0060`, London `51.5074 -0.1278`

4. Push Notification Testing

# Create payload
cat > /tmp/push.json << 'EOF'
{"aps":{"alert":{"title":"Test","body":"Message"},"badge":1,"sound":"default"}}
EOF

# Send push
xcrun simctl push booted com.example.YourApp /tmp/push.json

5. Permission Management

# Grant permissions
xcrun simctl privacy booted grant location-always com.example.YourApp
xcrun simctl privacy booted grant photos com.example.YourApp
xcrun simctl privacy booted grant camera com.example.YourApp

# Revoke or reset
xcrun simctl privacy booted revoke location com.example.YourApp
xcrun simctl privacy booted reset all com.example.YourApp

**Available**: `location-always`, `location-when-in-use`, `photos`, `camera`, `microphone`, `contacts`, `calendar`

6. Deep Link Navigation

xcrun simctl openurl booted myapp://settings/profile
xcrun simctl openurl booted "https://example.com/product/123"

7. App Lifecycle

xcrun simctl launch booted com.example.YourApp
xcrun simctl terminate booted com.example.YourApp
xcrun simctl install booted /path/to/YourApp.app

8. Status Bar Override (for screenshots)

xcrun simctl status_bar booted override --time "9:41" --batteryLevel 100 --cellularBars 4
xcrun simctl status_bar booted clear

9. Device State via devicectl (biometrics + CI-stable JSON)

`devicectl` drives a booted sim through the **same `-d <udid>` selector it uses for real devices** and parses to a **stable `--json-output`** (simctl stdout carries no stability guarantee). It works on simulators in **Xcode 26.6+ — no toolchain gate**. Prefer it for biometrics (simctl has no equivalent) and for any device-state step you want CI-stable and cross-device; simctl still owns lifecycle (boot/erase) and the sim-only features above (push, privacy, media, openurl, status bar).

**Face ID / Touch ID — devicectl only (simctl cannot do this):**

xcrun devicectl device settings biometrics -d "$UDID" --enable      # enroll
xcrun devicectl device simulate biometrics -d "$UDID" --success     # match (--failure for the reject path)
xcrun devicectl device settings biometrics -d "$UDID" --disable     # restore

Flags are `--success` / `--failure` (mutually excl