Skip to content

English · 日本語

Getting started — iOS track

Finishes the Getting started loop on an iOS Simulator via the XCUITest backend (the sole iOS backend since BE-0290 retired idb). Needs macOS + Xcode. On a machine without a Mac, follow the web track instead — the same loop against a browser, no Xcode or Simulator required.

Related: Getting started · web track · showcase · drivers

Complete Steps 1–3 of the shared walkthrough first (install, unit tests, read a scenario) — they need nothing Mac-specific. This page picks up at Step 4.

What you'll need

For… You need
Steps 1–3 (shared) macOS or Linux, Python 3.13 (managed via uv)
Steps 4–5 below macOS with Xcode (the iOS Simulator + xcodebuild, which the XCUITest backend drives) and XcodeGen (to build the showcase). No extra brew install or pip extra — the XCUITest backend needs only Xcode

Step 4 — Build the showcase app

The repo ships the showcase fixture — the same app in SwiftUI and UIKit, each in an accessibility-on / -off variant — instrumented for every Bajutsu primitive. Build the SwiftUI accessibility product for the Simulator:

make -C demos/showcase swiftui-build         # xcodegen generate -> xcodebuild for the iOS Simulator

This produces BajutsuShowcaseSwiftUI.app under demos/showcase/ios/swiftui/build/…. (The .xcodeproj and build/ are gitignored — project.yml is the source of truth.) See showcase for the launch-env hooks and the identifier catalog.

Step 5 — Run a scenario on a Simulator

Boot a Simulator:

xcrun simctl boot "iPhone 15"                 # or boot one from Xcode > Open Developer Tool > Simulator

The XCUITest backend drives the app through a prebuilt on-device runner (the target's xcuitest.testRunner). The showcase config wires that runner and builds it for you as part of the one-shot make target below (make runner-build), so there is nothing extra to install — Xcode alone is enough.

The one-shot path is the make target. It builds the runner, installs the freshly built app, and runs the full showcase suite (skipping scenarios tagged xcuitest, systemalert, visual, or android, each of which has its own lane) on the booted device:

make -C demos/showcase run-swiftui

Or drive the CLI directly against the smoke scenario alone — a quicker, single-scenario check:

uv run bajutsu run --scenario demos/showcase/scenarios/smoke.yaml --target showcase-swiftui --backend ios --udid booted --no-erase

What the flags mean:

  • --target showcase-swiftui selects targets.showcase-swiftui from demos/showcase/showcase.config.yaml (bundle id, launch env, allowed id namespaces). The tool itself is app-agnostic; all per-target differences live in config (configuration).
  • --backend ios picks the iOS actuator (XCUITest; --backend xcuitest names it explicitly); --udid booted targets the currently booted Simulator.
  • --no-erase keeps the already-installed app instead of simctl erase-ing first.

On success you'll see a line like:

PASS  runs/20260610-120000/manifest.json

run exits 0 when every scenario passes, 1 on any failure, and that exit code is the CI (continuous integration) gate (run-loop).

Hit an environment problem (no booted Simulator, Xcode command-line tools missing)? Run uv run bajutsu doctor --target showcase-swiftui first — it prints a ✓/✗ checklist of the required CLIs and a booted device, then scores how well the current screen follows the identifier convention (configuration).

Continue to Step 6 — Read the report in the shared walkthrough.

Author with AI (iOS)

Let Claude explore the showcase app toward a goal and write the scenario for you (Tier 1). Put ANTHROPIC_API_KEY=sk-ant-… in a .env file, then:

uv run bajutsu record --target showcase-swiftui --goal "log in and increment the counter to 3"   # writes into the app's scenarios dir

Emit a native XCUITest

uv run bajutsu codegen demos/showcase/scenarios/smoke.yaml --target showcase-swiftui -o UITests/Smoke.swift

make -C demos/showcase ui-test shows the same pipeline end to end for real: it re-generates the repo's own checked-in fixture from components.yaml (a different scenario from the one above), then builds and runs it with xcodebuild test — codegen's real-compile verification, not a replay of the Smoke.swift file generated above. The structural mapping: codegen.