@mercuryo-ai/agentbrowse 0.2.61 → 0.2.63

package/docs/testing.md

@@ -1,30 +1,36 @@
 # AgentBrowse Testing Guide
 
-Use the published testing subpath when your package wraps AgentBrowse and you
-need a stable assistive-runtime helper in tests.
+Use the published `/testing` subpath when your package wraps AgentBrowse
+and needs a stable, typed set of testing helpers. The subpath covers two
+separate testing concerns: the assistive runtime (needed by
+`extract(...)` and goal-based `observe(...)` callers) and the
+`match` / `resolve` / `fill` primitives.
 
 ## Testing Export
 
 ```ts
 import {
+  // Match / resolve / fill fixtures
+  createFixtureMatchStore,
+  createFixtureGroupStore,
+  createFixtureResolver,
+  fixtureResolvedValue,
+  fixtureResolvedArtifact,
+  // Assistive runtime fixture
   installFetchBackedTestAssistiveRuntime,
   uninstallTestAssistiveRuntime,
 } from '@mercuryo-ai/agentbrowse/testing';
 ```
 
-## What It Does
+All exports are stable across minor versions within the package. Rely on
+them instead of reaching into `src/**/*.test-support.ts` files
+directly — those are implementation detail.
 
-`installFetchBackedTestAssistiveRuntime(...)` installs a process-global
-assistive runtime that sends structured chat requests over `fetch`.
+## Assistive Runtime Fixture
 
-Use it when:
-
-- your tests wrap `extract(...)`
-- your tests cover goal-based `observe(session, goal)`
-- your package wants to exercise the current public assistive runtime
-  shape
-
-## Example
+Installs a process-global assistive runtime that sends structured chat
+requests over `fetch`. Use it when your tests wrap `extract(...)` or
+goal-based `observe(session, goal)`.
 
 ```ts
 import {
@@ -45,7 +51,133 @@ afterEach(() => {
 });
 ```
 
-## Scope
-
 This helper targets the assistive runtime only. It does not mock browser
 sessions, pages, or observed targets.
