From e0a2cff6f80487efe7383c9c602443d33fbdd461 Mon Sep 17 00:00:00 2001
From: Misha Kaletsky <15040698+mmkal@users.noreply.github.com>
Date: Wed, 17 Jun 2026 17:22:45 +0100
Subject: [PATCH 01/35] Improve spinner waiter late-spinner failures
Fail fast in the no-spinner path so a delayed loading indicator cannot appear during the final Playwright action timeout and make the add-spinner hint contradict the current UI.
Also preserve the expanded loading-text selector via RegExp.source and add a regression covering a late spinner. This commit includes the staged spec readability cleanup from the working tree.
---
spec/spinner-waiter.spec.ts | 29 ++++++++++++++++++++++
src/plugins/spinner-waiter.ts | 46 +++++++++++++++++++++++++++++------
2 files changed, 68 insertions(+), 7 deletions(-)
diff --git a/spec/spinner-waiter.spec.ts b/spec/spinner-waiter.spec.ts
index 33c9d80..6833297 100644
--- a/spec/spinner-waiter.spec.ts
+++ b/spec/spinner-waiter.spec.ts
@@ -47,6 +47,35 @@ test("slow button fails when spinner doesn't match selector", async ({ page }) =
expect(error.message).toMatch(/Timeout .* exceeded/);
expect(error.message).toMatch(/If this is a slow operation.../);
});
+
+test("fails before a late spinner can make the no-spinner hint misleading", async ({ page }) => {
+ await page.setContent(`
+
+
Loading...
+
+ `);
+
+ await page.locator("#start").click();
+
+ const start = Date.now();
+ const error = await page.getByText("operation complete").waitFor().catch((e: Error) => e);
+ const elapsed = Date.now() - start;
+
+ expect(error).toBeInstanceOf(Error);
+ expect(error?.message).toMatch(/If this is a slow operation.../);
+ expect(elapsed).toBeLessThan(1500); // we don't tolerate the spinner taking a long time to appear
+ expect(await page.locator('[aria-label="Loading"]').isVisible()).toBe(false);
+});
+
test("slow button fails when spinner times out", async ({ page }) => {
await page.evaluate(() => Object.assign(window, { slowMutationTimeout: 6000 }));
spinnerWaiter.settings.enterWith({ spinnerTimeout: 3001 });
diff --git a/src/plugins/spinner-waiter.ts b/src/plugins/spinner-waiter.ts
index 4ee9253..7817d1f 100644
--- a/src/plugins/spinner-waiter.ts
+++ b/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,17 @@ 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(oneArgMethods);
+
const defaults: Required = {
spinnerSelectors: defaultSelectors,
spinnerTimeout: 30_000,
@@ -66,7 +71,7 @@ export const spinnerWaiter = Object.assign(
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();
@@ -87,9 +92,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 visible, no spinner, failing fast`);
try {
- return await next();
+ return await callOriginalWithTimeout(locator, method, args, 1);
} catch (error) {
adjustError(error as Error, suggestSpinnerMessage(spinnerLocator), "spinner-waiter.ts");
throw error;
@@ -147,7 +152,34 @@ async function waitForVisible(locator: Locator, { timeout = 1000 } = {}) {
if (await locator.isVisible()) return true;
await new Promise((resolve) => setTimeout(resolve, 100));
}
- return false;
+ return await locator.isVisible();
+}
+
+async function callOriginalWithTimeout(
+ locator: LocatorWithOriginal,
+ method: ActionContext["method"],
+ args: unknown[],
+ timeout: number,
+) {
+ return await (locator[`${method}_original`] as Function)(
+ ...withTimeoutOption(method, args, timeout),
+ );
+}
+
+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 {
+ return typeof value === "object" && value !== null && !Array.isArray(value);
}
/**
From 268d99cbb3eaf91ffd69e20368c4217281d92ca5 Mon Sep 17 00:00:00 2001
From: Misha Kaletsky <15040698+mmkal@users.noreply.github.com>
Date: Fri, 19 Jun 2026 22:38:17 +0100
Subject: [PATCH 02/35] better
---
AGENTS.md | 7 +
README.md | 15 +-
spec/plugin-system.spec.ts | 33 +++
spec/video-mode-ffmpeg.spec.ts | 132 +++++++++++
spec/video-mode.spec.ts | 143 ++++++++++-
src/index.ts | 2 +
src/plugin-system.ts | 98 +++++++-
src/plugins/index.ts | 9 +-
src/plugins/video-mode.ts | 422 ++++++++++++++++++++++++++++++++-
9 files changed, 843 insertions(+), 18 deletions(-)
create mode 100644 AGENTS.md
create mode 100644 spec/video-mode-ffmpeg.spec.ts
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..3652b56
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,7 @@
+# middlewright Agent Notes
+
+## Plugin Boundaries
+
+When plugins interact, preserve caller ergonomics and plugin ownership. Expose shared cross-cutting facts through neutral middleware context rather than coupling one plugin to another plugin's feature.
+
+For example, `spinnerWaiter` should own spinner-specific waiting and errors, while `videoMode` should own video highlighting, dead-air metadata, and ffmpeg output. If both need timing information, add or use neutral middleware context such as `ActionContext.timing`; do not make `spinnerWaiter` know about `videoMode.deadAir`.
diff --git a/README.md b/README.md
index 43832f1..b6eb45a 100644
--- a/README.md
+++ b/README.md
@@ -130,18 +130,29 @@ uiErrorReporter({ selector: '[data-type="error"]' });
### videoMode
-For producing demo/debugging videos people can actually follow: outlines the element in gold, pauses before each action, and pauses after the test so the video doesn't cut off abruptly. Enable it conditionally (e.g. `!!process.env.VIDEO_MODE && videoMode()`) together with Playwright's `video: "on"` and a generous `actionTimeout`.
+For producing demo/debugging videos people can actually follow: waits for the target element to become attached as dead air, outlines the element in gold, pauses before each action, and pauses after the test as dead air so the final cut doesn't keep teardown padding. Enable it conditionally (e.g. `!!process.env.VIDEO_MODE && videoMode()`) together with Playwright's `video: "on"` and a generous `actionTimeout`.
```ts
-videoMode({
+const video = videoMode({
pauseBefore: 1000,
pauseAfterTest: 3000,
highlightStyle: "3px solid gold",
skipMethods: ["waitFor"],
skipStackFrames: ["test-helpers.ts"], // don't slow down internal login/setup helpers
});
+
+// Use the returned plugin for invisible setup/bookkeeping that should not be
+// highlighted or slowed in video mode.
+await video.deadAir(async () => {
+ await page.goto("/login");
+ await page.locator("#email").fill("demo@example.com");
+});
```
+When Playwright video recording is enabled, `videoMode` saves `video-raw.webm`, uses `ffmpeg` to write `video-tight.webm` with dead air removed, and attaches both videos plus `video-mode.json` to the test report. If `ffmpeg` or `ffprobe` is missing, the trim step fails plainly so you know to install ffmpeg.
+
+Put `spinnerWaiter` before `videoMode` when you use both. Spinner-waiter still owns spinner-specific waiting and errors, while video-mode observes the pre-action "wait for attached" period as dead air and highlights immediately before the action.
+
### llmRecover
The most fun one, and the most dangerous one. When an action fails, it captures a screenshot, the accessibility snapshot, the page HTML and the error, asks Claude to respond with a JavaScript recovery function, and `eval`s it with `{ page, locator, error }` in scope. Up to `maxAttempts` tries, with attempt history fed back to the model.
diff --git a/spec/plugin-system.spec.ts b/spec/plugin-system.spec.ts
index ac8747c..540e0a6 100644
--- a/spec/plugin-system.spec.ts
+++ b/spec/plugin-system.spec.ts
@@ -72,6 +72,39 @@ test("middleware receives testInfo", async ({ page }, testInfo) => {
expect(seenTitle).toBe("middleware receives testInfo");
});
+test("middleware receives action timing", async ({ page }, testInfo) => {
+ let seenTiming: any;
+ await using plugged = await addPlugins({
+ page,
+ testInfo,
+ plugins: [
+ {
+ name: "timing-spy",
+ middleware: async (ctx, next) => {
+ seenTiming = ctx.timing;
+ return next();
+ },
+ },
+ ],
+ });
+ await plugged.setContent(``);
+
+ await plugged.locator("button").click();
+
+ expect(seenTiming).toMatchObject({
+ actionStartedAt: expect.any(Number),
+ attachedAt: expect.any(Number),
+ attachedAtStart: true,
+ middlewares: [
+ expect.objectContaining({
+ endedAt: expect.any(Number),
+ name: "timing-spy",
+ startedAt: expect.any(Number),
+ }),
+ ],
+ });
+});
+
test("pages without plugins fall through to the original behavior", async ({
page,
context,
diff --git a/spec/video-mode-ffmpeg.spec.ts b/spec/video-mode-ffmpeg.spec.ts
new file mode 100644
index 0000000..28f57ff
--- /dev/null
+++ b/spec/video-mode-ffmpeg.spec.ts
@@ -0,0 +1,132 @@
+import { execFile as execFileCallback } from "node:child_process";
+import { readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { test, expect } from "@playwright/test";
+import { addPlugins, spinnerWaiter, videoMode } from "../src/index.ts";
+
+const execFile = promisify(execFileCallback);
+
+test.use({ video: "on" });
+
+test("writes a video with dead air removed", async ({ page }, testInfo) => {
+ const video = videoMode({ pauseBefore: 1000, pauseAfterTest: 700 });
+ {
+ await using plugged = await addPlugins({
+ page,
+ testInfo,
+ plugins: [
+ spinnerWaiter({
+ log: (message) => console.log(`[spinnerWaiter] ${message}`),
+ spinnerTimeout: 12_000,
+ }),
+ video,
+ ],
+ });
+ await plugged.setViewportSize({ width: 800, height: 600 });
+ await plugged.setContent(`
+
+
Dead air workflow
+
Ready
+
+
+
+ `);
+
+ await plugged.locator("#start").click();
+ await plugged.locator("#review").click();
+ await plugged.locator("#approve").click();
+ await video.deadAir(async () => {
+ await new Promise((resolve) => setTimeout(resolve, 1700));
+ });
+ await plugged.locator("#receipt").click();
+
+ await plugged.locator("#done").waitFor();
+ await expect(plugged.locator("#done")).toContainText("Receipt ready");
+ }
+
+ const metadata = JSON.parse(
+ await readFile(join(testInfo.outputDir, "video-mode.json"), "utf8"),
+ );
+ expect(metadata).toMatchObject({
+ outputs: {
+ deadAirRemoved: "video-tight.webm",
+ raw: "video-raw.webm",
+ },
+ });
+ expect(
+ metadata.deadAir.filter((span: { end: number; start: number }) => span.end - span.start >= 1500)
+ .length,
+ ).toBeGreaterThanOrEqual(4);
+
+ const rawPath = join(testInfo.outputDir, metadata.outputs.raw);
+ const tightPath = join(testInfo.outputDir, metadata.outputs.deadAirRemoved);
+ const rawStats = await stat(rawPath);
+ const tightStats = await stat(tightPath);
+ console.log(`raw video written to ${rawPath}`);
+ console.log(`tight video written to ${tightPath}`);
+
+ expect(rawStats.size).toBeGreaterThan(0);
+ expect(tightStats.size).toBeGreaterThan(0);
+
+ const rawDuration = await videoDurationMs(rawPath);
+ const tightDuration = await videoDurationMs(tightPath);
+ expect(tightDuration).toBeLessThan(rawDuration);
+});
+
+const videoDurationMs = async (path: string) => {
+ const { stdout } = await execFile(
+ "ffprobe",
+ ["-v", "error", "-show_entries", "format=duration", "-of", "default=nokey=1:noprint_wrappers=1", path],
+ { maxBuffer: 1024 * 1024 },
+ );
+
+ return Math.round(Number(stdout.trim()) * 1000);
+};
diff --git a/spec/video-mode.spec.ts b/spec/video-mode.spec.ts
index 740c21d..5d3f1ca 100644
--- a/spec/video-mode.spec.ts
+++ b/spec/video-mode.spec.ts
@@ -1,3 +1,5 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
import { test, expect } from "@playwright/test";
import { addPlugins, videoMode } from "../src/index.ts";
@@ -31,15 +33,152 @@ test("highlights the element while the action runs, then cleans up", async ({
});
test("skipped methods are not highlighted or slowed down", async ({ page }, testInfo) => {
+ const video = videoMode({ pauseBefore: 5000, pauseAfterTest: 50, skipMethods: ["click"] });
await using plugged = await addPlugins({
page,
testInfo,
- plugins: [videoMode({ pauseBefore: 5000, pauseAfterTest: 50, skipMethods: ["click"] })],
+ plugins: [video],
});
- await plugged.setContent(``);
+ await plugged.setContent(`
+
+ `);
const start = Date.now();
await plugged.locator("#btn").click();
// A 5s pauseBefore would blow way past this if click weren't skipped
expect(Date.now() - start).toBeLessThan(2000);
+ expect(video.metadata().deadAir.some((span) => span.end - span.start >= 100)).toBe(true);
+});
+
+test("marks pre-action waits for attachment as dead air", async ({ page }, testInfo) => {
+ const video = videoMode({ pauseBefore: 20, pauseAfterTest: 50 });
+ await using plugged = await addPlugins({
+ page,
+ testInfo,
+ plugins: [video],
+ });
+ await plugged.setContent(`
+
+
+ `);
+
+ await plugged.locator("#late").click();
+
+ await expect(plugged.locator("#result")).toContainText("clicked");
+ expect(video.metadata().deadAir).toContainEqual(
+ expect.objectContaining({
+ end: expect.any(Number),
+ start: expect.any(Number),
+ }),
+ );
+ expect(video.metadata().deadAir.some((span) => span.end - span.start >= 100)).toBe(true);
+});
+
+test("pre-action attached waits honor action timeout", async ({ page }, testInfo) => {
+ await using plugged = await addPlugins({
+ page,
+ testInfo,
+ plugins: [videoMode({ pauseBefore: 20, pauseAfterTest: 50 })],
+ });
+ await plugged.setContent(`
+
+ `);
+
+ const start = Date.now();
+ const error = await plugged.locator("#late").click({ timeout: 100 }).catch((e: Error) => e);
+
+ expect(Date.now() - start).toBeLessThan(250);
+ expect(error).toBeInstanceOf(Error);
+ expect(String(error)).toContain("Timeout 100ms exceeded");
+});
+
+test("marks explicit attached waitFor calls as dead air", async ({ page }, testInfo) => {
+ const video = videoMode({ pauseBefore: 20, pauseAfterTest: 50 });
+ await using plugged = await addPlugins({
+ page,
+ testInfo,
+ plugins: [video],
+ });
+ await plugged.setContent(`
+
+ `);
+
+ await plugged.locator("#late").waitFor({ state: "attached" });
+
+ expect(video.metadata().deadAir.some((span) => span.end - span.start >= 100)).toBe(true);
+});
+
+test("deadAir runs actions without video highlighting and records metadata", async ({
+ page,
+}, testInfo) => {
+ const video = videoMode({ pauseBefore: 5000, pauseAfterTest: 50 });
+ {
+ await using plugged = await addPlugins({
+ page,
+ testInfo,
+ plugins: [video],
+ });
+
+ await plugged.setContent(`
+
+
+
+ `);
+
+ const start = Date.now();
+ await video.deadAir(async () => {
+ await new Promise((resolve) => setTimeout(resolve, 20));
+ await plugged.locator("#btn").click();
+ });
+
+ expect(Date.now() - start).toBeLessThan(2000);
+ await expect(plugged.locator("#result")).toContainText("(no style)");
+ expect(video.metadata()).toMatchObject({
+ outputs: {},
+ schemaVersion: 1,
+ timebase: "ms",
+ });
+ expect(video.metadata().deadAir).toContainEqual(
+ expect.objectContaining({ end: expect.any(Number), start: expect.any(Number) }),
+ );
+ }
+
+ const metadata = JSON.parse(
+ await readFile(join(testInfo.outputDir, "video-mode.json"), "utf8"),
+ );
+ expect(metadata).toMatchObject({
+ outputs: {},
+ schemaVersion: 1,
+ timebase: "ms",
+ });
+ expect(metadata.deadAir).toContainEqual(
+ expect.objectContaining({ end: expect.any(Number), start: expect.any(Number) }),
+ );
+ expect(metadata.deadAir[0].end).toBeGreaterThan(metadata.deadAir[0].start);
});
diff --git a/src/index.ts b/src/index.ts
index 884601f..5017322 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -6,6 +6,8 @@ export {
type Plugin,
type ActionContext,
type ActionMiddleware,
+ type ActionMiddlewareTiming,
+ type ActionTiming,
type NextFn,
type TestLifecycleEvents,
type LocatorWithOriginal,
diff --git a/src/plugin-system.ts b/src/plugin-system.ts
index 3cc6ccc..9013691 100644
--- a/src/plugin-system.ts
+++ b/src/plugin-system.ts
@@ -71,6 +71,20 @@ 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 */
@@ -95,12 +109,17 @@ export type Plugin = {
const PLUGIN_STATE = Symbol("playwrightPluginState");
type PluginState = {
- actionMiddlewares: ActionMiddleware[];
+ actionMiddlewares: RegisteredActionMiddleware[];
lifecycleEmitter: Emittery;
lifecycleCleanups: (() => void)[];
testInfo: TestInfo;
};
+type RegisteredActionMiddleware = {
+ name: string;
+ middleware: ActionMiddleware;
+};
+
type PageWithPlugins = Page & {
[PLUGIN_STATE]: PluginState;
[Symbol.asyncDispose]: () => Promise;
@@ -153,7 +172,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) {
@@ -214,6 +236,47 @@ 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 | undefined;
+
+ const poll = async () => {
+ if (stopped || timing.attachedAt !== undefined) {
+ return;
+ }
+
+ if (await locatorIsAttached(locator)) {
+ 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,
@@ -261,6 +324,17 @@ const patchLocatorPrototype = (
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 +342,33 @@ 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 () => {
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 });
diff --git a/src/plugins/index.ts b/src/plugins/index.ts
index 6ab1545..c79d292 100644
--- a/src/plugins/index.ts
+++ b/src/plugins/index.ts
@@ -1,5 +1,12 @@
export { hydrationWaiter, type HydrationWaiterOptions } from "./hydration-waiter.ts";
-export { videoMode, type VideoModeOptions } from "./video-mode.ts";
+export {
+ videoMode,
+ type VideoModeMetadata,
+ type VideoModeOptions,
+ type VideoModeOutputs,
+ type VideoModePlugin,
+ type VideoModeSpan,
+} from "./video-mode.ts";
export { spinnerWaiter, type SpinnerWaiterOptions, defaultSelectors } from "./spinner-waiter.ts";
export { uiErrorReporter, type UIErrorReporterOptions } from "./ui-error-reporter.ts";
export {
diff --git a/src/plugins/video-mode.ts b/src/plugins/video-mode.ts
index af2fde6..cc03f6b 100644
--- a/src/plugins/video-mode.ts
+++ b/src/plugins/video-mode.ts
@@ -6,9 +6,42 @@
* original: the hardcoded skip for iterate's test-helpers file is now the
* `skipStackFrames` option.
*/
+import { execFile as execFileCallback } from "node:child_process";
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { promisify } from "node:util";
import type { Locator } from "@playwright/test";
import type { Plugin, OverrideableMethod } from "../plugin-system.ts";
+const execFile = promisify(execFileCallback);
+
+export type VideoModeSpan = {
+ start: number;
+ end: number;
+};
+
+export type VideoModeOutputs = {
+ raw?: string;
+ deadAirRemoved?: string;
+};
+
+export type VideoModeMetadata = {
+ schemaVersion: 1;
+ timebase: "ms";
+ deadAir: VideoModeSpan[];
+ outputs: VideoModeOutputs;
+};
+
+export type VideoModePlugin = Plugin & {
+ /**
+ * Run invisible video bookkeeping without video-mode highlighting/pauses,
+ * and write the elapsed span to video-mode metadata.
+ */
+ deadAir(action: () => Promise): Promise;
+ /** Current metadata snapshot. Written to video-mode.json after the test. */
+ metadata(): VideoModeMetadata;
+};
+
export type VideoModeOptions = {
/** Pause duration before action (ms). Default: 1000 */
pauseBefore?: number;
@@ -26,8 +59,26 @@ export type VideoModeOptions = {
skipStackFrames?: string[];
};
+type VideoModeState = {
+ deadAirDepth: number;
+ deadAirSpans: VideoModeSpan[];
+ outputs: VideoModeOutputs;
+ startedAt?: number;
+};
+
+type TightVideoSegment = {
+ start: number;
+ end: number;
+};
+
/** Highlight element, pause, return disposable that unhighlights */
const setupHighlight = async (locator: Locator, style: string, pauseMs: number) => {
+ if (!(await locatorIsAttached(locator))) {
+ return {
+ [Symbol.dispose]: () => {},
+ };
+ }
+
try {
await locator.evaluate((el, s) => {
const prev = el.getAttribute("style") || "";
@@ -60,22 +111,278 @@ const setupHighlight = async (locator: Locator, style: string, pauseMs: number)
};
};
+const metadataFor = (state: VideoModeState): VideoModeMetadata => {
+ return {
+ deadAir: mergeVideoSpans(state.deadAirSpans),
+ outputs: state.outputs,
+ schemaVersion: 1,
+ timebase: "ms",
+ };
+};
+
+const recordDeadAir = async (state: VideoModeState, action: () => Promise) => {
+ if (!state.startedAt || state.deadAirDepth > 0) {
+ return await action();
+ }
+
+ const start = performance.now() - state.startedAt;
+ state.deadAirDepth += 1;
+
+ try {
+ return await action();
+ } finally {
+ state.deadAirDepth -= 1;
+ const end = performance.now() - state.startedAt;
+ state.deadAirSpans.push({
+ end: Math.round(end),
+ start: Math.round(start),
+ });
+ }
+};
+
+const mergeVideoSpans = (spans: VideoModeSpan[]) => {
+ const sorted = spans
+ .map((span) => ({
+ end: Math.round(span.end),
+ start: Math.round(span.start),
+ }))
+ .filter((span) => span.end > span.start)
+ .sort((left, right) => left.start - right.start || left.end - right.end);
+
+ const merged: VideoModeSpan[] = [];
+
+ for (const span of sorted) {
+ const previous = merged[merged.length - 1];
+
+ if (previous && span.start <= previous.end) {
+ previous.end = Math.max(previous.end, span.end);
+ continue;
+ }
+
+ merged.push(span);
+ }
+
+ return merged;
+};
+
+const formatSeconds = (ms: number) => {
+ const value = (ms / 1000).toFixed(3).replace(/\.?0+$/, "");
+ return value || "0";
+};
+
+const clipVideoSpan = (span: VideoModeSpan, finalEnd: number): VideoModeSpan | undefined => {
+ const start = Math.max(0, Math.min(Math.round(span.start), finalEnd));
+ const end = Math.max(0, Math.min(Math.round(span.end), finalEnd));
+
+ if (end <= start) {
+ return undefined;
+ }
+
+ return { end, start };
+};
+
+const videoSpansOverlap = (left: VideoModeSpan, right: VideoModeSpan) => {
+ return left.start < right.end && right.start < left.end;
+};
+
+const locatorIsAttached = async (locator: Locator) => {
+ try {
+ return (await locator.count()) > 0;
+ } catch {
+ return false;
+ }
+};
+
+const waitForTargetsAttached = (args: unknown[]) => {
+ const targetState = (args[0] as { state?: string } | undefined)?.state;
+ return !targetState || targetState === "attached";
+};
+
+const recordAttachedWaitFromTiming = async (
+ state: VideoModeState,
+ timing: { actionStartedAt: number; attachedAt?: number; attachedAtStart: boolean },
+ locator: Locator,
+) => {
+ if (!state.startedAt || timing.attachedAtStart) {
+ return;
+ }
+
+ if (timing.attachedAt === undefined && (await locatorIsAttached(locator))) {
+ timing.attachedAt = performance.now();
+ }
+
+ if (timing.attachedAt === undefined) {
+ return;
+ }
+
+ const start = Math.round(timing.actionStartedAt - state.startedAt);
+ const end = Math.round(timing.attachedAt - state.startedAt);
+
+ if (end > start) {
+ state.deadAirSpans.push({ end, start });
+ }
+};
+
+const tightVideoSegments = (options: {
+ deadAir: VideoModeSpan[];
+ finalEnd: number;
+}): TightVideoSegment[] => {
+ const finalEnd = Math.max(0, Math.round(options.finalEnd));
+
+ if (finalEnd === 0) {
+ return [];
+ }
+
+ const deadAir = mergeVideoSpans(
+ options.deadAir
+ .map((span) => clipVideoSpan(span, finalEnd))
+ .filter((span): span is VideoModeSpan => Boolean(span)),
+ );
+ const boundaries = new Set([0, finalEnd]);
+
+ for (const span of deadAir) {
+ boundaries.add(span.start);
+ boundaries.add(span.end);
+ }
+
+ const sortedBoundaries = [...boundaries].sort((left, right) => left - right);
+ const segments: TightVideoSegment[] = [];
+
+ for (let index = 0; index < sortedBoundaries.length - 1; index += 1) {
+ const start = sortedBoundaries[index];
+ const end = sortedBoundaries[index + 1];
+
+ if (end <= start) {
+ continue;
+ }
+
+ if (deadAir.some((span) => videoSpansOverlap(span, { end, start }))) {
+ continue;
+ }
+
+ const previous = segments[segments.length - 1];
+
+ if (previous && previous.end === start) {
+ previous.end = end;
+ continue;
+ }
+
+ segments.push({ end, start });
+ }
+
+ return segments;
+};
+
+const tightVideoFilter = (options: {
+ deadAir: VideoModeSpan[];
+ finalEnd: number;
+}) => {
+ const segments = tightVideoSegments(options);
+
+ if (
+ segments.length === 0 ||
+ (segments.length === 1 &&
+ segments[0].start === 0 &&
+ segments[0].end === Math.round(options.finalEnd))
+ ) {
+ return undefined;
+ }
+
+ const filters: string[] = [];
+ const labels: string[] = [];
+
+ for (let index = 0; index < segments.length; index += 1) {
+ const segment = segments[index];
+ const label = `tight${index}`;
+ labels.push(`[${label}]`);
+ filters.push(
+ `[0:v]trim=start=${formatSeconds(segment.start)}:end=${formatSeconds(segment.end)},setpts=PTS-STARTPTS[${label}]`,
+ );
+ }
+
+ const outputLabel = labels.length === 1 ? labels[0].slice(1, -1) : "tightout";
+
+ if (labels.length > 1) {
+ filters.push(`${labels.join("")}concat=n=${labels.length}:v=1:a=0[${outputLabel}]`);
+ }
+
+ return {
+ outputLabel,
+ value: filters.join(";"),
+ };
+};
+
+const videoDurationMs = async (path: string) => {
+ const { stdout } = await execFile(
+ "ffprobe",
+ ["-v", "error", "-show_entries", "format=duration", "-of", "default=nokey=1:noprint_wrappers=1", path],
+ { maxBuffer: 1024 * 1024 },
+ );
+ const seconds = Number(stdout.trim());
+
+ if (!Number.isFinite(seconds) || seconds <= 0) {
+ throw new Error(`Could not read video duration from ffprobe output: ${stdout}`);
+ }
+
+ return Math.round(seconds * 1000);
+};
+
+const removeDeadAirFromVideo = async (options: {
+ inputPath: string;
+ outputPath: string;
+ deadAir: VideoModeSpan[];
+}) => {
+ const finalEnd = await videoDurationMs(options.inputPath);
+ const filter = tightVideoFilter({
+ deadAir: options.deadAir,
+ finalEnd,
+ });
+
+ if (!filter) {
+ return false;
+ }
+
+ await execFile(
+ "ffmpeg",
+ [
+ "-y",
+ "-i",
+ options.inputPath,
+ "-filter_complex",
+ filter.value,
+ "-map",
+ `[${filter.outputLabel}]`,
+ "-an",
+ options.outputPath,
+ ],
+ { maxBuffer: 10 * 1024 * 1024 },
+ );
+
+ return true;
+};
+
/**
* Highlights elements before actions and pauses for video recording.
* Also pauses after tests complete for better video endings.
*/
-export const videoMode = (options: VideoModeOptions = {}): Plugin => {
+export const videoMode = (options: VideoModeOptions = {}): VideoModePlugin => {
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 || [];
+ const state: VideoModeState = {
+ deadAirDepth: 0,
+ deadAirSpans: [],
+ outputs: {},
+ startedAt: performance.now(),
+ };
return {
name: "video-mode",
- middleware: async ({ locator, method }, next) => {
- if (skipMethods.includes(method)) return next();
+ middleware: async ({ args, locator, method, timing }, next) => {
+ if (state.deadAirDepth > 0) return next();
// Skip if called from internal helpers (navigation, login flows etc)
if (skipStackFrames.length > 0) {
@@ -83,15 +390,114 @@ export const videoMode = (options: VideoModeOptions = {}): Plugin => {
if (skipStackFrames.some((frame) => stack.includes(frame))) return next();
}
- using _ = await setupHighlight(locator, highlightStyle, pauseBefore);
- return await next();
+ if (method === "waitFor") {
+ if (!waitForTargetsAttached(args)) {
+ return next();
+ }
+ try {
+ return await next();
+ } finally {
+ await recordAttachedWaitFromTiming(state, timing, locator);
+ }
+ }
+
+ if (skipMethods.includes(method)) {
+ try {
+ return await next();
+ } finally {
+ await recordAttachedWaitFromTiming(state, timing, locator);
+ }
+ }
+
+ try {
+ using _ = await setupHighlight(locator, highlightStyle, pauseBefore);
+ return await next();
+ } finally {
+ await recordAttachedWaitFromTiming(state, timing, locator);
+ }
+ },
+
+ deadAir: async (action) => {
+ return await recordDeadAir(state, action);
},
+ metadata: () => metadataFor(state),
+
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`);
+ const offBeforeTest = emitter.on("beforeTest", () => {
+ state.deadAirDepth = 0;
+ state.deadAirSpans = [];
+ state.outputs = {};
+ if (state.startedAt) {
+ state.deadAirSpans.push({
+ end: Math.round(performance.now() - state.startedAt),
+ start: 0,
+ });
+ } else {
+ state.startedAt = performance.now();
+ }
});
+
+ const offAfterTest = emitter.on("afterTest", async ({ page, testInfo }) => {
+ await recordDeadAir(state, async () => {
+ await new Promise((resolve) => setTimeout(resolve, pauseAfterTest));
+ });
+
+ const deadAir = metadataFor(state).deadAir;
+ const video = page.video();
+
+ if (video) {
+ const rawPath = join(testInfo.outputDir, "video-raw.webm");
+ const tightPath = join(testInfo.outputDir, "video-tight.webm");
+ await mkdir(testInfo.outputDir, { recursive: true });
+
+ if (!page.isClosed()) {
+ await page.close({ runBeforeUnload: false });
+ }
+
+ await video.saveAs(rawPath);
+ state.outputs.raw = "video-raw.webm";
+ await testInfo.attach("video-raw", {
+ contentType: "video/webm",
+ path: rawPath,
+ });
+
+ if (deadAir.length > 0) {
+ const wroteTightVideo = await removeDeadAirFromVideo({
+ deadAir,
+ inputPath: rawPath,
+ outputPath: tightPath,
+ });
+
+ if (wroteTightVideo) {
+ state.outputs.deadAirRemoved = "video-tight.webm";
+ await testInfo.attach("video-tight", {
+ contentType: "video/webm",
+ path: tightPath,
+ });
+ }
+ }
+ }
+
+ const metadata = metadataFor(state);
+ if (metadata.deadAir.length > 0) {
+ const path = join(testInfo.outputDir, "video-mode.json");
+ await mkdir(testInfo.outputDir, { recursive: true });
+ await writeFile(path, `${JSON.stringify(metadata, null, 2)}\n`);
+ await testInfo.attach("video-mode", {
+ contentType: "application/json",
+ path,
+ });
+ }
+
+ state.startedAt = undefined;
+ console.log(`video-mode metadata written to ${testInfo.outputDir}/video-mode.json`);
+ });
+
+ return () => {
+ offBeforeTest();
+ offAfterTest();
+ };
},
};
};
From 83a0424bbc380863b8dca32aa9fdc310b8e0f398 Mon Sep 17 00:00:00 2001
From: Misha Kaletsky <15040698+mmkal@users.noreply.github.com>
Date: Mon, 22 Jun 2026 12:42:35 +0100
Subject: [PATCH 03/35] Improve video-mode dead-air trimming
Teach spinnerWaiter to treat visible-but-disabled targets as not ready for click-like actions, so spinner-backed disabled buttons get the longer spinner wait instead of timing out at the action timeout.
Record elapsed middleware time before videoMode as dead air, which keeps spinnerWaiter independent while still trimming readiness waits from tight videos. Keep a short final visible hold before trimming after-test padding so the final result remains visible in the tight cut.
Update the ffmpeg video spec to use always-rendered disabled stage buttons, assert the final hold, and keep README guidance aligned with the plugin ordering behavior.
---
README.md | 4 +-
spec/spinner-waiter.spec.ts | 21 +++++++
spec/video-mode-ffmpeg.spec.ts | 102 +++++++++++++++++----------------
src/plugins/spinner-waiter.ts | 52 +++++++++++------
src/plugins/video-mode.ts | 71 +++++++++++++++++++++--
5 files changed, 176 insertions(+), 74 deletions(-)
diff --git a/README.md b/README.md
index b6eb45a..34d3c87 100644
--- a/README.md
+++ b/README.md
@@ -130,7 +130,7 @@ uiErrorReporter({ selector: '[data-type="error"]' });
### videoMode
-For producing demo/debugging videos people can actually follow: waits for the target element to become attached as dead air, outlines the element in gold, pauses before each action, and pauses after the test as dead air so the final cut doesn't keep teardown padding. Enable it conditionally (e.g. `!!process.env.VIDEO_MODE && videoMode()`) together with Playwright's `video: "on"` and a generous `actionTimeout`.
+For producing demo/debugging videos people can actually follow: marks pre-action waiting as dead air, outlines the element in gold, pauses before each action, and keeps a short final hold before trimming after-test padding as dead air. Enable it conditionally (e.g. `!!process.env.VIDEO_MODE && videoMode()`) together with Playwright's `video: "on"` and a generous `actionTimeout`.
```ts
const video = videoMode({
@@ -151,7 +151,7 @@ await video.deadAir(async () => {
When Playwright video recording is enabled, `videoMode` saves `video-raw.webm`, uses `ffmpeg` to write `video-tight.webm` with dead air removed, and attaches both videos plus `video-mode.json` to the test report. If `ffmpeg` or `ffprobe` is missing, the trim step fails plainly so you know to install ffmpeg.
-Put `spinnerWaiter` before `videoMode` when you use both. Spinner-waiter still owns spinner-specific waiting and errors, while video-mode observes the pre-action "wait for attached" period as dead air and highlights immediately before the action.
+Put `spinnerWaiter` before `videoMode` when you use both. Spinner-waiter still owns spinner-specific waiting and errors, while video-mode records the preceding middleware wait as dead air and highlights immediately before the action.
### llmRecover
diff --git a/spec/spinner-waiter.spec.ts b/spec/spinner-waiter.spec.ts
index 6833297..c9c3208 100644
--- a/spec/spinner-waiter.spec.ts
+++ b/spec/spinner-waiter.spec.ts
@@ -30,6 +30,27 @@ test("slow button succeeds when there's a spinner", async ({ page }) => {
await page.getByText("work done").waitFor();
});
+test("visible disabled button succeeds when there's a spinner", async ({ page }) => {
+ await page.setContent(`
+
+