@unotest/web 0.5.0 → 0.6.2

package/package.json

@@ -1,22 +1,14 @@
 {
   "name": "@unotest/web",
-  "version": "0.5.0",
+  "version": "0.6.2",
   "description": "AI-native E2E testing for web applications. MCP server (run_test / step / resume / inspect_runtime / agent_fix) + CLI runner + JavaScript DSL scenarios on a sandboxed AST engine + semantic DOM snapshots.",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
   },
   "author": "Ivan Volkov <ivan@volkov.io>",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/unotest/web.git"
-  },
-  "homepage": "https://github.com/unotest/web#readme",
-  "bugs": {
-    "url": "https://github.com/unotest/web/issues"
-  },
+  "homepage": "https://www.npmjs.com/package/@unotest/web",
   "type": "module",
-  "packageManager": "pnpm@10.12.4",
   "engines": {
     "node": ">=20"
   },
@@ -51,20 +43,41 @@
   "files": [
     "bin",
     "dist",
-    "examples/fixtures",
-    "!examples/fixtures/**/*.test.*",
+    "guides",
+    "examples/fixtures/break-fix-app/index.html",
+    "examples/fixtures/break-fix-app/README.md",
+    "examples/fixtures/break-fix-app/serve.mjs",
     "src/mcp/prompts",
     ".claude/skills",
+    ".claude/hooks",
     "CHANGELOG.md",
     "LICENSE",
     "README.md"
   ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "chokidar": "^4.0.3",
+    "dotenv": "^16.4.5",
+    "playwright": "^1.49.0",
+    "tsx": "^4.19.2",
+    "yaml": "^2.6.0",
+    "zod": "^3.23.8",
+    "@unotest/dsl": "^0.6.2",
+    "@unotest/protocol": "^0.6.2",
+    "@unotest/viewer": "^0.6.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "javascript-obfuscator": "^4.1.1",
+    "tsup": "^8.5.1",
+    "typescript": "^5.7.2"
+  },
   "scripts": {
     "typecheck": "tsc --noEmit",
     "design": "npx serve -l 3111 design",
     "test": "node --import tsx --test --test-reporter=spec 'src/**/*.test.ts' 'scripts/**/*.test.mjs' 'evals/**/*.test.ts'",
     "compile": "tsup",
-    "compile:all": "pnpm -C ../unotest-dsl compile && pnpm -C ../unotest-viewer compile && pnpm -C ../unotest-web compile",
+    "compile:all": "pnpm -C ../unotest-dsl compile && pnpm -C ../unotest-web compile && pnpm -C ../unotest-viewer compile",
     "lint:scenarios": "tsx src/runner/cli.ts lint",
     "smoke:bundle": "node scripts/smoke-bundle.mjs",
     "check:docs-sync": "node scripts/check-docs-sync.mjs",
@@ -74,6 +87,7 @@
     "check:skill-prompt-sync": "node scripts/check-skill-prompt-sync.mjs",
     "check:tarball": "node scripts/check-tarball.mjs",
     "check:sibling-versions": "node scripts/check-sibling-versions.mjs",
+    "build:guides": "node scripts/build-guides.mjs",
     "prepublish:check": "node scripts/prepublish-check.mjs",
     "evals:run": "tsx evals/run.ts",
     "evals:prepare": "tsx evals/prepare.ts",
@@ -83,33 +97,10 @@
     "perf:baseline": "node scripts/perf-baseline.mjs",
     "verify": "pnpm typecheck && pnpm lint:scenarios && pnpm check:surface && pnpm test",
     "obfuscate": "node scripts/obfuscate.mjs",
-    "build": "pnpm verify && pnpm compile && pnpm obfuscate && pnpm smoke:bundle && pnpm check:tarball",
+    "build": "pnpm verify && pnpm compile && pnpm obfuscate && pnpm smoke:bundle && pnpm build:guides && pnpm check:tarball",
     "e2e": "tsx src/runner/cli.ts e2e",
     "m1:cross-browser": "node scripts/m1-cross-browser.mjs",
     "mcp": "tsx src/mcp/server.ts",
-    "serve-fixture": "node examples/fixtures/break-fix-app/serve.mjs",
-    "prepublishOnly": "pnpm build"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.4",
-    "@unotest/dsl": "^0.5.0",
-    "@unotest/protocol": "^0.5.0",
-    "@unotest/viewer": "^0.5.0",
-    "dotenv": "^16.4.5",
-    "playwright": "^1.49.0",
-    "tsx": "^4.19.2",
-    "yaml": "^2.6.0",
-    "zod": "^3.23.8"
-  },
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "esbuild"
-    ]
-  },
-  "devDependencies": {
-    "@types/node": "^22.10.0",
-    "javascript-obfuscator": "^4.1.1",
-    "tsup": "^8.5.1",
-    "typescript": "^5.7.2"
+    "serve-fixture": "node examples/fixtures/break-fix-app/serve.mjs"
   }