+
+## Match / Resolve / Fill Fixtures
+
+Five builders let you exercise the primitives without constructing the
+internal match result objects by hand (which would bypass the accessor
+pattern and produce results that fail to fill). Prefer these over raw
+object literals in unit tests.
+
+### `createFixtureMatchStore(entries)`
+
+Builds an `AgentbrowseMatchStore` — an opaque single-field candidate
+source. The store's `entries()` returns candidate metadata without
+values; values are only read back through `store.read(candidateRef)`
+when `match(...)` needs them. Use this when your test wants to assert
+that raw values stay inside the store.
+
+```ts
+import { match } from '@mercuryo-ai/agentbrowse';
+import { createFixtureMatchStore } from '@mercuryo-ai/agentbrowse/testing';
+
+const store = createFixtureMatchStore([
+  {
+    candidateRef: 'profile.email.primary',
+    fieldKey: 'email',
+    type: 'email',
+    value: 'traveler@example.com',
+  },
+]);
+
+const matched = await match(emailTarget, { from: store });
+// matched.kind === 'ready' — and JSON.stringify(matched) does not
+// contain 'traveler@example.com'.
+```
+
+### `createFixtureGroupStore(entries)`
+
+The grouped counterpart — builds an `AgentbrowseGroupMatchStore` for
+whole-form candidates with artifacts. Same opacity guarantee:
+artifacts only come out through `store.readArtifact(candidateRef)`.
+
+```ts
+import { createFixtureGroupStore } from '@mercuryo-ai/agentbrowse/testing';
+
+const store = createFixtureGroupStore([
+  {
+    candidateRef: 'vault_login_1',
+    itemRef: 'vault_login_1',
+    label: 'Airline Login',
+    fieldKeys: ['username', 'password'],
+    confidence: 'high',
+    artifact: {
+      kind: 'values',
+      values: { username: 'traveler@example.com', password: 'secret' },
+    },
+  },
+]);
+
+const matched = await match(fillableForm, { from: store });
+```
+
+### `createFixtureResolver(resourcesByCandidateRef, { enableBatch? })`
+
+Builds an `AgentbrowseMatchResolver` adapter that satisfies the
+interface with recorded call history. Returns
+`{ adapter, resolveCalls, resolveBatchCalls }`. Pass
+`{ enableBatch: true }` to also wire up `resolveBatch`.
+
+```ts
+import { resolve, fill } from '@mercuryo-ai/agentbrowse';
+import {
+  createFixtureResolver,
+  fixtureResolvedValue,
+} from '@mercuryo-ai/agentbrowse/testing';
+
+const resolver = createFixtureResolver({
+  'candidate:password:0': fixtureResolvedValue('top-secret-password'),
+});
+
+const ready = await resolve(pendingMatch, { with: resolver.adapter });
+await fill(session, passwordTarget, ready);
+
+expect(resolver.resolveCalls).toHaveLength(1);
+expect(resolver.resolveCalls[0].candidateRef).toBe('candidate:password:0');
+```
+
+### `fixtureResolvedValue(value)` and `fixtureResolvedArtifact(artifact, options?)`
+
+Typed builders for the resource shapes returned by a resolver. Use them
+to avoid redeclaring `{ kind: 'value', ... }` in every fixture call.
+
+```ts
+fixtureResolvedValue('top-secret-password');
+// => { kind: 'value', value: 'top-secret-password' }
+
+fixtureResolvedArtifact(
+  { kind: 'values', values: { username: '…', password: '…' } },
+  { itemRef: 'vault_login_1', requestId: 'req_123' },
+);
+// => { kind: 'artifact', artifact, itemRef, requestId }
+```
+
+### Typing a grouped-only handler
+
+When a test only exercises the `ready_group` → `fill(...)` path, a
+bare `{ fill }` object typed as `AgentbrowseGroupFillHandler` is
+enough — no need to construct a full `AgentbrowseMatchResolver` with a
+stub `resolve`:
+
+```ts
+import type { AgentbrowseGroupFillHandler } from '@mercuryo-ai/agentbrowse';
+
+const applier: AgentbrowseGroupFillHandler = {
+  fill: vi.fn(async () => ({ success: true, outcomeType: 'filled' })),
+};
+
+await fill(session, fillableForm, readyGroupMatch, { resolver: applier });
+```
+
+## Scope
+
+These fixtures target two concerns only: the assistive runtime used by
+`extract` and goal-based `observe`, and the `match` / `resolve` / `fill`
+primitives. They do not mock browser sessions, pages, observed targets,
+or the underlying `act(...)` path — build those from real `launch(...)`
+sessions against a data: URL when an integration test needs them.
+
+See the [Match / Resolve / Fill Guide](./match-resolve-fill.md) for the
+full mental model of the primitives these fixtures exercise.

package/docs/troubleshooting.md

@@ -2,6 +2,11 @@
 
 Common failures and what to do about each.
 
