middlewright 0.1.0 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "middlewright",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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",
@@ -34,6 +34,7 @@
   "devDependencies": {
     "@playwright/test": "^1.57.0",
     "@types/node": "^24.10.9",
+    "pkg-pr-new": "^0.0.75",
     "publint": "^0.3.14",
     "typescript": "^5.9.3"
   },
@@ -43,9 +44,12 @@
   "engines": {
     "node": ">=20"
   },
+  "git": {
+    "sha": "d9b03dd"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
-    "typecheck": "tsc --noEmit",
-    "test": "playwright test"
+    "test": "playwright test",
+    "typecheck": "tsc --noEmit"
   }
 }

package/src/index.ts

@@ -4,8 +4,11 @@ export {
   oneArgMethods,
   overrideableMethods,
   type Plugin,
+  type PageExtensionContext,
   type ActionContext,
   type ActionMiddleware,
+  type ActionMiddlewareTiming,
+  type ActionTiming,
   type NextFn,
   type TestLifecycleEvents,
   type LocatorWithOriginal,

package/src/plugin-system.ts

@@ -71,10 +71,24 @@ export type ActionContext = {
   args: unknown[];
   page: Page;
   testInfo: TestInfo;
+  timing: ActionTiming;
+};
+
+export type ActionMiddlewareTiming = {
+  name: string;
+  startedAt: number;
+  endedAt?: number;
+};
+
+export type ActionTiming = {
+  actionStartedAt: number;
+  attachedAt?: number;
+  attachedAtStart: boolean;
+  middlewares: ActionMiddlewareTiming[];
 };
 
 /** Function that calls the next middleware or the original action */
-export type NextFn = () => Promise<unknown>;
+export type NextFn = (args?: unknown[]) => Promise<unknown>;
 
 /** Middleware function - wraps an action, must call next() */
 export type ActionMiddleware = (ctx: ActionContext, next: NextFn) => Promise<unknown>;
@@ -82,26 +96,62 @@ export type ActionMiddleware = (ctx: ActionContext, next: NextFn) => Promise<unk
 export type TestLifecycleEvents = {
   beforeTest: { page: Page; testInfo: TestInfo };
   afterTest: { page: Page; testInfo: TestInfo };
+  afterTestFinalize: { page: Page; testInfo: TestInfo };
 };
 
-export type Plugin = {
+export type PageExtensionContext = {
+  page: Page;
+  testInfo: TestInfo;
+};
+
+export type Plugin<PageExtension extends object = {}> = {
   name: string;
   /** Middleware to wrap locator actions. Called in registration order. */
   middleware?: ActionMiddleware;
   /** Subscribe to test lifecycle events */
   testLifecycle?: (emitter: Emittery<TestLifecycleEvents>) => void | (() => void);
+  /** Add explicit test controls to the page returned from addPlugins. */
+  pageExtension?: (ctx: PageExtensionContext) => PageExtension;
 };
 
 const PLUGIN_STATE = Symbol("playwrightPluginState");
 
 type PluginState = {
-  actionMiddlewares: ActionMiddleware[];
+  actionMiddlewares: RegisteredActionMiddleware[];
   lifecycleEmitter: Emittery<TestLifecycleEvents>;
   lifecycleCleanups: (() => void)[];
   testInfo: TestInfo;
 };
 
-type PageWithPlugins = Page & {
+type RegisteredActionMiddleware = {
+  name: string;
+  middleware: ActionMiddleware;
+};
+
+type MaybePlugin = Plugin<object> | false | null | undefined;
+
+type PluginPageExtension<T> = T extends Plugin<infer PageExtension> ? PageExtension : {};
+
+type PluginPageExtensionForEntry<T> = [Extract<T, Plugin<object>>] extends [never]
+  ? {}
+  : [Exclude<T, Plugin<object>>] extends [never]
+    ? PluginPageExtension<T>
+    : Partial<PluginPageExtension<T>>;
+
+type UnionToIntersection<T> = (T extends unknown ? (value: T) => void : never) extends (
+  value: infer Intersection,
+) => void
+  ? Intersection
+  : never;
+
+type PageExtensions<T extends readonly MaybePlugin[]> = UnionToIntersection<
+  {
+    [Index in keyof T]: PluginPageExtensionForEntry<T[Index]>;
+  }[number]
+> &
+  object;
+
+type PageWithPlugins<PageExtension extends object = {}> = Page & PageExtension & {
   [PLUGIN_STATE]: PluginState;
   [Symbol.asyncDispose]: () => Promise<void>;
 };
@@ -130,12 +180,12 @@ const getPluginState = (page: Page): PluginState | undefined => {
  * });
  * ```
  */
-export const addPlugins = async (params: {
+export const addPlugins = async <const Plugins extends readonly MaybePlugin[]>(params: {
   page: Page;
   testInfo: TestInfo;
-  plugins: (Plugin | false | null | undefined)[];
+  plugins: Plugins;
   boxedStackPrefixes?: (defaults: string[]) => string[];
-}): Promise<PageWithPlugins> => {
+}): Promise<PageWithPlugins<PageExtensions<Plugins>>> => {
   const { page, testInfo, plugins, boxedStackPrefixes } = params;
   // Patch Locator prototype once globally
   patchLocatorPrototype(page, boxedStackPrefixes);
@@ -153,7 +203,10 @@ export const addPlugins = async (params: {
     if (!plugin) continue;
 
     if (plugin.middleware) {
-      state.actionMiddlewares.push(plugin.middleware);
+      state.actionMiddlewares.push({
+        middleware: plugin.middleware,
+        name: plugin.name,
+      });
     }
 
     if (plugin.testLifecycle) {
@@ -162,15 +215,23 @@ export const addPlugins = async (params: {
     }
   }
 
-  const pageWithPlugins = page as PageWithPlugins;
+  const pageWithPlugins = page as PageWithPlugins<PageExtensions<Plugins>>;
   pageWithPlugins[PLUGIN_STATE] = state;
 
+  for (const plugin of plugins) {
+    if (!plugin) continue;
+    if (!plugin.pageExtension) continue;
+
+    Object.assign(pageWithPlugins, plugin.pageExtension({ page, testInfo }));
+  }
+
   // Emit beforeTest
   await state.lifecycleEmitter.emitSerial("beforeTest", { page, testInfo });
 
   // Add async dispose
   pageWithPlugins[Symbol.asyncDispose] = async () => {
     await state.lifecycleEmitter.emitSerial("afterTest", { page, testInfo });
+    await state.lifecycleEmitter.emitSerial("afterTestFinalize", { page, testInfo });
     state.lifecycleCleanups.forEach((cleanup) => cleanup());
   };
 
@@ -214,6 +275,52 @@ const loadSetBoxedStackPrefixes = (corePkg: string): ((prefixes: string[]) => vo
   return null;
 };
 
+const locatorIsAttached = async (locator: Locator) => {
+  try {
+    return (await locator.count()) > 0;
+  } catch {
+    return false;
+  }
+};
+
+const observeAttachedAt = (
+  locator: Locator,
+  timing: ActionTiming,
+  pollIntervalMs = 50,
+) => {
+  let stopped = false;
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+
+  const poll = async () => {
+    if (stopped || timing.attachedAt !== undefined) {
+      return;
+    }
+
+    const attached = await locatorIsAttached(locator);
+    if (stopped || timing.attachedAt !== undefined) {
+      return;
+    }
+
+    if (attached) {
+      timing.attachedAt = performance.now();
+      return;
+    }
+
+    timeout = setTimeout(() => {
+      void poll();
+    }, pollIntervalMs);
+  };
+
+  void poll();
+
+  return () => {
+    stopped = true;
+    if (timeout) {
+      clearTimeout(timeout);
+    }
+  };
+};
+
 /** Patch Locator prototype to run middleware. Safe to call multiple times. */
 const patchLocatorPrototype = (
   page: Page,
@@ -254,13 +361,25 @@ const patchLocatorPrototype = (
       this: LocatorWithOriginal,
       ...args: unknown[]
     ): Promise<unknown> {
-      const callOriginal = () => (this[`${method}_original`] as Function)(...args);
+      let currentArgs = args;
+      const callOriginal = () => (this[`${method}_original`] as Function)(...currentArgs);
 
       // 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 actionStartedAt = performance.now();
+      const attachedAtStart = await locatorIsAttached(this);
+      const timing: ActionTiming = {
+        actionStartedAt,
+        attachedAt: attachedAtStart ? actionStartedAt : undefined,
+        attachedAtStart,
+        middlewares: [],
+      };
+      const stopObservingAttached = attachedAtStart
+        ? () => {}
+        : observeAttachedAt(this, timing);
 
       const ctx: ActionContext = {
         locator: this,
@@ -268,19 +387,38 @@ const patchLocatorPrototype = (
         args,
         page: this.page(),
         testInfo: state.testInfo,
+        timing,
       };
 
       // Build middleware chain - each middleware calls next() to continue
       let index = 0;
-      const next: NextFn = async () => {
+      const next: NextFn = async (nextArgs) => {
+        if (nextArgs) {
+          currentArgs = nextArgs;
+          ctx.args = nextArgs;
+        }
+
         if (index < actionMiddlewares.length) {
-          const middleware = actionMiddlewares[index++];
-          return middleware(ctx, next);
+          const { middleware, name } = actionMiddlewares[index++];
+          const middlewareTiming: ActionMiddlewareTiming = {
+            name,
+            startedAt: performance.now(),
+          };
+          timing.middlewares.push(middlewareTiming);
+          try {
+            return await middleware(ctx, next);
+          } finally {
+            middlewareTiming.endedAt = performance.now();
+          }
         }
         return callOriginal();
       };
 
-      return next();
+      try {
+        return await next();
+      } finally {
+        stopObservingAttached();
+      }
     };
 
     Object.defineProperty(locatorPrototype, method, { value });

package/src/plugins/hydration-waiter.ts

@@ -25,6 +25,10 @@ export type HydrationWaiterOptions = {
  * only runs client-side.
  */
 export const hydrationWaiter = (options: HydrationWaiterOptions = {}): Plugin => {
+  if (process.env.PWDEBUG) {
+    return { name: "hydration-waiter" };
+  }
+
   const selector = options.selector || '[data-hydrated="false"]';
   const timeout = options.timeout || 10_000;
 

package/src/plugins/index.ts

@@ -1,5 +1,19 @@
 export { hydrationWaiter, type HydrationWaiterOptions } from "./hydration-waiter.ts";
-export { videoMode, type VideoModeOptions } from "./video-mode.ts";
+export {
+  videoMode,
+  type VideoModeControls,
+  type VideoModeHighlight,
+  type VideoModeMetadata,
+  type VideoModeOptions,
+  type VideoModeOutputPaths,
+  type VideoModeOutputs,
+  type VideoModePageExtension,
+  type VideoModeRect,
+  type VideoModePlugin,
+  type VideoModeSourceRange,
+  type VideoModeSpan,
+  type VideoModeViewport,
+} from "./video-mode.ts";
 export { spinnerWaiter, type SpinnerWaiterOptions, defaultSelectors } from "./spinner-waiter.ts";
 export { uiErrorReporter, type UIErrorReporterOptions } from "./ui-error-reporter.ts";
 export {

package/src/plugins/llm-recover.ts

@@ -69,6 +69,10 @@ export type RequestRecoveryCodeFn = (
 const pagesInRecovery = new WeakSet<object>();
 
 export const llmRecover = (options: LlmRecoverOptions = {}): Plugin => {
+  if (process.env.PWDEBUG) {
+    return { name: "llm-recover" };
+  }
+
   const expect = options.expect || playwrightExpect;
   const maxAttempts = options.maxAttempts || 3;
   const requestRecovery = options.requestRecoveryCode || createAnthropicProvider(options);

package/src/plugins/spinner-waiter.ts

@@ -8,8 +8,8 @@
  */
 import { AsyncLocalStorage } from "node:async_hooks";
 import type { Locator } from "@playwright/test";
-import type { Plugin, LocatorWithOriginal } from "../plugin-system.ts";
-import { adjustError } from "../plugin-system.ts";
+import type { ActionContext, LocatorWithOriginal, Plugin } from "../plugin-system.ts";
+import { adjustError, oneArgMethods } from "../plugin-system.ts";
 
 export type SpinnerWaiterOptions = {
   /** Selectors that indicate loading state */
@@ -22,12 +22,26 @@ export type SpinnerWaiterOptions = {
   log?: (message: string) => void;
 };
 
+/** Match `loading...`, (or really `anyVerbing...`). Also matches an ellipsis character "…" rather than "..." since LLMs like fancy unicode. */
+const loadingTextPattern = /(loading|pending|creating|verifying|starting|processing|syncing|building|\b\w+ing)[\s\w]*(\.\.\.|…)$/;
+
 const defaultSelectors = [
   `[aria-label="Loading"]`,
   `[data-spinner='true']`,
-  `:text-matches("(loading|pending|creating|verifying|starting|processing|syncing)\\.\\.\\.$", "i")`,
+  `:text-matches(${JSON.stringify(loadingTextPattern.source)}, "i")`,
 ];
 
+const oneArgMethodNames = new Set<string>(oneArgMethods);
+const enabledActionMethods = new Set<ActionContext["method"]>([
+  "clear",
+  "click",
+  "dblclick",
+  "fill",
+  "focus",
+  "press",
+  "type",
+]);
+
 const defaults: Required<SpinnerWaiterOptions> = {
   spinnerSelectors: defaultSelectors,
   spinnerTimeout: 30_000,
@@ -63,20 +77,24 @@ const suggestSpinnerMessage = (spinnerLocator: Locator) => [
  */
 export const spinnerWaiter = Object.assign(
   (options: SpinnerWaiterOptions = {}): Plugin => {
+    if (process.env.PWDEBUG) {
+      return { name: "spinner-waiter" };
+    }
+
     return {
       name: "spinner-waiter",
 
-      middleware: async ({ locator, method, page }, next) => {
+      middleware: async ({ args, locator, method, page }, next) => {
         const settings = getSettings(options);
         if (settings.disabled) return next();
 
         const start = Date.now();
         settings.log(`${locator}.${method}(...) starting`);
 
-        // Quick check if element is already visible
-        const elementVisible = await waitForVisible(locator, { timeout: 1000 });
-        if (elementVisible) {
-          settings.log(`${locator} already visible, proceeding`);
+        // Quick check if element is already ready for the attempted action.
+        const elementReady = await waitForReady(locator, method, { timeout: 1000 });
+        if (elementReady) {
+          settings.log(`${locator} already ready, proceeding`);
           return next();
         }
 
@@ -87,9 +105,9 @@ export const spinnerWaiter = Object.assign(
 
         if (!spinnerVisible) {
           // No spinner - call action, suggest adding one if it fails
-          settings.log(`${locator} not visible, no spinner, proceeding anyway`);
+          settings.log(`${locator} not ready, no spinner, failing fast`);
           try {
-            return await next();
+            return await next(withTimeoutOption(method, args, 1));
           } catch (error) {
             adjustError(error as Error, suggestSpinnerMessage(spinnerLocator), "spinner-waiter.ts");
             throw error;
@@ -102,18 +120,18 @@ export const spinnerWaiter = Object.assign(
 
         // Spinner is visible — wait for the element, but bail early if the spinner
         // disappears (the loading operation finished without producing the expected element).
-        const waitResult = await waitForVisibleWhileSpinning(locator, spinnerLocator, {
+        const waitResult = await waitForReadyWhileSpinning(locator, method, spinnerLocator, {
           timeout: settings.spinnerTimeout - 2000,
         });
 
         if (waitResult === "appeared") {
-          settings.log(`${locator} appeared after waiting`);
+          settings.log(`${locator} became ready after waiting`);
           return next();
         }
 
         if (waitResult === "spinner-gone") {
           settings.log(
-            `Spinner disappeared but element not visible — loading finished without expected result`,
+            `Spinner disappeared but element not ready — loading finished without expected result`,
           );
         } else {
           settings.log(`Spinner still visible after ${settings.spinnerTimeout}ms, UI likely stuck`);
@@ -125,7 +143,7 @@ export const spinnerWaiter = Object.assign(
         } catch (error) {
           const message =
             waitResult === "spinner-gone"
-              ? `Loading finished (spinner disappeared after ${Date.now() - start}ms) but the expected element never appeared.`
+              ? `Loading finished (spinner disappeared after ${Date.now() - start}ms) but the expected element was not ready.`
               : `Spinner was still visible after ${settings.spinnerTimeout}ms, the UI is likely stuck.`;
           adjustError(error as Error, [message], "spinner-waiter.ts");
           throw error;
@@ -141,22 +159,49 @@ export const spinnerWaiter = Object.assign(
   },
 );
 
-async function waitForVisible(locator: Locator, { timeout = 1000 } = {}) {
+async function locatorIsReady(locator: Locator, method: ActionContext["method"]) {
+  if (!(await locator.isVisible())) return false;
+  if (!enabledActionMethods.has(method)) return true;
+  return await locator.isEnabled();
+}
+
+async function waitForReady(
+  locator: Locator,
+  method: ActionContext["method"],
+  { timeout = 1000 } = {},
+) {
   const start = Date.now();
   while (Date.now() - start < timeout) {
-    if (await locator.isVisible()) return true;
+    if (await locatorIsReady(locator, method)) return true;
     await new Promise((resolve) => setTimeout(resolve, 100));
   }
-  return false;
+  return await locatorIsReady(locator, method);
+}
+
+function withTimeoutOption(method: ActionContext["method"], args: unknown[], timeout: number) {
+  const optionsIndex = oneArgMethodNames.has(method) ? 1 : 0;
+  const nextArgs = [...args];
+  const options = nextArgs[optionsIndex];
+  if (isOptionsObject(options)) {
+    nextArgs[optionsIndex] = { ...options, timeout };
+  } else {
+    nextArgs[optionsIndex] = { timeout };
+  }
+  return nextArgs;
+}
+
+function isOptionsObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
 /**
- * Wait for `target` to become visible, but bail early if `spinner` disappears.
- * Returns "appeared" if target showed up, "spinner-gone" if loading finished
+ * Wait for `target` to become ready, but bail early if `spinner` disappears.
+ * Returns "appeared" if target became ready, "spinner-gone" if loading finished
  * without the target, or "timeout" if spinner was still visible at deadline.
  */
-async function waitForVisibleWhileSpinning(
+async function waitForReadyWhileSpinning(
   target: Locator,
+  method: ActionContext["method"],
   spinner: Locator,
   { timeout = 1000 } = {},
 ): Promise<"appeared" | "spinner-gone" | "timeout"> {
@@ -164,7 +209,7 @@ async function waitForVisibleWhileSpinning(
   // Give the spinner a grace period before checking — it may flicker during transitions
   const spinnerGracePeriodMs = 3000;
   while (Date.now() - start < timeout) {
-    if (await target.isVisible()) return "appeared";
+    if (await locatorIsReady(target, method)) return "appeared";
     const elapsed = Date.now() - start;
     if (elapsed > spinnerGracePeriodMs && !(await spinner.isVisible())) return "spinner-gone";
     await new Promise((resolve) => setTimeout(resolve, 250));

package/src/plugins/ui-error-reporter.ts

@@ -20,6 +20,10 @@ export type UIErrorReporterOptions = {
  * their text to the error message for easier debugging.
  */
 export const uiErrorReporter = (options: UIErrorReporterOptions = {}): Plugin => {
+  if (process.env.PWDEBUG) {
+    return { name: "ui-error-reporter" };
+  }
+
   const selector = options.selector || '[data-type="error"]';
 
   return {