@opice/harness 0.0.3 → 0.0.4

package/README.md

@@ -41,9 +41,33 @@ browserTest('DataGrid', () => {
 `ElementHandle` properties:
 
 - `.exists`, `.text`, `.value`, `.isDisabled`, `.attr(name)`, `.count()`
-- `.click()`, `.fill(value)`, `.select(optionText)`
+- `.click()`, `.fill(value)`, `.select(optionText)`, `.focus()`, `.hover()`, `.press(key)`
 
 Each action call auto-scrolls into view and sleeps 500ms to let the UI settle.
+`.press(key)` focuses first, then sends the key (`Enter`, `Tab`, `Control+a`).
+
+### Accessible-name selectors
+
+For apps you can't annotate with `data-testid` (third-party UIs, generated form
+ids). These wrap agent-browser's `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'`). Each returns an
+`ElementHandle`.
+
+- `byRole(role, name?)` — by ARIA role, optionally filtered by accessible name.
+- `byLabel(text)` — a form control by its `<label>` (resolved via `for`/nesting).
+- `byText(text)` — a leaf element by its visible text.
+
+Actions go through `find`; queries (`.exists`, `.text`, …) and the focus/press
+path fall back to a small `eval`. Prefer `data-testid` + `el()` when you own the
+markup.
+
+### Navigation
+
+- `open(url)`, `reload()`, `back()`, `forward()` — page navigation. Use
+  `reload()` after writing auth to localStorage/cookies (an `eval`-triggered
+  reload is dropped by agent-browser).
+- `currentUrl()`, `currentPath()` — read `location.href` / `location.pathname`.
 
 ### Waiting
 
@@ -63,4 +87,8 @@ Each action call auto-scrolls into view and sleeps 500ms to let the UI settle.
 ## Configuration
 
 - `PLAYGROUND_URL` — base URL for `browserTest` (default `http://localhost:15180`).
-- `OPICE_ENDPOINT`, `OPICE_PROJECT`, `OPICE_API_KEY` — reporter config (currently no-op).
+- `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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@opice/harness",
-	"version": "0.0.3",
+	"version": "0.0.4",
 	"description": "Runtime primitives for opice — AI-driven E2E browser tests on top of agent-browser",
 	"type": "module",
 	"main": "./src/index.ts",

package/src/accessible.ts

@@ -0,0 +1,204 @@
+import { exec, q } from './agent-browser.js'
+import { el, type ElementHandle, evalJs } from './element.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 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'
+ *
+ * `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.
+ */
+
+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'`.
+ */
+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)})`,
+	})
+}
+
+/**
+ * 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)})`,
+	})
+}
+
+/** 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}]`
+	}
+}

package/src/element.ts

@@ -51,6 +51,10 @@ export interface ElementHandle {
 	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 {
@@ -90,6 +94,20 @@ export function el(selector: string): ElementHandle {
 			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)
+		},
 	}
 }
 

package/src/index.ts

@@ -1,6 +1,10 @@
 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 { browserTest, step } from './scenario.js'
 export type { BrowserTestOptions } from './scenario.js'
 

package/src/navigation.ts

@@ -0,0 +1,53 @@
+import { exec } from './agent-browser.js'
+import { evalJs } from './element.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.
+ */
+
+/** Navigate to a URL in the current session. */
+export function open(url: string): void {
+	exec(`agent-browser open ${url}`)
+}
+
+/** Reload the current page (and wait for the CLI to settle). */
+export function reload(): void {
+	exec('agent-browser reload')
+}
+
+/** Go back in history. */
+export function back(): void {
+	exec('agent-browser back')
+}
+
+/** Go forward in history. */
+export function forward(): void {
+	exec('agent-browser forward')
+}
+
+/** The current full URL (`location.href`). */
+export function currentUrl(): string {
+	return readLocation('href')
+}
+
+/** 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
+	}
+}

package/src/reporter.ts

@@ -26,10 +26,14 @@ export interface ReporterConfig {
 	apiKey: string
 	branch?: string
 	commit?: string
+	/** 'ci' for runs from automation, 'local' for opted-in dev runs. */
+	source?: 'ci' | 'local'
 }
 
 export interface StepEvent {
 	scenarioId: string
+	/** Authoring order within the scenario, assigned at step() call time. */
+	sequence: number
 	name: string
 	status: 'passed' | 'failed'
 	durationMs: number
@@ -96,6 +100,7 @@ class HttpReporter implements Reporter {
 		const response = await this.fetch('POST', '/api/v1/runs', {
 			branch: this.config.branch,
 			commit: this.config.commit,
+			source: this.config.source,
 		})
 		const runId = response['runId'] as string
 		// Synchronous write so the CLI can pick this up even if the test
@@ -136,6 +141,7 @@ class HttpReporter implements Reporter {
 			? await this.encodeScreenshot(event.screenshotPath)
 			: undefined
 		await this.fetch('POST', `/api/v1/runs/${runId}/scenarios/${event.scenarioId}/steps`, {
+			sequence: event.sequence,
 			name: event.name,
 			status: event.status,
 			durationMs: event.durationMs,
@@ -240,12 +246,24 @@ export function configureFromEnv(env: NodeJS.ProcessEnv = process.env): Reporter
 	if (!endpoint || !projectId || !apiKey) {
 		return new NoopReporter()
 	}
+	// Reporting is opt-in outside CI. A local `bun test` while authoring would
+	// otherwise stream half-finished runs onto the shared dashboard (they never
+	// get the CLI's POST /finish, so they'd sit there as "running" forever).
+	// CI reports automatically; OPICE_REPORT=always forces it locally, =never
+	// silences it everywhere.
+	const isCI = !!(env['CI'] || env['GITHUB_ACTIONS'])
+	const mode = (env['OPICE_REPORT'] ?? 'auto').toLowerCase()
+	const shouldReport = mode === 'never' ? false : mode === 'always' ? true : isCI
+	if (!shouldReport) {
+		return new NoopReporter()
+	}
 	const reporter = new HttpReporter({
 		endpoint,
 		projectId,
 		apiKey,
 		branch: env['OPICE_BRANCH'] ?? env['GITHUB_REF_NAME'],
 		commit: env['OPICE_COMMIT'] ?? env['GITHUB_SHA'],
+		source: isCI ? 'ci' : 'local',
 	})
 	setReporter(reporter)
 	return reporter

package/src/scenario.ts

@@ -51,6 +51,11 @@ function defaultScenarioFile(testFile: string | undefined): string | undefined {
 let currentScenarioId: string | null = null
 let currentScenarioStart: number = 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.
@@ -71,6 +76,7 @@ export function browserTest(name: string, fn: () => void, options: BrowserTestOp
 			setSession(session)
 			currentScenarioStart = Date.now()
 			currentScenarioFailures = 0
+			currentScenarioStepSeq = 0
 			try {
 				currentScenarioId = await reporter.startScenario({ name, hash: opts.hash, testFile, scenarioFile })
 			} catch {
@@ -126,6 +132,8 @@ export function browserTest(name: string, fn: () => void, options: BrowserTestOp
  */
 export function step(name: string, fn: () => void): void {
 	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' | 'failed' = 'passed'
 	let error: string | undefined
@@ -147,6 +155,7 @@ export function step(name: string, fn: () => void): void {
 		if (currentScenarioId) {
 			void reporter.recordStep({
 				scenarioId: currentScenarioId,
+				sequence,
 				name,
 				status,
 				durationMs,