axiom-test-simulator

What this skill does

> **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.

```bash
# 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
```

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

## Capabilities

### 1. Screenshot Capture
```bash
xcrun simctl io booted screenshot /tmp/screenshot-$(date +%s).png
```
**Use for**: Visual fixes, layout issues, error states, documentation

### 2. Video Recording
```bash
# 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
```bash
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
```bash
# 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
```bash
# 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
```bash
xcrun simctl openurl booted myapp://settings/profile
xcrun simctl openurl booted "https://example.com/product/123"
```

### 7. App Lifecycle
```bash
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)
```bash
xcrun simctl status_bar booted override --time "9:41" --batteryLevel 100 --cellularBars 4
xcrun simctl status_bar booted clear
```

### 9. Log Capture
```bash
# Stream logs for specific app
xcrun simctl spawn booted log stream --predicate 'subsystem == "com.example.YourApp"' --style compact

# Check recent crash logs
ls -lt "$HOME/Library/Logs/DiagnosticReports/"*.crash 2>/dev/null | head -5
```

### 10. App Inventory & Diagnostics
```bash
# List all installed apps on booted simulator
xcrun simctl listapps booted

# Get app container path (useful for inspecting sandbox)
xcrun simctl get_app_container booted com.example.YourApp data
xcrun simctl get_app_container booted com.example.YourApp app

# Get detailed app info
xcrun simctl appinfo booted com.example.YourApp

# Comprehensive system diagnostics (no archive = faster)
xcrun simctl diagnose --no-archive
```
**Use for**: Verifying app installation, inspecting app data, deep debugging

### 11. Simulator Management
```bash
# Clone simulator for test variants
xcrun simctl clone <source-udid> "Test Variant - Dark Mode"

# List available runtimes
xcrun simctl list runtimes -j | jq '.runtimes[] | {name, identifier, isAvailable}'

# Add CA certificate for proxy testing
xcrun simctl keychain booted add-root-cert /path/to/ca.pem
```

### 12. UI Automation with AXe (preflighted via `xcui doctor`)

**Installation:** AXe is the input/tree engine `xcui` builds on. Preflight it with `xcui doctor` (and `xcui doctor --install` to add it via brew, consented) rather than treating it as optional.

```bash
# Verify (or install) AXe in one step
xcui doctor          # exit 0 = AXe present + sim booted
xcui doctor --install  # installs cameroncooke/axe/axe via brew if missing
```

**Check availability:** `command -v axe`

```bash
# Discover UI elements first (get accessibility identifiers)
axe describe-ui --udid $UDID

# Tap by accessibility identifier (RECOMMENDED - stable)
axe tap --id "loginButton" --udid $UDID

# Tap by label
axe tap --label "Submit" --udid $UDID

# Tap at coordinates (less stable)
axe tap -x 200 -y 400 --udid $UDID

# Long press
axe tap -x 200 -y 400 --duration 1.0 --udid $UDID

# Gesture presets
axe gesture scroll-down --udid $UDID     # Scroll content down
axe gesture scroll-up --udid $UDID       # Scroll content up
axe gesture swipe-from-left-edge --udid $UDID  # Back navigation

# Custom swipe
axe swipe --start-x 200 --start-y 600 --end-x 200 --end-y 200 --udid $UDID

# Type text (field must be focused first)
axe tap --id "emailTextField" --udid $UDID
axe type "[email protected]" --udid $UDID

# Press Return key
axe key 40 --udid $UDID

# Hardware buttons
axe button home --udid $UDID
axe button lock --udid $UDID
axe button siri --udid $UDID
```
**Use for**: Automated UI flows when XCUITest not available, quick manual automation

### 13. Video Streaming with AXe (preflighted via `xcui doctor`)

```bash
# Stream video at 10 FPS (for monitoring)
axe stream-video --fps 10 --udid $UDID

# Record video (H.264)
axe record-video --output /tmp/recording.mp4 --udid $UDID
# Press Ctrl+C to stop

# Screenshot (alternative to simctl)
axe screenshot --output /tmp/screenshot.png --udid $UDID
```
**Use for**: Live monitoring, recording test flows, capturing evidence

### 14. Scriptable Assertions & Accessibility with xcui

`xcui` (bundled) adds the test-harness semantics AXe lacks. **Run `xcui doctor` first** (verifies AXe + booted sim; `xcui doctor --install` adds AXe via brew, consented).

```bash
# Synchronize instead of sleeping
xcui wait --for-element loginButton --timeout 10s

# Assert on the a11y tree (exit 1 on failure)
xcui assert --id artist.hero --label "Artwork for …" --trait image --single

# Accessibility runs: set state, relaunch app, then assert
xcui a11y set --toggle reduce-transparency --value on --app com.example.App
xcui a11y set --toggle dynamic-type --value accessibility-extra-large
```

Supported `a11y set` toggles: `dynamic-type`, `increase-contrast`, `reduce-motion`, `reduce-transparency`. For taps, use `axe tap --id <id>` directly (real HID touch). Full referenc