XCSteward

Home / Alpha

Try the XCSteward 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.

Get it on GitHub Browse failure modes

XCSteward is an early, open-source alpha. It is local-first and runs on your Mac — there is no signup, no waitlist, and no account. The honest deal: it is most useful if you can point it at a real, reproducible failure rather than try it out of curiosity.

Current CLI workflow

Install the CLI locally, create or inspect a project profile, then run through the human or machine path. XCSteward's product surface is the CLI and its JSON contract; there is no hosted service or dashboard involved. 

# requires macOS with a recent local Xcode
brew tap acyment/tap
brew install xcsteward
xcsteward profile init --detect --json

Human path

A plain wait prints the queued job id, status/log/watch/follow commands, job directory, and compact updates. Use watch or follow from another terminal when you want to keep observing an existing job. 

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

Agent path

Agents and scripts should parse JSON from stdout and ignore human text. Add --progress to long-running JSON waits when stderr JSON events are useful; when command events are available those progress lines add phase and phase_elapsed_seconds. Then use explain --json for bounded triage before opening raw logs. 

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

Useful supporting commands include projects --json, profile show <name> --json, status <job-id> --watch --json for newline-delimited JobSummary updates, repeatable submit --metadata key=value plus --label, repeatable submit --env KEY=VALUE for per-run xcodebuild environment injection, and cleanup --caches for XCSteward-owned cache and retained evidence cleanup. XCSteward records env override keys, not sensitive values.

Failure inspection

If build succeeds but the test runner never really starts, XCSteward treats the outcome as environment/bootstrap failure rather than real test execution failure. runner_bootstrap_failure means runner or environment setup failed before XCTest attached; inspect the summary first, then use explain --json before opening raw logs.

If the test command hits its timeout before XCSteward observes XCTest attach evidence, the subtype is pre_xctest_timeout: the command timed out before XCSteward observed real test execution. That stays a runner/bootstrap diagnosis, not a timed-out test case. 

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

When a job is queued or still in simulator/bootstrap setup, the combined log may not exist yet. In that case logs <job-id> reports that it is pending and points back to status <job-id> --watch.

doctor still keeps project preflight bounded. If .xctestrun integrity checking times out during a cold or long build, the warning now says no compiler error was observed before timeout, which is clearer diagnosis, not an invitation to wait forever.

Who this is for

Worth trying if you hit

  • Local simulator test runs that hang before tests start.
  • xcodebuild getting stuck resolving or booting destinations.
  • simctl or CoreSimulator getting wedged or deadlocked.
  • Cleanup and preboot scripts that have crept into your test ritual.
  • Local, CI-like test workflows running on a Mac.
  • Coding agents — or several scripts, jobs, and humans — touching Xcode tooling.

Not the right tool for

  • Broken tests that fail on their own logic.
  • App-level UI test flakiness and timing bugs in your test code.
  • Code signing and provisioning problems.
  • Missing or un-downloaded Xcode runtimes.
  • Bugs inside a specific simulator runtime / vendor image.
  • Network, backend, or mock-server instability.

What feedback is most valuable

Early on, depth beats volume. The reports that move the tool forward are specific: