@bugmole/cli 0.4.0

package/src/runtime/playwright-driver.ts

@@ -0,0 +1,620 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import type { Browser, BrowserContext, Locator, Page } from "playwright";
+import type { AppDriver, DriverContext, DriverPlatform, DriverResult, DriverStepResult } from "./driver.js";
+import {
+  contextOptionsFor,
+  installHint,
+  isMissingBrowserError,
+  launcherFor,
+  targetId,
+  type RunTarget,
+} from "./browser-matrix.js";
+import {
+  countFlowSteps,
+  interpolateStep,
+  describeAddressForLog,
+  describeLinkForLog,
+  describeStepForLog,
+  describeStepLabel,
+  isPatternText,
+  parseMaestroStyleFlow,
+  resolveFlowUrl,
+  type FlowStep,
+  type ParsedFlow,
+} from "./flow-language.js";
+import { analyzeFailure, rawFlowSteps, type FailureContext } from "./failure-analysis.js";
+import { createTempEmailInbox, deleteTempEmailInbox, extractFirstLink, waitForTempEmailMessage, type TempEmailInbox } from "../integrations/temp-email.js";
+
+export { parseMaestroStyleFlow } from "./flow-language.js";
+export type { FlowStep, FlowViewport, ParsedFlow } from "./flow-language.js";
+
+/**
+ * Drives web journeys with Playwright from Maestro-style flow files.
+ *
+ * Exists as the reliable alternative to the Maestro web driver, whose Beta web
+ * support can hang indefinitely on interaction commands in some environments
+ * (confirmed against Maestro's own documented example flow, both headless and
+ * headed) while Playwright drives the same pages without issue.
+ */
+
+const defaultStepTimeoutMs = 15_000;
+
+async function fileExists(target: string): Promise<boolean> {
+  try {
+    await fs.access(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Visibility as a person experiences it: rendered text, the value a person
+ * typed into a field, and the accessible name of a control they can see.
+ * Matching only rendered text would report an edited script line as missing.
+ *
+ * Authored as source text because it is evaluated inside the page, not here.
+ */
+const visibilityProbe = `(pattern, isRegex) => {
+  const matches = (value) => {
+    if (!value) return false;
+    return isRegex ? new RegExp(pattern).test(value) : value.includes(pattern);
+  };
+  const isVisible = (element) => {
+    const rect = element.getBoundingClientRect();
+    // Screen-reader-only text is clipped to a 1x1 box. It is real content for
+    // assistive technology and must not count as visible to a person, or a
+    // flow could never assert that a hidden label stayed hidden.
+    if (rect.width < 2 || rect.height < 2) return false;
+    const style = window.getComputedStyle(element);
+    if (style.visibility === "hidden" || style.display === "none" || Number(style.opacity) === 0) return false;
+    return true;
+  };
+  for (const element of Array.from(document.querySelectorAll("body *"))) {
+    if (!isVisible(element)) continue;
+    const tag = element.tagName;
+    if (tag === "INPUT" || tag === "TEXTAREA") {
+      if (matches(element.value) || matches(element.placeholder)) return true;
+    }
+    if (matches(element.getAttribute("aria-label"))) return true;
+    const ownText = Array.from(element.childNodes)
+      .filter((node) => node.nodeType === 3)
+      .map((node) => node.nodeValue || "")
+      .join("");
+    if (matches(ownText)) return true;
+  }
+  return false;
+}`;
+
+async function waitForVisibility(page: Page, text: string, shouldBeVisible: boolean, timeoutMs: number): Promise<void> {
+  const isRegex = isPatternText(text);
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    // Compiled inside the page: Playwright evaluates a bare string as an
+    // expression and drops the argument, so the probe is passed as data.
+    const visible = await page.evaluate(
+      (args: [string, string, boolean]) =>
+        (new Function(`return (${args[0]})`)() as (pattern: string, isRegex: boolean) => boolean)(args[1], args[2]),
+      [visibilityProbe, text, isRegex] as [string, string, boolean],
+    );
+    if (visible === shouldBeVisible) return;
+    if (Date.now() >= deadline) {
+      throw new Error(`Timed out after ${timeoutMs}ms waiting for "${text}" to be ${shouldBeVisible ? "visible" : "hidden"}.`);
+    }
+    await page.waitForTimeout(200);
+  }
+}
+
+/**
+ * True when an element is the actual hit-test target at its own center point
+ * -- not just painted, but reachable to a real tap. Compiled inside the page
+ * like visibilityProbe, since it references window/document that this file's
+ * lib config does not type-check. An element whose true center sits outside
+ * the viewport reports unreachable: a person would have to scroll to it
+ * first, same as here.
+ */
+const reachabilityProbe = `(element) => {
+  const rect = element.getBoundingClientRect();
+  if (rect.width < 1 || rect.height < 1) return false;
+  const style = window.getComputedStyle(element);
+  if (style.visibility === "hidden" || style.display === "none" || Number(style.opacity) === 0) return false;
+  const cx = rect.left + rect.width / 2;
+  const cy = rect.top + rect.height / 2;
+  if (cx < 0 || cx > window.innerWidth || cy < 0 || cy > window.innerHeight) return false;
+  const top = document.elementFromPoint(cx, cy);
+  return top === element || element.contains(top);
+}`;
+
+/**
+ * What a person could see on the page when a step failed: the controls and
+ * headings they could act on, any error messages, and fields that are empty
+ * or invalid. Field values are never read, only whether they are empty.
+ */
+const failureProbe = `() => {
+  const visible = (element) => {
+    const rect = element.getBoundingClientRect();
+    if (rect.width < 2 || rect.height < 2) return false;
+    const style = window.getComputedStyle(element);
+    return style.visibility !== "hidden" && style.display !== "none" && Number(style.opacity) !== 0;
+  };
+  const text = (element) => (element.innerText || element.textContent || "").replace(/\\s+/g, " ").trim();
+  const labelOf = (field) => {
+    const own = field.labels && field.labels[0] ? text(field.labels[0]) : "";
+    return own || field.getAttribute("aria-label") || field.getAttribute("placeholder") || field.getAttribute("name") || "";
+  };
+  const seen = new Set();
+  const candidates = [];
+  const add = (role, value) => {
+    const clean = (value || "").replace(/\\s+/g, " ").trim();
+    if (!clean || clean.length > 80 || seen.has(role + clean)) return;
+    seen.add(role + clean);
+    candidates.push({ role, text: clean });
+  };
+  for (const element of document.querySelectorAll("button, [role=button], input[type=submit]")) {
+    if (visible(element)) add("button", text(element) || element.getAttribute("aria-label") || element.value);
+  }
+  for (const element of document.querySelectorAll("a[href]")) if (visible(element)) add("link", text(element) || element.getAttribute("aria-label"));
+  for (const element of document.querySelectorAll("h1, h2, h3")) if (visible(element)) add("heading", text(element));
+  const invalidFields = [];
+  for (const field of document.querySelectorAll("input, textarea, select")) {
+    if (!visible(field) || field.type === "hidden") continue;
+    const label = labelOf(field);
+    if (label) add("field", label);
+    const empty = !field.value;
+    const invalid = field.getAttribute("aria-invalid") === "true" || (typeof field.matches === "function" && field.matches(":invalid"));
+    if (label && (invalid || (empty && field.required))) invalidFields.push({ label, type: field.type || field.tagName.toLowerCase(), empty });
+  }
+  const alerts = [];
+  for (const element of document.querySelectorAll("[role=alert], [aria-live=assertive], [aria-live=polite], .error, .invalid-feedback, [class*=error], [data-error]")) {
+    const message = text(element);
+    if (visible(element) && message && message.length <= 160 && !alerts.includes(message)) alerts.push(message);
+  }
+  return { url: location.href, title: document.title, candidates: candidates.slice(0, 80), alerts: alerts.slice(0, 10), invalidFields: invalidFields.slice(0, 10) };
+}`;
+
+/**
+ * Polls waitForClickable's target until it is reachable. Catches a real bug
+ * class assertVisible cannot -- an unrelated fixed-position element (a
+ * mascot, a floating action button, a toast) sitting on top of a link or
+ * button and silently swallowing the tap.
+ */
+async function waitForClickable(page: Page, locator: Locator, text: string, timeoutMs: number): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    const handle = await locator.elementHandle({ timeout: 1_000 }).catch(() => null);
+    const reachable = handle
+      ? await page
+          .evaluate(
+            (args: [string, unknown]) => (new Function("element", `return (${args[0]})(element)`))(args[1]) as boolean,
+            [reachabilityProbe, handle] as [string, unknown],
+          )
+          .catch(() => false)
+      : false;
+    await handle?.dispose().catch(() => undefined);
+    if (reachable) return;
+    if (Date.now() >= deadline) {
+      throw new Error(`"${text}" did not become clickable within ${timeoutMs}ms -- it is either off-screen or something else is on top of it.`);
+    }
+    await page.waitForTimeout(200);
+  }
+}
+
+/**
+ * Candidate locators in the order a person resolves a target: the control they
+ * can name, then the field labelled that way, then anything reading that way.
+ */
+/** Playwright needs its own ffmpeg build to write a video; nothing else does. */
+export function isMissingVideoEncoder(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error);
+  return /ffmpeg/i.test(message) && /doesn't exist|not found|ENOENT|requires ffmpeg/i.test(message);
+}
+
+function tapCandidates(page: Page, text: string): Locator[] {
+  const matcher = isPatternText(text) ? new RegExp(text) : text;
+  return [
+    page.getByRole("button", { name: matcher }),
+    page.getByRole("link", { name: matcher }),
+    page.getByLabel(matcher),
+    page.getByPlaceholder(matcher),
+    page.getByText(matcher, { exact: false }),
+  ];
+}
+
+async function resolveTapTarget(page: Page, text: string, index: number): Promise<Locator | null> {
+  for (const candidate of tapCandidates(page, text)) {
+    if ((await candidate.count()) > index) return candidate.nth(index);
+  }
+  return null;
+}
+
+export type PlaywrightDriverOptions = {
+  headless?: boolean;
+};
+
+export class PlaywrightDriver implements AppDriver {
+  readonly id = "playwright";
+  private readonly headless: boolean;
+
+  constructor(options: PlaywrightDriverOptions = {}) {
+    this.headless = options.headless ?? true;
+  }
+
+  supports(platform: DriverPlatform): boolean {
+    return platform === "web";
+  }
+
+  async run(context: DriverContext): Promise<DriverResult> {
+    const startedAt = Date.now();
+    const result = await this.runFlow(context);
+    return { ...result, durationMs: Date.now() - startedAt };
+  }
+
+  private async runFlow(context: DriverContext): Promise<DriverResult> {
+    if (!this.supports(context.platform)) {
+      return {
+        status: "blocked",
+        message: `Playwright driver does not support platform "${context.platform}".`,
+        artifacts: [],
+        failureCode: "unsupported_platform",
+      };
+    }
+
+    const target: RunTarget = context.runTarget ?? { id: targetId("chromium"), browser: "chromium" };
+    const emulation = contextOptionsFor(target);
+    if ("unsupported" in emulation) {
+      return { status: "blocked", message: emulation.unsupported, artifacts: [], failureCode: "unsupported_target" };
+    }
+
+    let flow: ParsedFlow;
+    let flowContent = "";
+    try {
+      const content = await fs.readFile(context.flowPath, "utf8");
+      flowContent = content;
+      flow = parseMaestroStyleFlow(content, context.target.baseUrl, { rebaseOrigin: context.rebaseOrigin });
+    } catch (error) {
+      return {
+        status: "blocked",
+        message: error instanceof Error ? error.message : "Failed to read/parse flow file.",
+        artifacts: [],
+        failureCode: "invalid_flow",
+      };
+    }
+
+    // Each target gets its own directory: targets of one run execute
+    // concurrently and would otherwise overwrite each other's evidence.
+    const artifactsDir = context.runTarget
+      ? path.join(context.artifactsDir, context.projectId, context.runId, context.journeyId, target.id)
+      : path.join(context.artifactsDir, context.projectId, context.runId, context.journeyId);
+    const videoDir = path.join(artifactsDir, "video");
+    await fs.mkdir(videoDir, { recursive: true });
+    const log: string[] = [];
+    const steps: DriverStepResult[] = [];
+    const pageErrors: string[] = [];
+    const consoleErrors: string[] = [];
+    const screenshots: { path: string; name: string }[] = [];
+    // Populated by requestTempEmail and consumed by interpolateStep/openEmailLink.
+    // Inboxes are deleted best-effort in the outer finally below, whether the
+    // flow passed or failed.
+    const flowContext: Record<string, string> = {};
+    const flowInboxes: Record<string, TempEmailInbox> = {};
+    const totalSteps = countFlowSteps(flow.steps);
+    const stepTimeoutMs = Math.min(context.timeoutMs, defaultStepTimeoutMs);
+    let browser: Browser | undefined;
+    let browserContext: BrowserContext | undefined;
+    let currentStepStartedAt: number | undefined;
+
+    const writeLog = async () => {
+      const logPath = path.join(artifactsDir, "playwright.log");
+      await fs.writeFile(logPath, log.join("\n"), "utf8").catch(() => undefined);
+      return logPath;
+    };
+    const stopTrace = async (): Promise<string | undefined> => {
+      if (!browserContext) return undefined;
+      const tracePath = path.join(artifactsDir, "playwright-trace.zip");
+      try {
+        await browserContext.tracing.stop({ path: tracePath });
+        return tracePath;
+      } catch {
+        return undefined;
+      }
+    };
+
+    try {
+      const launcher = launcherFor(target.browser);
+      try {
+        browser = await launcher.type.launch({ headless: this.headless, ...(launcher.channel ? { channel: launcher.channel } : {}) });
+      } catch (error) {
+        if (!isMissingBrowserError(error)) throw error;
+        const hint = installHint(target.browser);
+        log.push(hint);
+        return {
+          status: "blocked",
+          message: hint,
+          artifacts: [{ path: await writeLog(), contentType: "text/plain", name: "playwright.log" }],
+          failureCode: "browser_not_installed",
+        };
+      }
+      const storageState = context.sessionStatePath && (await fileExists(context.sessionStatePath)) ? context.sessionStatePath : undefined;
+      // Record at the page's real size; Playwright's default shrinks to 800px.
+      const videoSize = flow.viewport ?? emulation.options.viewport ?? { width: 1280, height: 720 };
+      const contextOptions = {
+        ...emulation.options,
+        storageState,
+        ...(flow.viewport ? { viewport: flow.viewport } : {}),
+      };
+      const openContext = async (withVideo: boolean) => {
+        const opened = await browser!.newContext(
+          withVideo ? { ...contextOptions, recordVideo: { dir: videoDir, size: videoSize } } : contextOptions,
+        );
+        // The trace is the step-by-step record a person opens to debug a run.
+        await opened.tracing.start({ screenshots: true, snapshots: true }).catch(() => undefined);
+        return opened;
+      };
+      browserContext = await openContext(true);
+      let page: Page;
+      try {
+        page = await browserContext.newPage();
+      } catch (error) {
+        // A worker without Playwright's ffmpeg can still run the test; it just
+        // can't record video. Losing the video beats losing the whole run.
+        if (!isMissingVideoEncoder(error)) throw error;
+        log.push("NOTE: no video recorded — Playwright's ffmpeg is missing. Run `npx playwright install ffmpeg` on this worker to record video.");
+        await browserContext.close().catch(() => undefined);
+        browserContext = await openContext(false);
+        page = await browserContext.newPage();
+      }
+      page.setDefaultTimeout(stepTimeoutMs);
+      page.on("pageerror", (error) => {
+        pageErrors.push(error.message);
+        log.push(`PAGE ERROR: ${error.message}`);
+      });
+      page.on("console", (message) => {
+        if (message.type() === "error") {
+          log.push(`CONSOLE ERROR: ${message.text()}`);
+          consoleErrors.push(message.text());
+        }
+      });
+
+      const capture = async (name: string) => {
+        const screenshotPath = path.join(artifactsDir, `${name.replace(/[^a-z0-9_-]+/gi, "-")}.png`);
+        await page.screenshot({ path: screenshotPath, fullPage: true });
+        screenshots.push({ path: screenshotPath, name: path.basename(screenshotPath) });
+        return screenshotPath;
+      };
+
+      const runStep = async (rawStep: FlowStep): Promise<void> => {
+        const step = interpolateStep(rawStep, flowContext);
+        switch (step.type) {
+          case "launchApp":
+            await page.goto(flow.url, { waitUntil: "load" });
+            return;
+          case "stopApp":
+            await page.goto("about:blank");
+            return;
+          case "openLink":
+            await page.goto(resolveFlowUrl(step.url, flow.url, flow.rebasedFrom, flow.rebasedOnto), { waitUntil: "load" });
+            return;
+          case "tapOn": {
+            const target = await resolveTapTarget(page, step.text, step.index);
+            if (!target) {
+              if (step.optional) {
+                log.push(`Skipped optional tapOn "${step.text}" (no match).`);
+                return;
+              }
+              throw new Error(`No element matching "${step.text}" at index ${step.index}.`);
+            }
+            await target.scrollIntoViewIfNeeded();
+            await target.click();
+            return;
+          }
+          case "inputText":
+            await page.keyboard.type(step.text);
+            return;
+          case "eraseText":
+            // Clears the focused field the way a person would: select all, delete.
+            await page.keyboard.press("ControlOrMeta+a");
+            await page.keyboard.press("Delete");
+            return;
+          case "pressKey":
+            await page.keyboard.press(step.key);
+            return;
+          case "assertVisible":
+            await waitForVisibility(page, step.text, true, step.timeoutMs ?? stepTimeoutMs);
+            return;
+          case "assertNotVisible":
+            await waitForVisibility(page, step.text, false, step.timeoutMs ?? stepTimeoutMs);
+            return;
+          case "assertClickable": {
+            const target = await resolveTapTarget(page, step.text, step.index);
+            if (!target) throw new Error(`No element matching "${step.text}" at index ${step.index}.`);
+            await waitForClickable(page, target, step.text, step.timeoutMs ?? stepTimeoutMs);
+            return;
+          }
+          case "scrollUntilVisible": {
+            const target = await resolveTapTarget(page, step.text, 0);
+            if (!target) throw new Error(`No element matching "${step.text}" to scroll to.`);
+            await target.scrollIntoViewIfNeeded();
+            return;
+          }
+          case "wait":
+            await page.waitForTimeout(step.ms);
+            return;
+          case "takeScreenshot":
+            await capture(step.name);
+            return;
+          case "retry": {
+            let lastError: unknown;
+            for (let attempt = 0; attempt <= step.maxRetries; attempt += 1) {
+              try {
+                for (const inner of step.steps) await runStep(inner);
+                return;
+              } catch (error) {
+                lastError = error;
+                log.push(`Retry attempt ${attempt + 1} failed: ${error instanceof Error ? error.message : String(error)}`);
+              }
+            }
+            throw lastError instanceof Error ? lastError : new Error("Retry block failed.");
+          }
+          case "requestTempEmail": {
+            const inbox = await createTempEmailInbox();
+            flowContext[step.as] = inbox.address;
+            flowInboxes[step.as] = inbox;
+            log.push(`Requested temp email inbox "${step.as}": ${describeAddressForLog(inbox.address)}`);
+            return;
+          }
+          case "openEmailLink": {
+            const inbox = flowInboxes[step.as];
+            if (!inbox) {
+              throw new Error(`openEmailLink references inbox "${step.as}", but no requestTempEmail step bound that name yet.`);
+            }
+            const message = await waitForTempEmailMessage(inbox, {
+              from: step.from,
+              subject: step.subject,
+              timeoutMs: step.timeoutMs ?? stepTimeoutMs,
+            });
+            const link = extractFirstLink(message, step.match);
+            log.push(`openEmailLink: message "${message.subject}" from ${message.from} -> ${describeLinkForLog(link)}`);
+            await page.goto(link, { waitUntil: "load" });
+            return;
+          }
+        }
+      };
+
+      for (const [index, step] of flow.steps.entries()) {
+        const stepStartedAt = Date.now();
+        currentStepStartedAt = stepStartedAt;
+        log.push(`Step ${index + 1}: ${describeStepForLog(step)}`);
+        await runStep(step);
+        steps.push({
+          sequenceNumber: index,
+          status: "passed",
+          label: describeStepLabel(step),
+          message: describeStepForLog(step),
+          durationMs: Date.now() - stepStartedAt,
+          timestamp: new Date().toISOString(),
+        });
+      }
+
+      const finalScreenshot = await capture("playwright-final");
+      if (context.sessionStatePath) await browserContext.storageState({ path: context.sessionStatePath });
+      const tracePath = await stopTrace();
+      const logPath = await writeLog();
+      const videoPath = await page.video()?.path();
+      await browserContext.close();
+      browserContext = undefined;
+
+      const artifacts = [
+        ...screenshots.map((shot) => ({ path: shot.path, contentType: "image/png", name: shot.name })),
+        { path: logPath, contentType: "text/plain", name: "playwright.log" },
+        ...(tracePath ? [{ path: tracePath, contentType: "application/zip", name: "playwright-trace.zip" }] : []),
+        ...(videoPath ? [{ path: videoPath, contentType: "video/webm", name: "playwright-run.webm" }] : []),
+      ];
+
+      // An uncaught page error means the journey crashed the app, whatever the
+      // assertions said; reporting it as passed would be false evidence.
+      if (pageErrors.length > 0 && !flow.ignorePageErrors) {
+        return {
+          status: "failed",
+          message: `Flow steps completed but the page raised ${pageErrors.length} uncaught error(s): ${pageErrors[0]}`,
+          artifacts,
+          recoverable: true,
+          failureCode: "page_error",
+          steps,
+        };
+      }
+
+      return {
+        status: "passed",
+        message: `Playwright flow completed (${totalSteps} step(s)); final screenshot at ${finalScreenshot}.`,
+        artifacts,
+        steps,
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Playwright flow failed.";
+      log.push(`ERROR: ${message}`);
+      // The step whose action threw failed; steps after it never ran and must
+      // not be reported as either passed or failed.
+      const failedStepIndex = steps.length;
+      steps.push({
+        sequenceNumber: failedStepIndex,
+        status: "failed",
+        ...(failedStepIndex < flow.steps.length ? { label: describeStepLabel(flow.steps[failedStepIndex]) } : {}),
+        message,
+        ...(currentStepStartedAt !== undefined ? { durationMs: Date.now() - currentStepStartedAt } : {}),
+        timestamp: new Date().toISOString(),
+      });
+      for (let index = steps.length; index < flow.steps.length; index += 1) {
+        steps.push({ sequenceNumber: index, status: "blocked", label: describeStepLabel(flow.steps[index]), message: "Not reached; an earlier step failed." });
+      }
+      const artifacts: DriverResult["artifacts"] = [];
+      try {
+        const failurePage = browserContext?.pages()[0];
+        if (failurePage && failedStepIndex < flow.steps.length) {
+          // Evidence for the analysis: what was on screen when the step failed.
+          const snapshot = await failurePage
+            .evaluate((source: string) => (new Function(`return (${source})`)() as () => unknown)(), failureProbe)
+            .catch(() => null) as Omit<FailureContext, "failedStepIndex" | "error" | "pageErrors" | "consoleErrors"> | null;
+          const failureContext: FailureContext = {
+            url: snapshot?.url,
+            title: snapshot?.title,
+            failedStepIndex,
+            failedStep: describeStepForLog(flow.steps[failedStepIndex]),
+            error: message,
+            pageErrors: [...pageErrors],
+            consoleErrors: consoleErrors.slice(0, 10),
+            candidates: snapshot?.candidates ?? [],
+            alerts: snapshot?.alerts ?? [],
+            invalidFields: snapshot?.invalidFields ?? [],
+          };
+          const contextPath = path.join(artifactsDir, "failure-context.json");
+          await fs.writeFile(contextPath, `${JSON.stringify(failureContext, null, 2)}\n`, "utf8");
+          artifacts.push({ path: contextPath, contentType: "application/json", name: "failure-context.json" });
+          try {
+            const analysis = analyzeFailure(flow.steps, rawFlowSteps(flowContent), failureContext);
+            const analysisPath = path.join(artifactsDir, "analysis.json");
+            await fs.writeFile(analysisPath, `${JSON.stringify(analysis, null, 2)}\n`, "utf8");
+            artifacts.push({ path: analysisPath, contentType: "application/json", name: "analysis.json" });
+            log.push(`ANALYSIS: ${analysis.title}`);
+          } catch (analysisError) {
+            log.push(`Analysis unavailable: ${analysisError instanceof Error ? analysisError.message : String(analysisError)}`);
+          }
+        }
+        if (failurePage) {
+          const failurePath = path.join(artifactsDir, "playwright-failure.png");
+          await failurePage.screenshot({ path: failurePath, fullPage: true });
+          artifacts.push({ path: failurePath, contentType: "image/png", name: "playwright-failure.png" });
+        }
+      } catch {
+        // A failure screenshot is best-effort; the error itself is captured below.
+      }
+      if (pageErrors.length > 0) log.push(`Uncaught page errors: ${pageErrors.join(" | ")}`);
+      const tracePath = await stopTrace();
+      if (tracePath) artifacts.push({ path: tracePath, contentType: "application/zip", name: "playwright-trace.zip" });
+      artifacts.push({ path: await writeLog(), contentType: "text/plain", name: "playwright.log" });
+      try {
+        const videoPath = await browserContext?.pages()[0]?.video()?.path();
+        await browserContext?.close();
+        browserContext = undefined;
+        if (videoPath) artifacts.push({ path: videoPath, contentType: "video/webm", name: "playwright-run.webm" });
+      } catch {
+        // Video finalization is best-effort; the run's failure is already captured above.
+      }
+      return {
+        status: "failed",
+        message,
+        artifacts,
+        recoverable: true,
+        failureCode: "flow_failed",
+        steps,
+      };
+    } finally {
+      await browserContext?.close().catch(() => undefined);
+      await browser?.close();
+      // Every requestTempEmail inbox gets deleted here, whether the flow
+      // passed or failed -- these are disposable by design and a QA run
+      // should not accumulate live mail.tm accounts every time it executes.
+      await Promise.all(Object.values(flowInboxes).map((inbox) => deleteTempEmailInbox(inbox)));
+    }
+  }
+}