+For the full per-command `error` code vocabulary (with short "when /
+action" notes), see
+[`api-reference.md` → Error codes by command](./api-reference.md#error-codes-by-command).
+This guide covers diagnosis patterns; the reference covers the codes.
+
 ## `launch(...)` Fails
 
 Most `launch(...)` failures come from the environment, not from AgentBrowse

package/examples/README.md

@@ -15,6 +15,7 @@ Then run the examples from `packages/agentbrowse`:
 npx tsx examples/basic.ts
 npx tsx examples/attach.ts
 npx tsx examples/extract.ts
+npx tsx examples/match-resolve-fill.ts
 ```
 
 Examples:
@@ -27,6 +28,12 @@ Examples:
 - `extract.ts`
   Runs structured extraction with an assistive runtime and a plain schema
   object.
+- `match-resolve-fill.ts`
+  Demonstrates `match`, `resolve`, and `fill` against a self-contained
+  data: URL form: `match(...)` picks candidates, `resolve(...)` walks an
+  unresolved plan through a stub vault resolver, and `fill(...)` applies
+  both values through the browser without placing them in the match
+  result itself.
 
 For protected-fill usage (paying with a card, filling login credentials
 from a user's vault), see [../docs/protected-fill.md](../docs/protected-fill.md).

package/examples/match-resolve-fill.ts

@@ -0,0 +1,107 @@
+import {
+  close,
+  fill,
+  launch,
+  match,
+  observe,
+  resolve,
+  type AgentbrowseMatchResolver,
+} from '@mercuryo-ai/agentbrowse';
+
+// Self-contained data URL with two inputs — keeps the example runnable
+// without depending on any external page.
+const FORM_PAGE = `data:text/html;charset=utf-8,${encodeURIComponent(`
+<!doctype html>
+<html lang="en">
+  <head><meta charset="utf-8"><title>Match / Resolve / Fill demo</title></head>
+  <body>
+    <form>
+      <label>Email <input type="email" name="email" autocomplete="email"></label>
+      <label>Password <input type="password" name="password" autocomplete="current-password"></label>
+    </form>
+  </body>
+</html>
+`)}`;
+
+// Fake resolver that stands in for a vault lookup. In production it would
+// call MagicPay, another secret manager, or an approval backend.
+const vaultResolver: AgentbrowseMatchResolver = {
+  async resolve(plan) {
+    if ('fillRef' in plan) {
+      throw new Error('This example does not support grouped resolution plans.');
+    }
+    if (plan.resolve.kind !== 'example_vault' || plan.resolve.key !== 'demo.password') {
+      throw new Error(`Unknown resolution plan: ${plan.resolve.kind} / ${plan.resolve.key}`);
+    }
+    return { kind: 'value', value: 'top-secret-password' };
+  },
+};
+
+const launchResult = await launch(FORM_PAGE, { headless: false });
+if (!launchResult.success) {
+  throw new Error(launchResult.reason ?? launchResult.message);
+}
+
+const { session } = launchResult;
+
+try {
+  const observed = await observe(session);
+  if (!observed.success) {
+    throw new Error(observed.reason ?? observed.message);
+  }
+
+  const emailTarget = observed.targets.find((target) => target.inputType === 'email');
+  const passwordTarget = observed.targets.find((target) => target.inputType === 'password');
+
+  if (!emailTarget || !passwordTarget) {
+    throw new Error('Expected email and password targets on the demo page.');
+  }
+
+  // ---- Simple path: match → fill ----------------------------------------
+  const emailMatch = await match(emailTarget, {
+    from: { email: 'traveler@example.com' },
+  });
+
+  if (emailMatch.kind !== 'ready') {
+    throw new Error(`Unexpected email match kind: ${emailMatch.kind}`);
+  }
+
+  // JSON.stringify proves the value is not in the match result itself.
+  console.info('email match kind:', emailMatch.kind);
+  console.info('email match serialised:', JSON.stringify(emailMatch));
+
+  const emailFill = await fill(session, emailTarget, emailMatch);
+  console.info('email fill success:', emailFill.success);
+
+  // ---- Explicit resolver path: match → resolve → fill -------------------
+  const passwordMatch = await match(passwordTarget, {
+    from: [
+      {
+        fieldKey: 'password',
+        type: 'secret',
+        resolve: { kind: 'example_vault', key: 'demo.password' },
+      },
+    ],
+  });
+
+  if (passwordMatch.kind !== 'needs_resolution') {
+    throw new Error(`Unexpected password match kind: ${passwordMatch.kind}`);
+  }
+
+  // The match result carries the plan, not the value. It is safe to log
+  // or to ship across a process boundary.
+  console.info('password plan:', passwordMatch.plan);
+
+  const passwordReady = await resolve(passwordMatch, { with: vaultResolver });
+  const passwordFill = await fill(session, passwordTarget, passwordReady);
+  console.info('password fill success:', passwordFill.success);
+
+  // ---- Equivalent one-call path -----------------------------------------
+  // `fill(...)` can do the resolve step inline when a resolver is passed:
+  //
+  //   await fill(session, passwordTarget, passwordMatch, { resolver: vaultResolver });
+  //
+  // Use it when you do not need to inspect the ready match between steps.
+} finally {
+  await close(session);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercuryo-ai/agentbrowse",
-  "version": "0.2.61",
+  "version": "0.2.63",
   "type": "module",
   "description": "Browser automation primitives library for AI agents",
   "license": "MIT",
@@ -11,7 +11,8 @@
     "ai-agent",
     "browser-sdk",
     "playwright",
-    "cdp"
+    "cdp",
+    "form-filling"
   ],
   "repository": {
     "type": "git",
@@ -81,6 +82,7 @@
     "test:e2e:autonomous": "npm run test:autonomous:scenarios",
     "test:e2e:autonomous:bare": "npm run test:autonomous:scenarios:bare",
     "check-types": "tsc --noEmit",
+    "check-types:examples": "npm run build && tsc -p tsconfig.examples.json",
     "lint": "biome check src docs README.md",
     "pack:verify": "node scripts/verify-pack-artifact.mjs",
     "smoke:pack-install": "node scripts/verify-pack-install-smoke.mjs"