Skip to content

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 expect judges.
  • Selectors are id-first. Here the id is data-testid, the web equivalent of iOS's accessibilityIdentifier, 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 web selects targets.web from demos/web/demo.config.yaml (its platform: web, subject.url, and scenarios dir). The tool itself is app-agnostic, and all per-target differences live in config (configuration).
  • --backend web checks the backend. The target's platform: web already 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 --scenario to run the target's whole scenarios directory (what make -C demos/web e2e does).

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.yaml first. 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.