@unotest/web

AI-native E2E testing for web apps. You don't write the tests — your AI agent does, by driving your real app through the MCP server. You review and commit.

MCP server + CLI runner + JavaScript DSL + semantic DOM snapshots + structured failure bundles.

1. Setup

npx @unotest/web@latest init

Run once in your project — any stack (Node, Django, Rails, Go, …), no package.json required. init writes the config and a starter scenario, sets up the browser (bundled Chromium, or your system Chrome if you pick it during the prompt), and wires the MCP config so Claude Code / Cursor / Codex pick the server up automatically. Re-run anytime to update — it never overwrites your edits.

2. Open the viewer

npx @unotest/web viewer

A local IDE-style UI for your tests — no cloud, no account. This is your home base: browse scenarios, run them, and watch each step live. (Details in §5.)

3. Create a test — just ask your agent

In your AI editor (Claude Code, Codex, Cursor, …), open your project and describe the flow in plain English:

"Open https://playground.unotest.com, go to the Click vs Double-click section, click the Click me button, and check that a popup appears."

Through the MCP server the agent explores your live app — clicking, filling, reading the real DOM via semantic snapshots — then writes a clean scenario to unotest/e2e/<name>.js with stable selectors (getByTestId → getByRole → … — never brittle CSS), runs it, and debugs itself if it fails. You get a reviewable .js test: read it, tweak it, commit it.

For best results, point the agent at its authoring guide, shipped with the package at node_modules/@unotest/web/guides/agent-integration.md.

4. Run a test

Click any scenario in the viewer, or run from the CLI:

npx @unotest/web e2e <name>      # one scenario
npx @unotest/web e2e             # list / usage

5. Watch it run — the viewer

npx @unotest/web viewer opens a local UI (no cloud, no account):

• Scenario tree — scenarios, collections, helpers, and run history.
• Run from the UI — results stream live over WebSocket as steps execute.
• Block view — each step(...) group folds into a section with per-step status; a failure pins an error card to the offending line.
• Step debugger — set gutter breakpoints, run paused, inspect the live DOM at each stop.
• Inspector — screenshots and failure artifacts per run.
• Integrated terminal — a docked xterm (toggle ⌃`) to drive the CLI without leaving the window.

Writing by hand (optional)

Scenarios are plain .js. Every executable step sits inside a step("what this does", () => { … }) block — plain-English intent the agent reads back to repair a step when a selector drifts:

function test_login() {
  step("Log in as the demo user", () => {
    goto('https://app.example.com');
    fill(getByLabel('Email'), '[email protected]');
    click(getByRole('button', { name: 'Continue' }));
  });

  step("Dashboard is shown after login", () => {
    assertText(getByRole('heading'), 'Dashboard');
  });
}

The DSL uses the familiar modern browser-automation vocabulary, so it reads the way you already expect:

• Navigation — goto, reload, waitForUrl
• Locators — getByRole, getByTestId, getByLabel, getByText, getByPlaceholder, locator
• Actions — click, fill, press, hover, check, uncheck, selectOption
• Assertions — assertText, assertUrl, assertVisible, assertChecked, expect
• Setup — dbQuery, dbExec, apiCall, shell, evaluate

Full reference, shipped with the package: node_modules/@unotest/web/guides/dsl-reference.md (plus operational guides alongside it in guides/).

Ecosystem

| Package | Role | |---|---| | @unotest/web | this package — CLI / MCP server / runner | | @unotest/viewer | local results browser | | @unotest/protocol | shared types | | @unotest/dsl | scenario parser + validator engine |

License

MIT — see LICENSE.