@unotest/web 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,158 @@
+# Changelog
+
+All notable changes to `@unotest/web` are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.5.0] - 2026-05-29
+
+### Added
+
+- **Recording mode (exploration sessions).** Eight new MCP tools —
+  `explore_start`, `explore_stop`, `explore_state`, `explore_step`,
+  `explore_record`, `explore_remove_step`, `generate_dsl_from_exploration`,
+  `save_exploration_as_test`. The agent drives the browser through
+  `explore_step`, which both executes the action and records it into a
+  session log. When done, `save_exploration_as_test` generates a DSL
+  scenario and runs it via `run_test`. Session data persists as JSONL
+  under `unotest/.explorations/` (override via `EXPLORATIONS_DIR`).
+- **Ref resolve-on-record.** Wire-only `{kind:"ref",ref:"eN"}` locators
+  emitted by `get_page_snapshot` are resolved to stable forms
+  (`getByTestId` / `getByRole` / `getByLabel` / `getByText` / `locator`)
+  at record time. The persisted scenario contains no stale refs; execution
+  still uses the original ref-locator for precise targeting.
+
+### Changed (BREAKING)
+
+- **14 per-action MCP tools removed.** `click`, `double_click`, `fill`,
+  `hover`, `press`, `check`, `uncheck`, `select_option`,
+  `scroll_into_view`, `goto`, `reload`, `wait_for`, `wait_for_text`,
+  `wait_for_url` are replaced by `explore_step { action, locator, … }`.
+  Without an `explorationId`, `explore_step` runs the action ad-hoc with
+  the same semantics as the removed tools.
+
+## [0.4.0] - 2026-04-25
+
+### Added
+
+- **Debug logging v2 — folder per call (`UNOTEST_DEBUG=1`).** Each MCP
+  tool call gets its own directory `unotest/.debug/<session>/<NNN>-<tool>/`
+  containing: `call.json` (args, events, result), `before.html` / `after.html`
+  (full shadow-pierced DOM), `before.txt` / `after.txt` (outline),
+  `diff.txt` (line-level LCS diff of outline), `aria.yaml` (ARIA tree),
+  `resolved/<ref>.html` (outerHTML of the resolved element). On failure:
+  `page.html` + `screenshot.png`. Levels: `=1` / `=full` all artifacts;
+  `=summary` tool + snapshot only, no HTML; unset — no I/O.
+- **`audit_last_run` MCP tool.** Deterministic rule-based audit of the
+  last debug session: catches `ref-before-snapshot`, `resolve-loop`,
+  missing `section` descriptions, and selector downgrades.
+- **`get_last_mcp_log` filters.** `errors`, `layer:N`, `tool:N`,
+  `exploration:<id>` — narrow the JSONL log to relevant events.
+- **Resolver: `data-*` stable-id hints.** `data-id`, `data-guid`,
+  `data-key` and similar attributes are detected and used as primary
+  CSS selectors (`[data-id="…"]`), making table-row locators stable
+  across re-renders.
+- **Resolver: tooltip / label `data-*` hints.** `data-tooltip`,
+  `data-shadow-title`, `data-original-title` and similar attributes
+  provide display names for icon-only controls.
+- **Resolver: clickable-row detection.** Non-control elements with
+  `cursor:pointer` or `onclick` and a stable `data-*` id appear in
+  the outline as `[clickable]` entries, collapsing large grids to the
+  meaningful rows.
+- **Ancestor-scope disambiguation.** When a best locator candidate is
+  ambiguous (multiple matches), the resolver climbs to the nearest
+  unique ancestor and emits a single combined CSS selector
+  (`<ancestorSel> <childCss>`) rather than failing.
+
+## [0.3.0] - 2026-03-18
+
+### Added
+
+- **`UNOTEST_DEBUG` logging.** Set `UNOTEST_DEBUG=1` to write a
+  structured JSONL log to `unotest/.debug/mcp-latest.jsonl`. Captures
+  tool calls, resolver decisions, and driver events. Readable via the
+  `get_last_mcp_log` MCP tool.
+- **`get_last_mcp_log` MCP tool.** Returns the last N lines of the
+  debug log. Agents use it to self-diagnose stale refs and resolve
+  failures without human intervention.
+- **Shadow DOM full-capture.** `before.html` / `after.html` artifacts
+  pierce shadow roots via `getComputedStyle` — plain `outerHTML` misses
+  shadow-hosted content.
+
+### Fixed
+
+- Outline renderer truncated role names longer than 32 chars; now
+  preserves full name.
+- `RefResolver` emitted duplicate `getByText` selectors when two
+  adjacent elements had identical visible text; now falls back to
+  positional nth-selector.
+
+## [0.2.0] - 2026-01-08
+
+### Added
+
+- **Local results viewer (`unotest-web viewer`).** Opens a browser UI
+  showing live test results, step logs, and screenshots. Backed by
+  [`@unotest/viewer`](https://github.com/unotest/viewer) — installed
+  automatically as a dependency.
+- **`open_viewer` MCP tool.** Starts the viewer server in the background
+  and returns its URL. Subsequent calls reuse the running instance.
+- **Collection runner (`unotest-web collection <name>`).** Runs every
+  scenario listed in `unotest/e2e/_collections/<name>.yaml` under a
+  shared parent run-id. Supports `--workers=N` for parallel execution
+  and `--bail` to stop on first failure.
+- **`install-chromium` command.** Downloads Playwright's bundled Chromium
+  (~150 MB) for environments without a system browser.
+- **`list_runtimes` MCP tool.** Returns all active scenario runtimes in
+  the current session (run-id, scenario name, status, step count).
+
+### Fixed
+
+- `unotest-web init` failed silently when the target directory existed
+  but was missing `unotest/`; now creates missing subdirectories.
+- `run_test` returned a stale run-id when called concurrently with an
+  in-progress run; each call now allocates a fresh id atomically.
+
+## [0.1.0] - 2025-10-01
+
+Initial release.
+
+### Added
+
+- **DSL — JavaScript scenarios on a sandboxed AST engine.** Scenario
+  files are `.js` in `unotest/e2e/` using Playwright-vocabulary
+  primitives (`goto`, `click`, `fill`, `getByRole`, `getByTestId`,
+  `assertText`, and ~54 others). The AST parser (now published as
+  [`@unotest/dsl`](https://github.com/unotest/dsl)) supports method
+  chains, options-object literals, and raw backtick strings.
+- **MCP server with 37 tools.** Bundled server (`unotest-web mcp`,
+  default subcommand): 6 debugger tools (`run_test`, `step`, `resume`,
+  `inspect_runtime`, `abort_runtime`, `list_runtimes`), 21 browser
+  interaction tools, 4 multi-context tools (`list_pages`, `switch_page`,
+  `new_context`, `close_context`), 6 failure-bundle tools, and
+  `agent_fix`.
+- **Semantic DOM canvas.** Inspection layer producing a compact,
+  agent-readable view of the page (role / name / relevant attributes).
+  Used for both live snapshots and failure bundles.
+- **Failure bundle — tier 1 + 2 capture.** On test failure the runner
+  writes `failure.json`, `console.json`, `snapshot.json`, and
+  `screenshot.png` to `unotest/.runs/<runId>/`. Accessible via
+  `list_failures`, `get_failure_trace`, and related MCP tools.
+- **`agent_fix` workflow.** `mcp__unotest-web__agent_fix` builds a
+  structured fix-context bundle (last failure, relevant DOM, scenario
+  excerpt). The package does not call an LLM or auto-apply patches —
+  human review is required.
+- **AST scenario linter (`unotest-web lint`).** Six rules: deep CSS
+  selectors, XPath, obfuscated class names, explicit `pause()` calls,
+  disambiguate-by-index, and discouraged `evaluate()` patterns. Severity
+  is config-driven via `unotest.config.*`.
+- **Project-agnostic sandbox primitives.** `shell(cmd, …args)` (execFile,
+  no shell interpolation), `dbQuery` / `dbExec` (lazy peer dependency —
+  pg / mysql2 / better-sqlite3 resolved from `sandbox.database` URL),
+  `apiCall(method, path, body?, headers?)` (against `sandbox.apiBaseUrl`).
+  Consumer-specific seeders live in `unotest/e2e/_helpers/`.
+- **Cross-browser support.** Chromium, Firefox, WebKit via Playwright.
+- **`unotest-web init`.** Bootstraps `unotest.config.mjs`,
+  `unotest/e2e/smoke-welcome.js`, `unotest/e2e/_helpers/`,
+  `unotest/.env`, MCP config, and Claude Code skill into any project.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ivan Volkov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,146 @@
+# @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 (once)
+
+Works in any project — Node, Django, Rails, Go, anything. No `package.json`
+required; everything runs through `npx`.
+
+```sh
+npx @unotest/web@latest init          # writes config, starter scenario, and .mcp.json
+npx @unotest/web install-chromium     # skip if you picked system Chrome during init
+```
+
+`init` is idempotent — it never overwrites your edits.
+
+## 2. Connect your agent
+
+`init` already wrote `.mcp.json` for you, **pinned to the version that ran
+it** so the MCP server never drifts. Most clients (Claude Code, Cursor, …)
+pick it up automatically. The entry it writes looks like:
+
+```json
+{
+  "mcpServers": {
+    "unotest-web": { "command": "npx", "args": ["-y", "@unotest/web@0.5.0", "mcp"] }
+  }
+}
+```
+
+Re-run `npx @unotest/web@latest init` to bump the pin. That's it — your
+agent now has the tools to explore your app and write tests.
+
+## 3. Create a test — just ask
+
+In your AI editor, point it at a running app and describe the flow in
+plain English:
+
+> **"Write an e2e test: log in as a demo user, open the first project,
+> and check the dashboard shows today's date."**
+
+The agent then, through the MCP server:
+
+1. **Explores your live app** (`explore_step` / `explore_record`) —
+   clicks, fills, navigates — and watches the real DOM via semantic
+   snapshots.
+2. **Writes the scenario** to `unotest/e2e/<name>.js`, picking stable
+   selectors (`getByTestId` → `getByRole` → … — never brittle CSS).
+3. **Runs it** (`run_test`) and, if it fails, **debugs itself** — reads
+   the paused browser state, the failure bundle, and console, then edits
+   and re-runs.
+
+You get a clean, reviewable `.js` test. You read it, tweak if you want,
+and commit. No hand-written selectors, no flaky waits.
+
+> Give the agent its authoring guide for best results — see
+> [agent-integration.md](https://github.com/unotest/web/blob/main/docs/manuals/agent-integration.md).
+
+## 4. Run your tests
+
+```sh
+npx @unotest/web e2e <name>           # one scenario
+npx @unotest/web e2e                  # see usage / list
+```
+
+Steps are grouped under `//@collapse("...")` blocks. The title says **what**
+the group does in plain English; the steps inside are **how**. This isn't
+decoration — it's the intent your agent reads back to repair a step when a
+selector drifts, and it's how the viewer and block-editor fold a scenario
+into readable sections. Every step lives inside a block:
+
+```js
+function test_login() {
+  //@collapse("Log in as demo user")
+  goto('https://app.example.com');
+  click(getByRole('button', { name: /sign in/i }));
+  fill(getByLabel('Email'), 'demo@example.com');
+  fill(getByLabel('Password'), 'demo');
+  click(getByRole('button', { name: 'Continue' }));
+  //@endcollapse
+
+  //@collapse("Dashboard is shown after login")
+  assertText(getByRole('heading'), 'Dashboard');
+  //@endcollapse
+}
+```
+
+## 5. Watch it run — the viewer
+
+```sh
+npx @unotest/web viewer
+```
+
+A local IDE-style UI for your test runs (no cloud, no account):
+
+- **Scenario tree** — browse scenarios, collections, helpers, and run history.
+- **Run from the UI** — launch any scenario or collection; results stream
+  live over WebSocket as steps execute.
+- **Block view** — each `//@collapse` group rendered as a foldable section
+  with per-step status; failures pin an error card to the offending line.
+- **Step debugger** — set breakpoints in the gutter, run paused, and
+  inspect the live DOM at each stop.
+- **Inspector** — screenshots and failure artifacts per run.
+- **Integrated terminal** — a docked xterm (toggle with `` ⌃` ``) to drive
+  the CLI without leaving the window.
+- **Source ↔ block** — switch between the raw `.js` and the block view.
+
+---
+
+## Writing by hand (optional)
+
+Scenarios are plain `.js`. 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: [`dsl-reference.md`](https://github.com/unotest/web/blob/main/docs/dsl-reference.md).
+
+## Browser support
+
+Chromium — use your system Chrome, or a bundled build via
+`npx @unotest/web install-chromium`.
+
+## Ecosystem
+
+| Package | Role |
+|---|---|
+| `@unotest/web` | this package — CLI / MCP server / runner |
+| [`@unotest/viewer`](https://github.com/unotest/viewer) | local results browser |
+| [`@unotest/protocol`](https://github.com/unotest/protocol) | shared types |
+| [`@unotest/dsl`](https://github.com/unotest/dsl) | scenario parser + validator engine |
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).

package/bin/unotest-web.js

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+// CLI dispatcher for @unotest/web.
+//
+//   unotest-web                       → MCP server (default)
+//   unotest-web mcp                   → MCP server (explicit)
+//   unotest-web e2e <name>            → run scenario unotest/e2e/<name>.js
+//   unotest-web init                  → bootstrap consumer project
+//   unotest-web serve-fixture         → local break/fix fixture server
+//   unotest-web lint                  → lint scenarios
+//   unotest-web prepare-fix --failing → compose fix context for external LLM (D-25)
+//
+// All entries are compiled by tsup to dist/ before publish. This dispatcher
+// resolves the right one and execs it via plain node. NO tsx at runtime —
+// consumers don't install dev deps and consumer scenarios are pure `.js`
+// parsed by the bundled vendor/dsl AST engine (D-27). tsx is only used as
+// a dev fallback when dist/ is absent (fresh clone without `pnpm build`).
+
+import { spawn } from "node:child_process";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { dirname, resolve, join } from "node:path";
+import { createRequire } from "node:module";
+import { existsSync, readFileSync } from "node:fs";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const root = resolve(here, "..");
+
+// Load <cwd>/unotest/.env into process.env before anything else (MCP server
+// and CLI both reach buildLaunchOpts / config / db drivers via process.env).
+// Existing process.env wins — values from `.mcp.json` env or the user's
+// shell override the file. Format: KEY=VALUE per line, `#` comments,
+// surrounding single/double quotes stripped if balanced.
+function loadUnotestEnv() {
+  const path = join(process.cwd(), "unotest", ".env");
+  if (!existsSync(path)) return;
+  let raw;
+  try { raw = readFileSync(path, "utf8"); } catch { return; }
+  for (const line of raw.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (trimmed === "" || trimmed.startsWith("#")) continue;
+    const eq = trimmed.indexOf("=");
+    if (eq <= 0) continue;
+    const key = trimmed.slice(0, eq).trim();
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) continue;
+    if (process.env[key] !== undefined) continue;
+    let value = trimmed.slice(eq + 1).trim();
+    if (value.length >= 2) {
+      const first = value[0];
+      const last = value[value.length - 1];
+      if ((first === '"' || first === "'") && first === last) {
+        value = value.slice(1, -1);
+      }
+    }
+    process.env[key] = value;
+  }
+}
+loadUnotestEnv();
+
+// Resolve tsx CLI binary from @unotest/web's own node_modules. tsx CLI
+// (`tsx/cli` export → dist/cli.mjs) handles both legacy and modern Node
+// loader registration internally — more robust across Node versions than
+// `node --import tsx/esm`, which had issues on some setups dynamically
+// importing .ts via pathToFileURL.
+function resolveTsxCli() {
+  const req = createRequire(import.meta.url);
+  return req.resolve("tsx/cli");
+}
+
+const args = process.argv.slice(2);
+const sub = args[0];
+
+// Each route declares its compiled entry under dist/ AND its source entry
+// under src/. In published packages dist/ exists (built by prepublishOnly);
+// in a fresh clone we fall back to running TS sources via tsx so that
+// `unotest-web --help` works without an explicit `pnpm build` first.
+function dispatch(sub) {
+  switch (sub) {
+    case "mcp":
+      return { dist: "dist/mcp/server.js", src: "src/mcp/server.ts", forwardArgs: [] };
+    case "e2e":
+      return { dist: "dist/runner/cli.js", src: "src/runner/cli.ts", forwardArgs: args };
+    case "init":
+      return {
+        dist: "dist/runner/init.js",
+        src: "src/runner/init.ts",
+        forwardArgs: args.slice(1),
+      };
+    case "install-chromium":
+      return {
+        dist: "dist/runner/install-chromium.js",
+        src: "src/runner/install-chromium.ts",
+        forwardArgs: [],
+      };
+    case "serve-fixture":
+      return {
+        dist: "dist/runner/serve-fixture.js",
+        src: "src/runner/serve-fixture.ts",
+        forwardArgs: args.slice(1),
+      };
+    case "lint":
+      return { dist: "dist/runner/cli.js", src: "src/runner/cli.ts", forwardArgs: ["lint"] };
+    case "viewer":
+      return { dist: "dist/runner/cli.js", src: "src/runner/cli.ts", forwardArgs: ["viewer"] };
+    case "prepare-fix":
+      return {
+        dist: "dist/runner/prepare-fix.js",
+        src: "src/runner/prepare-fix.ts",
+        forwardArgs: args.slice(1),
+      };
+    case "--help":
+    case "-h":
+    case "--version":
+      return { dist: "dist/runner/cli.js", src: "src/runner/cli.ts", forwardArgs: args };
+    default:
+      if (sub === undefined) {
+        return { dist: "dist/mcp/server.js", src: "src/mcp/server.ts", forwardArgs: [] };
+      }
+      return { dist: "dist/runner/cli.js", src: "src/runner/cli.ts", forwardArgs: args };
+  }
+}
+
+const { dist, src, forwardArgs } = dispatch(sub);
+const distPath = resolve(root, dist);
+
+// Init is interactive (browser prompt) — running it via spawn through
+// npx loses the prompt suffix mid-flush on some shells (Claude Code's
+// REPL, nvm shim variants). Direct import keeps stdio attached to the
+// real TTY without a spawn hop. We import the compiled module and call
+// `runInit` directly so we can await its promise — the module's own
+// self-invoke `if (invokedDirectly)` block fires only when bin spawns
+// a child, which we explicitly skip here.
+if (sub === "init" && existsSync(distPath)) {
+  const initModule = await import(pathToFileURL(distPath).href);
+  try {
+    const { exitCode } = await initModule.runInit(forwardArgs);
+    // exitCode (not process.exit) → pending stdout writes drain on
+    // TTY-pipe boundaries before termination.
+    process.exitCode = exitCode;
+  } catch (e) {
+    process.stderr.write(`init: ${e?.message ?? e}\n`);
+    process.exitCode = 1;
+  }
+} else {
+
+// D-27: every subcommand runs the compiled JS under dist/ when present.
+// Consumer scenarios are pure `.js` read by the bundled vendor parser, so
+// no TS loader is needed at runtime. tsx is used only as a dev fallback
+// when dist/ is absent (fresh clone without `pnpm build`).
+let cmd = process.execPath;
+let cmdArgs;
+if (existsSync(distPath)) {
+  // Published / built path — run compiled JS directly.
+  cmdArgs = [distPath, ...forwardArgs];
+} else {
+  const srcPath = resolve(root, src);
+  const haveSrc = existsSync(srcPath);
+  const haveDist = existsSync(distPath);
+  if (!haveSrc && !haveDist) {
+    process.stderr.write(
+      `[unotest-web] missing entry: neither ${dist} nor ${src} exists.\n` +
+        `Did you delete dist/ AND src/? Reinstall the package or run \`pnpm install\`.\n`,
+    );
+    process.exit(1);
+  }
+  // tsx-backed dev fallback — only reached when dist/ is missing (fresh
+  // clone before `pnpm build`). Published packages always ship dist/.
+  let tsxCliPath;
+  try {
+    tsxCliPath = resolveTsxCli();
+  } catch (e) {
+    process.stderr.write(
+      `[unotest-web] tsx not found: ${e.message ?? e}\n` +
+        `tsx ships as a runtime dep — did the install complete? Run \`pnpm install\`.\n`,
+    );
+    process.exit(1);
+  }
+  // tsx CLI handles its own loader registration; prefer src in the dev
+  // fallback path so devs editing src/ see their changes without rebuild.
+  const entryForTsx = haveSrc ? srcPath : distPath;
+  cmdArgs = [tsxCliPath, entryForTsx, ...forwardArgs];
+}
+
+const child = spawn(cmd, cmdArgs, { stdio: "inherit" });
+// Surface spawn failures explicitly — empty stderr on a silent exit makes
+// debugging miserable for consumers. Reviewers hit this in a prior round.
+child.on("error", (err) => {
+  process.stderr.write(`[unotest-web] failed to spawn child: ${err.message ?? err}\n`);
+  process.exit(1);
+});
+child.on("exit", (code, signal) => {
+  if (code === null && signal) {
+    process.stderr.write(`[unotest-web] child terminated by signal: ${signal}\n`);
+    process.exit(1);
+  }
+  process.exit(code ?? 1);
+});
+
+} // end else (spawn path — non-init subcommands)