@opice/harness 0.0.3 → 0.1.0

package/README.md

@@ -1,66 +1,130 @@
 # @opice/harness
 
-Runtime primitives for [opice](../../README.md) — AI-driven E2E browser tests on top of [`agent-browser`](https://github.com/.../agent-browser).
+Runtime primitives for [opice](../../README.md) — AI-driven E2E browser tests on
+top of [Playwright](https://playwright.dev). The browser runs **in-process**
+under `bun test`; there is no CLI or daemon in the test path.
 
 ## Install
 
 ```bash
 bun add -D @opice/harness
+bunx playwright install chromium
 ```
 
-Requires `agent-browser` on `PATH` and a Bun test runner.
+Runs under the Bun test runner.
 
 ## Usage
 
 ```ts
-import { test, expect, describe } from 'bun:test'
-import { browserTest, el, tid, waitFor, step } from '@opice/harness'
+import { test, describe } from 'bun:test'
+import { browserTest, el, byRole, byLabel, step, expect } from '@opice/harness'
 
 browserTest('DataGrid', () => {
-  test('renders table structure', () => {
-    waitFor(() => el(tid('datagrid-table')).exists)
-    expect(el(tid('datagrid-header')).exists).toBe(true)
-  })
+  test('renders and is interactive', async () => {
+    await step('table is visible', async () => {
+      await expect(el('datagrid-table')).toBeVisible()
+    })
 
-  test('clicking a row highlights it', () => {
-    step('user clicks first row', () => {
-      el(tid('datagrid-row-0')).click()
+    await step('clicking a row highlights it', async () => {
+      await el('datagrid-row-0').click()
+      await expect(el('datagrid-row-0')).toHaveAttribute('data-highlighted', '')
     })
-    waitFor(() => el(`${tid('datagrid-row-0')}[data-highlighted]`).exists)
-  })
+  }, 60_000)
 }, { hash: 'datagrid' })
 ```
 
+The DSL is **async** and returns Playwright `Locator`s, so the full Locator API
+(`.click()`, `.fill()`, `.textContent()`, `.first()`, …) and the web-first
+`expect(locator)` assertions are available. `expect` is re-exported from the
+harness (Playwright's `expect`, which works under `bun:test`).
+
 ## API
 
-### Element handles
+### Locators
+
+- `el(selector)` — a `Locator`. A bare word is a test-id (`el('foo')` ≡
+  `getByTestId('foo')`, matching `data-testid`); anything with CSS-flavoured
+  characters is a raw CSS selector (`el('main h1')`).
+- `tid(id)` — build a `[data-testid="..."]` selector string for composing into a
+  larger CSS selector: `el(`${tid('row')} button`)`.
 
-- `el(selector)` — returns an `ElementHandle`. Plain test-ids are auto-wrapped: `el('foo')` ≡ `el('[data-testid="foo"]')`.
-- `tid(id)` — build a `[data-testid="..."]` selector string for compound selectors.
+### Accessible-name selectors
 
-`ElementHandle` properties:
+Native Playwright accessibility locators — reliable, real user gestures. Prefer
+these (or `data-testid`) over CSS.
 
-- `.exists`, `.text`, `.value`, `.isDisabled`, `.attr(name)`, `.count()`
-- `.click()`, `.fill(value)`, `.select(optionText)`
+- `byRole(role, name?)` — by ARIA role, optionally filtered by accessible name.
+- `byLabel(text)` — a form control by its `<label>` / `aria-label`.
+- `byText(text)` — by visible text.
 
-Each action call auto-scrolls into view and sleeps 500ms to let the UI settle.
+### Assertions
+
+- `expect(locator)` — Playwright's web-first, auto-retrying assertions:
+  `.toBeVisible()`, `.toHaveText()`, `.toContainText()`, `.toBeEnabled()`,
+  `.toHaveAttribute()`, … Prefer these over manual polling. Generic matchers
+  (`.toBe`, `.toEqual`) work too.
+
+### Navigation
+
+- `open(url)`, `reload()`, `back()`, `forward()` — page navigation (each awaits
+  the load event).
+- `currentUrl()`, `currentPath()` — read `location.href` / `location.pathname`
+  (synchronous).
 
 ### Waiting
 
-- `waitFor(condition, opts?)` — polls until the predicate is true; throws on timeout. Default 10s timeout, 200ms interval.
-- `wait(ms)` — fixed sleep. Avoid when `waitFor` works.
+- `waitFor(condition, opts?)` — polls a (possibly async) predicate until true;
+  throws on timeout (default 10s / 200ms). For predicates that don't map to a
+  retrying `expect` assertion.
+- `wait(ms)` — fixed sleep. Avoid when `waitFor` or `expect` works.
 
 ### Scenarios
 
-- `browserTest(name, fn, options?)` — top-level scenario. Opens a fresh agent-browser session in `beforeAll`, closes in `afterAll`. Pass `{ hash: 'foo' }` for `PLAYGROUND_URL#foo`, or just a string shorthand: `browserTest(name, fn, 'foo')`.
-- `step(name, fn)` — reportable step inside a scenario. Captures duration + screenshot. Reporter is a no-op until the opice platform is wired up.
+- `browserTest(name, fn, options?)` — top-level scenario. Launches a fresh
+  isolated Playwright browser + context + page in `beforeAll`, navigates to the
+  scenario URL, tears down in `afterAll`. Pass `{ hash: 'foo' }` for
+  `PLAYGROUND_URL#foo`, or a string shorthand: `browserTest(name, fn, 'foo')`.
+- `step(name, fn)` — reportable async step. `await step('…', async () => {…})`;
+  captures duration + screenshot. Reporter is a no-op until the platform is wired.
+
+### Custom verbs (user-land)
+
+Define a domain verb once in `<repo>/browser-tools.ts` and use it in **both** the
+authoring agent (`opice-browser`) and your tests:
+
+```ts
+// browser-tools.ts
+import { command, z } from '@opice/harness'
+
+export const fullEnum = command('fullEnum',
+  z.object({ label: z.string(), option: z.string() }),
+  async ({ page }, { label, option }) => {
+    await page.getByLabel(label).press('Enter')
+    await page.getByRole('button', { name: option }).click()
+  })
+```
+
+```ts
+// in a test
+import { call } from '@opice/harness'
+import { fullEnum } from '../browser-tools'
+await call(fullEnum, { label: 'Typ', option: 'Faktura' })
+```
 
 ### Misc
 
-- `screenshot(path?)` — saves a PNG, returns the path. Default path under `/tmp/`.
-- `evalJs(js)` — `agent-browser eval` passthrough.
+- `screenshot(path?)` — saves a PNG, returns the path (default under `/tmp/`).
+- `evalJs(js)` — `page.evaluate` passthrough (returns the real JS value).
+- `getPage()` / `getContext()` — the live Playwright `Page` / `BrowserContext`
+  for an escape hatch into the raw API.
 
 ## Configuration
 
 - `PLAYGROUND_URL` — base URL for `browserTest` (default `http://localhost:15180`).
-- `OPICE_ENDPOINT`, `OPICE_PROJECT`, `OPICE_API_KEY` — reporter config (currently no-op).
+- `OPICE_HEADED` (or `PWDEBUG`) — run headed for local debugging (default headless).
+- `OPICE_ENDPOINT`, `OPICE_PROJECT`, `OPICE_API_KEY` — reporter config (or a single `OPICE_DSN`).
+- `OPICE_REPORT` — `auto` (default: report only in CI), `always` (report locally too), or
+  `never`. Outside CI, reporting is opt-in so iterating with bare `bun test` doesn't stream
+  half-finished runs onto the shared dashboard. CI-detected runs are tagged `ci`, opted-in
+  local runs `local`.
+```

package/dist/accessible.d.ts

@@ -0,0 +1,28 @@
+import type { Locator, Page } from 'playwright';
+/** 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 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.
+ *
+ * All three return a `Locator`, so the full Locator API and `expect(locator)`
+ * assertions apply.
+ */
+/**
+ * Find an element by ARIA role and (optionally) its accessible name.
+ * `name` does a substring, case-insensitive match by default.
+ */
+export declare function byRole(role: Role, name?: string): Locator;
+/** Find a form control by its associated `<label>` (or `aria-label`) text. */
+export declare function byLabel(text: string): Locator;
+/** Find an element by its visible text (substring, case-insensitive). */
+export declare function byText(text: string): Locator;
+export {};
+//# sourceMappingURL=accessible.d.ts.map

package/dist/accessible.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"accessible.d.ts","sourceRoot":"","sources":["../src/accessible.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAG/C,gEAAgE;AAChE,KAAK,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;AAE5C;;;;;;;;;;;;;GAaG;AAEH;;;GAGG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED,8EAA8E;AAC9E,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE7C;AAED,yEAAyE;AACzE,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE5C"}

package/dist/accessible.js

@@ -0,0 +1,31 @@
+import { getPage } from './context.js';
+/**
+ * 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 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.
+ *
+ * All three return a `Locator`, so the full Locator API and `expect(locator)`
+ * assertions apply.
+ */
+/**
+ * Find an element by ARIA role and (optionally) its accessible name.
+ * `name` does a substring, case-insensitive match by default.
+ */
+export function byRole(role, name) {
+    return getPage().getByRole(role, name == null ? undefined : { name });
+}
+/** Find a form control by its associated `<label>` (or `aria-label`) text. */
+export function byLabel(text) {
+    return getPage().getByLabel(text);
+}
+/** Find an element by its visible text (substring, case-insensitive). */
+export function byText(text) {
+    return getPage().getByText(text);
+}
+//# sourceMappingURL=accessible.js.map

package/dist/accessible.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"accessible.js","sourceRoot":"","sources":["../src/accessible.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAKtC;;;;;;;;;;;;;GAaG;AAEH;;;GAGG;AACH,MAAM,UAAU,MAAM,CAAC,IAAU,EAAE,IAAa;IAC/C,OAAO,OAAO,EAAE,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,IAAI,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAA;AACtE,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,OAAO,CAAC,IAAY;IACnC,OAAO,OAAO,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,CAAA;AAClC,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,MAAM,CAAC,IAAY;IAClC,OAAO,OAAO,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,CAAA;AACjC,CAAC"}

package/dist/command.d.ts

@@ -0,0 +1,65 @@
+import type { Locator, Page } from 'playwright';
+import { z } from 'zod';
+/**
+ * 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 declare function command<S extends z.ZodType>(name: string, params: S, run: (ctx: CommandCtx, args: z.infer<S>) => Promise<unknown>, description?: string): Command<S>;
+/** Build the command context bound to a specific page. */
+export declare function makeCtx(page: Page): CommandCtx;
+/** Validate args against a command's schema and run it on `page`. */
+export declare function runCommand(page: Page, cmd: Command, rawArgs: unknown): Promise<unknown>;
+/**
+ * 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 declare function call<S extends z.ZodType>(cmd: Command<S>, args: z.infer<S>): Promise<unknown>;
+/**
+ * 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 declare function findUserCommandsFile(from?: string): string | null;
+/**
+ * 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 declare function loadUserCommands(from?: string): Promise<Map<string, Command>>;
+export { z };
+//# sourceMappingURL=command.d.ts.map

package/dist/command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../src/command.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAC/C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAIvB;;;;;;;;;;;;;;;GAeG;AAEH,iFAAiF;AACjF,MAAM,WAAW,UAAU;IAC1B,IAAI,EAAE,IAAI,CAAA;IACV,sEAAsE;IACtE,EAAE,CAAC,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAA;IACrC,MAAM,CAAC,IAAI,EAAE,UAAU,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;IACtE,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;IAC9B,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;CAC7B;AAED,MAAM,WAAW,OAAO,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO;IACvD,IAAI,EAAE,MAAM,CAAA;IACZ,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,MAAM,EAAE,CAAC,CAAA;IACT,GAAG,EAAE,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;CAC5D;AAED,0EAA0E;AAC1E,wBAAgB,OAAO,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAC1C,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,CAAC,EACT,GAAG,EAAE,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,EAC5D,WAAW,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,CAAC,CAAC,CAEZ;AAED,0DAA0D;AAC1D,wBAAgB,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,UAAU,CAQ9C;AAED,qEAAqE;AACrE,wBAAsB,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAG7F;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,IAAI,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAEnG;AAaD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,GAAE,MAAsB,GAAG,MAAM,GAAG,IAAI,CAWhF;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAanF;AAED,OAAO,EAAE,CAAC,EAAE,CAAA"}

package/dist/command.js

@@ -0,0 +1,88 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { z } from 'zod';
+import { getPage } from './context.js';
+import { locatorOn } from './element.js';
+/** Define a browser command. See `CommandCtx` for what `ctx` provides. */
+export function command(name, params, run, description) {
+    return { name, params, run, description };
+}
+/** Build the command context bound to a specific page. */
+export function makeCtx(page) {
+    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, cmd, rawArgs) {
+    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(cmd, args) {
+    return runCommand(getPage(), cmd, args);
+}
+/** Duck-type check: is a module export a `Command`? */
+function isCommand(value) {
+    return (typeof value === 'object'
+        && value !== null
+        && typeof value.name === 'string'
+        && typeof value.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 = process.cwd()) {
+    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) {
+    const registry = new Map();
+    const file = findUserCommandsFile(from);
+    if (!file)
+        return registry;
+    const mod = (await import(pathToFileURL(file).href));
+    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 };
+//# sourceMappingURL=command.js.map

package/dist/command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.js","sourceRoot":"","sources":["../src/command.ts"],"names":[],"mappings":"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"}

package/dist/context.d.ts

@@ -0,0 +1,10 @@
+import { type BrowserContext, type Page } from 'playwright';
+/** The active page, or throw if called outside a `browserTest` scenario. */
+export declare function getPage(): Page;
+/** The active browser context (for cookies/storage, new tabs, etc.). */
+export declare function getContext(): BrowserContext;
+/** Launch a fresh isolated browser + context + page. Called from `beforeAll`. */
+export declare function launchPage(): Promise<Page>;
+/** Close the page, context, and browser. Called from `afterAll`. */
+export declare function closePage(): Promise<void>;
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,KAAK,cAAc,EAAE,KAAK,IAAI,EAAE,MAAM,YAAY,CAAA;AAoBnF,4EAA4E;AAC5E,wBAAgB,OAAO,IAAI,IAAI,CAK9B;AAED,wEAAwE;AACxE,wBAAgB,UAAU,IAAI,cAAc,CAK3C;AAED,iFAAiF;AACjF,wBAAsB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAKhD;AAED,oEAAoE;AACpE,wBAAsB,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAS/C"}

package/dist/context.js

@@ -0,0 +1,50 @@
+import { chromium } 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 = null;
+let context = null;
+let page = null;
+/** Headed mode for local debugging (`OPICE_HEADED=1` or Playwright's `PWDEBUG`). */
+function headed() {
+    return !!(process.env['OPICE_HEADED'] || process.env['PWDEBUG']);
+}
+/** The active page, or throw if called outside a `browserTest` scenario. */
+export function getPage() {
+    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() {
+    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() {
+    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() {
+    try {
+        await context?.close();
+    }
+    finally {
+        await browser?.close();
+        page = null;
+        context = null;
+        browser = null;
+    }
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAgD,MAAM,YAAY,CAAA;AAEnF;;;;;;;GAOG;AAEH,IAAI,OAAO,GAAmB,IAAI,CAAA;AAClC,IAAI,OAAO,GAA0B,IAAI,CAAA;AACzC,IAAI,IAAI,GAAgB,IAAI,CAAA;AAE5B,oFAAoF;AACpF,SAAS,MAAM;IACd,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAA;AACjE,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,OAAO;IACtB,IAAI,CAAC,IAAI,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,yEAAyE,CAAC,CAAA;IAC3F,CAAC;IACD,OAAO,IAAI,CAAA;AACZ,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,UAAU;IACzB,IAAI,CAAC,OAAO,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,wEAAwE,CAAC,CAAA;IAC1F,CAAC;IACD,OAAO,OAAO,CAAA;AACf,CAAC;AAED,iFAAiF;AACjF,MAAM,CAAC,KAAK,UAAU,UAAU;IAC/B,OAAO,GAAG,MAAM,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,CAAA;IACxD,OAAO,GAAG,MAAM,OAAO,CAAC,UAAU,EAAE,CAAA;IACpC,IAAI,GAAG,MAAM,OAAO,CAAC,OAAO,EAAE,CAAA;IAC9B,OAAO,IAAI,CAAA;AACZ,CAAC;AAED,oEAAoE;AACpE,MAAM,CAAC,KAAK,UAAU,SAAS;IAC9B,IAAI,CAAC;QACJ,MAAM,OAAO,EAAE,KAAK,EAAE,CAAA;IACvB,CAAC;YAAS,CAAC;QACV,MAAM,OAAO,EAAE,KAAK,EAAE,CAAA;QACtB,IAAI,GAAG,IAAI,CAAA;QACX,OAAO,GAAG,IAAI,CAAA;QACd,OAAO,GAAG,IAAI,CAAA;IACf,CAAC;AACF,CAAC"}

package/dist/dsn.d.ts

@@ -0,0 +1,17 @@
+/**
+ * An opice DSN packs everything a project needs to report into one string:
+ *
+ *   OPICE_DSN=https://<apiKey>@<host>/<slug>
+ *
+ * The api key rides in the userinfo, the host is the platform endpoint, and
+ * the first path segment is the project slug. It's the single value the
+ * dashboard hands you to drop into `.env`; the individual `OPICE_*` vars still
+ * win when set, so a DSN is purely a convenience fallback.
+ */
+export interface OpiceDsn {
+    apiKey: string;
+    endpoint: string;
+    project: string;
+}
+export declare function parseOpiceDsn(raw: string | undefined | null): OpiceDsn | null;
+//# sourceMappingURL=dsn.d.ts.map

package/dist/dsn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dsn.d.ts","sourceRoot":"","sources":["../src/dsn.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,WAAW,QAAQ;IACxB,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;CACf;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,QAAQ,GAAG,IAAI,CAY7E"}

package/dist/dsn.js

@@ -0,0 +1,17 @@
+export function parseOpiceDsn(raw) {
+    if (!raw)
+        return null;
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return null;
+    }
+    const apiKey = decodeURIComponent(url.username);
+    const project = url.pathname.replace(/^\/+/, '').split('/')[0] ?? '';
+    if (!apiKey || !project)
+        return null;
+    return { apiKey, endpoint: `${url.protocol}//${url.host}`, project };
+}
+//# sourceMappingURL=dsn.js.map

package/dist/dsn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dsn.js","sourceRoot":"","sources":["../src/dsn.ts"],"names":[],"mappings":"AAgBA,MAAM,UAAU,aAAa,CAAC,GAA8B;IAC3D,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAA;IACrB,IAAI,GAAQ,CAAA;IACZ,IAAI,CAAC;QACJ,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAA;IACnB,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,IAAI,CAAA;IACZ,CAAC;IACD,MAAM,MAAM,GAAG,kBAAkB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;IAC/C,MAAM,OAAO,GAAG,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;IACpE,IAAI,CAAC,MAAM,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAA;IACpC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,GAAG,CAAC,QAAQ,KAAK,GAAG,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,CAAA;AACrE,CAAC"}

package/dist/element.d.ts

@@ -0,0 +1,50 @@
+import type { Locator, Page } from 'playwright';
+/**
+ * Resolve a selector into a `Locator` on an explicit page — the shared core
+ * behind `el()` and the command-registry context. Bare identifiers become
+ * test-ids (`getByTestId`, matching `data-testid`); anything with CSS-flavoured
+ * characters (`[ ] . # : > ` or a space) is a raw CSS selector.
+ */
+export declare function locatorOn(page: Page, selectorOrTestId: string): Locator;
+/**
+ * Resolve a selector into a Playwright `Locator`.
+ *
+ * Bare identifiers are auto-wrapped as test-ids (`page.getByTestId`, which
+ * matches `data-testid` by default); anything with CSS-flavoured characters
+ * (`[ ] . # : > ` or a space) is treated as a raw CSS selector. Heuristic — if
+ * you need a plain-tag selector (e.g. `h1`), give it structure (`main h1`).
+ *
+ * The returned value is a real Playwright `Locator`, so the full Locator API
+ * (`.click()`, `.fill()`, `.textContent()`, `.first()`, `.nth()`, …) and the
+ * web-first `expect(locator)` assertions are available. All actions auto-wait
+ * for actionability and fire real user gestures.
+ */
+export declare function el(selectorOrTestId: string): Locator;
+/**
+ * Build a `[data-testid="..."]` selector string, for composing into a larger
+ * CSS selector: `el(`${tid('row')} button`)`. For a plain test-id, prefer
+ * `el('row')` directly.
+ */
+export declare function tid(testId: string): string;
+/**
+ * Poll a (possibly async) condition until it returns true or times out.
+ *
+ * Prefer Playwright's retrying assertions — `await expect(el('x')).toBeVisible()`,
+ * `.toHaveText(...)` — which auto-wait and give better failure messages. Keep
+ * `waitFor` for arbitrary predicates that don't map to a locator assertion.
+ */
+export declare function waitFor(condition: () => boolean | Promise<boolean>, { timeout, interval, message }?: {
+    timeout?: number;
+    interval?: number;
+    message?: string;
+}): Promise<void>;
+/** Fixed sleep. Avoid when possible — prefer `waitFor` or retrying assertions. */
+export declare function wait(ms: number): Promise<void>;
+/**
+ * Evaluate JavaScript in the page and return its result. Thin wrapper over
+ * `page.evaluate`; the value is the real JS value (not a JSON string).
+ */
+export declare function evalJs<T = unknown>(js: string): Promise<T>;
+/** Capture a screenshot to `path` (or a temp file) and return the path. */
+export declare function screenshot(path?: string): Promise<string>;
+//# sourceMappingURL=element.d.ts.map

package/dist/element.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"element.d.ts","sourceRoot":"","sources":["../src/element.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAM/C;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAKvE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,EAAE,CAAC,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;;;GAIG;AACH,wBAAgB,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE1C;AAED;;;;;;GAMG;AACH,wBAAsB,OAAO,CAC5B,SAAS,EAAE,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,EAC3C,EAAE,OAAsB,EAAE,QAAwB,EAAE,OAAO,EAAE,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GAC3H,OAAO,CAAC,IAAI,CAAC,CAef;AAED,kFAAkF;AAClF,wBAAsB,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEpD;AAED;;;GAGG;AACH,wBAAgB,MAAM,CAAC,CAAC,GAAG,OAAO,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAE1D;AAED,2EAA2E;AAC3E,wBAAsB,UAAU,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAI/D"}

package/dist/element.js

@@ -0,0 +1,82 @@
+import { getPage } from './context.js';
+const POLL_INTERVAL = 200;
+const POLL_TIMEOUT = 10_000;
+/**
+ * Resolve a selector into a `Locator` on an explicit page — the shared core
+ * behind `el()` and the command-registry context. Bare identifiers become
+ * test-ids (`getByTestId`, matching `data-testid`); anything with CSS-flavoured
+ * characters (`[ ] . # : > ` or a space) is a raw CSS selector.
+ */
+export function locatorOn(page, selectorOrTestId) {
+    if (/[\[\].#:> ]/.test(selectorOrTestId)) {
+        return page.locator(selectorOrTestId);
+    }
+    return page.getByTestId(selectorOrTestId);
+}
+/**
+ * Resolve a selector into a Playwright `Locator`.
+ *
+ * Bare identifiers are auto-wrapped as test-ids (`page.getByTestId`, which
+ * matches `data-testid` by default); anything with CSS-flavoured characters
+ * (`[ ] . # : > ` or a space) is treated as a raw CSS selector. Heuristic — if
+ * you need a plain-tag selector (e.g. `h1`), give it structure (`main h1`).
+ *
+ * The returned value is a real Playwright `Locator`, so the full Locator API
+ * (`.click()`, `.fill()`, `.textContent()`, `.first()`, `.nth()`, …) and the
+ * web-first `expect(locator)` assertions are available. All actions auto-wait
+ * for actionability and fire real user gestures.
+ */
+export function el(selectorOrTestId) {
+    return locatorOn(getPage(), selectorOrTestId);
+}
+/**
+ * Build a `[data-testid="..."]` selector string, for composing into a larger
+ * CSS selector: `el(`${tid('row')} button`)`. For a plain test-id, prefer
+ * `el('row')` directly.
+ */
+export function tid(testId) {
+    return `[data-testid="${testId}"]`;
+}
+/**
+ * Poll a (possibly async) condition until it returns true or times out.
+ *
+ * Prefer Playwright's retrying assertions — `await expect(el('x')).toBeVisible()`,
+ * `.toHaveText(...)` — which auto-wait and give better failure messages. Keep
+ * `waitFor` for arbitrary predicates that don't map to a locator assertion.
+ */
+export async function waitFor(condition, { timeout = POLL_TIMEOUT, interval = POLL_INTERVAL, message } = {}) {
+    const start = Date.now();
+    while (Date.now() - start < timeout) {
+        try {
+            if (await condition())
+                return;
+        }
+        catch {
+            // condition threw — treat as not yet ready
+        }
+        await new Promise((resolve) => setTimeout(resolve, interval));
+    }
+    if (!(await condition())) {
+        const elapsed = Date.now() - start;
+        const hint = message ?? condition.toString().slice(0, 120);
+        throw new Error(`waitFor timed out after ${elapsed}ms: ${hint}`);
+    }
+}
+/** Fixed sleep. Avoid when possible — prefer `waitFor` or retrying assertions. */
+export async function wait(ms) {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Evaluate JavaScript in the page and return its result. Thin wrapper over
+ * `page.evaluate`; the value is the real JS value (not a JSON string).
+ */
+export function evalJs(js) {
+    return getPage().evaluate(js);
+}
+/** Capture a screenshot to `path` (or a temp file) and return the path. */
+export async function screenshot(path) {
+    const target = path ?? `/tmp/opice-screenshot-${Date.now()}.png`;
+    await getPage().screenshot({ path: target });
+    return target;
+}
+//# sourceMappingURL=element.js.map