English · 日本語
Bajutsu documentation¶
Implementation-grounded reference for the natural-language-driven end-to-end (E2E) testing tool. Its deterministic core is platform-neutral. The one platform-specific seam is the backend behind a single
Driverinterface, so a new platform is a new backend. The iOS Simulator (XCUITest) backend, a web (Playwright) backend, and an Android (adb) backend have all landed. Flutter apps run through those same backends unchanged, with no separate Flutter backend.
README.mdis the introduction, andDESIGN.mdcovers the design rationale. This set of pages explains what the code actually does today, feature by feature. Planned work is in the roadmap.
Bajutsu takes test scenarios written in (or recorded from) natural language, drives an app (tap / type / swipe / wait), and verifies the result with machine-checkable assertions. The backend is the only platform-specific seam, so swapping it runs the same scenarios on the iOS Simulator (XCUITest) or in a browser (Playwright).
The central idea is to keep AI out of the continuous integration (CI) gate. AI is the scenario author and the failure investigator, never the pass/fail judge (see concepts).
The big picture of the data flow¶
architecture shows which module owns each box and how the modules depend on each other, including a dependency-layer view of the same system.
Pages (suggested reading order)¶
New here? Start with the Getting started tutorial, a hands-on walkthrough (install → unit tests → scenario → device run → report). Then return to the reference pages below. On a machine without a Mac (Linux, Windows, a container), follow the web track instead. It runs the same loop against a browser with the Playwright backend, and needs no Xcode or Simulator.
| # | Page | What it covers |
|---|---|---|
| 1 | concepts | Design philosophy & core principles (determinism, two tiers, stability ladder, the AI boundary) |
| 2 | glossary | Term-by-term reference for the domain vocabulary; disambiguates the near-synonym clusters (driver / backend / actuator / platform · target / app / device · scenario vs. test · trace vs. triage) |
| 3 | architecture | Module layout, dependencies, and the implementation status (implemented / unwired) |
| 4 | developer-guide | A guide to the source tree and how to work in it: file layout, the four contracts, the scenario DSL and selectors, the classes in each layer, and the development and verification routine |
| 5 | scenarios | Scenario YAML grammar (steps / waits / assertions / capture tokens) = the authoring reference |
| 6 | dsl-grammar | The formal grammar of the scenario DSL (domain-specific language) — EBNF + every validation constraint — the normative spec behind scenarios |
| 7 | selectors | Selector model and deterministic resolution (0/1/2+ matches); how assertions evaluate = the determinism core |
| 8 | drivers | Driver abstraction · XCUITest (iOS) / playwright (web) / adb (Android) / fake · capability differences · the simctl environment |
| 9 | run-loop | Orchestrator (observe → act → verify) · waits · retries · run results |
| 10 | evidence | Evidence subsystem (instant / interval · capturePolicy · provider · redact) |
| 11 | reporting | Reports (manifest.json / JUnit / HTML) and the runs/ layout |
| 12 | configuration | Config layering (defaults × targets) · onboarding a new target · the doctor convention score |
| 13 | recording | AI authoring (Tier 1 record) · the Agent abstraction · system-alert handling |
| 14 | codegen | Scenario → native XCUITest / Playwright / UI Automator generation |
| 15 | cli | Full reference for CLI commands and options |
| 16 | showcase | The showcase suite — the single iOS fixture (exercises every primitive) |
| 17 | ci | Running in CI — the repo's own workflows + the reusable bajutsu-e2e action |
| 18 | self-hosting | Run serve as a token-authenticated LaunchAgent on a single Mac behind Tailscale (BE-0016 Tier A) |
| 19 | vision | The three axes of growth (reach / scale / authoring) — how far each has already gotten, and the constraints all of them respect; reach's platform-portability design (selectors, id conventions, phasing) lives in its own section |
| 20 | ai-development | Working agreement for AI agents + humans in parallel (the gate, branches, pre-push hook, worktrees) — the long form of CLAUDE.md |
| 21 | roadmap-workflow | The ideation → implementation cycle: the ideation skill authors a BE proposal, the implement-be skill ships it (placeholder IDs, the Approved → Implemented lifecycle) |
| 22 | contributor-workflow-tutorial | Hands-on walkthrough of that cycle: one idea from /ideation to a merged proposal, then /implement-be to a merged PR, with a worked good-vs-bad proposal example and when to use propose-and-build |
Quick start¶
uv sync --group dev # .venv + deps + dev tools
uv run pytest -q # unit tests (no Simulator needed)
# Against the showcase fixture (needs a real Simulator)
make -C demos/showcase swiftui-build # build the fixture app
make -C demos/showcase run-swiftui # run the scenarios on the iOS (XCUITest) backend
Minimal CLI:
bajutsu run --target <name> [--scenario file.yaml] # default: the app's whole scenarios dir
bajutsu doctor --target <name> # convention score
bajutsu record --target <name> --goal "..." [--out file] # AI explore + record (needs API key)
bajutsu codegen <scenario.yaml> --target <name> -o UITests/Foo.swift
bajutsu serve # local web UI (Tier 1; not for CI)
cli lists every command and option.
How this documentation is written¶
- Code is the source of truth. Each statement maps to the current implementation (
bajutsu/), withfile.py:linepointers at key spots. - Design vs. implementation gaps are explicit. A feature that
DESIGN.mddescribes but the code does not yet wire up (the externalmockServercommand, superseded by scenariomocks) is flagged on each page and in the architecture status table. - Languages. English is primary, and a Japanese translation lives under
ja/. Code comments and docstrings are in English.