# Axiom Test Simulator

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

- Skill: `charleswiltgen/axiom-test-simulator` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add charleswiltgen/axiom-test-simulator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/charleswiltgen/axiom-test-simulator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- License: MIT
- Author: charleswiltgen (https://skillmd.com/u/charleswiltgen)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/charleswiltgen/axiom-test-simulator

---



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

# 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 DeviceHub` (Xcode 27 replaced Simulator.app with DeviceHub.app — naming only `Simulator` is a silent no-op there)

## 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)

Prefer the preset — one command, Apple's classic values (9:41, full bars, 100% battery):

```bash
xcrun devicectl device simulate statusBar preset -d "$SIM" screenshot
# ... capture ...
xcrun devicectl device simulate statusBar clear -d "$SIM"
```

Hand-rolling the fields instead (`simctl status_bar` on Xcode 26, or when you need
`--operatorName`, which devicectl lacks):

```bash
xcrun simctl status_bar "$SIM" clear      # ALWAYS clear first — override merges
xcrun simctl status_bar "$SIM" override --time "9:41" --batteryState charged \
  --batteryLevel 100 --cellularMode active --cellularBars 4
xcrun simctl status_bar "$SIM" list       # assert on THIS, not on the exit code
```

**Clear before override, and verify by readback.** `override` merges into whatever is already
set, and several values silently fail while still exiting 0 — `--operatorName` won't overwrite
an existing carrier name, and `--dataNetwork wifi` becomes `5G` if any `--cellularMode` is in
the same call. A stale status bar in a shipped screenshot is the failure this prevents. Flag spellings differ between the two tools and are not interchangeable
(`draining` vs `discharging`, `--cellular-strength` vs `--cellularBars`). Full detail, including
the bad `--cellular-strength` help range and the JSON backtick quirk, is in
axiom-tools (`skills/device-control-ref.md`, Status bar for screenshots).

### 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); the status bar is shared — both tools write the same override store.

**Face ID / Touch ID — devicectl only (simctl cannot do this):**
```bash
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 exclusive) — **not** `--match`.

**Other verified device-state primitives:**
```bash
xcrun devicectl device orientation set -d "$UDID" landscapeLeft           # portrait|portraitUpsideDown|landscapeLeft|landscapeRight
xcrun devicectl device process sendMemoryWarning -d "$UDID" --pid <pid>    # memory-pressure scenario
```

The full verified catalog — `info displays`, `settings appearance`, `simulate location` / `statusBar`, and the `CoreDeviceError 1001` "device-only on a sim" cases — lives in `axiom-tools (skills/device-control-ref.md)`. Consult it for the complete set and exact JSON keys.

### 10. 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
```

### 11. 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

### 12. 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
```

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

**Drive input through `xcui` when it is available.** The input verbs below (`tap`, `type`, `swipe`, `gesture`, `button`, `key`, `screenshot`, …) forward to AXe verbatim — same flags, same output, same exit code — and inherit xcui's SimulatorKit/`DEVELOPER_DIR` handling, so they keep working under an Xcode that AXe cannot load on its own.

**Check first: `command -v xcui`.** It is on PATH automatically only on Claude Code. On Codex, Pi, and MCP installs no binary ships, so if it is absent, drop the `xcui ` prefix and run the same command as `axe …` — identical flags — then handle `DEVELOPER_DIR` yourself only if bare AXe reports a SimulatorKit load failure.

`axe describe-ui` (what xcui itself parses) and `axe stream-video` / `record-video` (long-running) are always called bare.

**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)
xcui tap --id "loginButton" --udid $UDID

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

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

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

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

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

# Type text (field must be focused first)
xcui tap --id "emailTextField" --udid $UDID
xcui type "user@example.com" --udid $UDID

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

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

### 14. 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)
xcui screenshot --output /tmp/screenshot.png --udid $UDID
```
**Use for**: Live monitoring, recording test flows, capturing evidence

### 15. 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 `xcui tap --id <id>` (forwards to AXe's real HID touch). Full reference: `axiom-tools (skills/xcui-ref.md)`.

### 16. Network Conditioning (low-bitrate / latency / loss)

Two no-sudo paths — **never run `sudo dnctl`/`pfctl` on the user's machine unprompted.**

- **In-process (default, no install)** — register a throttling `URLProtocol` on the app's `URLSession` to inject latency / byte-rate cap / failures deterministically. Full harness: `axiom-testing (skills/ui-testing.md)` → "No-sudo, automatable conditioning". Use this first; it is never unavailable.
- **Proxy (optional, gated in preflight)** — if `TOXIPROXY_AVAILABLE=true`, route real traffic through toxiproxy. If `false`, tell the user the proxy path is unavailable, give `brew install toxiproxy` + https://github.com/Shopify/toxiproxy, and fall back to the `URLProtocol` path — do not silently skip the test.

```bash
# proxy path (only when TOXIPROXY_AVAILABLE=true)
toxiproxy-cli create api --listen localhost:6443 --upstream api.example.com:443
toxiproxy-cli toxic add api -t bandwidth -a rate=30      # KB/s low-bitrate
toxiproxy-cli toxic add api -t latency   -a latency=400  # ms delay
```
**Use for**: slow-network UX, spinner/timeout/offline states, low-bitrate media. NLC/`dnctl` (whole-Mac, needs sudo) is a last resort for traffic neither path can reach.

## Test Workflow

1. **Setup**: Check simulator state, boot if needed
2. **Configure**: Set location, permissions, etc.
3. **Execute**: Launch app, wait 2s for render, perform action
4. **Capture**: Screenshot, video, logs
5. **Analyze**: Review visual state, check for errors
6. **Report**: Actual vs expected, pass/fail
7. **Save**: If this is a new device/app selection, save to `.axiom/preferences.yaml` (see `axiom-tools (skills/xclog-ref.md)` skill)

## Crash Detection

Before reporting a test failure, check for new `.ips` files:

```bash
ls -t ~/Library/Logs/DiagnosticReports/*.ips 2>/dev/null | head -5
```

If any file's mtime is within the test-run window, run:

```bash
xcsym crash --format=summary <path>
```

Include the structured crash summary in the test-failure report (pattern_tag, exception type, top frames, and dSYM status). If xcsym returns `{"error":"hang_report"}` on stdout (exit 1), the `.ips` is a hang (`bug_type=298`), not a crash — report the hang separately and skip crash triage (link to `axiom-performance (skills/hang-diagnostics.md)`). See `axiom-tools (skills/xcsym-ref.md)` for full xcsym usage and the exit-code table.

## Output Format

```markdown
## Simulator Test Results

### Environment
- **Simulator**: [Device] ([iOS version])
- **App**: [Bundle ID]
- **Scenario**: [What was tested]

### Evidence
- **Screenshot**: [path]
- **Logs**: [relevant entries]

### Analysis
**Expected**: [What should happen]
**Actual**: [What happened]
**Result**: ✅ PASS / ❌ FAIL

### Issues Detected
- [Issue with severity]

### Next Steps
1. [Recommended action]
```

## Guidelines

1. Always check simulator state first
2. Wait for UI to stabilize (`sleep 2`) before screenshots
3. Check logs after each action
4. Use descriptive file names with timestamps
5. Read and analyze screenshots (you're multimodal)
6. Ask for bundle ID if not provided

## Comprehensive Diagnostics (simctl diagnose)

For deep troubleshooting and bug reports, use `simctl diagnose` to collect logs and system state.

```bash
# Basic diagnostic collection (opens archive in Finder when done)
xcrun simctl diagnose

# Faster collection without archive (useful for quick inspection)
xcrun simctl diagnose --no-archive --output /tmp/sim-diag

# Collect from specific device only
xcrun simctl diagnose --udid $UDID

# Include app data containers (warning: may include private data)
xcrun simctl diagnose --data-container

# Full collection with no timeout (for complex issues)
xcrun simctl diagnose -X --all-logs
```

### Best Practices for Diagnostic Collection

1. **Leave affected simulator booted** — More information collected from booted devices
2. **Enable verbose logging first** — For hard-to-reproduce issues:
   ```bash
   xcrun simctl logverbose booted enable
   # Reboot simulator, reproduce issue, then run diagnose
   xcrun simctl diagnose
   ```
3. **Collect right after reproducing** — Logs rotate, so capture immediately
4. **Use --no-archive for quick inspection** — Faster when you just need to check logs

### What's Collected

- System logs and crash reports
- Simulator configuration and state
- Device logs from booted simulators
- CoreSimulator service logs
- Optionally: app data containers (--data-container)

**Use for**: Filing Apple bug reports, debugging simulator infrastructure issues, investigating crashes that happen before your code runs

## Error Quick Reference

| Symptom | Fix |
|---------|-----|
| Screenshot is black | `sleep 5` then retry |
| "Unable to boot" | `xcrun simctl shutdown all && killall -9 Simulator DeviceHub` (26 = Simulator, 27 = DeviceHub) |
| "Device not found" | `xcrun simctl list devices` to see available |
| Deep link doesn't work | Check URL scheme in Info.plist |
| Push fails | Validate JSON: `python -m json.tool < push.json` |

## Resources

**WWDC**: 2020-10647 (Become a Simulator expert)

**Docs**: /xcode/running-your-app-in-simulator-or-on-a-device

## Related

**Preflighted Tools:**
- **xcui**: bundled — scriptable wait/assert/a11y + AXe preflight. See `axiom-tools (skills/xcui-ref.md)`.
- **AXe**: the HID input + `describe-ui` engine — preflight with `xcui doctor` (`xcui doctor --install` adds it via brew).

For deep link debugging: `axiom-swift (skills/deep-link-debugging.md)` skill
For build issues: `build-fixer` agent
For AXe reference: `axiom-xcode-mcp` skill
For running tests: `test-runner` agent
For static accessibility source scanning: `accessibility-auditor` agent