web-tester-for-claude 0.4.0

package/bin/web-tester.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+// web-tester launcher. Delegates to the TypeScript CLI via tsx so we can ship
+// source rather than pre-built JS — the runtime cost is one tsx startup
+// (~150ms on warm cache) and it keeps the published package tiny.
+//
+// We resolve tsx from this package's own node_modules so the launcher never
+// fights with the consumer project's installed version. The CLI entry is
+// `../src/cli.ts` relative to this file regardless of where npm placed us
+// (top-level node_modules, pnpm's nested layout, npx cache, etc).
+
+const { spawnSync } = require("node:child_process");
+const { resolve } = require("node:path");
+
+const PACKAGE_ROOT = resolve(__dirname, "..");
+const CLI_ENTRY = resolve(PACKAGE_ROOT, "src/cli.ts");
+
+let tsxBin;
+try {
+  tsxBin = require.resolve("tsx/cli", { paths: [PACKAGE_ROOT] });
+} catch (err) {
+  console.error(
+    "web-tester: could not locate tsx (web-tester's TypeScript runner).\n" +
+      "  Reinstall web-tester-for-claude (this should have come with it as a dep).\n" +
+      `  Underlying error: ${err && err.message ? err.message : err}`
+  );
+  process.exit(1);
+}
+
+const result = spawnSync(
+  process.execPath,
+  [tsxBin, CLI_ENTRY, ...process.argv.slice(2)],
+  { stdio: "inherit" }
+);
+
+process.exit(result.status ?? 1);

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "web-tester-for-claude",
+  "version": "0.4.0",
+  "description": "Drive your dev site in Playwright, map it, capture console + network + DOM + screenshots + video, write one structured report. Built for AI coding agents and humans.",
+  "keywords": [
+    "playwright",
+    "ai",
+    "claude",
+    "claude-code",
+    "agent",
+    "agent-skill",
+    "browser-automation",
+    "testing",
+    "qa",
+    "e2e",
+    "crawler",
+    "sitemap",
+    "regression",
+    "report"
+  ],
+  "license": "MIT",
+  "author": "Haroon Khan <hkhan6916@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hkhan6916/web-tester-for-claude.git"
+  },
+  "homepage": "https://github.com/hkhan6916/web-tester-for-claude#readme",
+  "bugs": "https://github.com/hkhan6916/web-tester-for-claude/issues",
+  "type": "commonjs",
+  "bin": {
+    "web-tester": "./bin/web-tester.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "tsconfig.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "web-tester": "tsx src/cli.ts",
+    "init": "tsx src/cli.ts init",
+    "map": "tsx src/cli.ts map",
+    "inspect": "tsx src/cli.ts inspect",
+    "kb": "tsx src/cli.ts kb",
+    "tsc": "tsc --noEmit",
+    "prepublishOnly": "tsc --noEmit"
+  },
+  "dependencies": {
+    "dotenv": "^16.4.7",
+    "playwright": "^1.59.1",
+    "tsx": "^4.21.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.41",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/browser/attrs.ts

@@ -0,0 +1,79 @@
+import type { Page } from "playwright";
+
+export type UiAttribute = {
+  name: string;
+  alias: string;
+  type: string | null;
+  hidden: boolean;
+  value: string;
+  label: string;
+};
+
+/**
+ * Best-effort "is the page done rendering?" gate, driven by `data-attr-*`
+ * markers on the page.
+ *
+ * Convention:
+ *   <element data-attr-name="…" data-attr-selected-label="…" />
+ *
+ * If your app paints any element with a `data-attr-name` attribute, this
+ * step will wait until at least one of them carries a non-empty
+ * `data-attr-selected-label` — typically the last attribute to populate
+ * when async state has finished arriving. That's a reliable "everything
+ * settled" signal that doesn't depend on network idle.
+ *
+ * Fast-path: if no `data-attr-name` exists on the page within `probeMs`,
+ * we return immediately rather than waiting out the full timeout. So
+ * `settle` is cheap on pages that don't use the convention at all — it
+ * adds ~3 s and moves on.
+ *
+ * Apps that don't use `data-attr-*` markers should prefer
+ * `--step wait:networkidle` over `--step settle`.
+ */
+const SETTLE_PROBE_MS = 3_000;
+
+export async function waitForAttrsReady(
+  page: Page,
+  timeoutMs: number
+): Promise<{ probed: boolean; settled: boolean }> {
+  try {
+    await page
+      .locator("[data-attr-name]")
+      .first()
+      .waitFor({ state: "attached", timeout: SETTLE_PROBE_MS });
+  } catch {
+    return { probed: false, settled: false };
+  }
+  const settled = await page
+    .waitForFunction(
+      () => {
+        const candidates = document.querySelectorAll("[data-attr-name]");
+        for (const el of Array.from(candidates)) {
+          const label = el.getAttribute("data-attr-selected-label") ?? "";
+          if (label.trim().length > 0) return true;
+        }
+        return false;
+      },
+      undefined,
+      { timeout: timeoutMs, polling: 100 }
+    )
+    .then(() => true)
+    .catch(() => false);
+  return { probed: true, settled };
+}
+
+export async function readUiAttributes(page: Page): Promise<UiAttribute[]> {
+  return page
+    .evaluate(() => {
+      const elements = document.querySelectorAll<HTMLElement>("[data-attr-name]");
+      return Array.from(elements).map((el) => ({
+        name: el.getAttribute("data-attr-name") ?? "",
+        alias: el.getAttribute("data-attr-alias") ?? "",
+        type: el.getAttribute("data-attr-type"),
+        hidden: el.getAttribute("data-attr-hidden") === "true",
+        value: el.getAttribute("data-attr-selected-value") ?? "",
+        label: el.getAttribute("data-attr-selected-label") ?? ""
+      }));
+    })
+    .catch(() => [] as UiAttribute[]);
+}

package/src/browser/session.ts

@@ -0,0 +1,139 @@
+import { existsSync } from "node:fs";
+import {
+  type Browser,
+  type BrowserContext,
+  chromium,
+  type Page
+} from "playwright";
+import { ensureWebTesterHome, SESSION_STATE_PATH } from "../util/paths";
+
+const DEFAULT_VIEWPORT = { width: 1280, height: 900 };
+const DEFAULT_UA = "Mozilla/5.0 (compatible; web-tester)";
+
+export type SessionOptions = {
+  baseUrl: string;
+  headed?: boolean;
+  viewport?: { width: number; height: number };
+  userAgent?: string;
+  /** Directory to record a video into. If omitted, no recording. */
+  videoDir?: string;
+  /**
+   * When true (the default), `~/.web-tester/session.json` is loaded into
+   * the browser context if it exists, so runs against authenticated pages
+   * can skip the login flow. Pass `false` to force an anonymous context
+   * (e.g. to test the logged-out experience).
+   */
+  loadStorageState?: boolean;
+};
+
+export type Session = {
+  browser: Browser;
+  context: BrowserContext;
+  page: Page;
+  baseUrl: string;
+  /** True if `SESSION_STATE_PATH` existed and was loaded into this context. */
+  storageStateLoaded: boolean;
+  /**
+   * Persist the current browser context (cookies + localStorage) to
+   * `~/.web-tester/session.json` so subsequent runs can skip the login
+   * dance. Safe to call multiple times — overwrites in place.
+   */
+  saveStorageState: () => Promise<void>;
+  /** Resolves to the saved video file path after the context is closed. */
+  videoPath: () => Promise<string | null>;
+  close: () => Promise<void>;
+};
+
+/**
+ * Hides Next.js dev-mode overlays (portal, toasts, error dialogs) so they
+ * don't intercept clicks or appear in screenshots. They use Shadow DOM and
+ * survive page CSS `display:none`, so a MutationObserver also removes them.
+ * Consent banners and other app-specific widgets are deliberately left alone.
+ */
+const NEXTJS_OVERLAY_HIDE_CSS = `
+  nextjs-portal,
+  [data-nextjs-toast],
+  [data-nextjs-dialog-overlay],
+  [data-nextjs-dialog] {
+    display: none !important;
+    visibility: hidden !important;
+    pointer-events: none !important;
+    opacity: 0 !important;
+  }
+  html, body { overflow: auto !important; }
+`;
+
+export const DEFAULT_SESSION_VIEWPORT = DEFAULT_VIEWPORT;
+export const DEFAULT_SESSION_UA = DEFAULT_UA;
+
+export async function configureContext(
+  context: BrowserContext,
+  _baseUrl: string
+): Promise<void> {
+  // Injected as a content string, not a function: tsx's esbuild compile
+  // would otherwise wrap functions with `__name(...)` helpers that don't
+  // exist in the browser and surface as a page error on every run.
+  const initScript = `
+(function (css) {
+  function inject() {
+    var style = document.createElement('style');
+    style.setAttribute('data-web-tester', 'overlay-suppression');
+    style.textContent = css;
+    (document.head || document.documentElement).appendChild(style);
+  }
+  if (document.head) inject();
+  else document.addEventListener('DOMContentLoaded', inject, { once: true });
+
+  function killPortals() {
+    var portals = document.querySelectorAll('nextjs-portal, [data-nextjs-toast], [data-nextjs-dialog-overlay]');
+    portals.forEach(function (p) { p.remove(); });
+  }
+  killPortals();
+  var observer = new MutationObserver(killPortals);
+  function start() {
+    if (document.body) observer.observe(document.body, { childList: true, subtree: true });
+  }
+  if (document.body) start();
+  else document.addEventListener('DOMContentLoaded', start, { once: true });
+})(${JSON.stringify(NEXTJS_OVERLAY_HIDE_CSS)});
+`;
+  await context.addInitScript({ content: initScript });
+}
+
+export async function openSession(opts: SessionOptions): Promise<Session> {
+  const baseUrl = opts.baseUrl.replace(/\/$/, "");
+  const viewport = opts.viewport ?? DEFAULT_VIEWPORT;
+  const browser = await chromium.launch({ headless: !opts.headed });
+  const shouldLoadState = opts.loadStorageState !== false;
+  const storageStateLoaded = shouldLoadState && existsSync(SESSION_STATE_PATH);
+  const context = await browser.newContext({
+    viewport,
+    userAgent: opts.userAgent ?? DEFAULT_UA,
+    recordVideo: opts.videoDir ? { dir: opts.videoDir, size: viewport } : undefined,
+    ...(storageStateLoaded ? { storageState: SESSION_STATE_PATH } : {})
+  });
+  await configureContext(context, baseUrl);
+  const page = await context.newPage();
+  return {
+    browser,
+    context,
+    page,
+    baseUrl,
+    storageStateLoaded,
+    saveStorageState: async () => {
+      ensureWebTesterHome();
+      await context.storageState({ path: SESSION_STATE_PATH });
+    },
+    videoPath: async () => {
+      const video = page.video();
+      if (!video) return null;
+      // Playwright finalises the video file on context close, so callers must
+      // call this *after* close(). Resolves to the absolute path on disk.
+      return video.path().catch(() => null);
+    },
+    close: async () => {
+      await context.close().catch(() => {});
+      await browser.close().catch(() => {});
+    }
+  };
+}