@humanjs/playwright 0.9.0 → 0.10.0

package/README.md

@@ -380,6 +380,26 @@ Generated tests are built to *be tests*: they run `speed: process.env.CI ? 'inst
 
 Two more options: `{ steps: true }` groups the actions into `test.step(...)` blocks (a new step per navigation) for collapsible sections in the HTML report and trace; `{ baseUrl: true }` rewrites same-origin `goto`s to relative paths and adds a note to set `use.baseURL` in your `playwright.config.ts` — so the same test runs against local / staging / prod.
 
+### Replaying a timeline
+
+`replayTimeline(page, timeline, options?)` runs a recorded `Timeline` against a live page, driving it through the same humanized primitives the exported test uses — without spawning a test runner. It runs each event in order, reports per-step status via `onStep`, and **stops at the first failure** (like a real test).
+
+```ts
+import { chromium, replayTimeline } from '@humanjs/playwright';
+
+const page = await (await chromium.launch({ headless: false })).newPage();
+const result = await replayTimeline(page, recording.timeline, {
+  personality: 'careful',
+  onStep: ({ index, type, status }) => console.log(`${index} ${type}: ${status}`),
+});
+
+result.status; // 'pass' | 'fail'
+result.failedIndex; // index of the failing step, when failed
+result.steps; // per-step { index, type, status, error? }
+```
+
+`assert` events are evaluated with plain Playwright APIs — there's no `@playwright/test` dependency — so they approximate `expect` (`toBeVisible` via `waitFor`, `toHaveText` via normalized text equality, `toHaveURL` via `page.url()`) without its auto-retry on text/url. Pass an `AbortSignal` via `{ signal }` to cancel a run; it rejects with an `AbortError`. The cursor is on and `speed` is `'human'` by default so the replay is watchable. You own `page`'s lifecycle — `replayTimeline` doesn't close it. This is the engine behind the `@humanjs/generator` dashboard's **Run** button.
+
 By default the actual typed/pasted text is captured into the timeline (and the exported code). Values typed into `input[type="password"]` are always masked; set `captureInputs: false` to record none — exports then emit empty-string placeholders:
 
 ```ts

package/dist/{chunk-3X36PFTS.cjs → chunk-665R4N7R.cjs}

@@ -945,8 +945,17 @@ async function detectKindFromTag(locator) {
   return void 0;
 }
 
-// src/recording/codegen.ts
+// src/recording/targets.ts
 var POINT_RE = /^point\((-?\d+(?:\.\d+)?),\s*(-?\d+(?:\.\d+)?)\)$/;
