Files
rea/src/browser/PlaywrightBrowserScenarioProvider.test.ts
T
morluto 3460ceac3f fix(browser): retain exact scenario cleanup ownership
Transfer canonical leases through opening, session and storage boundaries. Keep response deadlines separate from actual completion, drain independent owners, and join late opening failure cleanup before confirming recovery. Remove error copies in favor of canonical primary/cleanup composition.

Preserve exact caller reasons, completed observations and independent physical failures through final-close cancellation and retry. Closes #4869.

Validation:155 tests pass across15 focused source, service, CLI subprocess and MCP files; static/docs/discovery1551 pass. Two original-revision controls fail as expected. Bounded authored-session public CLI comparison preserves equivalent Evidence and1282 reply token estimates; no real Chromium qualification or forced-termination recovery claim (#4659).
2026-10-18 03:22:29 +08:00

1230 lines
40 KiB
TypeScript

import { failBrowserScenarioOperation } from "./PlaywrightScenarioBrowser.js";
import { AnalysisCleanupLease } from "../artifacts/AnalysisCleanupLease.js";
// Fake-backed composition coverage; real browser verification lives in
// `npm run verify:browser`.
import { describe, expect, it, vi } from "vitest";
import type { BrowserScenarioSessionPort } from "./BrowserScenarioSessionPort.js";
import { PlaywrightBrowserScenarioProvider } from "./PlaywrightBrowserScenarioProvider.js";
import { sanitizeBrowserUrl } from "../domain/browserObservation.js";
import { PlaywrightScenarioBrowserCleanupOwner } from "./PlaywrightScenarioBrowser.js";
import {
browserScenarioSchema,
type BrowserScenario,
} from "../domain/browserScenario.js";
import type { BrowserScenarioAction } from "../domain/browserScenarioValues.js";
import {
browserStepArtifactsSchema,
type BrowserScenarioEvent,
type BrowserScenarioEventFamily,
type BrowserStepArtifacts,
} from "../domain/browserScenarioCaptureValues.js";
import { PLAYWRIGHT_RESPONSE_BODY_PROVENANCE_LIMITATION } from "../domain/browserNetworkEvidence.js";
import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
import { compareBrowserScenarios } from "../domain/browserScenarioDiff.js";
import { compareBrowserScenariosInputSchema } from "../domain/browserScenarioDiffValues.js";
import {
AnalysisCancelledError,
AnalysisOutputError,
AnalysisTimeoutError,
} from "../domain/analysisErrorCore.js";
const scenario = (
options: {
readonly mode?: "launch" | "connect";
readonly captures?: readonly (
| "screenshot"
| "dom"
| "accessibility"
| "url"
| "history"
| "storage"
)[];
readonly events?: readonly (
| "console"
| "page-errors"
| "network"
| "websockets"
| "frames"
| "workers"
| "popups"
| "downloads"
)[];
readonly actions?: number;
} = {},
): BrowserScenario =>
browserScenarioSchema.parse({
browser:
options.mode === "connect"
? {
mode: "connect",
cdp_endpoint: "http://127.0.0.1:9222",
target_id: "page-1",
}
: {
mode: "launch",
executable_path: "/opt/chromium",
},
start_url: { url: "https://app.example.test/" },
actions: Array.from({ length: options.actions ?? 1 }, (_, index) => ({
step_id: `wait_${index}`,
action: "wait_for_timeout",
duration_ms: 1,
})),
storage: {},
secrets: [],
capture: {
after_each_step: options.captures ?? ["url"],
at_end: [],
events: options.events ?? [],
},
});
const connectedPlatformEmulationLimitation = expect.stringContaining(
"Detaching a CDP page session may clear caller-owned navigator.platform emulation",
);
type SnapshotKind = BrowserScenario["capture"]["after_each_step"][number];
interface FakeSessionFailures {
readonly incomplete?: boolean;
readonly action?: Error;
readonly capture?: { readonly call: number; readonly error: Error };
readonly close?: Error;
}
const artifactState = (
kind: SnapshotKind,
requested: ReadonlySet<SnapshotKind>,
incomplete: boolean,
) => {
if (!requested.has(kind)) return { state: "not_requested" as const };
if (kind === "url")
return {
state: "captured" as const,
value: sanitizeBrowserUrl("https://app.example.test/current"),
};
if (incomplete && kind === "screenshot")
return {
state: "truncated" as const,
observed: 2_048,
retained: 0,
reason: "fixture limit",
};
return { state: "missing" as const, reason: "fixture unavailable" };
};
class FakeSession implements BrowserScenarioSessionPort {
readonly product = "Fake Chromium";
readonly version = "1";
readonly initialUrl = "about:blank";
readonly processOwnership: "provider-owned" | "external";
cleanupLease = new AnalysisCleanupLease(async () => {
await this.close();
}, ["browser_transport"]);
closeCalls = 0;
performCalls = 0;
captureCalls = 0;
onPerform: (() => void) | undefined;
onClose: (() => void) | undefined;
eventGaps: readonly string[] = [];
eventItems: readonly BrowserScenarioEvent[] = [];
constructor(
readonly mode: "launch" | "connect",
private readonly failures: FakeSessionFailures = {},
) {
this.processOwnership = mode === "launch" ? "provider-owned" : "external";
}
currentUrl() {
return "https://app.example.test/current";
}
sanitizeUrl(value: string) {
return sanitizeBrowserUrl(value);
}
setStep(_index: number) {}
nextEventSequence() {
return 1;
}
lastEventSequence() {
return 0;
}
events(): ReturnType<BrowserScenarioSessionPort["events"]> {
return {
retained: this.eventItems.length,
dropped: 0,
items: this.eventItems,
omissions: {
by_kind: [],
network_transactions: [],
network_transaction_range: null,
},
};
}
eventLimitations(): readonly string[] {
return this.eventGaps;
}
async perform(_action: BrowserScenarioAction, signal?: AbortSignal) {
this.performCalls += 1;
this.onPerform?.();
if (signal?.aborted === true) throw new Error("request cancelled");
if (this.failures.action !== undefined) throw this.failures.action;
}
capture(
requested: ReadonlySet<SnapshotKind>,
_signal?: AbortSignal,
): Promise<BrowserStepArtifacts> {
this.captureCalls += 1;
if (this.failures.capture?.call === this.captureCalls)
return Promise.reject(this.failures.capture.error);
return Promise.resolve(
browserStepArtifactsSchema.parse({
screenshot: artifactState(
"screenshot",
requested,
this.failures.incomplete === true,
),
dom: artifactState("dom", requested, this.failures.incomplete === true),
accessibility: artifactState(
"accessibility",
requested,
this.failures.incomplete === true,
),
url: artifactState("url", requested, this.failures.incomplete === true),
history: artifactState(
"history",
requested,
this.failures.incomplete === true,
),
storage: artifactState(
"storage",
requested,
this.failures.incomplete === true,
),
}),
);
}
close() {
this.closeCalls += 1;
this.onClose?.();
if (this.failures.close !== undefined)
return Promise.reject(this.failures.close);
return Promise.resolve(
this.mode === "launch"
? ("terminated-owned-process" as const)
: ("disconnected-external" as const),
);
}
redactError(error: unknown) {
return error instanceof Error
? error.message.replaceAll("secret", "[REDACTED]")
: "fixture failure";
}
}
describe("PlaywrightBrowserScenarioProvider", () => {
it("reports response-body provenance uncertainty without marking event coverage missing", async () => {
const session = new FakeSession("launch");
const selected = scenario();
session.eventItems = [
{
sequence: 1,
step_index: 0,
kind: "response",
transaction_id: "request-1",
redirected_from_transaction_id: null,
method: "GET",
url: sanitizeBrowserUrl("https://app.example.test/main.js"),
resource_type: "script",
header_names: [],
status: 200,
failure: null,
},
{
sequence: 2,
step_index: 0,
kind: "network-content",
transaction_id: "request-1",
source_event_sequence: 1,
phase: "response",
headers: { state: "not_requested" },
body: {
state: "captured",
representation: "playwright-response-body-bytes",
encoding: "base64",
content: "",
bytes: 0,
sha256:
"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
media_type: "text/javascript",
redacted: false,
},
},
];
const input = browserScenarioSchema.parse({
...selected,
capture: {
...selected.capture,
network: { ...selected.capture.network, response_body: true },
},
});
const provider = new PlaywrightBrowserScenarioProvider(() =>
Promise.resolve(session),
);
const result = await provider.captureScenario(input);
if (!result.ok) throw result.error;
expect(result.value.limitations).toContain(
PLAYWRIGHT_RESPONSE_BODY_PROVENANCE_LIMITATION,
);
expect(result.value.completeness.missing_sections).not.toContain("events");
expect(result.value.events.items[1]).toMatchObject({
kind: "network-content",
body: {
state: "captured",
representation: "playwright-response-body-bytes",
},
});
});
it("makes reported event gaps ineligible for equality even in launch mode", async () => {
const session = new FakeSession("launch");
session.eventGaps = ["Popup frames before discovery are unavailable"];
const provider = new PlaywrightBrowserScenarioProvider(() =>
Promise.resolve(session),
);
const result = await provider.captureScenario(
scenario({ events: ["frames"] }),
);
if (!result.ok) throw result.error;
expect(result.value.completeness).toMatchObject({
status: "incomplete",
equality_eligible: false,
missing_sections: ["events"],
});
expect(result.value.limitations).toContain(session.eventGaps[0]);
});
it("returns an initial state and every step beyond the former action ceiling", async () => {
const session = new FakeSession("launch");
const provider = new PlaywrightBrowserScenarioProvider(() =>
Promise.resolve(session),
);
const result = await provider.captureScenario(scenario({ actions: 129 }));
if (!result.ok) throw result.error;
expect(result.value.scenario.action_count).toBe(129);
expect(result.value.steps).toHaveLength(130);
expect(result.value.steps.at(-1)?.step_id).toBe("wait_128");
});
it("makes missing and truncated captures ineligible for equality", async () => {
const session = new FakeSession("launch", { incomplete: true });
const provider = new PlaywrightBrowserScenarioProvider(() =>
Promise.resolve(session),
);
const result = await provider.captureScenario(
scenario({ captures: ["screenshot", "dom"] }),
);
if (!result.ok) throw result.error;
expect(result.value.completeness).toMatchObject({
status: "truncated",
equality_eligible: false,
missing_sections: ["dom"],
truncated_sections: ["screenshot"],
});
});
it("records one failed step, cancels later actions, and still cleans up", async () => {
const session = new FakeSession("launch", {
action: new Error("fixture secret action failure"),
});
const provider = new PlaywrightBrowserScenarioProvider(() =>
Promise.resolve(session),
);
const result = await provider.captureScenario(scenario({ actions: 2 }));
if (!result.ok) throw result.error;
expect(result.value.steps.map(({ status }) => status)).toEqual([
"completed",
"failed",
"cancelled",
]);
expect(result.value.steps[1]?.error).toBe(
"fixture [REDACTED] action failure",
);
expect(session.performCalls).toBe(1);
expect(session.closeCalls).toBe(1);
expect(result.value.completeness.equality_eligible).toBe(false);
});
});
describe("connected browser scenario captures", () => {
it("disconnects external CDP sessions and marks pre-attach events missing", async () => {
const session = new FakeSession("connect");
const provider = new PlaywrightBrowserScenarioProvider(() =>
Promise.resolve(session),
);
const result = await provider.captureScenario(
scenario({ mode: "connect" }),
);
if (!result.ok) throw result.error;
expect(result.value.browser).toMatchObject({
process_ownership: "external",
cleanup: "disconnected-external",
});
expect(result.value.completeness).toMatchObject({
status: "incomplete",
equality_eligible: false,
missing_sections: ["events"],
});
expect(result.value.limitations).toEqual(
expect.arrayContaining([connectedPlatformEmulationLimitation]),
);
expect(session.closeCalls).toBe(1);
});
it("retains the attached platform-emulation limitation in partial observations", async () => {
const session = new FakeSession("connect", {
capture: { call: 1, error: new Error("fixture capture failure") },
});
const provider = new PlaywrightBrowserScenarioProvider(() =>
Promise.resolve(session),
);
const result = await provider.captureScenario(
scenario({ mode: "connect" }),
);
expect(result.ok).toBe(false);
if (result.ok) return;
expect(projectAnalysisError(result.error)).toMatchObject({
details: {
partial_observation: {
capture: {
limitations: expect.arrayContaining([
connectedPlatformEmulationLimitation,
]),
},
},
},
});
});
});
describe("PlaywrightBrowserScenarioProvider timing", () => {
it("keeps capture elapsed values valid across a backward wall-clock jump", async () => {
let wallClock = 10_000;
vi.spyOn(Date, "now").mockImplementation(() => wallClock);
const session = new FakeSession("launch");
session.onPerform = () => {
wallClock = 1;
};
const provider = new PlaywrightBrowserScenarioProvider(() =>
Promise.resolve(session),
);
try {
const result = await provider.captureScenario(scenario());
if (!result.ok) throw result.error;
expect(wallClock).toBe(1);
expect(Number.isInteger(result.value.duration_ms)).toBe(true);
expect(result.value.duration_ms).toBeGreaterThanOrEqual(0);
expect(
result.value.steps.every(
({ elapsed_ms }) => Number.isInteger(elapsed_ms) && elapsed_ms >= 0,
),
).toBe(true);
} finally {
vi.restoreAllMocks();
}
});
});
describe("PlaywrightBrowserScenarioProvider comparison coverage", () => {
it("keeps quiet captures with different event families from comparing unchanged", async () => {
const capture = async (events: readonly BrowserScenarioEventFamily[]) => {
const provider = new PlaywrightBrowserScenarioProvider(() =>
Promise.resolve(new FakeSession("launch")),
);
const result = await provider.captureScenario(scenario({ events }));
if (!result.ok) throw result.error;
return result.value;
};
const compare = async (
before: readonly BrowserScenarioEventFamily[],
after: readonly BrowserScenarioEventFamily[],
) =>
compareBrowserScenarios(
compareBrowserScenariosInputSchema.parse({
before_scenario: await capture(before),
after_scenario: await capture(after),
}),
);
const recorded = await capture(["page-errors", "console", "console"]);
expect(recorded.completeness.equality_eligible).toBe(true);
expect(recorded.scenario.event_families).toEqual([
"console",
"page-errors",
]);
for (const [before, after] of [
[[], ["console"]],
[["console"], ["page-errors"]],
] as const) {
const compared = await compare(before, after);
expect(compared.overall_status).toBe("unknown");
expect(
compared.steps.flatMap((step) => step.artifact_diffs),
).toContainEqual(
expect.objectContaining({
artifact: "events",
status: "unknown",
reason: expect.stringContaining("Event family selections differ"),
}),
);
}
expect(
(await compare(["console", "page-errors"], ["page-errors", "console"]))
.overall_status,
).toBe("unchanged");
});
});
describe("PlaywrightBrowserScenarioProvider cleanup", () => {
it("returns a cleanup failure with completed observations when close fails", async () => {
const session = new FakeSession("launch", {
action: new Error("fixture secret action failure"),
close: new Error("browser close failed"),
});
const provider = new PlaywrightBrowserScenarioProvider(() =>
Promise.resolve(session),
);
const result = await provider.captureScenario(scenario());
expect(result.ok).toBe(false);
if (result.ok) return;
const projection = projectAnalysisError(result.error);
expect(projection).toMatchObject({
code: "cleanup_incomplete",
details: {
cleanup: "incomplete",
resources: ["browser_transport"],
partial_observation: {
kind: "browser-scenario-observation",
capture: {
browser: { cleanup: "incomplete" },
steps: [
{ step_id: "scenario_start" },
{ step_id: "wait_0", status: "failed" },
],
},
},
},
});
expect(session.closeCalls).toBe(1);
});
});
describe("PlaywrightBrowserScenarioProvider operation failures", () => {
it.each([{ cleanupFails: false }, { cleanupFails: true }])(
"retains typed partial data when operation fails and cleanupFails=$cleanupFails",
async ({ cleanupFails }) => {
const session = new FakeSession("launch", {
capture: {
call: 2,
error: new AnalysisOutputError(
"capture_browser_scenario",
"step capture failed",
{
capturedOutput: {
stdout: "partial stdout",
stderr: "",
truncated: false,
},
cleanup: {
reason: "capture cleanup is uncertain",
resources: ["capture_handle"],
},
},
),
},
...(cleanupFails ? { close: new Error("browser close failed") } : {}),
});
session.eventItems = [
{
sequence: 1,
step_index: 0,
kind: "console",
level: "log",
text: "navigation started",
url: sanitizeBrowserUrl("https://app.example.test/"),
},
];
const provider = new PlaywrightBrowserScenarioProvider(() =>
Promise.resolve(session),
);
const result = await provider.captureScenario(scenario());
expect(result.ok).toBe(false);
if (result.ok) return;
const projection = projectAnalysisError(result.error);
expect(projection).toMatchObject({
code: "cleanup_incomplete",
details: {
...(cleanupFails
? {
diagnostics: {
primary_error: {
code: "cleanup_incomplete",
details: {
operation: "capture_browser_scenario",
diagnostics: {
primary_error: {
details: { reason: "step capture failed" },
},
},
},
},
cleanup_error: { code: "cleanup_incomplete" },
},
}
: { reason: "step capture failed" }),
partial_observation: {
kind: "browser-scenario-observation",
capture: {
browser: {
cleanup: cleanupFails
? "incomplete"
: "terminated-owned-process",
},
steps: [{ step_id: "scenario_start" }],
events: {
retained: 1,
dropped: 0,
items: [
expect.objectContaining({ text: "navigation started" }),
],
omissions: {
by_kind: [],
network_transactions: [],
network_transaction_range: null,
},
},
},
},
},
});
expect(result.error.capturedOutput).toEqual({
stdout: "partial stdout",
stderr: "",
truncated: false,
});
expect(result.error.cleanupResources).toEqual(
cleanupFails
? ["capture_handle", "browser_transport"]
: ["capture_handle"],
);
if (!cleanupFails)
expect(result.error.cleanup).toEqual({
reason: "capture cleanup is uncertain",
resources: ["capture_handle"],
});
expect(session.closeCalls).toBe(1);
},
);
});
describe("PlaywrightBrowserScenarioProvider cancellation and timeout", () => {
it.each([
{
name: "cancellation",
error: new AnalysisCancelledError("capture_browser_scenario"),
code: "cancelled",
category: "cancelled",
details: { operation: "capture_browser_scenario", cleanup: "complete" },
},
{
name: "timeout",
error: new AnalysisTimeoutError("capture_browser_scenario", 250),
code: "provider_timeout",
category: "timeout",
details: { operation: "capture_browser_scenario", timeout_ms: 250 },
},
])(
"preserves $name category and details when cleanup succeeds",
async ({ error, code, category, details }) => {
const session = new FakeSession("launch", {
capture: { call: 1, error },
});
const provider = new PlaywrightBrowserScenarioProvider(() =>
Promise.resolve(session),
);
const result = await provider.captureScenario(scenario());
expect(result.ok).toBe(false);
if (result.ok) return;
const projection = projectAnalysisError(result.error);
expect(projection).toMatchObject({
code,
category,
details: {
...details,
partial_observation: {
kind: "browser-scenario-observation",
capture: { browser: { cleanup: "terminated-owned-process" } },
},
},
});
expect(session.closeCalls).toBe(1);
},
);
});
describe("PlaywrightBrowserScenarioProvider request cancellation", () => {
it("does not open a session for an already-cancelled request", async () => {
let opens = 0;
const provider = new PlaywrightBrowserScenarioProvider(() => {
opens += 1;
return Promise.resolve(new FakeSession("launch"));
});
const controller = new AbortController();
controller.abort();
const result = await provider.captureScenario(scenario(), {
signal: controller.signal,
});
expect(result.ok).toBe(false);
expect(opens).toBe(0);
});
it("cancels an active action and still closes the session", async () => {
const controller = new AbortController();
const cancellationReason = new Error("cancel active scenario");
const session = new FakeSession("launch");
session.onPerform = () => controller.abort(cancellationReason);
const provider = new PlaywrightBrowserScenarioProvider(() =>
Promise.resolve(session),
);
const result = await provider.captureScenario(scenario(), {
signal: controller.signal,
});
expect(result).toMatchObject({
ok: false,
error: {
_tag: "AnalysisCancelledError",
partialObservation: {
kind: "browser-scenario-observation",
capture: {
browser: { cleanup: "terminated-owned-process" },
steps: [{ status: "completed" }, { status: "cancelled" }],
},
},
},
});
if (result.ok) throw new Error("Expected active scenario cancellation");
expect(result.error.cause).toBe(cancellationReason);
expect(session.closeCalls).toBe(1);
});
it("retains the completed capture when cancellation arrives during final close", async () => {
const controller = new AbortController();
const cancellationReason = new Error("cancel final close");
const session = new FakeSession("launch");
session.onClose = () => controller.abort(cancellationReason);
const provider = new PlaywrightBrowserScenarioProvider(() =>
Promise.resolve(session),
);
const result = await provider.captureScenario(scenario(), {
signal: controller.signal,
});
expect(session.closeCalls).toBe(1);
expect(result).toMatchObject({
ok: false,
error: {
_tag: "AnalysisCancelledError",
partialObservation: {
kind: "browser-scenario-observation",
capture: {
browser: { cleanup: "terminated-owned-process" },
steps: [{ status: "completed" }, { status: "completed" }],
},
},
},
});
if (result.ok) throw new Error("Expected final-close cancellation");
expect(result.error.cause).toBe(cancellationReason);
});
it("retains final-close cancellation alongside failed cleanup", async () => {
const controller = new AbortController();
const session = new FakeSession("launch", {
close: new Error("fixture close failed"),
});
session.onClose = () => controller.abort();
const provider = new PlaywrightBrowserScenarioProvider(() =>
Promise.resolve(session),
);
const result = await provider.captureScenario(scenario(), {
signal: controller.signal,
});
expect(result).toMatchObject({
ok: false,
error: {
_tag: "ProviderAdapterError",
cleanupIncomplete: true,
partialObservation: {
kind: "browser-scenario-observation",
capture: {
browser: { cleanup: "incomplete" },
steps: [{ status: "completed" }, { status: "completed" }],
},
},
},
});
if (result.ok)
throw new Error("Expected final-close cancellation with cleanup");
let primary = result.error.cleanupPrimary;
while (primary?.cleanupPrimary !== undefined)
primary = primary.cleanupPrimary;
expect(primary).toMatchObject({ _tag: "AnalysisCancelledError" });
expect(primary?.cause).toBe(controller.signal.reason);
await expect(provider.close()).rejects.toMatchObject({
_tag: "ProviderAdapterError",
operation: "capture_browser_scenario",
});
expect(session.closeCalls).toBe(2);
});
});
it("shares concurrent close and retries browser cleanup after failure", async () => {
const browserClose = vi
.fn<() => Promise<void>>()
.mockRejectedValueOnce(new Error("browser close failed"))
.mockResolvedValue(undefined);
const removeProfile = vi
.fn<() => Promise<void>>()
.mockResolvedValue(undefined);
const finishEvents = vi
.fn<() => Promise<void>>()
.mockResolvedValue(undefined);
const cleanupSettlements: boolean[] = [];
const cleanup = new PlaywrightScenarioBrowserCleanupOwner({
closeBrowser: browserClose,
removeProfile,
onSettled: (browserClosed) => cleanupSettlements.push(browserClosed),
});
const first = cleanup.close(finishEvents);
const concurrent = cleanup.close(finishEvents);
await expect(first).rejects.toMatchObject({ reason: "cleanup_failed" });
await expect(concurrent).rejects.toMatchObject({ reason: "cleanup_failed" });
expect(browserClose).toHaveBeenCalledTimes(1);
expect(removeProfile).not.toHaveBeenCalled();
expect(finishEvents).toHaveBeenCalledTimes(1);
expect(cleanupSettlements).toEqual([false]);
await expect(cleanup.close(finishEvents)).resolves.toBeUndefined();
await expect(cleanup.close(finishEvents)).resolves.toBeUndefined();
expect(browserClose).toHaveBeenCalledTimes(2);
expect(removeProfile).toHaveBeenCalledTimes(1);
expect(finishEvents).toHaveBeenCalledTimes(1);
expect(cleanupSettlements).toEqual([false, true]);
});
it("keeps failed event finalization failed across cleanup retries", async () => {
const finishEvents = vi
.fn<() => Promise<void>>()
.mockRejectedValue(new Error("event finalization failed"));
const closeBrowser = vi
.fn<() => Promise<void>>()
.mockResolvedValue(undefined);
const cleanup = new PlaywrightScenarioBrowserCleanupOwner({
closeBrowser,
removeProfile: undefined,
});
await expect(cleanup.close(finishEvents)).rejects.toMatchObject({
reason: "cleanup_failed",
});
await expect(cleanup.close(finishEvents)).rejects.toMatchObject({
reason: "cleanup_failed",
});
expect(finishEvents).toHaveBeenCalledTimes(1);
expect(closeBrowser).toHaveBeenCalledTimes(1);
});
it.each(["launch", "connect"] as const)(
"reports locale coverage in %s success and retained operation/cleanup failures",
async (mode) => {
const input = scenario({ mode });
input.environment.locale = "fr-FR";
for (const failures of [
{},
{
capture: {
call: 1,
error: new AnalysisCancelledError("capture_browser_scenario"),
},
},
{ close: new Error("fixture cleanup interrupted") },
]) {
const session = new FakeSession(mode, failures);
const provider = new PlaywrightBrowserScenarioProvider(
async () => session,
);
const result = await provider.captureScenario(input);
expect(result.ok).toBe(!("capture" in failures || "close" in failures));
const expected = {
limitations:
mode === "connect"
? expect.arrayContaining([
"Attached locale fr-FR applies to Intl formatting only; navigator.language(s) and Accept-Language remain caller-controlled. Use launch mode for matching page and request languages.",
])
: expect.not.arrayContaining([
expect.stringContaining("Attached locale"),
]),
};
if (result.ok) expect(result.value).toMatchObject(expected);
else
expect(projectAnalysisError(result.error)).toMatchObject({
details: {
partial_observation: {
kind: "browser-scenario-observation",
capture: expected,
},
},
});
expect(session.closeCalls).toBe(1);
}
},
);
it.each([false, true])(
"follows the browser owner through provider recovery (operation failed: %s)",
async (operationFailed) => {
const reason = { caller: "authored capture cancellation" };
const primary = new AnalysisCancelledError("capture_browser_scenario", {
cause: reason,
});
const session = new FakeSession(
"launch",
operationFailed ? { capture: { call: 1, error: primary } } : {},
);
let denied = true;
const owner = new PlaywrightScenarioBrowserCleanupOwner({
closeBrowser: async () => {},
removeProfile: async () => {
if (denied) throw new Error("profile removal denied");
},
});
session.cleanupLease = owner.cleanupLease;
session.close = async () => {
await owner.close();
return "terminated-owned-process";
};
const provider = new PlaywrightBrowserScenarioProvider(async () => session);
try {
const result = await provider.captureScenario(scenario());
if (result.ok) throw new Error("Expected retained cleanup");
expect(result.error.cleanupIncomplete).toBe(true);
expect(result.error.cleanupResources).toEqual(["browser_profile"]);
const partial = result.error.partialObservation;
await expect(provider.close()).rejects.toMatchObject({
cleanupIncomplete: true,
});
denied = false;
await provider.close();
expect(result.error.cleanupIncomplete).toBe(false);
expect(result.error.cleanupResources).toEqual([]);
expect(result.error.partialObservation).toBe(partial);
if (operationFailed) {
let restored = result.error.cleanupPrimary;
while (restored?.cleanupPrimary !== undefined)
restored = restored.cleanupPrimary;
expect(restored).toBe(primary);
expect(primary.cause).toBe(reason);
expect(projectAnalysisError(result.error)).toMatchObject({
code: "cancelled",
});
}
} finally {
denied = false;
await provider.close();
}
},
);
it("resolves the returned failure after retrying a plain session cleanup capability", async () => {
const session = new FakeSession("launch");
let denied = true;
session.close = async () => {
if (denied) throw new Error("authored session cleanup denial");
return "terminated-owned-process";
};
const provider = new PlaywrightBrowserScenarioProvider(async () => session);
try {
const result = await provider.captureScenario(scenario());
if (result.ok) throw new Error("Expected cleanup failure");
expect(result.error.cleanupIncomplete).toBe(true);
const failed: unknown = await provider
.close()
.catch((cause: unknown) => cause);
expect(failed).toMatchObject({ cleanupIncomplete: true });
denied = false;
await provider.close();
expect(result.error).toMatchObject({
cleanupIncomplete: false,
cleanupResources: [],
});
expect(failed).toMatchObject({
cleanupIncomplete: false,
cleanupResources: [],
});
} finally {
denied = false;
await provider.close();
}
});
it("retries every retained opening cleanup and preserves the original failure through mixed recovery", async () => {
let denied = true;
let healthyCloses = 0;
const physical = new AnalysisOutputError(
"capture_browser_scenario",
"authored open failure",
);
const provider = new PlaywrightBrowserScenarioProvider(
async (_scenario, options) => {
options.retainCleanup?.(
new AnalysisCleanupLease(async () => {
if (denied) throw new Error("first cleanup denied");
}, ["first cleanup"]),
);
options.retainCleanup?.(
new AnalysisCleanupLease(async () => {
healthyCloses++;
}, ["healthy cleanup"]),
);
throw physical;
},
);
try {
const result = await provider.captureScenario(scenario());
if (result.ok) throw new Error("Expected opening failure");
const failed: unknown = await provider
.close()
.catch((cause: unknown) => cause);
expect(failed).toMatchObject({ cleanupIncomplete: true });
expect(result.error.cleanupIncomplete).toBe(true);
expect(healthyCloses).toBe(1);
denied = false;
await provider.close();
expect(result.error).toMatchObject({
cleanupIncomplete: false,
cleanupResources: [],
});
expect(failed).toMatchObject({
cleanupIncomplete: false,
cleanupResources: [],
});
expect(result.error.cleanupPrimary).toBe(physical);
expect(healthyCloses).toBe(1);
} finally {
denied = false;
await provider.close();
}
});
it("keeps a cancelled opening incomplete until its retained late cleanup finishes", async () => {
let finish: () => void = () => {};
const late = new Promise<void>((resolve) => {
finish = resolve;
});
const reason = { caller: "cancelled opening before late handshake" };
const primary = new AnalysisCancelledError("capture_browser_scenario", {
cause: reason,
});
const provider = new PlaywrightBrowserScenarioProvider(
async (_scenario, options) => {
options.retainCleanup?.(
new AnalysisCleanupLease(() => late, ["late opening"]),
);
throw primary;
},
);
try {
const result = await provider.captureScenario(scenario());
if (result.ok) throw new Error("Expected cancelled opening");
expect(result.error.cleanupIncomplete).toBe(true);
const closing = provider.close();
await Promise.resolve();
expect(result.error.cleanupIncomplete).toBe(true);
finish();
await closing;
expect(result.error).toMatchObject({
cleanupIncomplete: false,
cleanupResources: [],
});
expect(result.error.cleanupPrimary).toBe(primary);
expect(primary.cause).toBe(reason);
expect(projectAnalysisError(result.error)).toMatchObject({
code: "cancelled",
});
} finally {
finish();
await provider.close();
}
});
it.each([false, true])(
"follows late browser acknowledgement without another retry (cancelled during close: %s)",
async (cancelled) => {
vi.useFakeTimers();
let acknowledge: () => void = () => {};
const acknowledgement = new Promise<void>((resolve) => {
acknowledge = resolve;
});
const caller = new AbortController();
const reason = { caller: "during final browser close" };
const owner = new PlaywrightScenarioBrowserCleanupOwner({
closeBrowser: () => acknowledgement,
removeProfile: undefined,
});
const session = new FakeSession("launch");
session.cleanupLease = owner.cleanupLease;
session.close = async () => {
if (cancelled) caller.abort(reason);
await owner.close();
return "terminated-owned-process";
};
const provider = new PlaywrightBrowserScenarioProvider(async () => session);
try {
const pending = provider.captureScenario(scenario(), {
signal: caller.signal,
});
await vi.advanceTimersByTimeAsync(30_000);
const result = await pending;
if (result.ok) throw new Error("Expected timed out cleanup response");
expect(result.error.cleanupIncomplete).toBe(true);
const partial = result.error.partialObservation;
acknowledge();
await owner.cleanupLease.release();
expect(result.error).toMatchObject({
cleanupIncomplete: false,
cleanupResources: [],
});
expect(result.error.partialObservation).toBe(partial);
if (cancelled) {
expect(projectAnalysisError(result.error)).toMatchObject({
code: "cancelled",
});
let primary = result.error.cleanupPrimary;
while (primary?.cleanupPrimary !== undefined)
primary = primary.cleanupPrimary;
expect(primary?.cause).toBe(reason);
}
} finally {
acknowledge();
await provider.close();
vi.useRealTimers();
}
},
);
it("retains a profile-only opening lease without adding transport labels or waiting for another retry", async () => {
let denied = true;
let releases = 0;
const primary = new AnalysisOutputError(
"capture_browser_scenario",
"authored opening failure",
);
const lease = new AnalysisCleanupLease(async () => {
releases++;
if (denied) throw new Error("profile removal denied");
}, ["browser_profile"]);
const provider = new PlaywrightBrowserScenarioProvider(
async (_scenario, options) => {
try {
return await failBrowserScenarioOperation(lease, primary);
} catch (cause: unknown) {
options.retainCleanup?.(lease);
throw cause;
}
},
);
try {
const result = await provider.captureScenario(scenario());
if (result.ok) throw new Error("Expected opening failure");
expect(result.error).toMatchObject({
cleanupIncomplete: true,
cleanupResources: ["browser_profile"],
});
denied = false;
await lease.release();
expect(result.error).toMatchObject({
cleanupIncomplete: false,
cleanupResources: [],
});
expect(projectAnalysisError(result.error)).toMatchObject({
code: "unreadable_output",
});
await provider.close();
expect(releases).toBe(2);
} finally {
denied = false;
await provider.close();
}
});
it("keeps an earlier physical failure primary when final cleanup also observes cancellation", async () => {
const caller = new AbortController();
const physical = new Error("physical capture failure");
const primary = new AnalysisOutputError(
"capture_browser_scenario",
physical.message,
{ cause: physical },
);
const session = new FakeSession("launch", {
capture: { call: 1, error: primary },
});
let denied = true;
session.close = async () => {
caller.abort({ caller: "later during final cleanup" });
if (denied) throw new Error("cleanup denied");
return "terminated-owned-process";
};
const provider = new PlaywrightBrowserScenarioProvider(async () => session);
try {
const result = await provider.captureScenario(scenario(), {
signal: caller.signal,
});
if (result.ok) throw new Error("Expected physical failure");
denied = false;
await provider.close();
expect(result.error.cleanupIncomplete).toBe(false);
expect(projectAnalysisError(result.error)).toMatchObject({
code: "unreadable_output",
});
let restored = result.error.cleanupPrimary;
while (restored?.cleanupPrimary !== undefined)
restored = restored.cleanupPrimary;
expect(restored).toBe(primary);
expect(primary.cause).toBe(physical);
} finally {
denied = false;
await provider.close();
}
});