middlewright 0.1.0

package/dist/plugins/video-mode.js

@@ -0,0 +1,124 @@
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+/** Highlight element, pause, return disposable that unhighlights */
+const setupHighlight = async (locator, style, pauseMs) => {
+    try {
+        await locator.evaluate((el, s) => {
+            const prev = el.getAttribute("style") || "";
+            el.setAttribute("data-video-prev-style", prev);
+            el.setAttribute("style", `${prev}; outline: ${s} !important; outline-offset: 2px !important;`);
+        }, style);
+    }
+    catch {
+        // Element may not be ready yet, ignore
+    }
+    await new Promise((resolve) => setTimeout(resolve, pauseMs));
+    return {
+        [Symbol.dispose]: () => {
+            // Fire-and-forget cleanup - don't wait for it
+            locator
+                .evaluate((el) => {
+                const prev = el.getAttribute("data-video-prev-style");
+                if (typeof prev === "string") {
+                    el.setAttribute("style", prev);
+                    el.removeAttribute("data-video-prev-style");
+                }
+            })
+                .catch(() => {
+                // Element may be gone or not actionable, ignore
+            });
+        },
+    };
+};
+/**
+ * Highlights elements before actions and pauses for video recording.
+ * Also pauses after tests complete for better video endings.
+ */
+export const videoMode = (options = {}) => {
+    const pauseBefore = options.pauseBefore || 1000;
+    const pauseAfterTest = options.pauseAfterTest || 3000;
+    const highlightStyle = options.highlightStyle || "3px solid gold";
+    const skipMethods = options.skipMethods || ["waitFor"];
+    const skipStackFrames = options.skipStackFrames || [];
+    return {
+        name: "video-mode",
+        middleware: async ({ locator, method }, next) => {
+            const env_1 = { stack: [], error: void 0, hasError: false };
+            try {
+                if (skipMethods.includes(method))
+                    return next();
+                // Skip if called from internal helpers (navigation, login flows etc)
+                if (skipStackFrames.length > 0) {
+                    const stack = new Error().stack || "";
+                    if (skipStackFrames.some((frame) => stack.includes(frame)))
+                        return next();
+                }
+                const _ = __addDisposableResource(env_1, await setupHighlight(locator, highlightStyle, pauseBefore), false);
+                return await next();
+            }
+            catch (e_1) {
+                env_1.error = e_1;
+                env_1.hasError = true;
+            }
+            finally {
+                __disposeResources(env_1);
+            }
+        },
+        testLifecycle: (emitter) => {
+            return emitter.on("afterTest", async ({ testInfo }) => {
+                await new Promise((resolve) => setTimeout(resolve, pauseAfterTest));
+                console.log(`video will be written to ${testInfo.outputDir}/video.webm`);
+            });
+        },
+    };
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "middlewright",
+  "version": "0.1.0",
+  "description": "A plugin/middleware system for Playwright locator actions — spinner-aware waiting, hydration gates, UI error reporting, video highlighting, and LLM-powered recovery. A hack, but a useful one.",
+  "keywords": [
+    "playwright",
+    "plugin",
+    "middleware",
+    "testing",
+    "e2e",
+    "spinner",
+    "flaky-tests"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/iterate/middlewright.git"
+  },
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "dedent": "^1.7.0",
+    "emittery": "^1.2.0"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.57.0",
+    "@types/node": "^24.10.9",
+    "publint": "^0.3.14",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "@playwright/test": ">=1.49.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "playwright test"
+  }
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+export {
+  addPlugins,
+  adjustError,
+  oneArgMethods,
+  overrideableMethods,
+  type Plugin,
+  type ActionContext,
+  type ActionMiddleware,
+  type NextFn,
+  type TestLifecycleEvents,
+  type LocatorWithOriginal,
+  type OverrideableMethod,
+  type OneArgMethod,
+} from "./plugin-system.ts";
+
+export * from "./plugins/index.ts";

package/src/plugin-system.ts