-}
+}

package/src/mcp/prompts/agent-test-author.md

@@ -19,7 +19,7 @@ Anthropic-, OpenAI-, or Google-specific prompt syntax.
 You are writing and debugging end-to-end tests for a web application,
 using the `@unotest/web` MCP tools. Your job is to:
 
-1. Author `.js` scenarios under `unotest/e2e/` that follow this
+1. Author `.js` scenarios under `unotest/e2e/<feature>/` that follow this
    project's DSL — Playwright-vocabulary primitives (`goto`, `click`,
    `fill`, `getByRole`, `assertText`, …).
 2. Run them through the debugger tools (`run_test`, `step`, `resume`,
@@ -35,6 +35,20 @@ is at
 [dsl-reference.md](https://github.com/unotest/web/blob/main/docs/dsl-reference.md).
 Read that before writing more than a one-line scenario.
 
+## Layout — scenarios live in feature subfolders (hard rule)
+
+Never place a scenario directly in `unotest/e2e/`. Every test file goes in a
+feature/page subfolder that mirrors the site structure:
+
+- `unotest/e2e/auth/login.js`
+- `unotest/e2e/checkout/apply-coupon.js`
+- `unotest/e2e/catalog/open-first-car-card.js`
+
+The linter rejects a test in the e2e root (`lint:scenario-in-root`), and
+`save_exploration_as_test` requires a `<feature>/<name>` path. Pick the folder
+from the area of the app under test. Shared helpers live in
+`unotest/e2e/_helpers/`; `_template.js` is a starting point to copy.
+
 ## Locator hierarchy (D-22, hard rule)
 
 When choosing a selector, prefer in this exact order:
@@ -169,6 +183,62 @@ If a primitive throws with "sandbox.X is not configured", tell the
 user to add it to `unotest.config.*`. Do not infer secrets from the
 environment yourself.
 
+## External variables & secrets
+
+Don't hard-code logins, passwords, base URLs, or tokens in a scenario.
+Reference them by a bare **UPPER_SNAKE** identifier — the runtime resolves it
+from the project's variable store:
+
+```js
+goto(APP_BASE_URL);
+fill(getByLabel('Email'),    TEST_USER_EMAIL);
+fill(getByLabel('Password'), TEST_USER_PASSWORD);
+```
+
+- Non-secret values live in `unotest/.env`; secret values in
+  `unotest/.secrets` (both gitignored). No `env()` / `secret()` wrapper and no
+  `${...}` — just the bare name.
+- A lowercase / mixed-case identifier is an in-scenario binding (a variable you
+  assigned earlier), not an external one.
+- An UPPER_SNAKE name that isn't in either file fails the run with
+  "external variable X not found — add it to unotest/.env". When you need a
+  value the project hasn't defined, tell the user to add it; don't inline a
+  literal.
+- Secret values are auto-masked (`‹secret:NAME›`) in the debug log, so a
+  password passed to `fill` never lands on disk verbatim.
+
+**While recording (`explore_*`):** `explore_start` returns
+`availableVariables` (the project's declared names). When a step's value is one
+of them, pass it as **`{{NAME}}`** — `explore_step({action:"fill", …,
+value:"{{PASSWORD}}"})`. (A bare `NAME` also works when it's a declared
+variable, but `{{NAME}}` is unambiguous in a plain string value, so prefer
+it.) The runner substitutes the real value LIVE (so the login actually works)
+and records a bare reference, so the saved test reads `fill(loc, PASSWORD)` and
+the secret never enters the file or logs. The same applies to any
+value/locator-text that is a variable (`goto` URL via `{{APP_BASE_URL}}`, a row
+found by `getByText({{PARK}})`). If you pass a name that isn't declared, the
+step returns a `variableHint` — define it in `.env`/`.secrets` or use a literal.
+
+## Reusable flows (auth/setup you record once)
+
+A login (or any setup block) that many tests share should be a reusable
+`flow_<name>()` helper, not re-recorded per test. `explore_start` returns
+`availableFlows` — the flows already on disk.
+
+- **Flow already exists** (it's in `availableFlows`): call
+  `explore_run_flow({ explorationId, name })`. It replays the flow LIVE (you end
+  up logged in) and records a single `flow_<name>()` call — don't re-record the
+  steps.
+- **First time** (no flow yet): record the block normally but put
+  `flow:"signin"` on every step of it (`explore_step({…, flow:"signin"})`).
+  On `save_exploration_as_test`, those steps are extracted into
+  `unotest/e2e/_helpers/signin.js` as `flow_signin()`, and the test calls
+  `flow_signin()` in their place. One save writes both files.
+
+Use the SAME flow name on every step of the block. Variables inside a flow
+(`{{LOGIN}}` etc.) resolve at replay/run time, so the secret never lives in the
+flow file either.
+
 ## When a locator matches `N elements`
 
 Every locator must resolve to exactly one element. When you see