SimLanes

Clean simulator lanes for multi-app Apple testing.

SimLanes prevents stale simulator installs, bundle-ID collisions, and fake release screenshots by proving app identity before it streams, screenshots, or hands a simulator to another agent.

Why

When several apps share simulator devices, it is easy to launch the wrong installed app under a reused bundle identifier or trust a screenshot from stale simulator state. This gets worse when multiple coding agents are building, installing, and screenshotting Apple apps in parallel.

SimLanes turns every simulator into an explicit lane:

app identity -> simulator UDID -> clean install -> identity proof -> launch -> screenshot/report

Install

pipx install git+https://github.com/anupamchugh/simlanes.git

For local development:

python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
pip install -e ".[dev]"
pytest

Quick Start

Create a manifest:

{
  "session": "apple-app-smoke",
  "apps": [
    {
      "label": "Example iOS",
      "platform": "iOS",
      "lane": "example-ios",
      "device": "00000000-0000-0000-0000-000000000000",
      "appPath": "build/Debug-iphonesimulator/Example.app",
      "bundleId": "com.example.app",
      "displayName": "Example",
      "conflicts": ["com.example.old"]
    }
  ]
}

Then run:

simlanes check examples/example-session.json
simlanes run examples/example-session.json --output build/simlanes --shutdown-after
simlanes run examples/example-session.json --queue
simlanes clean examples/example-session.json --serve-sim --continue-on-error

What It Checks

• Source .app/Info.plist exists.
• Source bundle ID matches the manifest.
• Source display name matches the manifest.
• A simulator lane is assigned to only one app identity.
• The same bundle ID is not reused for different display names in one session.
• Conflicting bundle IDs are uninstalled before install.
• Installed simulator app container matches the expected identity.
• simctl launch succeeds before screenshot/report capture.
• Optional serve-sim streaming starts only after identity passes.

Modes

Dedicated Lane Mode

Default. One app/platform gets one simulator UDID. This is the strongest anti-contamination mode.

simlanes run examples/example-session.json

Queue Mode

Queue mode lets apps share a simulator while serializing access with a lock file:

simlanes run examples/example-session.json --queue

Locks live at:

/tmp/simlanes/locks/<simulator-udid>.lock

Use this when watchOS or visionOS simulators are expensive to keep booted, or when multiple agents need a constrained simulator pool.

Reset Lane Mode

simlanes run examples/example-session.json --reset-lane

This shuts down and erases the simulator before install. It is slower but useful when simulator state is badly stuck.

Shutdown After Mode

simlanes run examples/example-session.json --shutdown-after

Use this for laptop-friendly sweeps. It shuts down each simulator after evidence is collected.

Clean Mode

simlanes clean examples/example-session.json --serve-sim --continue-on-error

Clean mode is manifest-scoped. It shuts down only the simulator lanes declared in your manifest and can also kill detached serve-sim helpers.

Reports

Each run writes:

• simlanes-report.json
• simlanes-report.md
• one screenshot per lane

Statuses:

Status	Meaning
PASS	Identity, install, launch, screenshot, and optional stream handoff completed.
WARN	Identity passed but launch proof was weaker than expected.
FAIL	A required lane step failed.

Relationship To serve-sim

serve-sim streams the simulator. SimLanes decides whether the simulator is safe to trust.

Good upstream pieces for serve-sim:

• manifest app identity preflight
• installed app identity verification
• app label/bundle metadata in stream JSON
• multi-device stream labels

Things SimLanes should keep:

• simulator lane policy
• multi-agent lock files
• reset/clean-room policy
• cross-app conflict policy
• release evidence reports

Build In Public

The first public wedge is simulator contamination: stop trusting screenshots and streams until the installed app identity is proven. The target user is an Apple app team using coding agents, CI, or parallel simulators across several apps.

Public progress should show real evidence:

• failed stale-app screenshots
• fixed SimLanes reports
• serve-sim integration PRs
• before/after simulator CPU/RAM cleanup
• real multi-app manifests

License

MIT