plain

From an agent session.
To a test you can keep.

Explore with your coding agent. Keep the passed steps as plain-English YAML. Replay the flow from your terminal.

All install options

For Claude Code, Codex and other MCP clients.

ExploreSaveReplay
Claude Code · browser plugin
/plugin marketplace add gabe4coding/plain
/plugin install plain@plain-marketplace

Jev is the small decision model that selects targets and checks claims.

Explore the app.
Describe the action.

Your agent sends targets and claims through MCP. Jev picks from structured candidates and judges accessible state.

Passed actions.
Written in plain language.

The flow takes shape as you explore. Only passed actions become steps in the saved spec.

The session ends.
The test stays.

Save writes the passed steps as YAML. Read it. Edit it. Commit it.

Run it again.
Without the agent.

The CLI replays your saved flow from its lock file. In no-judge mode, that takes no model call and no API key.

demo.playwright.dev / todomvc

A little less to do.

Your test environment.

What needs to be done?
buy milk
write a regression test
2 items left All · Active · Completed

“Add buy milk to the list.”

fill

the new todo input

press

Enter

expect

a todo item named ‘buy milk’ is listed

Passed steps

add-todo.yamlSaved spec
name: add a todo
url: https://demo.playwright.dev/todomvc
steps:
  - goto: /
  - fill:
      target: "the new todo input"
      value: "buy milk"
  - press: Enter
  - expect: "a todo item named 'buy milk' is listed"
Plain language. A file you own.
Your terminal
$ npx -p @gabe4coding/plain plain --mode no-judge add-todo.yaml

✓ goto
✓ fill
✓ press
✓ expect

Flow replayed

No coding agent. No model call.
A changed step is inconclusive, never passed.

plain, explained.

A seven-minute walkthrough of plain-English specs, Jev, the three engines, agent mode and the pick cache.

Same plain language.
Different engines.

A website. A desktop app. A phone. The language is familiar; the setup belongs to each platform. Not one portable spec.

the-internet.herokuapp.com / dropdown

Choose an option.

Dropdown List

Option 2

Selected: Option 2

The browser.

Playwright performs browser actions. Jev selects targets and checks accessible state.

url: https://the-internet.herokuapp.com
steps:
  - goto: /dropdown
  - select: { target: "the dropdown list",
              value: "Option 2" }
  - expect: "the dropdown's selected option is Option 2"

plain · Playwright

Full browser example ↗
Desktop Test Fixture

A message in progress.

Hello from the test app.
Preview

Preview before you send.

The desktop.

xa11y works with the native accessibility tree. macOS is tested; Windows and Linux parity is not verified.

app: Desktop Test Fixture
steps:
  - fill: { target: "the Message text field",
            value: "Hello from the test app." }
  - click: the Preview button

plain-computer · xa11y
Native accessibility permissions required.

Desktop setup ↗

Your test app.

buy milk
Add
buy milk

The phone.

Appium drives iOS and Android, React Native apps included. Use a configured Appium server and an installed app on a test device or simulator.

platform: android
device: emulator-5554
app: com.example.todo
steps:
  - tap: the Add button

plain-mobile · Appium
Platform, device and app are explicit.

Mobile setup ↗

Less time.
Measured, not promised.

Six local browser workflows. 108 trials against Playwright MCP 0.0.82.

25–52%lower mean time, by model

About the same API cost (−24% to +7%, including the agent + Jev)

21 September 2026 · revision 0c1698e. Synthetic interfaces; results depend on task and model. Two cost intervals include parity.

What the comparison measures

Discovery, actions, checks and recovery across six local workflows. A strict baseline failure involved a duplicate save.

The historical benchmark measures agent workflows, not a complete saved-spec round trip. Task-level results ↗

Choose who makes
the decision.

Different tools, different responsibilities.
ResponsibilityplainHandwritten PlaywrightPlaywright MCP
Plan the flowYou, or your coding agentYou, in test codeYour coding agent
Pick an elementJev selects a described targetYour explicit locatorAgent chooses a locator or snapshot reference
Check the resultJev judges a claimYour assertionAgent checks tool output or writes an assertion
Keep and replaySave passed MCP steps as YAML with a lock file. No-judge replay needs no model.Commit test code. Runner needs no model.Agent can write tests. No plain YAML save/replay contract.

Use conventional tests for exact API contracts, pixel comparisons, custom fixtures and assertions that must not depend on model judgment.

Uncertain is not passed.

