@opice/harness 0.0.4 → 0.1.0

package/dist/scenario.js

@@ -0,0 +1,162 @@
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { closePage, launchPage } from './context.js';
+import { screenshot } from './element.js';
+import { getReporter } from './reporter.js';
+/**
+ * `bun:test` is resolved lazily, at the moment `browserTest` registers a
+ * scenario — never at module load. That keeps `@opice/harness` importable
+ * under plain Node (the `opice-browser` authoring daemon imports the command
+ * registry from this package and runs on Node, where `bun:test` doesn't
+ * exist). Tests still register synchronously: `require` is sync under Bun.
+ */
+const require = createRequire(import.meta.url);
+function bunTest() {
+    return require('bun:test');
+}
+const PLAYGROUND_URL = process.env['PLAYGROUND_URL'] ?? 'http://localhost:15180';
+/**
+ * Best-effort capture of the `*.test.ts` path that called `browserTest`, by
+ * walking the stack for the first `.test.` frame. Reported so a failed
+ * scenario links back to its source file. Repo-relative when possible.
+ */
+function captureTestFile() {
+    const stack = new Error().stack;
+    if (!stack)
+        return undefined;
+    for (const line of stack.split('\n')) {
+        const match = line.match(/\(?((?:file:\/\/)?\/[^\s():]+\.test\.[tj]sx?)/);
+        if (match?.[1]) {
+            const abs = match[1].replace(/^file:\/\//, '');
+            try {
+                const rel = path.relative(process.cwd(), abs);
+                return rel.startsWith('..') ? abs : rel;
+            }
+            catch {
+                return abs;
+            }
+        }
+    }
+    return undefined;
+}
+function defaultScenarioFile(testFile) {
+    if (!testFile)
+        return undefined;
+    return testFile.replace(/\.test\.[tj]sx?$/, '.scenario.md');
+}
+let currentScenarioId = null;
+let currentScenarioStart = 0;
+let currentScenarioFailures = 0;
+// Monotonic per-scenario step counter. Assigned synchronously at each step()
+// call so order reflects authoring order — step records are POSTed
+// fire-and-forget and would otherwise be sequenced by arrival order at the
+// worker, which screenshot-encoding latency can reshuffle.
+let currentScenarioStepSeq = 0;
+/**
+ * Register a top-level browser test scenario.
+ *
+ * Each `browserTest(name, fn)` launches its own isolated Playwright browser +
+ * context + page, navigates to the playground URL, runs the given `fn` (which
+ * typically contains nested `describe`/`test` blocks), and tears the browser
+ * down in `afterAll`.
+ */
+export function browserTest(name, fn, options = {}) {
+    const opts = typeof options === 'string' ? { hash: options } : options;
+    const reporter = getReporter();
+    const testFile = captureTestFile();
+    const scenarioFile = opts.scenarioFile ?? defaultScenarioFile(testFile);
+    const { describe, beforeAll, afterAll } = bunTest();
+    describe(name, () => {
+        beforeAll(async () => {
+            currentScenarioStart = Date.now();
+            currentScenarioFailures = 0;
+            currentScenarioStepSeq = 0;
+            try {
+                currentScenarioId = await reporter.startScenario({ name, hash: opts.hash, testFile, scenarioFile });
+            }
+            catch {
+                currentScenarioId = null;
+            }
+            const page = await launchPage();
+            const base = opts.url ?? PLAYGROUND_URL;
+            const url = opts.hash ? `${base}#${opts.hash}` : base;
+            await page.goto(url);
+        }, 30_000);
+        afterAll(async () => {
+            try {
+                await closePage();
+            }
+            catch {
+                // ignore close errors
+            }
+            if (currentScenarioId) {
+                // Drain pending step records (incl. their screenshot uploads)
+                // before marking the scenario done. step() fires recordStep
+                // fire-and-forget; the test process would otherwise exit while
+                // those requests were still in flight.
+                try {
+                    await reporter.flush();
+                }
+                catch {
+                    // best-effort
+                }
+                const durationMs = Date.now() - currentScenarioStart;
+                const status = currentScenarioFailures > 0 ? 'failed' : 'passed';
+                try {
+                    await reporter.finishScenario({ scenarioId: currentScenarioId, status, durationMs });
+                }
+                catch {
+                    // best-effort
+                }
+            }
+            currentScenarioId = null;
+        }, 30_000);
+        fn();
+    });
+}
+/**
+ * A reportable step inside a scenario. Captures duration + screenshot on
+ * finish, forwards to the active reporter (no-op unless configured via env).
+ *
+ * The body may be sync or async; `step` always returns a promise, so call it
+ * with `await step('…', async () => { … })`.
+ */
+export async function step(name, fn) {
+    const reporter = getReporter();
+    // Capture order at call time, before the fire-and-forget record below.
+    const sequence = currentScenarioStepSeq++;
+    const start = Date.now();
+    let status = 'passed';
+    let error;
+    try {
+        await fn();
+    }
+    catch (e) {
+        status = 'failed';
+        error = e instanceof Error ? e.message : String(e);
+        currentScenarioFailures++;
+        throw e;
+    }
+    finally {
+        const durationMs = Date.now() - start;
+        let screenshotPath;
+        try {
+            screenshotPath = await screenshot();
+        }
+        catch {
+            // screenshot failure shouldn't fail the test
+        }
+        if (currentScenarioId) {
+            void reporter.recordStep({
+                scenarioId: currentScenarioId,
+                sequence,
+                name,
+                status,
+                durationMs,
+                error,
+                screenshotPath,
+            });
+        }
+    }
+}
+//# sourceMappingURL=scenario.js.map

package/dist/scenario.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scenario.js","sourceRoot":"","sources":["../src/scenario.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,IAAI,MAAM,WAAW,CAAA;AAC5B,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAE3C;;;;;;GAMG;AACH,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AAC9C,SAAS,OAAO;IACf,OAAO,OAAO,CAAC,UAAU,CAA8B,CAAA;AACxD,CAAC;AAED,MAAM,cAAc,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,IAAI,wBAAwB,CAAA;AAehF;;;;GAIG;AACH,SAAS,eAAe;IACvB,MAAM,KAAK,GAAG,IAAI,KAAK,EAAE,CAAC,KAAK,CAAA;IAC/B,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAA;IAC5B,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACtC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,+CAA+C,CAAC,CAAA;QACzE,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAChB,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAA;YAC9C,IAAI,CAAC;gBACJ,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,GAAG,CAAC,CAAA;gBAC7C,OAAO,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAA;YACxC,CAAC;YAAC,MAAM,CAAC;gBACR,OAAO,GAAG,CAAA;YACX,CAAC;QACF,CAAC;IACF,CAAC;IACD,OAAO,SAAS,CAAA;AACjB,CAAC;AAED,SAAS,mBAAmB,CAAC,QAA4B;IACxD,IAAI,CAAC,QAAQ;QAAE,OAAO,SAAS,CAAA;IAC/B,OAAO,QAAQ,CAAC,OAAO,CAAC,kBAAkB,EAAE,cAAc,CAAC,CAAA;AAC5D,CAAC;AAED,IAAI,iBAAiB,GAAkB,IAAI,CAAA;AAC3C,IAAI,oBAAoB,GAAW,CAAC,CAAA;AACpC,IAAI,uBAAuB,GAAG,CAAC,CAAA;AAC/B,6EAA6E;AAC7E,mEAAmE;AACnE,2EAA2E;AAC3E,2DAA2D;AAC3D,IAAI,sBAAsB,GAAG,CAAC,CAAA;AAE9B;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,EAAc,EAAE,UAAuC,EAAE;IAClG,MAAM,IAAI,GAAuB,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,OAAO,CAAA;IAC1F,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAA;IAC9B,MAAM,QAAQ,GAAG,eAAe,EAAE,CAAA;IAClC,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,IAAI,mBAAmB,CAAC,QAAQ,CAAC,CAAA;IACvE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,OAAO,EAAE,CAAA;IAEnD,QAAQ,CAAC,IAAI,EAAE,GAAG,EAAE;QACnB,SAAS,CAAC,KAAK,IAAI,EAAE;YACpB,oBAAoB,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;YACjC,uBAAuB,GAAG,CAAC,CAAA;YAC3B,sBAAsB,GAAG,CAAC,CAAA;YAC1B,IAAI,CAAC;gBACJ,iBAAiB,GAAG,MAAM,QAAQ,CAAC,aAAa,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,YAAY,EAAE,CAAC,CAAA;YACpG,CAAC;YAAC,MAAM,CAAC;gBACR,iBAAiB,GAAG,IAAI,CAAA;YACzB,CAAC;YACD,MAAM,IAAI,GAAG,MAAM,UAAU,EAAE,CAAA;YAC/B,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,IAAI,cAAc,CAAA;YACvC,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAA;YACrD,MAAM,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;QACrB,CAAC,EAAE,MAAM,CAAC,CAAA;QAEV,QAAQ,CAAC,KAAK,IAAI,EAAE;YACnB,IAAI,CAAC;gBACJ,MAAM,SAAS,EAAE,CAAA;YAClB,CAAC;YAAC,MAAM,CAAC;gBACR,sBAAsB;YACvB,CAAC;YACD,IAAI,iBAAiB,EAAE,CAAC;gBACvB,8DAA8D;gBAC9D,4DAA4D;gBAC5D,+DAA+D;gBAC/D,uCAAuC;gBACvC,IAAI,CAAC;oBACJ,MAAM,QAAQ,CAAC,KAAK,EAAE,CAAA;gBACvB,CAAC;gBAAC,MAAM,CAAC;oBACR,cAAc;gBACf,CAAC;gBACD,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,oBAAoB,CAAA;gBACpD,MAAM,MAAM,GAAG,uBAAuB,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAA;gBAChE,IAAI,CAAC;oBACJ,MAAM,QAAQ,CAAC,cAAc,CAAC,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,CAAA;gBACrF,CAAC;gBAAC,MAAM,CAAC;oBACR,cAAc;gBACf,CAAC;YACF,CAAC;YACD,iBAAiB,GAAG,IAAI,CAAA;QACzB,CAAC,EAAE,MAAM,CAAC,CAAA;QAEV,EAAE,EAAE,CAAA;IACL,CAAC,CAAC,CAAA;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,IAAI,CAAC,IAAY,EAAE,EAA8B;IACtE,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAA;IAC9B,uEAAuE;IACvE,MAAM,QAAQ,GAAG,sBAAsB,EAAE,CAAA;IACzC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;IACxB,IAAI,MAAM,GAAwB,QAAQ,CAAA;IAC1C,IAAI,KAAyB,CAAA;IAC7B,IAAI,CAAC;QACJ,MAAM,EAAE,EAAE,CAAA;IACX,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACZ,MAAM,GAAG,QAAQ,CAAA;QACjB,KAAK,GAAG,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAA;QAClD,uBAAuB,EAAE,CAAA;QACzB,MAAM,CAAC,CAAA;IACR,CAAC;YAAS,CAAC;QACV,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAA;QACrC,IAAI,cAAkC,CAAA;QACtC,IAAI,CAAC;YACJ,cAAc,GAAG,MAAM,UAAU,EAAE,CAAA;QACpC,CAAC;QAAC,MAAM,CAAC;YACR,6CAA6C;QAC9C,CAAC;QACD,IAAI,iBAAiB,EAAE,CAAC;YACvB,KAAK,QAAQ,CAAC,UAAU,CAAC;gBACxB,UAAU,EAAE,iBAAiB;gBAC7B,QAAQ;gBACR,IAAI;gBACJ,MAAM;gBACN,UAAU;gBACV,KAAK;gBACL,cAAc;aACd,CAAC,CAAA;QACH,CAAC;IACF,CAAC;AACF,CAAC"}

package/package.json

@@ -1,19 +1,21 @@
 {
 	"name": "@opice/harness",
-	"version": "0.0.4",
-	"description": "Runtime primitives for opice — AI-driven E2E browser tests on top of agent-browser",
+	"version": "0.1.0",
+	"description": "Runtime primitives for opice — AI-driven E2E browser tests on top of Playwright",
 	"type": "module",
 	"main": "./src/index.ts",
 	"types": "./src/index.ts",
 	"exports": {
 		".": {
 			"types": "./src/index.ts",
-			"import": "./src/index.ts",
-			"default": "./src/index.ts"
+			"bun": "./src/index.ts",
+			"import": "./dist/index.js",
+			"default": "./dist/index.js"
 		}
 	},
 	"files": [
 		"src",
+		"dist",
 		"README.md"
 	],
 	"scripts": {
@@ -31,5 +33,10 @@
 	},
 	"publishConfig": {
 		"access": "public"
+	},
+	"dependencies": {
+		"@playwright/test": "^1.60.0",
+		"playwright": "^1.60.0",
+		"zod": "^4.4.3"
 	}
 }

package/src/accessible.ts

@@ -1,204 +1,38 @@
-import { exec, q } from './agent-browser.js'
-import { el, type ElementHandle, evalJs } from './element.js'
+import type { Locator, Page } from 'playwright'
+import { getPage } from './context.js'
+
+/** The ARIA role union accepted by Playwright's `getByRole`. */
+type Role = Parameters<Page['getByRole']>[0]
 
 /**
  * Accessible-name selectors — `byRole` / `byLabel` / `byText`.
  *
  * opice prefers `data-testid` (see `el`), but real apps often can't be
  * annotated — third-party UIs, generated form-field ids, components you don't
- * own. These wrap agent-browser's own `find` locators, so a test reads the same
- * way the authoring dry-run drives the page:
- *
- *     byRole('button', 'Save').click()   ⇄   agent-browser find role button click --name 'Save'
- *     byLabel('Email').fill('a@b.c')     ⇄   agent-browser find label 'Email' fill 'a@b.c'
+ * own. These map straight onto Playwright's accessibility-aware locators, which
+ * compute the real ARIA accessible name and fire real user gestures. No
+ * in-page resolver, no stamping — the previous engine (agent-browser) was
+ * CSS-only and couldn't do this, which is a large part of why opice moved to
+ * Playwright.
  *
- * `find` covers actions only (click/fill/hover/check/…). Queries (`exists`,
- * `text`, …) and the focus/press path (Radix popovers open on focus+Enter, and
- * `find focus` is unreliable) fall back to a small `eval` against the same
- * accessible-name predicate. Accessible name is a pragmatic approximation
- * (`aria-label` || text || value), not the full ARIA computation.
+ * All three return a `Locator`, so the full Locator API and `expect(locator)`
+ * assertions apply.
  */
 
-let counter = 0
-
-/** Page-side helpers injected before each finder expression. */
-const HELPERS = `const __norm = s => (s||'').replace(/\\s+/g,' ').replace(/\\*/g,'').trim().toLowerCase();`
-	+ `const __match = (text, want) => { const a = __norm(text), b = __norm(want); return a === b || (b.length > 0 && a.includes(b)); };`
-
-interface Locator {
-	/** agent-browser `find` locator + value, e.g. `role button` or `label 'Email'`. */
-	readonly findPart: string
-	/** Options appended after the `find` action, e.g. ` --name 'Save'`. */
-	readonly findOpts: string
-	/** JS expression evaluating to the target `Element | null` in the page. */
-	readonly nodeExpr: string
-	readonly describe: string
-}
-
-function parseEval(raw: string): string {
-	try {
-		const value: unknown = JSON.parse(raw)
-		return typeof value === 'string' ? value : String(value)
-	} catch {
-		return raw
-	}
-}
-
-/** Evaluate `nodeExpr` and return whether it found an element. */
-function probe(loc: Locator, expr: string): string {
-	return parseEval(evalJs(`(() => { ${HELPERS} const node = (${loc.nodeExpr}); return (${expr}); })()`))
-}
-
-/** Stamp the matched element with a fresh `data-opice-ref` and return its selector. */
-function stamp(loc: Locator): string {
-	const ref = `opice-${++counter}`
-	const ok = parseEval(evalJs(
-		`(() => {`
-			+ `document.querySelectorAll('[data-opice-ref="${ref}"]').forEach(e => e.removeAttribute('data-opice-ref'));`
-			+ HELPERS
-			+ `const node = (${loc.nodeExpr});`
-			+ `if (!node) return 'NONE';`
-			+ `node.setAttribute('data-opice-ref', '${ref}');`
-			+ `return 'OK';`
-			+ `})()`,
-	))
-	if (ok !== 'OK') throw new Error(`${loc.describe} not found`)
-	return `[data-opice-ref="${ref}"]`
-}
-
-function handleFor(loc: Locator): ElementHandle {
-	const find = (action: string, text?: string): void => {
-		const textArg = text === undefined ? '' : ` ${q(text)}`
-		exec(`agent-browser find ${loc.findPart} ${action}${textArg}${loc.findOpts}`)
-	}
-	return {
-		// Queries — small eval against the accessible-name predicate.
-		get exists(): boolean {
-			return probe(loc, '!!node') === 'true'
-		},
-		get text(): string {
-			return probe(loc, "node ? (node.textContent||'') : ''")
-		},
-		get value(): string {
-			return probe(loc, "node ? (node.value||'') : ''")
-		},
-		get isDisabled(): boolean {
-			return probe(loc, '!!(node && (node.disabled || node.getAttribute(\'aria-disabled\') === \'true\'))') === 'true'
-		},
-		attr(name: string): string {
-			return probe(loc, `node ? (node.getAttribute(${JSON.stringify(name)})||'') : ''`)
-		},
-		// Accessible handles target a single element (the first match). For real
-		// counts use `el('css').count()`.
-		count(): number {
-			return probe(loc, '!!node') === 'true' ? 1 : 0
-		},
-		// Actions — agent-browser `find` passthrough (mirrors the authoring dry-run).
-		click(): void {
-			find('click')
-		},
-		fill(value: string): void {
-			find('fill', value)
-		},
-		select(optionText: string): void {
-			el(stamp(loc)).select(optionText)
-		},
-		focus(): void {
-			el(stamp(loc)).focus()
-		},
-		hover(): void {
-			find('hover')
-		},
-		press(key: string): void {
-			el(stamp(loc)).press(key)
-		},
-	}
-}
-
 /**
  * Find an element by ARIA role and (optionally) its accessible name.
- * `byRole('button', 'Save').click()` → `agent-browser find role button click --name 'Save'`.
- */
-export function byRole(role: string, name?: string): ElementHandle {
-	const sel = roleSelector(role)
-	const nodeExpr = `(() => {`
-		+ `const __sel = ${JSON.stringify(sel)};`
-		+ `const __want = ${JSON.stringify(name ?? null)};`
-		+ `const __accName = e => e.getAttribute('aria-label') || e.textContent || e.value || '';`
-		+ `return Array.from(document.querySelectorAll(__sel)).find(e => __want == null ? true : __match(__accName(e), __want)) || null;`
-		+ `})()`
-	return handleFor({
-		findPart: `role ${role}`,
-		findOpts: name === undefined ? '' : ` --name ${q(name)}`,
-		nodeExpr,
-		describe: `byRole(${role}${name ? `, ${JSON.stringify(name)}` : ''})`,
-	})
-}
-
-/**
- * Find a form control by its visible `<label>` text (resolved via `for`→id, a
- * nested control, or the next control after the label).
- * `byLabel('Email').fill('x')` → `agent-browser find label 'Email' fill 'x'`.
+ * `name` does a substring, case-insensitive match by default.
  */
-export function byLabel(text: string): ElementHandle {
-	const controls = 'input,textarea,select,button,[role=textbox],[role=combobox]'
-	const nodeExpr = `(() => {`
-		+ `const __want = ${JSON.stringify(text)};`
-		+ `const __label = Array.from(document.querySelectorAll('label')).find(l => __match(l.textContent, __want));`
-		+ `if (!__label) return null;`
-		+ `const __id = __label.getAttribute('for');`
-		+ `if (__id) { const c = document.getElementById(__id); if (c) return c; }`
-		+ `const __nested = __label.querySelector(${JSON.stringify(controls)}); if (__nested) return __nested;`
-		+ `let __n = __label.nextElementSibling;`
-		+ `while (__n) {`
-		+ `if (__n.matches && __n.matches(${JSON.stringify(controls)})) return __n;`
-		+ `const __inner = __n.querySelector && __n.querySelector(${JSON.stringify(controls)}); if (__inner) return __inner;`
-		+ `__n = __n.nextElementSibling;`
-		+ `}`
-		+ `return null;`
-		+ `})()`
-	return handleFor({
-		findPart: `label ${q(text)}`,
-		findOpts: '',
-		nodeExpr,
-		describe: `byLabel(${JSON.stringify(text)})`,
-	})
+export function byRole(role: Role, name?: string): Locator {
+	return getPage().getByRole(role, name == null ? undefined : { name })
 }
 
-/**
- * Find a leaf element by its visible text.
- * `byText('Saved').exists` / `byText('Continue').click()`.
- */
-export function byText(text: string): ElementHandle {
-	const nodeExpr = `(Array.from(document.querySelectorAll('body *')).find(e => e.children.length === 0 && __match(e.textContent, ${JSON.stringify(text)})) || null)`
-	return handleFor({
-		findPart: `text ${q(text)}`,
-		findOpts: '',
-		nodeExpr,
-		describe: `byText(${JSON.stringify(text)})`,
-	})
+/** Find a form control by its associated `<label>` (or `aria-label`) text. */
+export function byLabel(text: string): Locator {
+	return getPage().getByLabel(text)
 }
 
-/** CSS candidates per ARIA role (for the query/focus fallback predicate). */
-function roleSelector(role: string): string {
-	switch (role) {
-		case 'button':
-			return 'button,[role=button]'
-		case 'link':
-			return 'a[href],[role=link]'
-		case 'textbox':
-			return 'input:not([type=button]):not([type=submit]):not([type=reset]):not([type=checkbox]):not([type=radio]),textarea,[role=textbox],[contenteditable=true]'
-		case 'checkbox':
-			return 'input[type=checkbox],[role=checkbox]'
-		case 'combobox':
-			return 'select,[role=combobox]'
-		case 'heading':
-			return 'h1,h2,h3,h4,h5,h6,[role=heading]'
-		case 'option':
-			return 'option,[role=option]'
-		case 'tab':
-			return '[role=tab]'
-		default:
-			return `[role=${role}]`
-	}
+/** Find an element by its visible text (substring, case-insensitive). */
+export function byText(text: string): Locator {
+	return getPage().getByText(text)
 }

package/src/command.ts

@@ -0,0 +1,134 @@
+import { existsSync } from 'node:fs'
+import path from 'node:path'
+import { pathToFileURL } from 'node:url'
+import type { Locator, Page } from 'playwright'
+import { z } from 'zod'
+import { getPage } from './context.js'
+import { locatorOn } from './element.js'
+
+/**
+ * The shared command registry.
+ *
+ * A command is a named, schema-validated browser verb implemented once over a
+ * Playwright page. The same command object is used on both faces:
+ *
+ * - **authoring** — the `opice-browser` daemon loads it and exposes it to the
+ *   agent (`opice-browser <name> …`),
+ * - **tests** — the harness loads the same module so a test can call the verb
+ *   directly.
+ *
+ * Built-in verbs (open/click/fill/byRole/…) ship with the `opice-browser`
+ * daemon; user-land verbs live in a repo's `browser-tools.ts` and are picked up
+ * by `loadUserCommands`. Both are the *same* `Command` objects — that is the
+ * unification that closes the authoring↔test vocabulary gap.
+ */
+
+/** Page + accessibility-aware helpers handed to every command implementation. */
+export interface CommandCtx {
+	page: Page
+	/** Resolve a test-id (bare word) or raw CSS selector to a locator. */
+	el(selectorOrTestId: string): Locator
+	byRole(role: Parameters<Page['getByRole']>[0], name?: string): Locator
+	byLabel(text: string): Locator
+	byText(text: string): Locator
+}
+
+export interface Command<S extends z.ZodType = z.ZodType> {
+	name: string
+	/** One-line description, surfaced in `opice-browser commands`. */
+	description?: string
+	params: S
+	run: (ctx: CommandCtx, args: z.infer<S>) => Promise<unknown>
+}
+
+/** Define a browser command. See `CommandCtx` for what `ctx` provides. */
+export function command<S extends z.ZodType>(
+	name: string,
+	params: S,
+	run: (ctx: CommandCtx, args: z.infer<S>) => Promise<unknown>,
+	description?: string,
+): Command<S> {
+	return { name, params, run, description }
+}
+
+/** Build the command context bound to a specific page. */
+export function makeCtx(page: Page): CommandCtx {
+	return {
+		page,
+		el: (sel) => locatorOn(page, sel),
+		byRole: (role, name) => page.getByRole(role, name == null ? undefined : { name }),
+		byLabel: (text) => page.getByLabel(text),
+		byText: (text) => page.getByText(text),
+	}
+}
+
+/** Validate args against a command's schema and run it on `page`. */
+export async function runCommand(page: Page, cmd: Command, rawArgs: unknown): Promise<unknown> {
+	const args = cmd.params.parse(rawArgs)
+	return cmd.run(makeCtx(page), args)
+}
+
+/**
+ * Invoke a command against the active scenario page from inside a test. Pair
+ * with a direct import of the verb from `browser-tools.ts` so the args are
+ * type-checked against its schema:
+ *
+ * ```ts
+ * import { call } from '@opice/harness'
+ * import { fullEnum } from '../browser-tools'
+ * await call(fullEnum, { label: 'Typ', option: 'Faktura' })
+ * ```
+ */
+export async function call<S extends z.ZodType>(cmd: Command<S>, args: z.infer<S>): Promise<unknown> {
+	return runCommand(getPage(), cmd, args)
+}
+
+/** Duck-type check: is a module export a `Command`? */
+function isCommand(value: unknown): value is Command {
+	return (
+		typeof value === 'object'
+		&& value !== null
+		&& typeof (value as Command).name === 'string'
+		&& typeof (value as Command).run === 'function'
+		&& 'params' in value
+	)
+}
+
+/**
+ * Locate a repo's `browser-tools.ts` (or `.js`/`.mjs`), walking up from `from`.
+ * Returns the absolute path, or null if none is found before the filesystem
+ * root or a `package.json` boundary without one above it.
+ */
+export function findUserCommandsFile(from: string = process.cwd()): string | null {
+	let dir = path.resolve(from)
+	for (;;) {
+		for (const name of ['browser-tools.ts', 'browser-tools.js', 'browser-tools.mjs']) {
+			const candidate = path.join(dir, name)
+			if (existsSync(candidate)) return candidate
+		}
+		const parent = path.dirname(dir)
+		if (parent === dir) return null
+		dir = parent
+	}
+}
+
+/**
+ * Load user-land commands from a repo's `browser-tools.ts`. Returns a map keyed
+ * by command name (empty if the file is absent). Throws on a duplicate name.
+ */
+export async function loadUserCommands(from?: string): Promise<Map<string, Command>> {
+	const registry = new Map<string, Command>()
+	const file = findUserCommandsFile(from)
+	if (!file) return registry
+	const mod = (await import(pathToFileURL(file).href)) as Record<string, unknown>
+	for (const value of Object.values(mod)) {
+		if (!isCommand(value)) continue
+		if (registry.has(value.name)) {
+			throw new Error(`browser-tools.ts: duplicate command name "${value.name}" (${file})`)
+		}
+		registry.set(value.name, value)
+	}
+	return registry
+}
+
+export { z }

package/src/context.ts

@@ -0,0 +1,55 @@
+import { chromium, type Browser, type BrowserContext, type Page } from 'playwright'
+
+/**
+ * The live Playwright page for the running scenario. `browserTest` launches a
+ * fresh browser + context + page per scenario (`beforeAll`) and tears it down
+ * (`afterAll`); the DSL — `el`, `byRole`, navigation — reads the current page
+ * from here. This module replaces the old agent-browser CLI session handling:
+ * there is no shell-out and no daemon, the browser runs in-process under
+ * `bun test`.
+ */
+
+let browser: Browser | null = null
+let context: BrowserContext | null = null
+let page: Page | null = null
+
+/** Headed mode for local debugging (`OPICE_HEADED=1` or Playwright's `PWDEBUG`). */
+function headed(): boolean {
+	return !!(process.env['OPICE_HEADED'] || process.env['PWDEBUG'])
+}
+
+/** The active page, or throw if called outside a `browserTest` scenario. */
+export function getPage(): Page {
+	if (!page) {
+		throw new Error('opice: no active page — call DSL helpers inside a browserTest scenario.')
+	}
+	return page
+}
+
+/** The active browser context (for cookies/storage, new tabs, etc.). */
+export function getContext(): BrowserContext {
+	if (!context) {
+		throw new Error('opice: no active browser context — call inside a browserTest scenario.')
+	}
+	return context
+}
+
+/** Launch a fresh isolated browser + context + page. Called from `beforeAll`. */
+export async function launchPage(): Promise<Page> {
+	browser = await chromium.launch({ headless: !headed() })
+	context = await browser.newContext()
+	page = await context.newPage()
+	return page
+}
+
+/** Close the page, context, and browser. Called from `afterAll`. */
+export async function closePage(): Promise<void> {
+	try {
+		await context?.close()
+	} finally {
+		await browser?.close()
+		page = null
+		context = null
+		browser = null
+	}
+}