fix(electron): preserve waits and cancellation through renderer shutdown (#12972)

* fix(electron): preserve scenario waits through renderer crashes

* fix(electron): retain action cancellation across final Inspector failure

* fix(electron): collect active state in a single Inspector call
This commit is contained in:
morluto authored and GitHub committed 2026-11-21 03:08:49 +00:00
1 parent 5ca9f4874b
commit 2533a8b32b
9 files changed
+265 -192

No files matched your search

@@ -157,6 +157,8 @@ REA does not guess an entry point or remove arguments by filename patterns.
`window_index` selects from Playwright's current Page list at the start of each action. REA resolves that Page to its corresponding BrowserWindow once; the action's `target` uses the BrowserWindow's capture-scoped `window_id`, matching the window inventory. Reordering either enumeration after selection does not retarget the action. Handle cleanup failures retain the completed action records and remain owned for provider cleanup retry.
Once REA resolves the required window, the host clock controls the full wait even during a renderer crash.
Run the real fixture verifier with an operator-provided Electron runtime:
```bash
@@ -202,7 +204,9 @@ never appears, or a `wait` without `window_index` in an app that opens no
window, remains pending until cancelled. After cancellation, the final state
read has 5 seconds before REA keeps the initial snapshot instead; the
cancellation keeps the caller's reason and records that expiry in its
diagnostics.
diagnostics. When the caller interrupted an action and the final Inspector read
fails, REA reports the cancellation with the initial snapshot, the action
records, and the Inspector failure as a secondary diagnostic.
The shell policy is owned by `blockedShellResults` in
`scripts/electron-active-hook-boundaries.cjs`. Its synchronous blocks are:
`showItemInFolder` returns `undefined` and `writeShortcutLink` returns `false`.
+58 -37
View File
@@ -10,6 +10,10 @@ import {
electronActiveObservationResultSchema,
} from "../dist/domain/javascript/electronActiveObservation.js";
import { completeVerifierRun, createVerifierRun } from "./lib/verifier-run.mjs";
import {
VerifierFixture,
withVerifierFixture,
} from "./lib/verifier-fixture.mjs";
import { verifyElectronToolContracts } from "./verify/electron/tool-contracts.mjs";
const executable = process.env.REA_ELECTRON_EXECUTABLE;
@@ -20,48 +24,65 @@ if (executable === undefined || executable.length === 0)
const repositoryRoot = fileURLToPath(new URL("..", import.meta.url));
await verifyElectronToolContracts({ executable, repositoryRoot });
const fixtureApplicationRoot = join(
repositoryRoot,
"tests/conformance/readiness/electron",
);
const applicationRoot =
process.env.REA_ELECTRON_APPLICATION_ROOT ??
join(repositoryRoot, "tests/conformance/readiness/electron");
process.env.REA_ELECTRON_APPLICATION_ROOT ?? fixtureApplicationRoot;
const applicationPath =
process.env.REA_ELECTRON_APPLICATION_PATH ?? join(applicationRoot, "main.js");
const input = electronActiveObservationInputSchema.parse({
executable_path: executable,
application_path: applicationPath,
application_root: applicationRoot,
actions: [
{ step_id: "ipc", kind: "click", selector: "#run", window_index: 0 },
{
step_id: "open-url",
kind: "deep-link",
delivery: "open-url",
url: "rea-readiness://open-url",
},
{
step_id: "second-instance",
kind: "deep-link",
delivery: "second-instance",
url: "rea-readiness://second-instance",
},
{ step_id: "renderer-reload", kind: "renderer-reload", window_index: 1 },
{ step_id: "renderer-crash", kind: "renderer-crash", window_index: 1 },
{
step_id: "renderer-restart",
kind: "wait",
duration_ms: 250,
window_index: 1,
},
],
const isReadinessFixture =
applicationRoot === fixtureApplicationRoot &&
applicationPath === join(fixtureApplicationRoot, "main.js");
const profile = await VerifierFixture.open({
prefix: "rea-electron-readiness-",
private: false,
});
const verifierRun = createVerifierRun();
const result = await captureElectronScenario(
new PlaywrightElectronActiveProvider(process.env),
input,
);
if (!result.ok) throw result.error;
const capture = electronActiveObservationResultSchema.parse(
result.value.normalized_result,
);
const provider = new PlaywrightElectronActiveProvider(process.env);
profile.releaseAfter(() => provider.close());
const { input, capture } = await withVerifierFixture(profile, async () => {
const input = electronActiveObservationInputSchema.parse({
executable_path: executable,
application_path: applicationPath,
application_root: applicationRoot,
...(isReadinessFixture
? { args: [`--rea-verifier-profile=${profile.path}`] }
: {}),
actions: [
{ step_id: "ipc", kind: "click", selector: "#run", window_index: 0 },
{
step_id: "open-url",
kind: "deep-link",
delivery: "open-url",
url: "rea-readiness://open-url",
},
{
step_id: "second-instance",
kind: "deep-link",
delivery: "second-instance",
url: "rea-readiness://second-instance",
},
{ step_id: "renderer-reload", kind: "renderer-reload", window_index: 1 },
{ step_id: "renderer-crash", kind: "renderer-crash", window_index: 1 },
{
step_id: "settle-after-crash",
kind: "wait",
duration_ms: 250,
window_index: 1,
},
],
});
const result = await captureElectronScenario(provider, input);
if (!result.ok) throw result.error;
return {
input,
capture: electronActiveObservationResultSchema.parse(
result.value.normalized_result,
),
};
});
const crashAction = capture.actions.find(
({ kind }) => kind === "renderer-crash",
);
@@ -304,35 +304,55 @@ it("runs an untargeted deep-link without requiring a BrowserWindow", async () =>
]);
});
it("honors a caller-selected Electron wait duration exactly", async () => {
const input = electronActiveObservationInputSchema.parse({
executable_path: "/opt/electron",
application_path: "/opt/app/main.js",
application_root: "/opt/app",
actions: [{ step_id: "wait-long", kind: "wait", duration_ms: 60_000 }],
});
let duration = 0;
const page = {
waitForTimeout: async (value: number) => {
duration = value;
},
};
const application = {
windows: () => [page],
browserWindow: fixtureBrowserWindow,
firstWindow: async () => page,
};
it.each(["completed", "cancelled"] as const)(
"records a %s wait independently of the selected renderer",
async (status) => {
vi.useFakeTimers();
const controller = new AbortController();
const input = electronActiveObservationInputSchema.parse({
executable_path: "/opt/electron",
application_path: "/opt/app/main.js",
actions: [
{
step_id: "settle",
kind: "wait",
window_index: 0,
duration_ms: 60_000,
},
],
});
const page = {
waitForTimeout: async () => {
throw new Error("Page crashed");
},
};
const application = {
windows: () => [page],
browserWindow: fixtureBrowserWindow,
};
const observed = vi.fn();
const running = runElectronActions(
application as never,
input,
{ signal: controller.signal },
new ArtifactResourceScope(),
).then((value) => {
observed();
return value;
});
const { actions: result } = await runElectronActions(
application as never,
input,
{},
new ArtifactResourceScope(),
);
expect(result[0]).toMatchObject({ status: "completed" });
expect(duration).toBe(60_000);
});
await vi.advanceTimersByTimeAsync(59_999);
expect(observed).not.toHaveBeenCalled();
if (status === "cancelled") controller.abort("stop waiting");
else await vi.advanceTimersByTimeAsync(1);
expect((await running).actions[0]).toMatchObject({
step_id: "settle",
target: "window:42",
status,
});
expect(vi.getTimerCount()).toBe(0);
},
);
it("rejects action outcomes that disagree with their error state", () => {
const result = createElectronActiveObservationFixtureResult("/opt/app");
@@ -501,18 +521,13 @@ const finalState = {
},
};
/** An application whose four state reads settle only when `release` runs. */
/** An application whose state read settles only when `release` runs. */
const gatedStateApplication = () => {
let release = (): void => undefined;
const gate = new Promise<void>((resolve) => {
release = resolve;
});
const evaluate = vi
.fn()
.mockImplementationOnce(() => gate.then(() => finalState.windows))
.mockImplementationOnce(() => gate.then(() => finalState.metrics))
.mockImplementationOnce(() => gate.then(() => finalState.electronVersion))
.mockImplementationOnce(() => gate.then(() => finalState.hookSnapshot));
const evaluate = () => gate.then(() => finalState);
return {
application: { evaluate } as unknown as ElectronApplication,
release,
+63 -70
View File
@@ -1,5 +1,6 @@
import type { ElectronApplication, JSHandle, Page } from "playwright-core";
import { z } from "zod";
import { waitForAbortableDelay } from "../process/ProviderDeadline.js";
import { runWithExecutionLimits } from "./PlaywrightElectronExecution.js";
import type { ExecutionOptions } from "../ports/AnalysisProvider.js";
@@ -12,6 +13,7 @@ import { AnalysisError } from "../domain/analysisErrorBase.js";
import {
AnalysisCancelledError,
cancelledBy,
carriedReason,
} from "../domain/analysisErrorCore.js";
import { analysisErrorWithCleanupDependencies } from "../domain/analysisErrorCleanup.js";
import { BrowserObservationError } from "../domain/browserObservationError.js";
@@ -87,9 +89,11 @@ export const runElectronActions = async (
): Promise<{
readonly actions: ElectronActions;
readonly cleanupError?: AnalysisError;
readonly actionCancellation?: AnalysisError;
}> => {
const actions: ElectronActions = [];
let cleanupError: AnalysisError | undefined;
let actionCancellation: AnalysisError | undefined;
let stoppedBy: ScenarioActionStop | undefined;
for (const action of input.actions) {
const actionStartedAt = performance.now();
@@ -113,7 +117,7 @@ export const runElectronActions = async (
let actionError: string | null = null;
try {
if (options.signal?.aborted === true)
throw new BrowserObservationError(OPERATION, "cancelled");
throw cancelledBy(OPERATION, options.signal);
selectedWindow =
windowIndex === null
? undefined
@@ -154,11 +158,12 @@ export const runElectronActions = async (
options,
});
} catch (cause: unknown) {
stoppedBy =
if (
cause instanceof AnalysisCancelledError ||
(cause instanceof AnalysisError && cause.userCategory === "cancelled")
? "cancelled"
: "failed";
)
actionCancellation = cause;
stoppedBy = actionCancellation === undefined ? "failed" : "cancelled";
actionError = describeValidationFailure(cause);
}
const actionRecord = {
@@ -187,7 +192,11 @@ export const runElectronActions = async (
if (cleanupError !== undefined) stoppedBy = "failed";
}
}
return { actions, ...(cleanupError === undefined ? {} : { cleanupError }) };
return {
actions,
...(cleanupError === undefined ? {} : { cleanupError }),
...(actionCancellation === undefined ? {} : { actionCancellation }),
};
};
const ownActionWindow = (
@@ -278,21 +287,20 @@ const runAction = async ({
options.signal,
);
return;
case "wait": {
const page =
selectedWindow ??
(await runWithExecutionLimits(
application.firstWindow({
timeout: 0,
}),
case "wait":
if (selectedWindow === undefined)
await runWithExecutionLimits(
application.firstWindow({ timeout: 0 }),
options.signal,
));
await runWithExecutionLimits(
page.waitForTimeout(action.duration_ms),
options.signal,
);
);
// Window selection and the caller's delay have separate lifetimes. A
// renderer crash can close the Page clock during an intended recovery.
if (
(await waitForAbortableDelay(action.duration_ms, options.signal)) ===
"aborted"
)
throw cancelledBy(OPERATION, carriedReason(options.signal?.reason));
return;
}
case "renderer-reload":
if (selectedWindow === undefined)
throw new BrowserObservationError(OPERATION, "window_not_found");
@@ -352,8 +360,7 @@ const waitForWindow = async ({
signal,
}: WaitForWindowContext): Promise<Page> => {
while (true) {
if (signal?.aborted === true)
throw new BrowserObservationError(OPERATION, "cancelled");
if (signal?.aborted === true) throw cancelledBy(OPERATION, signal);
const window = application.windows()[windowIndex];
if (window !== undefined) return window;
await runWithExecutionLimits(
@@ -414,6 +421,13 @@ export const watchSingleInstanceLockRefusal = (
return refusal.signal;
};
const electronApplicationStateSchema = z.strictObject({
windows: z.array(electronActiveWindowSchema),
metrics: z.array(electronActiveProcessMetricSchema),
electronVersion: z.string(),
hookSnapshot: hookSnapshotSchema,
});
/** Read the current Electron windows, metrics, and hook snapshot. */
export const readApplicationState = async (
application: ElectronApplication,
@@ -423,9 +437,10 @@ export const readApplicationState = async (
readonly electronVersion: string;
readonly hookSnapshot: ElectronHookSnapshot;
}> => {
const windowMetadataPromise: Promise<ElectronWindowMetadata[]> = application
.evaluate(({ BrowserWindow }) =>
BrowserWindow.getAllWindows().map(
const state = await application.evaluate(({ BrowserWindow, app }) => {
const candidate = Reflect.get(globalThis, "__reaElectronActiveSnapshot");
return {
windows: BrowserWindow.getAllWindows().map(
(window: {
readonly id: number;
readonly webContents: {
@@ -444,11 +459,7 @@ export const readApplicationState = async (
destroyed: window.isDestroyed(),
}),
),
)
.then((value) => z.array(electronActiveWindowSchema).parse(value));
const processMetricsPromise: Promise<ElectronMetrics> = application
.evaluate(({ app }) =>
app
metrics: app
.getAppMetrics()
.map(
(metric: {
@@ -463,48 +474,30 @@ export const readApplicationState = async (
service_name: metric.serviceName ?? null,
}),
),
)
.then((value) => z.array(electronActiveProcessMetricSchema).parse(value));
const electronVersionPromise: Promise<string> = application
.evaluate(() => process.versions.electron)
.then((value) => z.string().parse(value));
const hookSnapshotPromise: Promise<ElectronHookSnapshot> = application
.evaluate(() => {
const candidate = Reflect.get(globalThis, "__reaElectronActiveSnapshot");
return typeof candidate === "function"
? candidate()
: {
events: [],
retention_budget_bytes: 0,
estimated_retained_bytes: 0,
event_serialized_byte_upper_bound: 0,
retained: 0,
dropped: 0,
dropped_ipc: 0,
dropped_runtime: 0,
dropped_event_families: [],
dropped_event_roles: [],
observed: 0,
observed_ipc: 0,
observed_runtime: 0,
hook_error: true,
single_instance_lock_refused: null,
};
})
.then((value) => hookSnapshotSchema.parse(value));
const [windowMetadata, processMetrics, electronVersion, hookSnapshot] =
await Promise.all([
windowMetadataPromise,
processMetricsPromise,
electronVersionPromise,
hookSnapshotPromise,
]);
return {
windows: windowMetadata,
metrics: processMetrics,
electronVersion,
hookSnapshot,
};
electronVersion: process.versions.electron,
hookSnapshot:
typeof candidate === "function"
? candidate()
: {
events: [],
retention_budget_bytes: 0,
estimated_retained_bytes: 0,
event_serialized_byte_upper_bound: 0,
retained: 0,
dropped: 0,
dropped_ipc: 0,
dropped_runtime: 0,
dropped_event_families: [],
dropped_event_roles: [],
observed: 0,
observed_ipc: 0,
observed_runtime: 0,
hook_error: true,
single_instance_lock_refused: null,
},
};
});
return electronApplicationStateSchema.parse(state);
};
/**
@@ -919,50 +919,68 @@ const captureWithController = async (
);
};
it("cancels a windowless wait action and cleans up the owned application", async () => {
const cleanupSpies = stubVerifiedElectronCleanup();
const state = {
windows: [],
metrics: [],
electronVersion: "44.0.0",
hookSnapshot: emptyHookSnapshot(),
};
vi.spyOn(electronActions, "readApplicationState").mockResolvedValue(state);
vi.spyOn(electronActions, "readFinalApplicationState").mockResolvedValue(
state,
);
const controller = new AbortController();
const reason = new Error("caller-reason");
const application = {
process: () => ({ pid: 424242 }),
close: vi.fn(async () => undefined),
windows: () => [],
firstWindow: vi.fn(() => {
queueMicrotask(() => controller.abort(reason));
return new Promise<never>(() => undefined);
}),
};
it.each(["read succeeds", "Inspector closes"] as const)(
"cancels a windowless wait action and cleans up the owned application (%s)",
async (finalRead) => {
const cleanupSpies = stubVerifiedElectronCleanup();
const state = {
windows: [],
metrics: [],
electronVersion: "44.0.0",
hookSnapshot: emptyHookSnapshot(),
};
vi.spyOn(electronActions, "readApplicationState").mockResolvedValue(state);
const inspectorFailure = new Error("Inspector closed during final read");
const read = vi.spyOn(electronActions, "readFinalApplicationState");
if (finalRead === "Inspector closes")
read.mockRejectedValue(inspectorFailure);
else read.mockResolvedValue(state);
const controller = new AbortController();
const reason = new Error("caller-reason");
const application = {
process: () => ({ pid: 424242 }),
close: vi.fn(async () => undefined),
windows: () => [],
firstWindow: vi.fn(() => {
queueMicrotask(() => controller.abort(reason));
return new Promise<never>(() => undefined);
}),
};
const result = await captureWithController(controller, application, [
{ step_id: "settle", kind: "wait", duration_ms: 10 },
]);
const result = await captureWithController(controller, application, [
{ step_id: "settle", kind: "wait", duration_ms: 10 },
]);
expect(application.firstWindow).toHaveBeenCalledOnce();
expect(application.close).toHaveBeenCalledOnce();
expect(cleanupSpies.some((spy) => spy.mock.calls.length > 0)).toBe(true);
if (result.ok) throw new Error("Expected the capture to be cancelled");
expect(result.error).toMatchObject({
_tag: "BrowserObservationError",
reason: "cancelled",
partialObservation: {
kind: "electron-active-observation",
capture: {
actions: [{ step_id: "settle", kind: "wait", status: "cancelled" }],
expect(application.firstWindow).toHaveBeenCalledOnce();
expect(application.close).toHaveBeenCalledOnce();
expect(cleanupSpies.some((spy) => spy.mock.calls.length > 0)).toBe(true);
if (result.ok) throw new Error("Expected the capture to be cancelled");
expect(result.error).toMatchObject({
_tag: "BrowserObservationError",
reason: "cancelled",
partialObservation: {
kind: "electron-active-observation",
capture: {
actions: [{ step_id: "settle", kind: "wait", status: "cancelled" }],
},
},
},
});
expect(result.error.cause).toBe(reason);
});
});
expect(result.error.cause).toBe(reason);
expect(result.error.secondaryFailures.map(({ cause }) => cause)).toEqual(
finalRead === "Inspector closes" ? [inspectorFailure] : [],
);
if (finalRead === "Inspector closes")
expect(result.error.partialObservation).toMatchObject({
capture: {
limitations: expect.arrayContaining([
expect.stringContaining(
"Final Windows, metrics, IPC, and timeline state is unknown",
),
]),
},
});
},
);
it("records actions after a failed action as not executed and keeps the capture", async () => {
stubVerifiedElectronCleanup();
@@ -979,8 +997,7 @@ it("records actions after a failed action as not executed and keeps the capture"
const click = vi.fn(async () => {
throw new Error("strict mode violation");
});
const waitForTimeout = vi.fn(async () => undefined);
const page = { locator: () => ({ click }), waitForTimeout };
const page = { locator: () => ({ click }) };
const application = {
process: () => ({ pid: 424242 }),
close: vi.fn(async () => undefined),
@@ -1010,7 +1027,6 @@ it("records actions after a failed action as not executed and keeps the capture"
if (!result.ok) throw result.error;
expect(click).toHaveBeenCalledOnce();
expect(waitForTimeout).not.toHaveBeenCalled();
expect(application.close).toHaveBeenCalledOnce();
expect(result.value.actions).toEqual([
{
@@ -261,9 +261,26 @@ export class PlaywrightElectronActiveProvider implements ElectronActiveObservati
actions = actionOutcome.actions;
if (actionOutcome.cleanupError !== undefined)
throw actionOutcome.cleanupError;
const state = await readFinalApplicationState(
application,
options.signal,
const signal = options.signal;
const actionCancellation = actionOutcome.actionCancellation;
const cancelledInAction =
signal?.aborted === true &&
actionCancellation !== undefined &&
Object.is(actionCancellation.cause, signal.reason);
const state = await readFinalApplicationState(application, signal).catch(
(cause: unknown) => {
const failure = providerError(cause);
// A cancellation already recorded for an action precedes the
// best-effort final read, which can lose its Inspector transport.
if (
cancelledInAction &&
!failure.cleanupIncomplete &&
!(failure instanceof AnalysisCancelledError) &&
failure.userCategory !== "cancelled"
)
throw actionCancellation.retainSecondaryFailure(failure);
throw failure;
},
);
const finalCapture = projectElectronActiveCapture(paths, actions, state);
retained = { stage: "final", state };
+1 -1
View File
@@ -857,7 +857,7 @@ it("reports every unresolved Electron path without starting a provider", async (
it("refuses an Electron wait longer than Node can schedule", async () => {
const capture = vi.fn();
const client = await activePathAdmissionClient(capture);
// Playwright's waitForTimeout(2 ** 31) returns after 1 ms.
// A delay above the Node timer range returns after 1 ms.
const result = await client.callTool({
name: "capture_electron_scenario",
arguments: {
@@ -7,6 +7,13 @@ const {
} = require("electron");
const { spawn } = require("node:child_process");
const profileArgument = "--rea-verifier-profile=";
const profile = process.argv.find((argument) =>
argument.startsWith(profileArgument),
);
if (profile !== undefined)
app.setPath("userData", profile.slice(profileArgument.length));
const windows = new Set();
const deliverDeepLink = (url) => {
for (const window of windows) window.webContents.send("deep-link", url);
+1 -1
View File
@@ -1609,7 +1609,7 @@ export const PROVIDER_LIFECYCLE_COVERAGE: Readonly<
cancel: covered(
test(
"src/browser/PlaywrightElectronActiveProvider.test.ts",
"cancels a windowless wait action and cleans up the owned application",
"cancels a windowless wait action and cleans up the owned application (%s)",
),
),
cleanup: covered(