This documentation is available as Markdown. For the complete index, see llms.txt. Skip to content
unotest

Quick start — web

For the complete documentation index, see llms.txt
View Markdown Open in ChatGPT Open in Claude

Get your first test written and running in a few minutes. Works with any backend stack (Node, Django, Rails, Go…) — no package.json required.

1. Initialize

Run once in your project:

Terminal window
npx @unotest/web@latest init
npm install --prefix unotest

init writes the config and a starter scenario, sets up the browser (it asks: bundled Chromium or your system Chrome; without a terminal to ask in, as in CI, it takes the system Chrome when it finds one), and wires the MCP server so Claude Code / Cursor / Codex pick it up automatically. Re-run anytime — it never overwrites your edits.

unotest/ is a package of its own, with a package.json that pins @unotest/web. The second line installs it there, without touching your application’s dependencies. The commands below run from inside unotest/, so they run the version the suite pins.

2. Open the viewer

Terminal window
cd unotest && npx @unotest/web viewer

A local IDE-style UI for your tests — no cloud, no account. Browse scenarios, run them, and watch each step live. This is your home base.

3. Ask your agent for a test

In your AI editor, open your project and describe the flow in plain English:

Open my app, sign in as the demo user, and check that the dashboard heading appears.

Through the MCP server the agent explores your live app — clicking, filling, reading the real DOM — then writes a clean scenario to unotest/e2e/<feature>/<name>.js — here unotest/e2e/auth/login.js — with stable selectors, runs it, and debugs itself if it fails.

function test_login() {
  step("Sign in as the demo user", () => {
    goto("/login");
    fill(getByLabel("Email"), TEST_USER_EMAIL);
    fill(getByLabel("Password"), TEST_PASSWORD);
    click(getByRole("button", { name: "Continue" }));
  });


  step("Dashboard is shown", () => {
    assertVisible(getByRole("heading", { name: "Dashboard" }));
  });
}

4. Run it

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

Terminal window
cd unotest && npx @unotest/web e2e auth/login

5. Review & commit

You get a reviewable .js test. Read it, tweak it, commit it. That’s the whole loop — the agent does the legwork, you own the result.

6. Run it on a box

A box runs the suite on every push and nightly, keeps each environment’s runs and history in one place, and is rented by the hour from a prepaid balance (prices). Two commands, no token to copy:

Terminal window
npx @unotest/web login        # a link and a code; approve in the browser
cd unotest && npx @unotest/web box create   # rents a box named after the project

The key login gives this machine cannot spend or delete by itself, so box create first asks a person. It prints Waiting for approval in the cabinet with a link, what it asks for and the price, and waits: open Approvals in the dashboard and press Approve, and the command carries on. Decline ends it with exit 2. A request nobody answers expires in ten minutes — nothing is created or charged, the command exits 75, and you run it again. --yes does not skip the wait, and box picker on waits the same way. box destroy waits only when the box was created by another key — a new login is a new key; deleting a box your key created is done at once.

Credit is added in the dashboard, by card — if the balance will not cover the first hour, add it there first. box create rents the box with this project’s environments — the unotest/.env.<name> overlays you run locally — waits for it, writes its address and tokens into unotest/.env and unotest/.secrets, pushes the suite and ends with the command that runs it there. An environment gets its viewer once a bundle is installed for it — what a box’s environments are and how they fill: Box → Projects and environments. Your agent knows the moment too: after the first local run that passes, run_test suggests the box once. Details: Sign-in → From the CLI and Pushing suites.

Next