@@ -0,0 +1,292 @@
+/**
+ * middlewright plugin system.
+ *
+ * Extracted from the iterate monorepo's internal Playwright test
+ * infrastructure (github.com/iterate/iterate, private). Modifications from the
+ * original: playwright-core internals are resolved relative to
+ * `@playwright/test` so this works under pnpm's strict node_modules layout,
+ * and locator actions on pages that never had plugins added fall through to
+ * the original implementation instead of throwing.
+ */
+import { createRequire } from "node:module";
+import * as path from "node:path";
+import Emittery from "emittery";
+import type { Locator, Page, TestInfo } from "@playwright/test";
+
+const require = createRequire(import.meta.url);
+
+// Methods that take an extra argument before options (e.g., fill(value, options))
+const oneArgMethods = ["fill", "type", "press"] as const;
+type OneArgMethod = (typeof oneArgMethods)[number];
+
+const overrideableMethods = [
+  "click",
+  "waitFor",
+  "clear",
+  "dblclick",
+  "blur",
+  "focus",
+  "hover",
+  ...oneArgMethods,
+] satisfies (keyof Locator)[];
+type OverrideableMethod = (typeof overrideableMethods)[number];
+
+export type LocatorWithOriginal = Locator & {
+  [K in OverrideableMethod as `${K}_original`]: Locator[K];
+};
+
+/**
+ * Append info to an error message and clean up stack trace.
+ * @param error - The error to modify
+ * @param info - Lines to append to the error message
+ * @param filterFile - Filename to remove from stack trace (e.g., "my-plugin.ts")
+ * @param color - ANSI color code (default: 33 = yellow). Use 31 for red.
+ */
+export const adjustError = (
+  error: Error,
+  info: string[],
+  filterFile?: string,
+  { color = 33 } = {},
+) => {
+  if (!error?.message) return;
+
+  Object.assign(error, { originalMessage: error.message, originalStack: error.stack });
+
+  if (info.length > 0) {
+    const infoBlock = info.map((line) => `  ${line}`).join("\n");
+    error.message = `${error.message}\n\x1b[${color}m${infoBlock}\x1b[0m\n`;
+  }
+
+  if (filterFile && error.stack) {
+    error.stack = error.stack
+      .split("\n")
+      .filter((line) => !line.includes(filterFile))
+      .join("\n");
+  }
+};
+
+export type ActionContext = {
+  locator: LocatorWithOriginal;
+  method: OverrideableMethod;
+  args: unknown[];
+  page: Page;
+  testInfo: TestInfo;
+};
+
+/** Function that calls the next middleware or the original action */
+export type NextFn = () => Promise<unknown>;
+
+/** Middleware function - wraps an action, must call next() */
+export type ActionMiddleware = (ctx: ActionContext, next: NextFn) => Promise<unknown>;
+
+export type TestLifecycleEvents = {
+  beforeTest: { page: Page; testInfo: TestInfo };
+  afterTest: { page: Page; testInfo: TestInfo };
+};
+
+export type Plugin = {
+  name: string;
+  /** Middleware to wrap locator actions. Called in registration order. */
+  middleware?: ActionMiddleware;
+  /** Subscribe to test lifecycle events */
+  testLifecycle?: (emitter: Emittery<TestLifecycleEvents>) => void | (() => void);
+};
+
+const PLUGIN_STATE = Symbol("playwrightPluginState");
+
+type PluginState = {
+  actionMiddlewares: ActionMiddleware[];
+  lifecycleEmitter: Emittery<TestLifecycleEvents>;
+  lifecycleCleanups: (() => void)[];
+  testInfo: TestInfo;
+};
+
+type PageWithPlugins = Page & {
+  [PLUGIN_STATE]: PluginState;
+  [Symbol.asyncDispose]: () => Promise<void>;
+};
+
+// Track if Locator prototype has been patched
+let prototypePatched = false;
+
+/** Get plugin state from a page */
+const getPluginState = (page: Page): PluginState | undefined => {
+  return (page as PageWithPlugins)[PLUGIN_STATE];
+};
+
+/**
+ * Add plugins to a page. Returns a disposable page that cleans up on dispose.
+ *
+ * @example
+ * ```ts
+ * await using page = await addPlugins({
+ *   page: basePage,
+ *   testInfo,
+ *   plugins: [
+ *     hydrationWaiter(),
+ *     spinnerWaiter(),
+ *     videoMode(),
+ *   ]
+ * });
+ * ```
+ */
+export const addPlugins = async (params: {
+  page: Page;
+  testInfo: TestInfo;
+  plugins: (Plugin | false | null | undefined)[];
+  boxedStackPrefixes?: (defaults: string[]) => string[];
+}): Promise<PageWithPlugins> => {
+  const { page, testInfo, plugins, boxedStackPrefixes } = params;
+  // Patch Locator prototype once globally
+  patchLocatorPrototype(page, boxedStackPrefixes);
+
+  // Initialize state on page
+  const state: PluginState = {
+    actionMiddlewares: [],
+    lifecycleEmitter: new Emittery(),
+    lifecycleCleanups: [],
+    testInfo,
+  };
+
+  // Register plugins
+  for (const plugin of plugins) {
+    if (!plugin) continue;
+
+    if (plugin.middleware) {
+      state.actionMiddlewares.push(plugin.middleware);
+    }
+
+    if (plugin.testLifecycle) {
+      const cleanup = plugin.testLifecycle(state.lifecycleEmitter);
+      if (cleanup) state.lifecycleCleanups.push(cleanup);
+    }
+  }
+
+  const pageWithPlugins = page as PageWithPlugins;
+  pageWithPlugins[PLUGIN_STATE] = state;
+
+  // Emit beforeTest
+  await state.lifecycleEmitter.emitSerial("beforeTest", { page, testInfo });
+
+  // Add async dispose
+  pageWithPlugins[Symbol.asyncDispose] = async () => {
+    await state.lifecycleEmitter.emitSerial("afterTest", { page, testInfo });
+    state.lifecycleCleanups.forEach((cleanup) => cleanup());
+  };
+
+  return pageWithPlugins;
+};
+
+/**
+ * Resolve playwright-core starting from @playwright/test. Under pnpm's strict
+ * layout, playwright-core isn't reachable from this package - only via the
+ * host project's @playwright/test.
+ */
+const resolvePlaywrightInternals = () => {
+  const testPkg = require.resolve("@playwright/test/package.json");
+  const requireFromTest = createRequire(testPkg);
+  const playwrightPkg = requireFromTest.resolve("playwright/package.json");
+  const corePkg = createRequire(playwrightPkg).resolve("playwright-core/package.json");
+  return { testPkg, playwrightPkg, corePkg };
+};
+
+/**
+ * setBoxedStackPrefixes is an internal playwright-core API
+ * (https://github.com/microsoft/playwright/issues/38818 asks for it to be made
+ * official) and has already moved once: playwright-core <= 1.59 exposed it
+ * from lib/utils, 1.60+ from the utils namespace of lib/coreBundle. Returns
+ * null when it can't be found - everything works without it, you just see
+ * plugin frames in stack traces.
+ */
+const loadSetBoxedStackPrefixes = (corePkg: string): ((prefixes: string[]) => void) | null => {
+  const coreRequire = createRequire(corePkg);
+  for (const load of [
+    () => coreRequire("./lib/utils").setBoxedStackPrefixes,
+    () => coreRequire("./lib/coreBundle").utils.setBoxedStackPrefixes,
+  ]) {
+    try {
+      const fn = load();
+      if (typeof fn === "function") return fn;
+    } catch {
+      // try the next layout
+    }
+  }
+  return null;
+};
+
+/** Patch Locator prototype to run middleware. Safe to call multiple times. */
+const patchLocatorPrototype = (
+  page: Page,
+  boxedStackPrefixes?: (defaults: string[]) => string[],
+) => {
+  if (prototypePatched) return;
+  prototypePatched = true;
+
+  const internals = resolvePlaywrightInternals();
+
+  // Exclude this file from stack traces in Playwright reports
+  if (!process.env.PLAYWRIGHT_PLUGIN_DEBUG) {
+    const setBoxedStackPrefixes = loadSetBoxedStackPrefixes(internals.corePkg);
+    if (setBoxedStackPrefixes) {
+      const getPrefixes = boxedStackPrefixes || ((defaults) => defaults);
+      const prefixes = getPrefixes([
+        path.dirname(internals.testPkg),
+        path.dirname(internals.playwrightPkg),
+        path.dirname(internals.corePkg),
+        import.meta.filename,
+      ]);
+      setBoxedStackPrefixes(prefixes);
+    } else {
+      console.warn(
+        "[middlewright] could not find setBoxedStackPrefixes in this playwright-core version - " +
+          "stack traces in reports will include plugin frames",
+      );
+    }
+  }
+
+  const dummyLocator = page.locator("body");
+  const locatorPrototype = dummyLocator.constructor.prototype;
+
+  for (const method of overrideableMethods) {
+    locatorPrototype[`${method}_original`] = locatorPrototype[method];
+
+    const value = async function patchedMethod(
+      this: LocatorWithOriginal,
+      ...args: unknown[]
+    ): Promise<unknown> {
+      const callOriginal = () => (this[`${method}_original`] as Function)(...args);
+
+      // Pages that never had plugins added (e.g. a second page in the same
+      // worker) fall through to the original implementation.
+      const state = getPluginState(this.page());
+      if (!state) return callOriginal();
+      const actionMiddlewares = state.actionMiddlewares;
+
+      const ctx: ActionContext = {
+        locator: this,
+        method,
+        args,
+        page: this.page(),
+        testInfo: state.testInfo,
+      };
+
+      // Build middleware chain - each middleware calls next() to continue
+      let index = 0;
+      const next: NextFn = async () => {
+        if (index < actionMiddlewares.length) {
+          const middleware = actionMiddlewares[index++];
+          return middleware(ctx, next);
+        }
+        return callOriginal();
+      };
+
+      return next();
+    };
+
+    Object.defineProperty(locatorPrototype, method, { value });
+  }
+};
+
+// Re-export types for plugin authors
+export type { OverrideableMethod, OneArgMethod };
+export { oneArgMethods, overrideableMethods };