Jev selects and checks. The engine acts. An uncertain result stays inconclusive, with evidence you can inspect.

Put it to work.

Install the browser plugin in your coding agent, or run a spec with npx. Use Node 22 or newer and npm. Add a provider key before your first run.

In Claude Code
/plugin marketplace add gabe4coding/plain
/plugin install plain@plain-marketplace
In your terminal
codex plugin marketplace add gabe4coding/plain
codex plugin add plain@plain-marketplace
In your terminal
npx -p @gabe4coding/plain plain todo.yaml

Then, add your key.

All plugins and CLIs read the user env file. Do not commit it.

# ~/.config/plain/.env
TYPESAFE_API_KEY=<your key>

Get a key from TypeSafe ↗, or follow the Vercel AI Gateway key setup ↗. For Gateway, use AI_GATEWAY_API_KEY instead.

Key and environment options ↗

Plugins: plain for browser, plain-computer for desktop, plain-mobile for mobile.

npx installs the package. plain installs Chromium on first run. For other engines, see all plugin instructions.

One file.
Terminal to CI.

Start with the repository’s todo spec. It uses a public demo, needs no login and starts with goto.

Download todo.yaml

Exact repository spec.

Run the first spec.

npx -p @gabe4coding/plain plain todo.yaml

Set the API key first. npx installs the scoped package. plain installs Chromium on its first run.

Then run it in GitHub Actions

Commit todo.yaml at your repository root. Save this workflow as .github/workflows/browser-specs.yml.

name: Browser specs
on: [pull_request]
permissions:
  contents: read
jobs:
  specs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: gabe4coding/plain@v3.1.0
        with:
          specs: todo.yaml
          mode: auto-healing
          junit: plain-results/junit.xml
          artifacts: plain-results
          artifact-name: plain-results
        env:
          TYPESAFE_API_KEY: ${{ secrets.TYPESAFE_API_KEY }}
Download the workflow

Set TYPESAFE_API_KEY as a repository secret. Fork pull requests do not receive this secret.

Run the spec once on your computer and commit its lock file. Then set mode: no-judge: the CI run makes no model call and needs no key.

Pinned to v3.1.0, the published release. @main can run a commit before npm has that version.

The action uploads JUnit on every run and failure artifacts when a run fails. It does not publish a results check.

Action setup and inputs ↗ · Report formats ↗ · Screenshots and traces ↗

Workflow from the CI guide and action.yml.

More examples: forms, spatial claims and native apps
Forms, selects and checkboxes
Public demo at the-internet.herokuapp.com. No login or hooks. Download the exact spec. Run npx -p @gabe4coding/plain plain components-forms.yaml.
Repeated controls in rows and cards
The corrected benchmark includes catalog browsing and account-row edits. Read the task-level results ↗. Reproduction needs the local workflow harness and provider keys, not a standalone public-page spec.
Spatial claims
Read the local fixture spec ↗. Run from a built checkout with node scripts/e2e.mjs --only spatial --skip-mcp. The runner serves the fixture locally.
Native apps
Mobile examples and exact setup ↗. Appium, the platform driver and a test device or simulator are prerequisites. Preserve the fixture hooks and relative paths. Desktop setup and permissions ↗.

Before you run it.

Does replay still cost model calls?

Not in no-judge mode. It replays the committed lock file with no Jev call and no API key. A step that changed is inconclusive, never passed. The default auto-healing mode replays the lock file too, but Jev repairs changed steps and judges every claim. Run modes ↗ · Measured costs ↗.

What is the lock file?

A passing run writes a lock file next to each spec: a locator for each target and a hash of each passing claim. Commit it with the spec. A diff shows which step changed. It holds no values from env or hooks. Lock files ↗.

What happens when a target is ambiguous?

A weak pick is inconclusive, not passed. Write specific targets and scope claims with within. Thresholds and phrasing ↗.

Can it understand layout and visual appearance?

Jev reads structured candidates and accessible state, not screenshots. Spatial prompts also receive rendered bounds. Bounds do not prove color or image appearance. Evidence and limits ↗.

What do I need, and where is my key?

Node 22+, npm and a TypeSafe or Vercel AI Gateway key. All CLIs read ~/.config/plain/.env. Desktop needs accessibility permissions. Mobile needs Appium and a configured device. Requirements and key options ↗.

Is this a replacement for every test?

No. Keep explicit conventional tests for exact assertions and pixel-level checks. Use test environments only. Stop before payment, booking or sending. Usage rules ↗.