@humanjs/playwright 0.8.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-RCMSDC3N.cjs → chunk-665R4N7R.cjs}

@@ -580,6 +580,51 @@ async function executeUpload(target, files, ctx) {
   }
   await locator.setInputFiles(files);
 }
+
+// src/internal/select-substring.ts
+function selectSubstringInElement(el, needleRaw) {
+  const needle = needleRaw.replace(/\s+/g, " ").trim();
+  if (!needle) return false;
+  const map = [];
+  let normalized = "";
+  let prevSpace = true;
+  const walker = document.createTreeWalker(el, NodeFilter.SHOW_TEXT);
+  for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+    const text = node;
+    const data = text.data;
+    for (let i = 0; i < data.length; i++) {
+      const ch = data.charAt(i);
+      if (/\s/.test(ch)) {
+        if (!prevSpace) {
+          normalized += " ";
+          map.push([text, i]);
+        }
+        prevSpace = true;
+      } else {
+        normalized += ch;
+        map.push([text, i]);
+        prevSpace = false;
+      }
+    }
+  }
+  if (normalized.endsWith(" ")) {
+    normalized = normalized.slice(0, -1);
+    map.pop();
+  }
+  const start = normalized.indexOf(needle);
+  if (start === -1) return false;
+  const startPos = map[start];
+  const endPos = map[start + needle.length - 1];
+  if (!startPos || !endPos) return false;
+  const range = document.createRange();
+  range.setStart(startPos[0], startPos[1]);
+  range.setEnd(endPos[0], endPos[1] + 1);
+  const selection = window.getSelection();
+  if (!selection) return false;
+  selection.removeAllRanges();
+  selection.addRange(range);
+  return true;
+}
 async function executeType(target, value, ctx) {
   const locator = typeof target === "string" ? ctx.page.locator(target) : target;
   if (value.length === 0) {
@@ -696,6 +741,118 @@ function normalizeKey(key) {
 function isMac() {
   return process.platform === "darwin";
 }
+
+// src/mouse-helper/index.ts
+var CURSOR_PATH = "M 0 0 L 16 6 L 8 9.5 L 5 19 Z";
+var INSTALLED_FLAG = /* @__PURE__ */ Symbol.for("@humanjs/playwright:mouse-helper:installed");
+async function installMouseHelper(target, options = {}) {
+  const tagged = target;
+  if (tagged[INSTALLED_FLAG]) return;
+  tagged[INSTALLED_FLAG] = true;
+  const config = {
+    color: options.color ?? "#f5a55c",
+    stroke: "#020203",
+    size: options.size ?? 22,
+    showClicks: options.showClicks ?? true,
+    haloOpacity: options.haloOpacity ?? 0.18,
+    path: CURSOR_PATH
+  };
+  await target.addInitScript(installScript, config);
+  const attachPageHooks = (page) => {
+    page.on("domcontentloaded", () => {
+      page.evaluate(installScript, config).catch(() => void 0);
+    });
+  };
+  const pages = "pages" in target ? target.pages() : [target];
+  for (const page of pages) attachPageHooks(page);
+  if ("on" in target && "newPage" in target) {
+    target.on("page", attachPageHooks);
+  }
+  await Promise.all(
+    pages.map((page) => page.evaluate(installScript, config).catch(() => void 0))
+  );
+}
+function installScript(config) {
+  if (document.querySelector("[data-humanjs-cursor]")) return;
+  const attach = () => {
+    const cursor = document.createElement("div");
+    cursor.setAttribute("aria-hidden", "true");
+    cursor.setAttribute("data-humanjs-cursor", "true");
+    cursor.style.cssText = [
+      "position: fixed",
+      "left: 0",
+      "top: 0",
+      `width: ${config.size}px`,
+      `height: ${config.size + 4}px`,
+      "pointer-events: none",
+      "z-index: 2147483647",
+      // Start visible at (0, 0) so the cursor is on screen from the moment
+      // the page loads — without this the helper looks like nothing happened
+      // until the first mousemove arrives.
+      "opacity: 1",
+      "transform: translate(0px, 0px)",
+      // CSS interpolates between successive `mousemove` updates so the
+      // cursor reads as continuous motion instead of discrete hops. Slightly
+      // longer than the path-walker's typical step interval (~30–80ms) so
+      // each tween is still settling when the next move lands → no pauses.
+      "transition: transform 110ms ease-out, opacity 0.18s ease-out",
+      "will-change: transform"
+    ].join("; ");
+    const haloRadius = Math.round(config.size * 0.6);
+    cursor.innerHTML = `
+      <svg width="${config.size}" height="${config.size + 4}" viewBox="0 0 22 24" style="overflow: visible;">
+        <circle cx="0" cy="0" r="${haloRadius}" fill="${config.color}" opacity="${config.haloOpacity}" />
+        <path d="${config.path}" fill="${config.color}" stroke="${config.stroke}" stroke-width="0.7" stroke-linejoin="round" />
+      </svg>
+    `;
+    document.body.appendChild(cursor);
+    let lastX = 0;
+    let lastY = 0;
+    const onMove = (e) => {
+      lastX = e.clientX;
+      lastY = e.clientY;
+      cursor.style.transform = `translate(${lastX}px, ${lastY}px)`;
+      cursor.style.opacity = "1";
+    };
+    window.addEventListener("mousemove", onMove, { capture: true, passive: true });
+    document.addEventListener("mousemove", onMove, { capture: true, passive: true });
+    document.addEventListener(
+      "mouseleave",
+      () => {
+        cursor.style.opacity = "0";
+      },
+      { capture: true, passive: true }
+    );
+    if (config.showClicks) {
+      const styleEl = document.createElement("style");
+      styleEl.textContent = "@keyframes humanjs-ripple { 0% { transform: translate(-50%, -50%) scale(0.4); opacity: 0.9; } 100% { transform: translate(-50%, -50%) scale(2); opacity: 0; } }";
+      document.head.appendChild(styleEl);
+      window.addEventListener(
+        "mousedown",
+        () => {
+          const ripple = document.createElement("div");
+          ripple.style.cssText = [
+            "position: fixed",
+            `left: ${lastX}px`,
+            `top: ${lastY}px`,
+            "width: 28px",
+            "height: 28px",
+            "border-radius: 50%",
+            `border: 1.5px solid ${config.color}`,
+            "pointer-events: none",
+            "z-index: 2147483646",
+            "animation: humanjs-ripple 0.45s ease-out forwards"
+          ].join("; ");
+          document.body.appendChild(ripple);
+          window.setTimeout(() => ripple.remove(), 500);
+        },
+        { capture: true, passive: true }
+      );
+    }
+  };
+  if (document.body) attach();
+  else document.addEventListener("DOMContentLoaded", attach, { once: true });
+}
 async function executeRead(target, ctx, options = {}) {
   let words = 0;
   let locator;
@@ -788,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) {
@@ -855,6 +1021,13 @@ function emitAction(e, opts = {}) {
       const { code } = targetArg(p.target);
       return `  await human.${e.type}(${code});`;
     }
+    case "selectText": {
+      const { code } = targetArg(p.target);
+      if (typeof p.text === "string" && p.text.length > 0) {
+        return `  await human.selectText(${code}, { text: ${q(p.text)} });`;
+      }
+      return `  await human.selectText(${code});`;
+    }
     case "selectOption": {
       const { code } = targetArg(p.target);
       return `  await human.selectOption(${code}, ${serializeSelectValues(p.values)});`;
@@ -904,6 +1077,14 @@ function emitAction(e, opts = {}) {
       return "  await human.goBack();";
     case "goForward":
       return "  await human.goForward();";
+    case "assert": {
+      const kind = String(p.kind ?? "visible");
+      if (kind === "url") return `  await expect(page).toHaveURL(${q(p.value)});`;
+      const { code } = targetArg(p.target);
+      if (kind === "text")
+        return `  await expect(page.locator(${code})).toHaveText(${q(p.value)});`;
+      return `  await expect(page.locator(${code})).toBeVisible();`;
+    }
     default:
       return `  // unsupported action: ${e.type}`;
   }
@@ -913,7 +1094,7 @@ function needsSleepImport(timeline) {
 }
 function generateHumanJS(timeline) {
   const imports = needsSleepImport(timeline) ? "import { chromium, createHuman, sleep } from '@humanjs/playwright';" : "import { chromium, createHuman } from '@humanjs/playwright';";
-  const body = timeline.events.map((e) => emitAction(e)).join("\n");
+  const body = timeline.events.filter((e) => e.type !== "assert").map((e) => emitAction(e)).join("\n");
   return `${imports}
 
 async function main() {
@@ -1010,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();
@@ -1435,120 +1760,6 @@ async function startCapture(page, options = {}) {
     }
   };
 }
-
-// src/mouse-helper/index.ts
-var CURSOR_PATH = "M 0 0 L 16 6 L 8 9.5 L 5 19 Z";
-var INSTALLED_FLAG = /* @__PURE__ */ Symbol.for("@humanjs/playwright:mouse-helper:installed");
-async function installMouseHelper(target, options = {}) {
-  const tagged = target;
-  if (tagged[INSTALLED_FLAG]) return;
-  tagged[INSTALLED_FLAG] = true;
-  const config = {
-    color: options.color ?? "#f5a55c",
-    stroke: "#020203",
-    size: options.size ?? 22,
-    showClicks: options.showClicks ?? true,
-    haloOpacity: options.haloOpacity ?? 0.18,
-    path: CURSOR_PATH
-  };
-  await target.addInitScript(installScript, config);
-  const attachPageHooks = (page) => {
-    page.on("domcontentloaded", () => {
-      page.evaluate(installScript, config).catch(() => void 0);
-    });
-  };
-  const pages = "pages" in target ? target.pages() : [target];
-  for (const page of pages) attachPageHooks(page);
-  if ("on" in target && "newPage" in target) {
-    target.on("page", attachPageHooks);
-  }
-  await Promise.all(
-    pages.map((page) => page.evaluate(installScript, config).catch(() => void 0))
-  );
-}
-function installScript(config) {
-  if (document.querySelector("[data-humanjs-cursor]")) return;
-  const attach = () => {
-    const cursor = document.createElement("div");
-    cursor.setAttribute("aria-hidden", "true");
-    cursor.setAttribute("data-humanjs-cursor", "true");
-    cursor.style.cssText = [
-      "position: fixed",
-      "left: 0",
-      "top: 0",
-      `width: ${config.size}px`,
-      `height: ${config.size + 4}px`,
-      "pointer-events: none",
-      "z-index: 2147483647",
-      // Start visible at (0, 0) so the cursor is on screen from the moment
-      // the page loads — without this the helper looks like nothing happened
-      // until the first mousemove arrives.
-      "opacity: 1",
-      "transform: translate(0px, 0px)",
-      // CSS interpolates between successive `mousemove` updates so the
-      // cursor reads as continuous motion instead of discrete hops. Slightly
-      // longer than the path-walker's typical step interval (~30–80ms) so
-      // each tween is still settling when the next move lands → no pauses.
-      "transition: transform 110ms ease-out, opacity 0.18s ease-out",
-      "will-change: transform"
-    ].join("; ");
-    const haloRadius = Math.round(config.size * 0.6);
-    cursor.innerHTML = `
-      <svg width="${config.size}" height="${config.size + 4}" viewBox="0 0 22 24" style="overflow: visible;">
-        <circle cx="0" cy="0" r="${haloRadius}" fill="${config.color}" opacity="${config.haloOpacity}" />
-        <path d="${config.path}" fill="${config.color}" stroke="${config.stroke}" stroke-width="0.7" stroke-linejoin="round" />
-      </svg>
-    `;
-    document.body.appendChild(cursor);
-    let lastX = 0;
-    let lastY = 0;
-    const onMove = (e) => {
-      lastX = e.clientX;
-      lastY = e.clientY;
-      cursor.style.transform = `translate(${lastX}px, ${lastY}px)`;
-      cursor.style.opacity = "1";
-    };
-    window.addEventListener("mousemove", onMove, { capture: true, passive: true });
-    document.addEventListener("mousemove", onMove, { capture: true, passive: true });
-    document.addEventListener(
-      "mouseleave",
-      () => {
-        cursor.style.opacity = "0";
-      },
-      { capture: true, passive: true }
-    );
-    if (config.showClicks) {
-      const styleEl = document.createElement("style");
-      styleEl.textContent = "@keyframes humanjs-ripple { 0% { transform: translate(-50%, -50%) scale(0.4); opacity: 0.9; } 100% { transform: translate(-50%, -50%) scale(2); opacity: 0; } }";
-      document.head.appendChild(styleEl);
-      window.addEventListener(
-        "mousedown",
-        () => {
-          const ripple = document.createElement("div");
-          ripple.style.cssText = [
-            "position: fixed",
-            `left: ${lastX}px`,
-            `top: ${lastY}px`,
-            "width: 28px",
-            "height: 28px",
-            "border-radius: 50%",
-            `border: 1.5px solid ${config.color}`,
-            "pointer-events: none",
-            "z-index: 2147483646",
-            "animation: humanjs-ripple 0.45s ease-out forwards"
-          ].join("; ");
-          document.body.appendChild(ripple);
-          window.setTimeout(() => ripple.remove(), 500);
-        },
-        { capture: true, passive: true }
-      );
-    }
-  };
-  if (document.body) attach();
-  else document.addEventListener("DOMContentLoaded", attach, { once: true });
-}
-
-// src/index.ts
 async function createHuman(page, options = {}) {
   const personality = core.resolvePersonality(options.personality ?? "careful");
   const rng = core.createRng(options.seed);
@@ -1558,6 +1769,9 @@ async function createHuman(page, options = {}) {
   for (const plugin of plugins) {
     await plugin.install?.(context);
   }
+  if (options.cursor !== false && typeof page.addInitScript === "function") {
+    await installMouseHelper(page, typeof options.cursor === "object" ? options.cursor : {});
+  }
   let hasRecorded = false;
   let activeRecordingEvents = null;
   let activeRecordingStartMs = 0;
@@ -1740,6 +1954,27 @@ async function createHuman(page, options = {}) {
         () => executeSelectOption(target, values, mouseCtx())
       );
     },
+    async selectText(target, options2) {
+      const text = options2?.text;
+      await performAction(
+        {
+          type: "selectText",
+          params: { target: describeMouseTarget(target), ...text !== void 0 ? { text } : {} }
+        },
+        async () => {
+          if (speed !== "instant") {
+            await executeMove(target, mouseCtx());
+          }
+          const locator = typeof target === "string" ? page.locator(target) : target;
+          if (text === void 0) {
+            await locator.selectText();
+            return;
+          }
+          const found = await locator.evaluate(selectSubstringInElement, text);
+          if (!found) await locator.selectText();
+        }
+      );
+    },
     async upload(target, files) {
       await performAction(
         {
@@ -1993,6 +2228,9 @@ Object.defineProperty(exports, "webkit", {
 });
 exports.Recording = Recording;
 exports.createHuman = createHuman;
+exports.generateHumanJS = generateHumanJS;
+exports.generatePlaywrightTest = generatePlaywrightTest;
 exports.installMouseHelper = installMouseHelper;
-//# sourceMappingURL=chunk-RCMSDC3N.cjs.map
-//# sourceMappingURL=chunk-RCMSDC3N.cjs.map
+exports.replayTimeline = replayTimeline;
+//# sourceMappingURL=chunk-665R4N7R.cjs.map
+//# sourceMappingURL=chunk-665R4N7R.cjs.map