English · 日本語
Getting started — run a scenario in a browser¶
This page finishes the Getting started loop on any operating system. It runs against a real web app in a browser through the Playwright backend, with no macOS, no Xcode, and no iOS Simulator. If you also have a Mac, the iOS track finishes the same loop on a Simulator instead.
Related: Getting started · iOS track · drivers · glossary
Complete Steps 1–3 of the shared walkthrough first: install, run the unit tests, and read a scenario. Step 1 there covers the base install, and this page adds the one extra line the web backend needs. This page picks up at Step 4.
Why a web track¶
Bajutsu's headline claim is "a platform is a backend". The deterministic core, the scenario
format, and the reporter are identical whichever backend actuates the UI. The
iOS track finishes on a Simulator (the XCUITest backend), which needs a Mac with Xcode.
This track finishes the same loop against a browser (the web / Playwright backend), which runs on
Linux, Windows, or macOS alike. The same backend drives Bajutsu's own web demo on the Linux gate
(demos/web).
The vocabulary here follows the glossary. A backend is the platform a target
declares with platform: (here web). It resolves to an actuator, the Playwright engine that
performs the taps and types. A target is one targets.<name> config entry describing the app
under test. A web target names its app by subject.url, whereas an iOS target names it by
subject.id.
What you'll need¶
| For… | You need |
|---|---|
| Steps 1–3 (shared) | any OS, Python 3.13 (managed via uv) |
| Steps 4–5 below | uv sync --extra web + uv run playwright install chromium (no Mac / Simulator) |
uv sync --extra web # adds the Playwright python package
uv run playwright install chromium # downloads the Chromium binary Playwright drives
The --extra web line and the playwright install line are what the web backend adds on top of
the base install from Step 1. The Chromium binary is a separate
download, not a pip dependency.
Step 4 — Serve the demo web app¶
The web demo ships a tiny static app under demos/web/app: onboarding →
login → counter, written in vanilla JavaScript with stable data-testid ids. Serve the app locally
so that a browser (and Bajutsu) can reach it:
make -C demos/web app-serve # serves demos/web/app on 127.0.0.1:8787 (Ctrl-C to stop)
Leave the server running and open http://127.0.0.1:8787/index.html in your own browser to try the app by hand. Click Get started, sign in with any email and password, and increment the counter. That is exactly the flow the demo's scenario automates:
scenarios:
- name: onboard, log in, and increment the counter
steps:
- tap: { id: onboarding.start }
- type: { text: "a@b.com", into: { id: auth.email } }
- type: { text: "pw", into: { id: auth.password } }
- tap: { id: auth.submit }
- wait: { for: { id: home.title }, timeout: 5 } # condition wait, never a fixed sleep
- tap: { id: counter.increment }
- tap: { id: counter.increment }
expect:
- exists: { id: home.title }
- value: { sel: { id: counter.value }, equals: "2" }
This scenario uses exactly the same step/expect grammar as the iOS track's smoke test:
- Steps act, and
expectjudges. - Selectors are id-first. Here the id is
data-testid, the web equivalent of iOS'saccessibilityIdentifier, and it goes through the same selector-resolution core as every other backend (selectors, drivers). - Waits are conditions.
- An ambiguous selector fails immediately.
Only the specific scenario differs from track to track. See
demos/web/scenarios/smoke.yaml for the full file.
Step 5 — Run a scenario in the browser¶
The one-shot path is the make target. It installs the web backend if needed, serves the app in
the background, runs the demo's scenarios through Playwright, and tears the server down. No manual
serve is required.
make -C demos/web e2e
Alternatively, drive the CLI directly against the app you served in Step 4. This is the same run, written out:
uv run bajutsu run --scenario demos/web/scenarios/smoke.yaml --target web --backend web --config demos/web/demo.config.yaml
The flags mean the following:
--target webselectstargets.webfromdemos/web/demo.config.yaml(itsplatform: web,subject.url, and scenarios dir). The tool itself is app-agnostic, and all per-target differences live in config (configuration).--backend webchecks the backend. The target'splatform: webalready picks the actuator, the Playwright engine driving Chromium. A value that disagrees with the target exits with code 2. No Xcode and no Simulator are involved.- Omit
--scenarioto run the target's whole scenarios directory (whatmake -C demos/web e2edoes).
A successful run prints a line like this:
PASS runs/20260610-120000/manifest.json
run exits 0 when every scenario passes and 1 on any failure. The continuous integration (CI)
gate reads that exit code (run-loop). The verdict comes purely from the
scenario's machine assertions (the counter reads 2), never from an LLM.
Hit an environment problem, such as Chromium not installed or the web extra missing? Run
uv run bajutsu doctor --target web --config demos/web/demo.config.yamlfirst. It prints a ✓/✗ checklist of what the web backend needs.
Continue to Step 6 — Read the report in the shared walkthrough
(open with xdg-open on Linux instead of open).
Author with AI (web)¶
Let Claude explore the web app toward a goal and write the scenario for you (Tier 1). Put
ANTHROPIC_API_KEY=sk-ant-… in a .env file, then run:
make -C demos/web record GOAL="Get started, then increment the counter three times and confirm it shows 3."
With no key and no browser, the offline twin reproduces the same record loop deterministically
(make -C demos/web record-offline). recording explains how the authoring loop
works.
Onboard your own web app¶
Add a targets.<name> entry with platform: web and your app's URL as subject.url. Then give the
app's elements stable data-testid ids. See configuration.