@opice/harness 0.0.4 → 0.1.1

package/src/element.ts

@@ -1,134 +1,91 @@
-import { exec, q } from './agent-browser.js'
+import type { Locator, Page } from 'playwright'
+import { getPage } from './context.js'
 
 const POLL_INTERVAL = 200
 const POLL_TIMEOUT = 10_000
-const ACTION_SETTLE_MS = 500
 
 /**
- * Auto-wrap bare identifiers as `[data-testid="…"]` selectors; treat anything
- * with CSS-flavoured characters as a raw selector. Heuristic — if you need a
- * plain-tag selector (e.g. `h1`), give it some structure (e.g. `main h1`) or
- * use a descendant/attribute form.
+ * 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.
  */
-function resolveSelector(selectorOrTestId: string): string {
+export function locatorOn(page: Page, selectorOrTestId: string): Locator {
 	if (/[\[\].#:> ]/.test(selectorOrTestId)) {
-		return selectorOrTestId
+		return page.locator(selectorOrTestId)
 	}
-	return `[data-testid="${selectorOrTestId}"]`
+	return page.getByTestId(selectorOrTestId)
 }
 
 /**
- * Poll a condition until it returns true or timeout.
- * Use instead of fixed sleep — stable on both fast local and slow CI.
+ * 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 waitFor(
-	condition: () => boolean,
+export function el(selectorOrTestId: string): Locator {
+	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: string): string {
+	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: () => boolean | Promise<boolean>,
 	{ timeout = POLL_TIMEOUT, interval = POLL_INTERVAL, message }: { timeout?: number; interval?: number; message?: string } = {},
-): void {
+): Promise<void> {
 	const start = Date.now()
 	while (Date.now() - start < timeout) {
 		try {
-			if (condition()) return
+			if (await condition()) return
 		} catch {
 			// condition threw — treat as not yet ready
 		}
-		Bun.sleepSync(interval)
+		await new Promise((resolve) => setTimeout(resolve, interval))
 	}
-	if (!condition()) {
+	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}`)
 	}
 }
 
-export interface ElementHandle {
-	readonly exists: boolean
-	readonly text: string
-	readonly value: string
-	readonly isDisabled: boolean
-	attr(name: string): string
-	count(): number
-	click(): void
-	fill(value: string): void
-	select(optionText: string): void
-	focus(): void
-	hover(): void
-	/** Focus the element, then send a key (e.g. `Enter`, `Escape`, `ArrowDown`). */
-	press(key: string): void
-}
-
-export function el(selector: string): ElementHandle {
-	const sel = resolveSelector(selector)
-	const quoted = q(sel)
-	return {
-		get exists(): boolean {
-			return parseInt(exec(`agent-browser get count ${quoted}`), 10) > 0
-		},
-		get text(): string {
-			return exec(`agent-browser get text ${quoted}`)
-		},
-		get value(): string {
-			return exec(`agent-browser get value ${quoted}`)
-		},
-		get isDisabled(): boolean {
-			return exec(`agent-browser is enabled ${quoted}`) !== 'true'
-		},
-		attr(name: string): string {
-			return exec(`agent-browser get attr ${name} ${quoted}`)
-		},
-		count(): number {
-			return parseInt(exec(`agent-browser get count ${quoted}`), 10) || 0
-		},
-		click(): void {
-			exec(`agent-browser scrollintoview ${quoted}`)
-			exec(`agent-browser click ${quoted}`)
-			Bun.sleepSync(ACTION_SETTLE_MS)
-		},
-		fill(value: string): void {
-			exec(`agent-browser scrollintoview ${quoted}`)
-			exec(`agent-browser fill ${quoted} ${q(value)}`)
-			Bun.sleepSync(ACTION_SETTLE_MS)
-		},
-		select(optionText: string): void {
-			exec(`agent-browser scrollintoview ${quoted}`)
-			exec(`agent-browser select ${quoted} ${q(optionText)}`)
-			Bun.sleepSync(ACTION_SETTLE_MS)
-		},
-		focus(): void {
-			exec(`agent-browser scrollintoview ${quoted}`)
-			exec(`agent-browser focus ${quoted}`)
-		},
-		hover(): void {
-			exec(`agent-browser scrollintoview ${quoted}`)
-			exec(`agent-browser hover ${quoted}`)
-			Bun.sleepSync(ACTION_SETTLE_MS)
-		},
-		press(key: string): void {
-			exec(`agent-browser focus ${quoted}`)
-			exec(`agent-browser press ${key}`)
-			Bun.sleepSync(ACTION_SETTLE_MS)
-		},
-	}
+/** Fixed sleep. Avoid when possible — prefer `waitFor` or retrying assertions. */
+export async function wait(ms: number): Promise<void> {
+	await new Promise((resolve) => setTimeout(resolve, ms))
 }
 
 /**
- * Build a `[data-testid="..."]` selector for compound selectors.
- * Usage: el(`${tid('parent')} button`)
+ * 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 tid(testId: string): string {
-	return `[data-testid="${testId}"]`
-}
-
-export function wait(ms: number): void {
-	Bun.sleepSync(ms)
-}
-
-export function evalJs(js: string): string {
-	return exec(`agent-browser eval ${q(js)}`)
+export function evalJs<T = unknown>(js: string): Promise<T> {
+	return getPage().evaluate(js) as Promise<T>
 }
 
-export function screenshot(path?: string): string {
+/** Capture a screenshot to `path` (or a temp file) and return the path. */
+export async function screenshot(path?: string): Promise<string> {
 	const target = path ?? `/tmp/opice-screenshot-${Date.now()}.png`
-	exec(`agent-browser screenshot ${target}`)
+	await getPage().screenshot({ path: target })
 	return target
 }

package/src/index.ts

@@ -1,10 +1,11 @@
 export { el, tid, waitFor, wait, evalJs, screenshot } from './element.js'
-export type { ElementHandle } from './element.js'
 
 export { byLabel, byRole, byText } from './accessible.js'
 
 export { back, currentPath, currentUrl, forward, open, reload } from './navigation.js'
 
+export { getPage, getContext } from './context.js'
+
 export { browserTest, step } from './scenario.js'
 export type { BrowserTestOptions } from './scenario.js'
 
@@ -13,3 +14,13 @@ export type { Reporter, ReporterConfig, StepEvent, ScenarioStart, ScenarioFinish
 
 export { parseOpiceDsn } from './dsn.js'
 export type { OpiceDsn } from './dsn.js'
+
+export { command, call, runCommand, makeCtx, loadUserCommands, findUserCommandsFile, z } from './command.js'
+export type { Command, CommandCtx } from './command.js'
+
+// Playwright's web-first `expect` (retrying locator matchers + generic matchers)
+// works under `bun:test`; re-export it so tests use a single `expect`.
+export { expect } from '@playwright/test'
+
+// The DSL returns Playwright Locators directly — re-export the type.
+export type { Locator } from 'playwright'

package/src/navigation.ts

@@ -1,53 +1,41 @@
-import { exec } from './agent-browser.js'
-import { evalJs } from './element.js'
+import { getPage } from './context.js'
 
 /**
  * Page navigation primitives. `browserTest` opens the scenario URL for you in
  * `beforeAll`; these are for mid-scenario navigation — following a hard link,
  * reloading after mutating storage/cookies, or going back/forward.
  *
- * Note on reload: a reload triggered from inside `evalJs('location.reload()')`
- * is dropped by agent-browser (the eval's execution context is torn down before
- * the navigation commits), so `reload()` shells out to the CLI instead. Use it
- * after writing auth tokens to localStorage/cookies so the app re-reads them.
+ * Each navigating call waits for the `load` event (Playwright's default), so
+ * the old agent-browser reload caveat (a reload from inside `eval` getting
+ * dropped) no longer applies — `reload()` drives the page directly.
  */
 
-/** Navigate to a URL in the current session. */
-export function open(url: string): void {
-	exec(`agent-browser open ${url}`)
+/** Navigate to a URL in the current page. */
+export async function open(url: string): Promise<void> {
+	await getPage().goto(url)
 }
 
-/** Reload the current page (and wait for the CLI to settle). */
-export function reload(): void {
-	exec('agent-browser reload')
+/** Reload the current page. */
+export async function reload(): Promise<void> {
+	await getPage().reload()
 }
 
 /** Go back in history. */
-export function back(): void {
-	exec('agent-browser back')
+export async function back(): Promise<void> {
+	await getPage().goBack()
 }
 
 /** Go forward in history. */
-export function forward(): void {
-	exec('agent-browser forward')
+export async function forward(): Promise<void> {
+	await getPage().goForward()
 }
 
 /** The current full URL (`location.href`). */
 export function currentUrl(): string {
-	return readLocation('href')
+	return getPage().url()
 }
 
 /** The current path (`location.pathname`). */
 export function currentPath(): string {
-	return readLocation('pathname')
-}
-
-function readLocation(prop: 'href' | 'pathname'): string {
-	const raw = evalJs(`location.${prop}`)
-	try {
-		const value: unknown = JSON.parse(raw)
-		return typeof value === 'string' ? value : raw
-	} catch {
-		return raw
-	}
+	return new URL(getPage().url()).pathname
 }

package/src/scenario.ts

@@ -1,10 +1,21 @@
-import { describe, beforeAll, afterAll } from 'bun:test'
-import crypto from 'node:crypto'
+import { createRequire } from 'node:module'
 import path from 'node:path'
-import { exec, setSession } from './agent-browser.js'
-import { waitFor, screenshot } from './element.js'
+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(): typeof import('bun:test') {
+	return require('bun:test') as typeof import('bun:test')
+}
+
 const PLAYGROUND_URL = process.env['PLAYGROUND_URL'] ?? 'http://localhost:15180'
 
 export interface BrowserTestOptions {
@@ -60,20 +71,20 @@ let currentScenarioStepSeq = 0
 /**
  * Register a top-level browser test scenario.
  *
- * Each `browserTest(name, fn)` opens its own agent-browser session, navigates
- * to the playground URL, runs the given `fn` (which typically contains nested
- * `describe`/`test` blocks), and closes the session in `afterAll`.
+ * 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: string, fn: () => void, options: BrowserTestOptions | string = {}): void {
 	const opts: BrowserTestOptions = 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 () => {
-			const session = `opice-${crypto.randomUUID().slice(0, 8)}`
-			setSession(session)
 			currentScenarioStart = Date.now()
 			currentScenarioFailures = 0
 			currentScenarioStepSeq = 0
@@ -82,25 +93,18 @@ export function browserTest(name: string, fn: () => void, options: BrowserTestOp
 			} catch {
 				currentScenarioId = null
 			}
+			const page = await launchPage()
 			const base = opts.url ?? PLAYGROUND_URL
 			const url = opts.hash ? `${base}#${opts.hash}` : base
-			exec(`agent-browser open ${url}`)
-			waitFor(() => {
-				try {
-					return exec('agent-browser get title').length > 0
-				} catch {
-					return false
-				}
-			}, { timeout: 15_000 })
+			await page.goto(url)
 		}, 30_000)
 
 		afterAll(async () => {
 			try {
-				exec('agent-browser close')
+				await closePage()
 			} catch {
 				// ignore close errors
 			}
-			setSession(null)
 			if (currentScenarioId) {
 				// Drain pending step records (incl. their screenshot uploads)
 				// before marking the scenario done. step() fires recordStep
@@ -129,8 +133,11 @@ export function browserTest(name: string, fn: () => void, options: BrowserTestOp
 /**
  * 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 function step(name: string, fn: () => void): void {
+export async function step(name: string, fn: () => void | Promise<void>): Promise<void> {
 	const reporter = getReporter()
 	// Capture order at call time, before the fire-and-forget record below.
 	const sequence = currentScenarioStepSeq++
@@ -138,7 +145,7 @@ export function step(name: string, fn: () => void): void {
 	let status: 'passed' | 'failed' = 'passed'
 	let error: string | undefined
 	try {
-		fn()
+		await fn()
 	} catch (e) {
 		status = 'failed'
 		error = e instanceof Error ? e.message : String(e)
@@ -148,7 +155,7 @@ export function step(name: string, fn: () => void): void {
 		const durationMs = Date.now() - start
 		let screenshotPath: string | undefined
 		try {
-			screenshotPath = screenshot()
+			screenshotPath = await screenshot()
 		} catch {
 			// screenshot failure shouldn't fail the test
 		}

package/src/agent-browser.ts

@@ -1,30 +0,0 @@
-import { execSync } from 'node:child_process'
-
-const EXEC_TIMEOUT = 30_000
-
-let currentSession: string | null = null
-
-export function setSession(session: string | null): void {
-	currentSession = session
-}
-
-export function getSession(): string | null {
-	return currentSession
-}
-
-export function exec(cmd: string): string {
-	const sessionFlag = currentSession ? `--session ${currentSession} ` : ''
-	const fullCmd = cmd.replace(/^agent-browser /, `agent-browser ${sessionFlag}`)
-	try {
-		const raw = execSync(fullCmd, { encoding: 'utf-8', timeout: EXEC_TIMEOUT, stdio: ['pipe', 'pipe', 'pipe'] }).trim()
-		return raw.replace(/\x1B\[[0-9;]*m/g, '')
-	} catch (e: unknown) {
-		const err = e as { stdout?: string; stderr?: string; message?: string }
-		const output = err.stdout?.trim() ?? err.stderr?.trim() ?? err.message ?? 'unknown error'
-		throw new Error(`agent-browser command failed: ${fullCmd}\n${output}`)
-	}
-}
-
-export function q(s: string): string {
-	return `'${s.replace(/'/g, "'\\''")}'`
-}