package/src/plugins/hydration-waiter.ts

@@ -0,0 +1,46 @@
+/**
+ * hydration-waiter: don't interact with the app before it's interactive.
+ *
+ * Extracted from the iterate monorepo's internal Playwright test
+ * infrastructure (github.com/iterate/iterate, private).
+ */
+import type { Plugin, LocatorWithOriginal } from "../plugin-system.ts";
+
+export type HydrationWaiterOptions = {
+  /** Selector for unhydrated state. Default: '[data-hydrated="false"]' */
+  selector?: string;
+  /** Timeout for hydration. Default: 10_000 */
+  timeout?: number;
+  /** Whether to skip this plugin. Default: false */
+  disabled?: boolean;
+};
+
+/**
+ * Waits for the app to be hydrated before any locator action.
+ * Looks for `[data-hydrated="false"]` and waits for it to disappear.
+ *
+ * Your app needs to cooperate: render `data-hydrated="false"` on some element
+ * server-side and flip it to "true" (or remove it) once the framework has
+ * hydrated. With React, for example, flip it in a top-level component that
+ * only runs client-side.
+ */
+export const hydrationWaiter = (options: HydrationWaiterOptions = {}): Plugin => {
+  const selector = options.selector || '[data-hydrated="false"]';
+  const timeout = options.timeout || 10_000;
+
+  return {
+    name: "hydration-waiter",
+    middleware: async ({ page }, next) => {
+      if (options.disabled) return next();
+
+      const unhydratedLocator = page.locator(selector) as LocatorWithOriginal;
+      const isUnhydrated = await unhydratedLocator.isVisible();
+
+      if (isUnhydrated) {
+        await unhydratedLocator.waitFor_original({ state: "hidden", timeout });
+      }
+
+      return next();
+    },
+  };
+};

package/src/plugins/index.ts

@@ -0,0 +1,11 @@
+export { hydrationWaiter, type HydrationWaiterOptions } from "./hydration-waiter.ts";
+export { videoMode, type VideoModeOptions } from "./video-mode.ts";
+export { spinnerWaiter, type SpinnerWaiterOptions, defaultSelectors } from "./spinner-waiter.ts";
+export { uiErrorReporter, type UIErrorReporterOptions } from "./ui-error-reporter.ts";
+export {
+  llmRecover,
+  type LlmRecoverOptions,
+  type AttemptRecord,
+  type RecoveryContext,
+  type RequestRecoveryCodeFn,
+} from "./llm-recover.ts";