When local iOS Simulator test runs hang.

Why this exists

The pain did not start with CI. It got much worse the day coding agents started running iOS tests for me — across more than one app at the same time, on the same Mac.

A single xcodebuild or Simulator run is already fragile on its own: runs hang before tests start, simctl stops responding, CoreSimulator wedges. Once several agents, scripts, CI-like jobs, and a human can all touch Xcode tooling on one machine, those same failures get frequent and stop being reproducible.

Read the full origin story →

How XCSteward helps

It does not rewrite your tests or replace xcodebuild. It governs how runs are executed, isolated, and cleaned up so the simulator subsystem stays in a state you can reason about.

• A controlled local execution lane. Run tests through one predictable path instead of ad-hoc xcodebuild invocations scattered across scripts and agents.
• A scheduler / queue. Submit runs from multiple agents and scripts; they execute in a coordinated order rather than colliding on shared state.
• Readiness checks. Confirm the simulator subsystem and device are actually ready — not just "Booted" — before handing off to xcodebuild.
• Isolated artifacts. Per-run DerivedData, result bundles, logs, and structured summaries, so runs do not overwrite each other.
• Timeouts and cleanup. Bound each phase so a wedge becomes a fast, legible failure, and tear down devices and processes deterministically afterward.
• Observable CLI runs. Plain waits print the job id, job directory, watch/follow commands, and compact progress instead of disappearing into a silent command.
• Explicit bootstrap diagnosis. Pre-XCTest runner or environment setup failures are classified separately from real test failures, with the simulator detail and artifacts preserved.
• A JSON contract for automation. Agents and scripts can use JSON summaries, phase-aware progress events, profile discovery, metadata, per-run env injection, and bounded explanations instead of scraping human text.

Human UX, machine contract

XCSteward is a local CLI, not a dashboard, SaaS, or MCP layer. The current developer experience has two surfaces: compact human output for watching long runs, and a JSON contract for agents and automation.

For humans

Plain submit --wait is no longer a silent black box. It prints the queued job id, status/log/watch/follow commands, job directory, and compact wait updates. From another terminal, status <job-id> --watch [--interval <seconds>] polls until the job is terminal and logs --follow streams the combined log until completion.

xcsteward submit --project app --wait --wait-timeout 900
xcsteward status <job-id> --watch
xcsteward logs <job-id> --follow

For agents and automation

Machine users should keep using --json. Long-running JSON waits can add --progress for JSON-lines events on stderr while stdout stays reserved for the final JSON document. When command events are available, those progress events add phase and phase_elapsed_seconds. For streaming status, status <job-id> --watch --json emits newline-delimited full JobSummary objects.

xcsteward profile init --detect --json
xcsteward submit --project app --wait --wait-timeout 900 --json --progress --env API_BASE_URL=http://127.0.0.1:8080
xcsteward explain <job-id> --json

• Discover configured profiles with projects --json and inspect one with profile show <name> --json.
• Bootstrap a detectable repo with profile init --detect --json and follow its next_commands.
• Preserve ownership hints with repeatable submit --metadata key=value and --label.
• Inject per-run environment for xcodebuild with repeatable submit --env KEY=VALUE; CLI overrides beat profile [env] for that job only, and XCSteward records override keys rather than sensitive values.
• Prefer explain <job-id> --json for bounded triage before opening raw logs; use cleanup --caches for XCSteward-owned cache and retained evidence cleanup.
• Keep doctor as bounded preflight: if .xctestrun integrity checking times out during a cold or long build, the warning now says no compiler error was observed before timeout rather than pretending it diagnosed the build.

When setup fails before XCTest attaches

If CoreSimulator fails before XCTest attaches, XCSteward reports an environment failure with the simulator error and artifacts, rather than making you decide from a silent terminal or raw xcodebuild output whether the app regressed. The result class runner_bootstrap_failure means runner or environment setup failed before XCTest attached; it can come from simulator boot, destination, launch session, artifact, or runner setup issues.

Signatures such as Unable to boot the Simulator, launchd failed to respond, Failed to start launchd_sim, NSPOSIXErrorDomain code=60, Failed to prepare device, or testmanagerd connection loss are classified separately from real test failures. submit --wait, status, and explain --json preserve the underlying detail and may suggest a bounded next step, such as shutting down or erasing the selected simulator before retrying once.

If the test command times out before XCSteward observes XCTest attach or test-execution evidence, it still stays runner_bootstrap_failure with diagnostic_excerpt.subtype = pre_xctest_timeout. Plainly: the test command hit its timeout before XCSteward observed XCTest attach evidence. The final summary says XCTest did not attach before the test command timed out, and terminal JSON can include the phase, timeout seconds, evidence paths, and a capped diagnostic excerpt.

xcsteward status <job-id> --watch
xcsteward explain <job-id> --json
xcsteward logs <job-id>

When a job is still queued or in simulator/bootstrap setup and the combined log is not ready, logs <job-id> points back to status <job-id> --watch instead of turning a pending log into an opaque missing-file error.

Try the alpha

Have a real failure mode around xcodebuild, simctl, Simulator readiness, cleanup, local CI-like workflows, or coding agents running iOS tests? Try the OSS alpha, or open an issue with your setup. It is local-first — no signup, no waitlist. The early feedback that helps most is specific: real logs, real setups, real failure modes, and the cases where XCSteward does not help.

Install with Homebrew:

# requires macOS with a recent local Xcode
brew tap acyment/tap
brew install xcsteward

Dogfooded across 16 real iOS projects and 160 local jobs — each tracked in the public dogfood ledger. It is honest about where it stands: early, alpha-stage OSS, narrow on purpose.

Read the full alpha & reporting guide →

Built by Alan Cyment, a Buenos Aires–based developer and organizational consultant, while dogfooding coding agents on iOS projects.