Skip to content

armgit / rea

Public Imported from GitHub
0

Reverse engineer anything with agents, from app behavior down to native binaries.

fix(browser): capture popup network and report early event gaps (#614)

N0zoM1z0f557207887ca
diff --git a/docs/browser-scenario-contract.md b/docs/browser-scenario-contract.md
index cdd61588d..768ab65ef 100644
--- a/docs/browser-scenario-contract.md
+++ b/docs/browser-scenario-contract.md
@@ -60,6 +60,23 @@ inline without application-defined size ceilings. Other missing sections
remain explicit and make the capture ineligible for equality claims.
Attach-mode captures also declare the unavoidable pre-attach event gap.
+Selected event families are observed on the root page and discovered descendant
+popups, including nested popups. Popup lifecycle records are emitted only when
+`popups` is selected. Launch-mode network observation starts at the owned
+context before navigation, so popup document requests, redirects, and responses
+are included once. Connected contexts can contain unrelated tabs: only network
+events with a frame belonging to the root or a discovered popup are retained.
+Initial popup requests without a frame cannot be attributed in shared contexts
+and are omitted; attach coverage remains incomplete.
+
+Playwright reports new popup Pages after their first navigation has committed.
+It buffers early console messages and page errors, but the pinned API cannot
+recover every earlier frame, worker, WebSocket, or download event. If one of
+those families is selected and a popup is discovered, REA reports the family gap
+in `limitations`, marks `events` missing, and disables equality eligibility.
+Later events remain available; no initial navigation is synthesized from the
+popup's current URL.
+
Each request names the exact launch executable or loopback CDP endpoint, target,
actions, and capture behavior. Origin filters and environment-variable names
are included when the scenario needs them.
diff --git a/scripts/lib/browser-popup-e2e.mjs b/scripts/lib/browser-popup-e2e.mjs
new file mode 100644
index 000000000..bf46d2ffc
--- /dev/null
+++ b/scripts/lib/browser-popup-e2e.mjs
@@ -0,0 +1,252 @@
+import assert from "node:assert/strict";
+import { execFile } from "node:child_process";
+import { once } from "node:events";
+import { createServer } from "node:http";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { chromium } from "playwright-core";
+import { Client } from "@modelcontextprotocol/client";
+import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
+
+import { PlaywrightBrowserScenarioProvider } from "../../dist/browser/PlaywrightBrowserScenarioProvider.js";
+import { PlaywrightScenarioEvents } from "../../dist/browser/PlaywrightScenarioEvents.js";
+import { BrowserScenarioSecrets } from "../../dist/browser/BrowserScenarioSecrets.js";
+import { browserScenarioSchema } from "../../dist/domain/browserScenario.js";
+import { compareBrowserScenarios } from "../../dist/domain/browserScenarioDiff.js";
+import { browserScenarioCaptureSchema } from "../../dist/domain/browserScenarioCapture.js";
+import { parseEvidence } from "../../dist/domain/evidence.js";
+
+const document = (path) => {
+ if (path.startsWith("/nested"))
+ return `<script>throw new Error("nested popup failure")</script>
+ <script>opener.postMessage("nested-ready", "*")</script>`;
+ if (path.startsWith("/popup"))
+ return `<script>throw new Error("popup failure")</script>
+ <script>onmessage = e => {
+ if (e.data === "nested-ready") opener.postMessage("popup-ready", "*");
+ }; window.open("/nested");</script><iframe src="/child"></iframe>`;
+ if (path.startsWith("/child")) return "child frame";
+ return `<script>onmessage = e => {
+ if (e.data === "popup-ready") document.body.dataset.ready = "true";
+ }</script><button onclick="window.open('/redirect')">Open popup</button>`;
+};
+
+const scenarioFor = (executable, origin, events) =>
+ browserScenarioSchema.parse({
+ browser: { mode: "launch", executable_path: executable },
+ start_url: { url: origin },
+ actions: [
+ {
+ step_id: "open",
+ action: "click",
+ locator: { kind: "role", role: "button", name: "Open popup" },
+ },
+ {
+ step_id: "ready",
+ action: "wait_for",
+ locator: { kind: "css", selector: "body[data-ready=true]" },
+ state: "attached",
+ timeout_ms: 10_000,
+ },
+ ],
+ capture: { events, after_each_step: [], at_end: [] },
+ });
+
+const capture = async (scenario) => {
+ const result = await new PlaywrightBrowserScenarioProvider().captureScenario(
+ scenario,
+ );
+ if (!result.ok) throw result.error;
+ assert.ok(
+ result.value.steps.every((step) => step.status === "completed"),
+ JSON.stringify(result.value.steps),
+ );
+ return result.value;
+};
+
+const assertNetwork = (result, origin) => {
+ for (const path of ["/redirect", "/popup", "/nested"])
+ for (const kind of ["request", "response"])
+ assert.equal(
+ result.events.items.filter(
+ (event) => event.kind === kind && event.url?.url === origin + path,
+ ).length,
+ 1,
+ `${kind} ${path} must be captured exactly once`,
+ );
+ assert.equal(result.completeness.equality_eligible, true);
+ assert.equal(compareWithSelf(result).overall_status, "unchanged");
+};
+
+const compareWithSelf = (capture) =>
+ compareBrowserScenarios({
+ before_scenario: capture,
+ after_scenario: capture,
+ normalization: { rules: [] },
+ });
+
+const verifySharedContext = async (executable, origin) => {
+ const browser = await chromium.launch({
+ executablePath: executable,
+ headless: true,
+ });
+ try {
+ const context = await browser.newContext();
+ const page = await context.newPage();
+ const foreign = await context.newPage();
+ const secrets = BrowserScenarioSecrets.resolve(
+ scenarioFor(executable, origin, ["network"]),
+ {},
+ );
+ assert.ok(secrets);
+ const events = new PlaywrightScenarioEvents({
+ page,
+ context,
+ ownsContext: false,
+ enabled: new Set(["network"]),
+ secrets,
+ });
+ await Promise.all([
+ page.goto(origin),
+ foreign.goto(origin + "/popup?unrelated-tab"),
+ ]);
+ await page.getByRole("button", { name: "Open popup", exact: true }).click();
+ await page.locator("body[data-ready=true]").waitFor({ timeout: 10_000 });
+ const retained = events.result().items;
+ assert.ok(
+ events
+ .limitations()
+ .some((value) => value.includes("Shared-context network")),
+ );
+ assert.ok(retained.some((event) => event.url?.url === origin + "/"));
+ assert.ok(!JSON.stringify(retained).includes("unrelated-tab"));
+ } finally {
+ await browser.close();
+ }
+};
+
+const verifyTransports = async (executable, origin) => {
+ const scenario = scenarioFor(executable, origin, ["network"]);
+ const entrypoint = fileURLToPath(new URL("../rea.mjs", import.meta.url));
+ const env = {
+ PATH: process.env.PATH ?? "/usr/bin:/bin",
+ REA_LOG_LEVEL: "silent",
+ HOPPER_LAUNCHER_PATH: "/rea-unconfigured-deep-provider/hopper",
+ };
+ const { stdout } = await promisify(execFile)(
+ process.execPath,
+ [
+ entrypoint,
+ "capture-browser-scenario",
+ JSON.stringify(scenario),
+ "--json",
+ ],
+ { env, timeout: 60_000, maxBuffer: 16 * 1024 * 1024 },
+ );
+ assertNetwork(
+ browserScenarioCaptureSchema.parse(
+ parseEvidence(JSON.parse(stdout)).normalized_result,
+ ),
+ origin,
+ );
+ const transport = new StdioClientTransport({
+ command: process.execPath,
+ args: [entrypoint, "mcp"],
+ env,
+ stderr: "pipe",
+ });
+ const client = new Client({ name: "popup-real-e2e", version: "1" });
+ try {
+ await client.connect(transport);
+ const captured = await client.callTool(
+ { name: "capture_browser_scenario", arguments: scenario },
+ { timeout: 60_000 },
+ );
+ assert.notEqual(captured.isError, true, JSON.stringify(captured));
+ const evidence = parseEvidence({
+ ...captured.structuredContent?.evidence,
+ normalized_result: captured.structuredContent?.result,
+ });
+ assertNetwork(
+ browserScenarioCaptureSchema.parse(evidence.normalized_result),
+ origin,
+ );
+ } finally {
+ try {
+ await client.close();
+ } finally {
+ await transport.close();
+ }
+ }
+};
+
+/** Verify popup timing, selection, coverage, and shared-context isolation on Chromium. */
+export async function verifyPopupEventCoverage(executable) {
+ const server = createServer((request, response) => {
+ if (request.url === "/redirect") {
+ response.writeHead(302, { Location: "/popup" });
+ response.end();
+ } else {
+ response.setHeader("Content-Type", "text/html");
+ response.end(document(request.url ?? "/"));
+ }
+ });
+ server.listen(0, "127.0.0.1");
+ await once(server, "listening");
+ try {
+ const address = server.address();
+ assert.ok(address !== null && typeof address === "object");
+ const origin = `http://127.0.0.1:${address.port}`;
+ assertNetwork(
+ await capture(scenarioFor(executable, origin, ["network"])),
+ origin,
+ );
+ const errors = await capture(
+ scenarioFor(executable, origin, ["page-errors"]),
+ );
+ assert.deepEqual(
+ errors.events.items.map((event) => event.kind),
+ ["page-error", "page-error"],
+ );
+ assert.ok(
+ errors.events.items.some((event) => event.message === "popup failure"),
+ );
+ assert.ok(
+ errors.events.items.some(
+ (event) => event.message === "nested popup failure",
+ ),
+ );
+ for (const family of ["frames", "workers", "websockets", "downloads"]) {
+ const result = await capture(scenarioFor(executable, origin, [family]));
+ assert.equal(result.completeness.equality_eligible, false);
+ assert.ok(result.completeness.missing_sections.includes("events"));
+ assert.equal(compareWithSelf(result).overall_status, "unknown");
+ assert.ok(
+ result.limitations.some((limitation) =>
+ limitation.includes(`Popup ${family}`),
+ ),
+ );
+ }
+ await verifySharedContext(executable, origin);
+ await verifyTransports(executable, origin);
+ return {
+ mocked: false,
+ initial_network: true,
+ redirects: true,
+ nested_popups: true,
+ unselected_lifecycle_absent: true,
+ popup_event_gaps_explicit: true,
+ incomplete_comparison_unknown: true,
+ shared_context_isolation: true,
+ cli: true,
+ stdio_mcp: true,
+ };
+ } finally {
+ server.closeAllConnections();
+ await new Promise((resolve, reject) =>
+ server.close((error) =>
+ error === undefined ? resolve() : reject(error),
+ ),
+ );
+ }
+}
diff --git a/scripts/verify-real-browser.mjs b/scripts/verify-real-browser.mjs
index 8abb6534e..21cfee8f9 100644
--- a/scripts/verify-real-browser.mjs
+++ b/scripts/verify-real-browser.mjs
@@ -34,6 +34,7 @@ import {
} from "./lib/browser-scenario-verifier.mjs";
import { completeVerifierRun, createVerifierRun } from "./lib/verifier-run.mjs";
import { verifyLargeScreenshotE2e } from "./lib/browser-screenshot-e2e.mjs";
+import { verifyPopupEventCoverage } from "./lib/browser-popup-e2e.mjs";
const REAL_BROWSER_STARTUP_TIMEOUT_MS = 30_000;
const SCENARIO_SECRET_VALUE = "rea-browser-verifier-secret";
@@ -318,6 +319,7 @@ try {
);
const largeScreenshot = await verifyLargeScreenshotE2e(endpoint, site.origin);
+ const popupEvents = await verifyPopupEventCoverage(executable);
process.stdout.write(
`${JSON.stringify({
verifier_run: await completeVerifierRun(verifierRun),
@@ -336,6 +338,7 @@ try {
pageScopedTransport: true,
screenshotBytes: screenshot.value.artifact.bytes,
largeScreenshot,
+ popupEvents,
browserScenarioCli: true,
browserScenarioAttachCleanup: "disconnected-external",
browserScenarioLaunchCleanup: "terminated-owned-process",
diff --git a/src/browser/BrowserScenarioSessionPort.ts b/src/browser/BrowserScenarioSessionPort.ts
index 0ccdf684d..f3120cba8 100644
--- a/src/browser/BrowserScenarioSessionPort.ts
+++ b/src/browser/BrowserScenarioSessionPort.ts
@@ -26,6 +26,8 @@ export interface BrowserScenarioSessionPort {
readonly dropped: number;
readonly items: readonly BrowserScenarioEvent[];
};
+ /** Gaps in selected event families that prevent complete capture claims. */
+ eventLimitations?(): readonly string[];
perform(action: BrowserScenarioAction, signal?: AbortSignal): Promise<void>;
capture(
requested: ReadonlySet<SnapshotKind>,
diff --git a/src/browser/PlaywrightBrowserScenarioProvider.test.ts b/src/browser/PlaywrightBrowserScenarioProvider.test.ts
index 167c71b92..e97aac402 100644
--- a/src/browser/PlaywrightBrowserScenarioProvider.test.ts
+++ b/src/browser/PlaywrightBrowserScenarioProvider.test.ts
@@ -99,6 +99,7 @@ class FakeSession implements BrowserScenarioSessionPort {
performCalls = 0;
captureCalls = 0;
onPerform: (() => void) | undefined;
+ eventGaps: readonly string[] = [];
private step = 0;
constructor(
@@ -138,6 +139,10 @@ class FakeSession implements BrowserScenarioSessionPort {
return { retained: 0, dropped: 0, items: [] };
}
+ eventLimitations(): readonly string[] {
+ return this.eventGaps;
+ }
+
async perform(_action: BrowserScenarioAction, signal?: AbortSignal) {
this.performCalls += 1;
this.onPerform?.();
@@ -184,6 +189,24 @@ class FakeSession implements BrowserScenarioSessionPort {
}
describe("PlaywrightBrowserScenarioProvider", () => {
+ 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({
+ open: () => Promise.resolve(session),
+ });
+ const result = await provider.captureScenario(
+ scenario({ events: ["frames"] }),
+ );
+ expect(result.ok).toBe(true);
+ 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({
diff --git a/src/browser/PlaywrightBrowserScenarioProvider.ts b/src/browser/PlaywrightBrowserScenarioProvider.ts
index 89e917c9a..54142a9da 100644
--- a/src/browser/PlaywrightBrowserScenarioProvider.ts
+++ b/src/browser/PlaywrightBrowserScenarioProvider.ts
@@ -234,6 +234,7 @@ const globalCompleteness = (
({ completeness }) => completeness.truncated_sections,
);
if (session.mode === "connect") missing.push("events");
+ if ((session.eventLimitations?.().length ?? 0) > 0) missing.push("events");
return classifyBrowserScenarioCompleteness(missing, truncated);
};
@@ -299,6 +300,7 @@ const runScenario = async (
"Event sequence records provider receipt order; simultaneous browser causality is not inferred.",
"Response bodies are not retained.",
"Storage values are hashed only after declared-secret redaction.",
+ ...(session.eventLimitations?.() ?? []),
...(session.mode === "connect"
? [
"CDP attachment cannot recover pre-attach events or guarantee launch-time context options.",
diff --git a/src/browser/PlaywrightScenarioEvents.ts b/src/browser/PlaywrightScenarioEvents.ts
index 2b355c586..4fa6237ca 100644
--- a/src/browser/PlaywrightScenarioEvents.ts
+++ b/src/browser/PlaywrightScenarioEvents.ts
@@ -1,4 +1,5 @@
import type {
+ BrowserContext,
ConsoleMessage,
Download,
Frame,
@@ -34,6 +35,9 @@ type UnindexedEvent = BrowserScenarioEvent extends infer Event
interface EventCaptureOptions {
readonly page: Page;
+ readonly context?: BrowserContext;
+ /** A fresh launch context is wholly owned; connected contexts can contain other tabs. */
+ readonly ownsContext?: boolean;
readonly enabled: ReadonlySet<EventName>;
readonly secrets: BrowserScenarioSecrets;
}
@@ -45,10 +49,41 @@ export class PlaywrightScenarioEvents {
private sequence = 0;
private readonly enabled: ReadonlySet<EventName>;
private readonly secrets: BrowserScenarioSecrets;
+ private readonly ownsContext: boolean;
+ private readonly pages = new Set<Page>();
+ private readonly incompleteFamilies = new Set<EventName>();
constructor(options: EventCaptureOptions) {
this.enabled = options.enabled;
this.secrets = options.secrets;
+ this.ownsContext = options.ownsContext === true;
+ this.pages.add(options.page);
+ if (this.ownsContext && this.enabled.size > 0)
+ (options.context ?? options.page.context()).on("page", (page) =>
+ this.popup(page),
+ );
+ if (this.enabled.has("network")) {
+ const context = options.context ?? options.page.context();
+ const inScope = (request: Request): boolean => {
+ if (this.ownsContext) return true;
+ try {
+ return this.pages.has(request.frame().page());
+ } catch {
+ // Initial popup navigations can lack a frame. Never guess ownership
+ // from a URL in a shared context; connect captures are attach-limited.
+ return false;
+ }
+ };
+ context.on("request", (request) => {
+ if (inScope(request)) this.request("request", request);
+ });
+ context.on("response", (response) => {
+ if (inScope(response.request())) this.response(response);
+ });
+ context.on("requestfailed", (request) => {
+ if (inScope(request)) this.request("request-failed", request);
+ });
+ }
this.observePage(options.page);
}
@@ -64,6 +99,20 @@ export class PlaywrightScenarioEvents {
return this.sequence;
}
+ /** Report selected popup event families with unrecoverable pre-discovery gaps. */
+ limitations(): readonly string[] {
+ const popupGaps = [...this.incompleteFamilies].map(
+ (family) =>
+ `Popup ${family} events before Page discovery are unavailable; later events are retained.`,
+ );
+ return this.enabled.has("network") && !this.ownsContext
+ ? [
+ "Shared-context network capture excludes requests without a known root or descendant Page frame.",
+ ...popupGaps,
+ ]
+ : popupGaps;
+ }
+
result(): {
readonly retained: number;
readonly dropped: number;
@@ -98,13 +147,6 @@ export class PlaywrightScenarioEvents {
error.stack === undefined ? null : this.secrets.redact(error.stack),
});
});
- if (this.enabled.has("network")) {
- page.on("request", (request) => this.request("request", request));
- page.on("response", (response) => this.response(response));
- page.on("requestfailed", (request) =>
- this.request("request-failed", request),
- );
- }
if (this.enabled.has("websockets"))
page.on("websocket", (socket) => this.webSocket(socket));
if (this.enabled.has("frames")) {
@@ -116,9 +158,8 @@ export class PlaywrightScenarioEvents {
}
if (this.enabled.has("workers"))
page.on("worker", (worker) => this.worker(worker));
- // Every selectable event can also be emitted by a child popup page, and a
- // popup is only reachable through this one subscription, so any selection at
- // all must observe popups. Lifecycle events stay gated on `popups` below.
+ // Any selected family needs descendant discovery in shared contexts.
+ // Popup lifecycle records remain gated on their own selector below.
if (this.enabled.size > 0) page.on("popup", (popup) => this.popup(popup));
if (this.enabled.has("downloads"))
page.on("download", (download) => this.download(download));
@@ -241,6 +282,15 @@ export class PlaywrightScenarioEvents {
}
private popup(page: Page): void {
+ if (this.pages.has(page)) return;
+ this.pages.add(page);
+ for (const family of [
+ "frames",
+ "workers",
+ "websockets",
+ "downloads",
+ ] as const)
+ if (this.enabled.has(family)) this.incompleteFamilies.add(family);
const opened = {
url: page.url() === "" ? null : this.safeUrl(page.url()),
name: null,
diff --git a/src/browser/PlaywrightScenarioSession.ts b/src/browser/PlaywrightScenarioSession.ts
index 43c81eb16..c71022f0c 100644
--- a/src/browser/PlaywrightScenarioSession.ts
+++ b/src/browser/PlaywrightScenarioSession.ts
@@ -163,6 +163,8 @@ export class PlaywrightScenarioSession implements BrowserScenarioSessionPort {
);
const events = new PlaywrightScenarioEvents({
page: opened.page,
+ context: opened.context,
+ ownsContext: scenario.browser.mode === "launch",
enabled: new Set(scenario.capture.events),
secrets,
});
@@ -212,6 +214,11 @@ export class PlaywrightScenarioSession implements BrowserScenarioSessionPort {
return this.eventCapture.result();
}
+ /** Preserve event coverage gaps for the aggregate capture's completeness. */
+ eventLimitations(): readonly string[] {
+ return this.eventCapture.limitations();
+ }
+
async perform(
action: BrowserScenarioAction,
signal?: AbortSignal,