+function parsePointTarget(desc) {
+  const match = String(desc ?? "").match(POINT_RE);
+  return match ? { x: Number(match[1]), y: Number(match[2]) } : null;
+}
+function resolveMouseTarget(desc) {
+  return parsePointTarget(desc) ?? String(desc ?? "");
+}
+
+// src/recording/codegen.ts
 var POINT_COMMENT = " // raw coordinate \u2014 replace with a locator for a stable selector";
 var UNCAPTURED_COMMENT = " // input not captured (masked or captureInputs disabled) \u2014 fill in (e.g. process.env.X)";
 function q(value) {
@@ -1182,6 +1191,150 @@ ${todo}
 });
 `;
 }
+function abortError() {
+  const error = new Error("Replay aborted");
+  error.name = "AbortError";
+  return error;
+}
+async function replayTimeline(page, timeline, options = {}) {
+  const events = Array.isArray(timeline) ? timeline : timeline.events;
+  const { onStep, signal } = options;
+  if (signal?.aborted) throw abortError();
+  const human = await createHuman(page, {
+    personality: options.personality ?? "careful",
+    speed: options.speed ?? "human",
+    ...options.seed !== void 0 ? { seed: options.seed } : {},
+    ...options.cursor !== void 0 ? { cursor: options.cursor } : {}
+  });
+  const startedAt = Date.now();
+  const steps = [];
+  for (const [index, event] of events.entries()) {
+    if (signal?.aborted) throw abortError();
+    onStep?.({ index, type: event.type, status: "running" });
+    try {
+      await runEvent(human, page, event);
+    } catch (cause) {
+      const error = cause instanceof Error ? cause.message : String(cause);
+      steps.push({ index, type: event.type, status: "fail", error });
+      onStep?.({ index, type: event.type, status: "fail", error });
+      return { status: "fail", steps, failedIndex: index, durationMs: Date.now() - startedAt };
+    }
+    steps.push({ index, type: event.type, status: "pass" });
+    onStep?.({ index, type: event.type, status: "pass" });
+  }
+  return { status: "pass", steps, durationMs: Date.now() - startedAt };
+}
+function parseScrollTarget(target) {
+  const value = String(target ?? "natural");
+  const by = value.match(/^by:(-?\d+(?:\.\d+)?)$/);
+  if (by) return { by: Number(by[1]) };
+  const to = value.match(/^to:(-?\d+(?:\.\d+)?)$/);
+  if (to) return { to: Number(to[1]) };
+  return value;
+}
+var normalizeText = (value) => (value ?? "").replace(/\s+/g, " ").trim();
+async function runAssert(page, params) {
+  const kind = String(params.kind ?? "visible");
+  if (kind === "url") {
+    const actual = page.url();
+    const expected = String(params.value ?? "");
+    if (actual !== expected) {
+      throw new Error(`expected URL ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`);
+    }
+    return;
+  }
+  const locator = page.locator(String(params.target ?? "")).first();
+  await locator.waitFor({ state: "visible" });
+  if (kind === "text") {
+    const actual = normalizeText(await locator.textContent());
+    const expected = normalizeText(String(params.value ?? ""));
+    if (actual !== expected) {
+      throw new Error(`expected text ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`);
+    }
+  }
+}
+async function runEvent(human, page, event) {
+  const p = event.params;
+  switch (event.type) {
+    case "goto":
+      await human.goto(String(p.url ?? ""));
+      return;
+    case "click":
+      await human.click(resolveMouseTarget(p.target));
+      return;
+    case "rightClick":
+      await human.rightClick(resolveMouseTarget(p.target));
+      return;
+    case "doubleClick":
+      await human.doubleClick(resolveMouseTarget(p.target));
+      return;
+    case "move":
+      await human.move(resolveMouseTarget(p.target));
+      return;
+    case "hover":
+      await human.hover(String(p.target ?? ""));
+      return;
+    case "drag":
+      await human.drag(resolveMouseTarget(p.from), resolveMouseTarget(p.to));
+      return;
+    case "type":
+      await human.type(String(p.target ?? ""), event.inputValue ?? "");
+      return;
+    case "paste":
+      await human.paste(String(p.target ?? ""), event.inputValue ?? "");
+      return;
+    case "clear":
+      await human.clear(String(p.target ?? ""));
+      return;
+    case "check":
+      await human.check(String(p.target ?? ""));
+      return;
+    case "uncheck":
+      await human.uncheck(String(p.target ?? ""));
+      return;
+    case "selectText":
+      await human.selectText(
+        String(p.target ?? ""),
+        typeof p.text === "string" ? { text: p.text } : void 0
+      );
+      return;
+    case "selectOption":
+      await human.selectOption(String(p.target ?? ""), p.values);
+      return;
+    case "upload":
+      await human.upload(String(p.target ?? ""), p.files);
+      return;
+    case "press":
+      await human.press(String(p.key ?? ""));
+      return;
+    case "scroll":
+      await human.scroll(parseScrollTarget(p.target));
+      return;
+    case "read": {
+      const target = String(p.target ?? "");
+      if (/^\d+ words$/.test(target) || /^text:\d+ chars$/.test(target)) return;
+      await human.read(target);
+      return;
+    }
+    case "sleep":
+      await core.sleep(Number(p.ms) || 0);
+      return;
+    case "reload":
+      await human.reload();
+      return;
+    case "goBack":
+      await human.goBack();
+      return;
+    case "goForward":
+      await human.goForward();
+      return;
+    case "assert":
+      await runAssert(page, p);
+      return;
+    default:
+      return;
+  }
+}
 
 // src/recording/index.ts
 var pendingFrameCleanups = /* @__PURE__ */ new Set();
@@ -2078,5 +2231,6 @@ exports.createHuman = createHuman;
 exports.generateHumanJS = generateHumanJS;
 exports.generatePlaywrightTest = generatePlaywrightTest;
 exports.installMouseHelper = installMouseHelper;
-//# sourceMappingURL=chunk-3X36PFTS.cjs.map
-//# sourceMappingURL=chunk-3X36PFTS.cjs.map
+exports.replayTimeline = replayTimeline;
+//# sourceMappingURL=chunk-665R4N7R.cjs.map
+//# sourceMappingURL=chunk-665R4N7R.cjs.map