From 32549cb3f535ca61bb8441b790531116b047fe88 Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Sat, 21 Nov 2026 12:04:53 -0500 Subject: [PATCH] test(web): consolidate attached emulation and CDP admission checks (#13156) --- src/browser/PlaywrightCdpSession.test.ts | 118 +++--- src/browser/PlaywrightScenarioBrowser.test.ts | 377 ++++++++---------- 2 files changed, 213 insertions(+), 282 deletions(-) diff --git a/src/browser/PlaywrightCdpSession.test.ts b/src/browser/PlaywrightCdpSession.test.ts index b438d4cdfa..805cfbcf6d 100644 --- a/src/browser/PlaywrightCdpSession.test.ts +++ b/src/browser/PlaywrightCdpSession.test.ts @@ -1,84 +1,62 @@ import { EventEmitter } from "node:events"; -import type { BrowserContext, CDPSession, Page } from "playwright-core"; -import { describe, expect, it, vi } from "vitest"; +import type { CDPSession, Page } from "playwright-core"; +import { expect, it, vi } from "vitest"; import { newPlaywrightCdpSession } from "./PlaywrightCdpSession.js"; -const fakeSession = (): EventEmitter & { - send: ReturnType; - detach: ReturnType; -} => - Object.assign(new EventEmitter(), { +const open = async () => { + const raw = Object.assign(new EventEmitter(), { send: vi.fn(async () => ({})), - detach: vi.fn(async () => undefined), }); + const session = await newPlaywrightCdpSession( + { newCDPSession: async () => raw as unknown as CDPSession }, + {} as Page, + "capture_browser_scenario", + ); + return { raw, session }; +}; -describe("Playwright CDP session event relay", () => { - it("keeps a listener failure inside the session and rejects later commands with it", async () => { - const raw = fakeSession(); - const session = await newPlaywrightCdpSession( - { - newCDPSession: async () => raw as unknown as CDPSession, - } as Pick, - {} as Page, - "capture_browser_scenario", - ); - const listenerFailure = new Error("listener rejected a malformed event"); - const listener = vi.fn(() => { - throw listenerFailure; - }); - session.on("Runtime.executionContextsCleared", listener); - - // Playwright emits from its connection callback; nothing may escape here. - expect(() => - raw.emit("Runtime.executionContextsCleared", {}), - ).not.toThrow(); - raw.emit("Runtime.executionContextsCleared", {}); - - expect(listener).toHaveBeenCalledTimes(1); - await expect(session.send("Page.enable")).rejects.toMatchObject({ - _tag: "BrowserObservationError", - reason: "protocol_error", - cause: listenerFailure, - }); - expect(raw.send).not.toHaveBeenCalled(); +it("keeps a listener failure inside the session and rejects later commands with it", async () => { + const { raw, session } = await open(); + const listenerFailure = new Error("listener rejected a valid event"); + const listener = vi.fn(() => { + throw listenerFailure; }); + session.on("Runtime.executionContextsCleared", listener); + + // Playwright emits from its connection callback; nothing may escape here. + raw.emit("Runtime.executionContextsCleared", {}); + raw.emit("Runtime.executionContextsCleared", {}); + + expect(listener).toHaveBeenCalledOnce(); + const failure = await session + .send("Page.enable") + .catch((cause: unknown) => cause); + expect(failure).toMatchObject({ + _tag: "BrowserObservationError", + reason: "protocol_error", + }); + expect(failure).toHaveProperty("cause", listenerFailure); + expect(raw.send).not.toHaveBeenCalled(); }); -// JavaScript verifiers can name any command or event; the session refuses an -// unregistered one before it reaches the browser or subscribes. -describe("Playwright CDP session registry", () => { - const open = async () => { - const raw = fakeSession(); - const session = await newPlaywrightCdpSession( - { - newCDPSession: async () => raw as unknown as CDPSession, - } as Pick, - {} as Page, - "capture_browser_scenario", - ); - return { raw, session }; - }; - - it("refuses an unregistered command without sending it", async () => { - const { raw, session } = await open(); - await expect( - // @ts-expect-error This protocol command has no registered result schema. - session.send("Accessibility.getPartialAXTree"), - ).rejects.toMatchObject({ - _tag: "BrowserObservationError", - reason: "protocol_error", - }); - expect(raw.send).not.toHaveBeenCalled(); +it("refuses unregistered commands and events before they reach Playwright", async () => { + const { raw, session } = await open(); + await expect( + // @ts-expect-error This protocol command has no registered result schema. + session.send("Accessibility.getPartialAXTree"), + ).rejects.toMatchObject({ + _tag: "BrowserObservationError", + reason: "protocol_error", }); + expect(raw.send).not.toHaveBeenCalled(); + expect(() => + // @ts-expect-error This protocol event has no registered payload schema. + session.on("Network.dataReceived", () => undefined), + ).toThrow(expect.objectContaining({ reason: "protocol_error" })); + expect(raw.listenerCount("Network.dataReceived")).toBe(0); - it("refuses an unregistered event without subscribing", async () => { - const { raw, session } = await open(); - expect(() => - // @ts-expect-error This protocol event has no registered payload schema. - session.on("Network.dataReceived", () => undefined), - ).toThrow(expect.objectContaining({ reason: "protocol_error" })); - expect(raw.listenerCount("Network.dataReceived")).toBe(0); - }); + await expect(session.send("Page.enable")).resolves.toEqual({}); + expect(raw.send).toHaveBeenCalledExactlyOnceWith("Page.enable", undefined); }); diff --git a/src/browser/PlaywrightScenarioBrowser.test.ts b/src/browser/PlaywrightScenarioBrowser.test.ts index cd2533877d..3c20e9f913 100644 --- a/src/browser/PlaywrightScenarioBrowser.test.ts +++ b/src/browser/PlaywrightScenarioBrowser.test.ts @@ -498,6 +498,7 @@ const attachedBrowserFixture = ( readonly isTargetClosed?: () => boolean; readonly isBrowserConnected?: () => boolean; } = {}, + commandTimeoutMs?: number, ) => { const discoverySession = { send: vi.fn(async () => ({ targetInfo: { targetId: "page-1" } })), @@ -539,6 +540,9 @@ const attachedBrowserFixture = ( }, start_url: { url: "https://example.test" }, actions: [{ step_id: "wait", action: "wait_for_timeout", duration_ms: 1 }], + ...(commandTimeoutMs === undefined + ? {} + : { command_timeout_ms: commandTimeoutMs }), }); return { browser, @@ -711,133 +715,176 @@ it.each(["locale", "focus"] as const)( }, ); -it("does not clear an attached environment override it failed to acquire", async () => { - const fixture = attachedBrowserFixture({ - send: async (method, parameters) => { - if ( - method === "Emulation.setLocaleOverride" && - (parameters as { locale?: string }).locale === "en-US" - ) - throw new Error("caller already owns locale"); - }, - }); - - await expect(fixture.open()).rejects.toThrow("caller already owns locale"); - expect(fixture.environmentSession.send).not.toHaveBeenCalledWith( - "Emulation.setLocaleOverride", - { locale: "" }, - ); - expect(fixture.environmentSession.send).toHaveBeenCalledWith( - "Emulation.clearDeviceMetricsOverride", - undefined, - ); - expect(fixture.environmentSession.detach).toHaveBeenCalledOnce(); - expect(fixture.browser.close).toHaveBeenCalledOnce(); -}); - -it("restores an attached environment override whose success reply is malformed", async () => { - const fixture = attachedBrowserFixture({ - send: async (method, parameters) => { - if ( - method === "Emulation.setLocaleOverride" && - (parameters as { locale?: string }).locale === "en-US" - ) +it.each(["rejected", "malformed acknowledgement"] as const)( + "restores only acquired overrides when locale application returns %s", + async (outcome) => { + const localeFailure = new Error("caller already owns locale"); + const fixture = attachedBrowserFixture({ + send: async (method, parameters) => { + if ( + method !== "Emulation.setLocaleOverride" || + (parameters as { locale?: string }).locale !== "en-US" + ) + return; + if (outcome === "rejected") throw localeFailure; return "applied"; - return undefined; - }, - }); - - await expect(fixture.open()).rejects.toMatchObject({ - reason: "protocol_error", - }); - expect(fixture.environmentSession.send).toHaveBeenCalledWith( - "Emulation.setLocaleOverride", - { locale: "" }, - ); - expect(fixture.environmentSession.detach).toHaveBeenCalledOnce(); -}); - -it("waits for a cancelled environment mutation before restoring it", async () => { - const localeMutation = phaseGate(); - const fixture = attachedBrowserFixture({ - send: async (method, parameters) => { - if ( - method === "Emulation.setLocaleOverride" && - (parameters as { locale?: string }).locale === "en-US" - ) { - await localeMutation.hold(); - } - }, - }); - const controller = new AbortController(); - const opening = fixture.open(controller.signal); - try { - await localeMutation.reached(opening, "locale mutation"); - const cancelled = expect(opening).rejects.toMatchObject({ - _tag: "AnalysisCancelledError", + }, }); - controller.abort(); - await new Promise((resolve) => setImmediate(resolve)); - expect(fixture.environmentSession.send).not.toHaveBeenCalledWith( - "Emulation.setLocaleOverride", - { locale: "" }, + const result = await fixture.open().then( + (opened) => ({ opened }), + (failure: unknown) => ({ failure }), ); - - localeMutation.release(); - await cancelled; - expect(fixture.environmentSession.send).toHaveBeenCalledWith( - "Emulation.setLocaleOverride", - { locale: "" }, + if ("opened" in result) { + await result.opened.cleanup.close(); + throw new Error("Expected locale acquisition failure"); + } + const { failure } = result; + if (outcome === "rejected") expect(failure).toBe(localeFailure); + else expect(failure).toMatchObject({ reason: "protocol_error" }); + expect( + vi.mocked(fixture.environmentSession.send).mock.calls.slice(2), + ).toEqual( + outcome === "rejected" + ? [["Emulation.clearDeviceMetricsOverride", undefined]] + : [ + ["Emulation.setLocaleOverride", { locale: "" }], + ["Emulation.clearDeviceMetricsOverride", undefined], + ], ); expect(fixture.environmentSession.detach).toHaveBeenCalledOnce(); expect(fixture.browser.close).toHaveBeenCalledOnce(); - } finally { - controller.abort(); - localeMutation.release(); - const opened = await opening.catch(() => undefined); - await opened?.cleanup.close(); - } -}); + }, +); -it("releases cleanup ownership when the attached target is destroyed", async () => { - let targetClosed = false; - const fixture = attachedBrowserFixture({ - send: async (method, parameters) => { - if ( - targetClosed && - method === "Emulation.setTimezoneOverride" && - (parameters as { timezoneId?: string }).timezoneId === "" - ) - throw new Error("Target closed"); - }, - isTargetClosed: () => targetClosed, - }); - const opened = await fixture.open(); - targetClosed = true; +it.each([ + { + mutation: "locale", + method: "Emulation.setLocaleOverride", + stop: "cancellation", + }, + { mutation: "media", method: "Emulation.setEmulatedMedia", stop: "deadline" }, + { + mutation: "focus", + method: "Emulation.setFocusEmulationEnabled", + stop: "deadline", + }, +] as const)( + "joins a pending $mutation acknowledgement after $stop before restoring it", + async ({ mutation, method, stop }) => { + const pending = phaseGate(); + const progress: string[] = []; + const restoreOrHold = async (reset: boolean) => { + if (reset) progress.push("restored"); + else { + await pending.hold(); + progress.push("acknowledged"); + } + }; + const fixture = attachedBrowserFixture( + { + send: async (command, parameters) => { + if (command !== method) return; + const options = parameters as { locale?: string; enabled?: boolean }; + await restoreOrHold( + options.locale === "" || options.enabled === false, + ); + }, + emulateMedia: async (options) => { + if (mutation === "media") + await restoreOrHold(options?.colorScheme === null); + }, + detach: async () => { + progress.push("detached"); + }, + closeBrowser: async () => { + progress.push("disconnected"); + }, + }, + 40, + ); + vi.useFakeTimers(); + const caller = new AbortController(); + const reason = new Error("cancel while applying locale"); + const observed = vi.fn(); + const opening = fixture.open(caller.signal); + void opening.then(observed, observed); + try { + await pending.reached(opening, method); + if (stop === "cancellation") caller.abort(reason); + await vi.advanceTimersByTimeAsync(stop === "deadline" ? 40 : 0); + expect(observed).not.toHaveBeenCalled(); + expect(progress).toEqual([]); - await opened.cleanup.close(); - expect(fixture.browser.close).toHaveBeenCalledOnce(); -}); + pending.release(); + const failure = await opening.catch((cause: unknown) => cause); + if (stop === "deadline") + expect(failure).toMatchObject({ + reason: "timeout", + diagnostics: { phase: "command", command_timeout_ms: 40, method }, + }); + else { + expect(failure).toBeInstanceOf(AnalysisCancelledError); + expect(failure).toHaveProperty("cause", reason); + } + expect(progress).toEqual([ + "acknowledged", + "restored", + "detached", + "disconnected", + ]); + const commands = vi + .mocked(fixture.environmentSession.send) + .mock.calls.map(([name]) => name); + expect( + commands.filter( + (name) => name === "Emulation.clearDeviceMetricsOverride", + ), + ).toHaveLength(mutation === "media" ? 0 : 1); + if (mutation === "locale") + expect(commands).not.toContain("Emulation.setTimezoneOverride"); + } finally { + caller.abort(reason); + pending.release(); + try { + const opened = await opening.catch(() => undefined); + await opened?.cleanup.close(); + } finally { + vi.useRealTimers(); + } + } + }, +); -it("releases cleanup ownership when the attached browser disconnects", async () => { - let connected = true; - const fixture = attachedBrowserFixture({ - send: async (method, parameters) => { - if ( - !connected && - method === "Emulation.setTimezoneOverride" && - (parameters as { timezoneId?: string }).timezoneId === "" - ) - throw new Error("Browser disconnected"); - }, - isBrowserConnected: () => connected, - }); - const opened = await fixture.open(); - connected = false; - - await opened.cleanup.close(); - expect(fixture.browser.close).not.toHaveBeenCalled(); -}); +it.each(["target destroyed", "browser disconnected"] as const)( + "releases attached ownership once the %s", + async (loss) => { + let lost = false; + const fixture = attachedBrowserFixture({ + send: async (method, parameters) => { + if ( + lost && + method === "Emulation.setTimezoneOverride" && + (parameters as { timezoneId?: string }).timezoneId === "" + ) + throw new Error(loss); + }, + isTargetClosed: () => lost && loss === "target destroyed", + isBrowserConnected: () => !lost || loss !== "browser disconnected", + }); + const opened = await fixture.open(); + try { + lost = true; + await opened.cleanup.close(); + expect(opened.cleanup.cleanupResources).toEqual([]); + expect(fixture.browser.close).toHaveBeenCalledTimes( + loss === "target destroyed" ? 1 : 0, + ); + } finally { + lost = false; + await opened.cleanup.close(); + } + }, +); it("cancels same-target queued connection before acquiring a browser", async () => { const makeScenario = (targetId: string) => @@ -1441,100 +1488,6 @@ it("closes a browser that connects after its deadline without waiting to report } }); -it.each(["media", "focus"] as const)( - "restores a late %s mutation after its deadline", - async (mutation) => { - let restored = false; - const scenario = browserScenarioSchema.parse({ - browser: { - mode: "connect", - cdp_endpoint: "http://127.0.0.1:9222", - target_id: "late-environment-target", - }, - start_url: { url: "https://example.test" }, - environment: { service_workers: "allow" }, - command_timeout_ms: 40, - actions: scenarioActions, - }); - const discoverySession = { - send: vi.fn(async () => ({ - targetInfo: { targetId: "late-environment-target" }, - })), - detach: vi.fn(async () => undefined), - } as unknown as CDPSession; - const environmentSession = { - send: vi.fn( - async (method: string, parameters?: { enabled?: boolean }) => { - if (method !== "Emulation.setFocusEmulationEnabled") return {}; - if (parameters?.enabled === false) { - if (mutation === "focus") restored = true; - } else if (mutation === "focus") - await new Promise((resolve) => setTimeout(resolve, 80)); - return {}; - }, - ), - detach: vi.fn(async () => undefined), - } as unknown as CDPSession; - const page = { - emulateMedia: vi.fn(async (options: { colorScheme?: string | null }) => { - if (options.colorScheme === null) { - if (mutation === "media") restored = true; - return; - } - if (mutation === "media") - await new Promise((resolve) => setTimeout(resolve, 80)); - }), - isClosed: vi.fn(() => false), - } as unknown as Page; - const context = { - pages: () => [page], - newCDPSession: vi - .fn() - .mockResolvedValueOnce(discoverySession) - .mockResolvedValueOnce(environmentSession), - } as unknown as BrowserContext; - const browser = { - close: vi.fn(async () => undefined), - contexts: () => [context], - isConnected: vi.fn(() => true), - version: () => "late-environment", - }; - await expect( - openPlaywrightScenarioBrowser( - scenario, - {}, - { - launcher: { - connectOverCDP: async () => browser, - launchPersistentContext: async () => { - throw new Error("Unexpected launch"); - }, - }, - }, - ), - ).rejects.toMatchObject({ - reason: "timeout", - userMessage: expect.stringContaining( - mutation === "media" - ? "Emulation.setEmulatedMedia" - : "Emulation.setFocusEmulationEnabled", - ), - }); - expect(restored).toBe(true); - if (mutation === "media") - expect(environmentSession.send).not.toHaveBeenCalledWith( - "Emulation.clearDeviceMetricsOverride", - undefined, - ); - else - expect(environmentSession.send).toHaveBeenCalledWith( - "Emulation.clearDeviceMetricsOverride", - undefined, - ); - expect(browser.close).toHaveBeenCalledOnce(); - }, -); - it.each([ new Error("Timeout unrelated launch diagnostic"), Object.assign(new Error("unrelated launch failure"), {