Improve frontend test framework (#22824)

* add error allowlist file for error collector

* add error collector for console + page + request errors

* wire error collector into frigateApp fixture

* add self-tests for error collector fixture

* gate strict error mode on E2E_STRICT_ERRORS=1

* triage pre-existing errors and seed allowlist

* add mockEmpty/mockError/mockDelay helpers for state-driven tests

* add self-tests for mock override helpers

* add mobile affordance helpers to BasePage

* add lint script for banned spec patterns and @mobile rule

* apply prettier fixes to new e2e files

* rewrite export.spec.ts

* clean up

* move export spec rewrite and bugfix to separate branch

web/e2e/fixtures/error-allowlist.ts

@@ -0,0 +1,116 @@
+/**
+ * Global allowlist of regex patterns that the error collector ignores.
+ *
+ * Each entry MUST include a comment explaining what it silences and why.
+ * The allowlist is filtered at collection time, so failure messages list
+ * only unfiltered errors.
+ *
+ * Per-spec additions go through the `expectedErrors` test fixture parameter
+ * (see error-collector.ts), not by editing this file. That keeps allowlist
+ * drift visible per-PR rather than buried in shared infrastructure.
+ *
+ * NOTE ON CONSOLE vs REQUEST ERRORS:
+ * When a network request returns a 5xx response, the browser emits two
+ * events that the error collector captures:
+ *   [request] "500 Internal Server Error <url>"  — from onResponse (URL included)
+ *   [console] "Failed to load resource: ..."     — from onConsole (URL NOT included)
+ *
+ * The request-level message includes the URL, so those patterns are specific.
+ * The console-level message text (from ConsoleMessage.text()) does NOT include
+ * the URL — the URL is stored separately in e.url. Therefore the console
+ * pattern for HTTP 500s cannot be URL-discriminated, and a single pattern
+ * covers all such browser echoes. This is safe because every such console
+ * error is already caught (and specifically matched) by its paired [request]
+ * entry below.
+ */
+
+export const GLOBAL_ALLOWLIST: RegExp[] = [
+  // -------------------------------------------------------------------------
+  // Browser echo of HTTP 5xx responses (console mirror of [request] events).
+  //
+  // Whenever the browser receives a 5xx response it emits a console error:
+  //   "Failed to load resource: the server responded with a status of 500
+  //    (Internal Server Error)"
+  // The URL is NOT part of ConsoleMessage.text() — it is stored separately.
+  // Every console error of this form is therefore paired with a specific
+  // [request] 500 entry below that names the exact endpoint. Allowlisting
+  // this pattern here silences the browser echo; the request-level entries
+  // enforce specificity.
+  // -------------------------------------------------------------------------
+  /Failed to load resource: the server responded with a status of 500/,
+
+  // -------------------------------------------------------------------------
+  // Mock infrastructure gaps — API endpoints not yet covered by ApiMocker.
+  //
+  // These produce 500s because Vite's preview server has no handler for them.
+  // Each is a TODO(real-bug): the mock should be extended so these endpoints
+  // return sensible fixture data in tests.
+  //
+  // Only [request] patterns are listed here; the paired [console] mirror is
+  // covered by the "Failed to load resource" entry above.
+  // -------------------------------------------------------------------------
+
+  // TODO(real-bug): ApiMocker registers "**/api/reviews**" (plural) but the
+  // app fetches /api/review (singular) for the review list and timeline.
+  // Affects: review.spec.ts, navigation.spec.ts, live.spec.ts, auth.spec.ts.
+  // Fix: add route handlers for /api/review and /api/review/** in api-mocker.ts.
+  /500 Internal Server Error.*\/api\/review(\?|\/|$)/,
+
+  // TODO(real-bug): /api/stats/history is not mocked; the system page fetches
+  // it for the detector/process history charts.
+  // Fix: add route handler for /api/stats/history in api-mocker.ts.
+  /500 Internal Server Error.*\/api\/stats\/history/,
+
+  // TODO(real-bug): /api/event_ids is not mocked; the explore/search page
+  // fetches it to resolve event IDs for display.
+  // Fix: add route handler for /api/event_ids in api-mocker.ts.
+  /500 Internal Server Error.*\/api\/event_ids/,
+
+  // TODO(real-bug): /api/sub_labels?split_joined=1 returns 500; the mock
+  // registers "**/api/sub_labels" which may not match when a query string is
+  // present, or route registration order causes the catch-all to win first.
+  // Fix: change the mock route to "**/api/sub_labels**" in api-mocker.ts.
+  /500 Internal Server Error.*\/api\/sub_labels/,
+
+  // TODO(real-bug): MediaMocker handles /api/*/latest.jpg but the app also
+  // requests /api/*/latest.webp (webp format) for camera snapshots.
+  // Affects: live.spec.ts, review.spec.ts, auth.spec.ts, navigation.spec.ts.
+  // Fix: add route handler for /api/*/latest.webp in MediaMocker.install().
+  /500 Internal Server Error.*\/api\/[^/]+\/latest\.webp/,
+  /failed: net::ERR_ABORTED.*\/api\/[^/]+\/latest\.webp/,
+
+  // -------------------------------------------------------------------------
+  // Mock infrastructure gap — WebSocket streams.
+  //
+  // Playwright's page.route() does not intercept WebSocket connections.
+  // The jsmpeg live-stream WS connections to /live/jsmpeg/* always fail
+  // with a 500 handshake error because the Vite preview server has no WS
+  // handler. TODO(real-bug): add WsMocker support for jsmpeg WebSocket
+  // connections, or suppress the connection attempt in the test environment.
+  // Affects: live.spec.ts (single camera view), auth.spec.ts.
+  // -------------------------------------------------------------------------
+  /WebSocket connection to '.*\/live\/jsmpeg\/.*' failed/,
+
+  // -------------------------------------------------------------------------
+  // Benign — lazy-loaded chunk aborts during navigation.
+  //
+  // When a test navigates away from a page while the browser is still
+  // fetching lazily-split JS/CSS asset chunks, the in-flight fetch is
+  // cancelled (net::ERR_ABORTED). This is normal browser behaviour on
+  // navigation and does not indicate a real error; the assets load fine
+  // on a stable connection.
+  // -------------------------------------------------------------------------
+  /failed: net::ERR_ABORTED.*\/assets\//,
+
+  // -------------------------------------------------------------------------
+  // Real app bug — Radix UI DialogContent missing accessible title.
+  //
+  // TODO(real-bug): A dialog somewhere in the app renders <DialogContent>
+  // without a <DialogTitle>, violating Radix UI's accessibility contract.
+  // The warning originates from the bundled main-*.js. Investigate which
+  // dialog component is missing the title and add a VisuallyHidden DialogTitle.
+  // Likely candidate: face-library or search-detail dialog in explore page.
+  // See: https://radix-ui.com/primitives/docs/components/dialog
+  // -------------------------------------------------------------------------
+  /`DialogContent` requires a `DialogTitle`/,
+];

web/e2e/fixtures/error-collector.ts

@@ -0,0 +1,122 @@
+/**
+ * Collects console errors, page errors, and failed network requests
+ * during a Playwright test, with regex-based allowlist filtering.
+ *
+ * Usage:
+ *   const collector = installErrorCollector(page, [...GLOBAL_ALLOWLIST]);
+ *   // ... run test ...
+ *   collector.assertClean();   // throws if any non-allowlisted error
+ *
+ * The collector is wired into the `frigateApp` fixture so every test
+ * gets it for free. Tests that intentionally trigger an error pass
+ * additional regexes via the `expectedErrors` fixture parameter.
+ */
+
+import type { Page, Request, Response, ConsoleMessage } from "@playwright/test";
+
+export type CollectedError = {
+  kind: "console" | "pageerror" | "request";
+  message: string;
+  url?: string;
+  stack?: string;
+};
+
+export type ErrorCollector = {
+  errors: CollectedError[];
+  assertClean(): void;
+};
+
+function isAllowlisted(message: string, allowlist: RegExp[]): boolean {
+  return allowlist.some((pattern) => pattern.test(message));
+}
+
+function firstStackFrame(stack: string | undefined): string | undefined {
+  if (!stack) return undefined;
+  const lines = stack
+    .split("\n")
+    .map((l) => l.trim())
+    .filter(Boolean);
+  // Skip the error message line (line 0); return the first "at ..." frame
+  return lines.find((l) => l.startsWith("at "));
+}
+
+function isSameOrigin(url: string, baseURL: string | undefined): boolean {
+  if (!baseURL) return true;
+  try {
+    return new URL(url).origin === new URL(baseURL).origin;
+  } catch {
+    return false;
+  }
+}
+
+export function installErrorCollector(
+  page: Page,
+  allowlist: RegExp[],
+): ErrorCollector {
+  const errors: CollectedError[] = [];
+  const baseURL = (
+    page.context() as unknown as { _options?: { baseURL?: string } }
+  )._options?.baseURL;
+
+  const onConsole = (msg: ConsoleMessage) => {
+    if (msg.type() !== "error") return;
+    const text = msg.text();
+    if (isAllowlisted(text, allowlist)) return;
+    errors.push({
+      kind: "console",
+      message: text,
+      url: msg.location().url,
+    });
+  };
+
+  const onPageError = (err: Error) => {
+    const text = err.message;
+    if (isAllowlisted(text, allowlist)) return;
+    errors.push({
+      kind: "pageerror",
+      message: text,
+      stack: firstStackFrame(err.stack),
+    });
+  };
+
+  const onResponse = (response: Response) => {
+    const status = response.status();
+    if (status < 500) return;
+    const url = response.url();
+    if (!isSameOrigin(url, baseURL)) return;
+    const text = `${status} ${response.statusText()} ${url}`;
+    if (isAllowlisted(text, allowlist)) return;
+    errors.push({ kind: "request", message: text, url });
+  };
+
+  const onRequestFailed = (request: Request) => {
+    const url = request.url();
+    if (!isSameOrigin(url, baseURL)) return;
+    const failure = request.failure();
+    const text = `failed: ${failure?.errorText ?? "unknown"} ${url}`;
+    if (isAllowlisted(text, allowlist)) return;
+    errors.push({ kind: "request", message: text, url });
+  };
+
+  page.on("console", onConsole);
+  page.on("pageerror", onPageError);
+  page.on("response", onResponse);
+  page.on("requestfailed", onRequestFailed);
+
+  return {
+    errors,
+    assertClean() {
+      if (errors.length === 0) return;
+      const formatted = errors
+        .map((e, i) => {
+          const stack = e.stack ? `\n      ${e.stack}` : "";
+          const url = e.url && e.url !== e.message ? ` (${e.url})` : "";
+          return `  ${i + 1}. [${e.kind}] ${e.message}${url}${stack}`;
+        })
+        .join("\n");
+      throw new Error(
+        `Page emitted ${errors.length} unexpected error${errors.length === 1 ? "" : "s"}:\n${formatted}`,
+      );
+    },
+  };
+}

web/e2e/fixtures/frigate-test.ts

@@ -6,6 +6,11 @@
  * @playwright/test directly. The `frigateApp` fixture provides a
  * fully mocked Frigate frontend ready for interaction.
  *
+ * The fixture also installs the error collector (see error-collector.ts).
+ * Any console error, page error, or same-origin failed request that is
+ * not on the global allowlist or the test's `expectedErrors` list will
+ * fail the test in the fixture's teardown.
+ *
  * CRITICAL: All route/WS handlers are registered before page.goto()
  * to prevent AuthProvider from redirecting to login.html.
  */
@@ -17,6 +22,8 @@ import {
   type ApiMockOverrides,
 } from "../helpers/api-mocker";
 import { WsMocker } from "../helpers/ws-mocker";
+import { installErrorCollector, type ErrorCollector } from "./error-collector";
+import { GLOBAL_ALLOWLIST } from "./error-allowlist";
 
 export class FrigateApp {
   public api: ApiMocker;
@@ -67,10 +74,43 @@ export class FrigateApp {
 
 type FrigateFixtures = {
   frigateApp: FrigateApp;
+  /**
+   * Per-test additional allowlist regex patterns. Tests that intentionally
+   * trigger errors (e.g. error-state tests that hit a mocked 500) declare
+   * their expected errors here so the collector ignores them.
+   *
+   * Default is `[]` — most tests should not need this.
+   */
+  expectedErrors: RegExp[];
+  errorCollector: ErrorCollector;
 };
 
 export const test = base.extend<FrigateFixtures>({
-  frigateApp: async ({ page }, use, testInfo) => {
+  expectedErrors: [[], { option: true }],
+
+  errorCollector: async ({ page, expectedErrors }, use, testInfo) => {
+    const collector = installErrorCollector(page, [
+      ...GLOBAL_ALLOWLIST,
+      ...expectedErrors,
+    ]);
+    await use(collector);
+    if (process.env.E2E_STRICT_ERRORS === "1") {
+      collector.assertClean();
+    } else if (collector.errors.length > 0) {
+      // Soft mode: attach errors to the test report so they're visible
+      // without failing the run.
+      await testInfo.attach("collected-errors.txt", {
+        body: collector.errors
+          .map((e) => `[${e.kind}] ${e.message}${e.url ? ` (${e.url})` : ""}`)
+          .join("\n"),
+        contentType: "text/plain",
+      });
+    }
+  },
+
+  frigateApp: async ({ page, errorCollector }, use, testInfo) => {
+    // Reference the collector so its `use()` runs and teardown fires
+    void errorCollector;
     const app = new FrigateApp(page, testInfo.project.name);
     await app.installDefaults();
     await use(app);

web/e2e/helpers/mock-overrides.ts

@@ -0,0 +1,56 @@
+/**
+ * Per-test mock overrides for driving empty / loading / error states.
+ *
+ * Playwright route handlers are LIFO: the most recently registered handler
+ * matching a URL takes precedence. The frigateApp fixture installs default
+ * mocks before the test body runs, so these helpers — called inside the
+ * test body — register AFTER the defaults and therefore win.
+ *
+ * Always call these BEFORE the navigation that triggers the request.
+ *
+ * Example:
+ *   await mockEmpty(page, "**\/api\/exports**");
+ *   await frigateApp.goto("/export");
+ *   // Page now renders the empty state
+ */
+
+import type { Page } from "@playwright/test";
+
+/** Return an empty array for the matched endpoint. */
+export async function mockEmpty(
+  page: Page,
+  urlPattern: string | RegExp,
+): Promise<void> {
+  await page.route(urlPattern, (route) => route.fulfill({ json: [] }));
+}
+
+/** Return an HTTP error for the matched endpoint. Default status 500. */
+export async function mockError(
+  page: Page,
+  urlPattern: string | RegExp,
+  status = 500,
+): Promise<void> {
+  await page.route(urlPattern, (route) =>
+    route.fulfill({
+      status,
+      json: { success: false, message: "Mocked error" },
+    }),
+  );
+}
+
+/**
+ * Delay the response by `ms` milliseconds before fulfilling with the
+ * provided body. Use to assert loading-state UI is visible during the
+ * delay window.
+ */
+export async function mockDelay(
+  page: Page,
+  urlPattern: string | RegExp,
+  ms: number,
+  body: unknown = [],
+): Promise<void> {
+  await page.route(urlPattern, async (route) => {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+    await route.fulfill({ json: body });
+  });
+}

web/e2e/pages/base.page.ts

@@ -79,4 +79,57 @@ export class BasePage {
   async waitForPageLoad() {
     await this.page.waitForSelector("#pageRoot", { timeout: 10_000 });
   }
+
+  /**
+   * Open the mobile-only export pane / sheet that slides up from the
+   * bottom on the export page. No-op on desktop. Returns the pane locator
+   * so the caller can assert against its contents.
+   */
+  async openMobilePane(): Promise<Locator> {
+    if (this.isDesktop) {
+      // Return the desktop equivalent (the main content area itself)
+      return this.pageRoot;
+    }
+    // Look for any element that opens a sheet/dialog on tap.
+    // Specific views override this with their own selector.
+    const pane = this.page.locator('[role="dialog"]').first();
+    return pane;
+  }
+
+  /**
+   * Open a side drawer (e.g. mobile filter drawer). View-specific page
+   * objects should override this with their actual trigger selector.
+   * The default implementation looks for a button labelled "Open menu"
+   * or "Filters" and clicks it, then returns the drawer locator.
+   */
+  async openDrawer(): Promise<Locator> {
+    if (this.isDesktop) {
+      return this.pageRoot;
+    }
+    const trigger = this.page
+      .getByRole("button", { name: /menu|filter/i })
+      .first();
+    if (await trigger.count()) {
+      await trigger.click();
+    }
+    return this.page.locator('[role="dialog"], [data-state="open"]').first();
+  }
+
+  /**
+   * Open a bottom sheet (vaul). View-specific page objects should
+   * override this with their actual trigger selector.
+   */
+  async openBottomSheet(): Promise<Locator> {
+    if (this.isDesktop) {
+      return this.pageRoot;
+    }
+    return this.page.locator("[vaul-drawer]").first();
+  }
+
+  /** Close any currently-open mobile overlay (drawer, sheet, dialog). */
+  async closeMobileOverlay(): Promise<void> {
+    if (this.isDesktop) return;
+    // Press Escape — Radix dialogs and vaul both close on Escape
+    await this.page.keyboard.press("Escape");
+  }
 }

web/e2e/scripts/lint-specs.mjs

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+/**
+ * Lint script for e2e specs. Bans lenient test patterns and requires
+ * a @mobile-tagged test in every spec under specs/ (excluding _meta/).
+ *
+ * Banned patterns:
+ *   - page.waitForTimeout(   — use expect().toPass() or waitFor instead
+ *   - if (await ... .isVisible())   — assertions must be unconditional
+ *   - if ((await ... .count()) > 0)   — same as above
+ *   - expect(... .length).toBeGreaterThan(0) on textContent results
+ *
+ * Escape hatch: append `// e2e-lint-allow` on any line to silence the
+ * check for that line. Use sparingly and explain why in a comment above.
+ *
+ * @mobile rule: every .spec.ts under specs/ (not specs/_meta/) must
+ * contain at least one test title or describe with the substring "@mobile".
+ *
+ * Specs in PENDING_REWRITE are exempt from all rules until they are
+ * rewritten with proper assertions and mobile coverage. Remove each
+ * entry when its spec is updated.
+ */
+
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SPECS_DIR = resolve(__dirname, "..", "specs");
+const META_PREFIX = resolve(SPECS_DIR, "_meta");
+
+// Specs exempt from lint rules until they are rewritten with proper
+// assertions and mobile coverage. Remove each entry when its spec is updated.
+const PENDING_REWRITE = new Set([
+  "auth.spec.ts",
+  "chat.spec.ts",
+  "classification.spec.ts",
+  "config-editor.spec.ts",
+  "explore.spec.ts",
+  "export.spec.ts",
+  "face-library.spec.ts",
+  "live.spec.ts",
+  "logs.spec.ts",
+  "navigation.spec.ts",
+  "replay.spec.ts",
+  "review.spec.ts",
+  "system.spec.ts",
+]);
+
+const BANNED_PATTERNS = [
+  {
+    name: "page.waitForTimeout",
+    regex: /\bwaitForTimeout\s*\(/,
+    advice:
+      "Use expect.poll(), expect(...).toPass(), or waitFor() with a real condition.",
+  },
+  {
+    name: "conditional isVisible() assertion",
+    regex: /\bif\s*\(\s*await\s+[^)]*\.isVisible\s*\(/,
+    advice:
+      "Assertions must be unconditional. Use expect(...).toBeVisible() instead.",
+  },
+  {
+    name: "conditional count() assertion",
+    regex: /\bif\s*\(\s*\(?\s*await\s+[^)]*\.count\s*\(\s*\)\s*\)?\s*[><=!]/,
+    advice:
+      "Assertions must be unconditional. Use expect(...).toHaveCount(n).",
+  },
+  {
+    name: "vacuous textContent length assertion",
+    regex: /expect\([^)]*\.length\)\.toBeGreaterThan\(0\)/,
+    advice:
+      "Assert specific content, not that some text exists.",
+  },
+];
+
+function walk(dir) {
+  const entries = readdirSync(dir);
+  const out = [];
+  for (const entry of entries) {
+    const full = join(dir, entry);
+    const st = statSync(full);
+    if (st.isDirectory()) {
+      out.push(...walk(full));
+    } else if (entry.endsWith(".spec.ts")) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+function lintFile(file) {
+  const basename = file.split("/").pop();
+  if (PENDING_REWRITE.has(basename)) return [];
+  if (file.includes("/specs/settings/")) return [];
+
+  const errors = [];
+  const text = readFileSync(file, "utf8");
+  const lines = text.split("\n");
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.includes("e2e-lint-allow")) continue;
+    for (const pat of BANNED_PATTERNS) {
+      if (pat.regex.test(line)) {
+        errors.push({
+          file,
+          line: i + 1,
+          col: 1,
+          rule: pat.name,
+          message: `${pat.name}: ${pat.advice}`,
+          source: line.trim(),
+        });
+      }
+    }
+  }
+
+  // @mobile rule: skip _meta
+  const isMeta = file.startsWith(META_PREFIX);
+  if (!isMeta) {
+    if (!/@mobile\b/.test(text)) {
+      errors.push({
+        file,
+        line: 1,
+        col: 1,
+        rule: "missing @mobile test",
+        message:
+          'Spec must contain at least one test or describe tagged with "@mobile".',
+        source: "",
+      });
+    }
+  }
+
+  return errors;
+}
+
+function main() {
+  const files = walk(SPECS_DIR);
+  const allErrors = [];
+  for (const f of files) {
+    allErrors.push(...lintFile(f));
+  }
+
+  if (allErrors.length === 0) {
+    console.log(`e2e:lint: ${files.length} spec files OK`);
+    process.exit(0);
+  }
+
+  for (const err of allErrors) {
+    const rel = relative(process.cwd(), err.file);
+    console.error(`${rel}:${err.line}:${err.col}  ${err.rule}`);
+    console.error(`  ${err.message}`);
+    if (err.source) console.error(`  > ${err.source}`);
+  }
+  console.error(
+    `\ne2e:lint: ${allErrors.length} error${allErrors.length === 1 ? "" : "s"} in ${files.length} files`,
+  );
+  process.exit(1);
+}
+
+main();

web/e2e/specs/_meta/error-collector.spec.ts

@@ -0,0 +1,112 @@
+/**
+ * Self-tests for the error collector fixture itself.
+ *
+ * These guard against future regressions in the safety net. Each test
+ * deliberately triggers (or avoids triggering) an error to verify the
+ * collector behaves correctly. Tests that expect to fail use the
+ * `expectedErrors` fixture parameter to allowlist their own errors.
+ */
+
+import { test, expect } from "../../fixtures/frigate-test";
+
+// test.use applies to a whole describe block in Playwright, so each test
+// that needs a custom allowlist gets its own describe.
+
+test.describe("Error Collector — clean @meta", () => {
+  test("clean page passes", async ({ frigateApp }) => {
+    await frigateApp.goto("/");
+    // No errors triggered. The fixture teardown should not throw.
+  });
+});
+
+test.describe("Error Collector — unallowlisted console error fails @meta", () => {
+  test("console.error fails the test when not allowlisted", async ({
+    page,
+    frigateApp,
+  }) => {
+    test.skip(
+      process.env.E2E_STRICT_ERRORS !== "1",
+      "Requires E2E_STRICT_ERRORS=1 to assert failure",
+    );
+    test.fail(); // We expect the fixture teardown to throw
+    await frigateApp.goto("/");
+    await page.evaluate(() => {
+      // eslint-disable-next-line no-console
+      console.error("UNEXPECTED_DELIBERATE_TEST_ERROR_xyz123");
+    });
+  });
+});
+
+test.describe("Error Collector — allowlisted console error passes @meta", () => {
+  test.use({ expectedErrors: [/ALLOWED_DELIBERATE_TEST_ERROR_xyz123/] });
+
+  test("console.error is silenced when allowlisted via expectedErrors", async ({
+    page,
+    frigateApp,
+  }) => {
+    await frigateApp.goto("/");
+    await page.evaluate(() => {
+      // eslint-disable-next-line no-console
+      console.error("ALLOWED_DELIBERATE_TEST_ERROR_xyz123");
+    });
+  });
+});
+
+test.describe("Error Collector — uncaught pageerror fails @meta", () => {
+  test("uncaught pageerror fails the test", async ({ page, frigateApp }) => {
+    test.skip(
+      process.env.E2E_STRICT_ERRORS !== "1",
+      "Requires E2E_STRICT_ERRORS=1 to assert failure",
+    );
+    test.fail();
+    await frigateApp.goto("/");
+    await page.evaluate(() => {
+      setTimeout(() => {
+        throw new Error("UNCAUGHT_DELIBERATE_TEST_ERROR_xyz789");
+      }, 0);
+    });
+    // Wait a frame to let the throw propagate before fixture teardown.
+    // The marker below silences the e2e:lint banned-pattern check on this line.
+    await page.waitForTimeout(100); // e2e-lint-allow: deliberate; need to await async throw
+  });
+});
+
+test.describe("Error Collector — 5xx fails @meta", () => {
+  test("same-origin 5xx response fails the test", async ({
+    page,
+    frigateApp,
+  }) => {
+    test.skip(
+      process.env.E2E_STRICT_ERRORS !== "1",
+      "Requires E2E_STRICT_ERRORS=1 to assert failure",
+    );
+    test.fail();
+    await page.route("**/api/version", (route) =>
+      route.fulfill({ status: 500, body: "boom" }),
+    );
+    await frigateApp.goto("/");
+    await page.evaluate(() => fetch("/api/version").catch(() => {}));
+    // Give the response listener a microtask to fire
+    await expect.poll(async () => true).toBe(true);
+  });
+});
+
+test.describe("Error Collector — allowlisted 5xx passes @meta", () => {
+  // Use a single alternation regex so test.use() receives a 1-element array.
+  // Playwright's isFixtureTuple() treats any [value, object] pair as a fixture
+  // tuple, so a 2-element array whose second item is a RegExp would be
+  // misinterpreted as [defaultValue, options]. Both the request collector
+  // error ("500 … /api/version") and the browser console error
+  // ("Failed to load resource … 500") are matched by the alternation below.
+  test.use({
+    expectedErrors: [/500.*\/api\/version|Failed to load resource.*500/],
+  });
+
+  test("allowlisted 5xx passes", async ({ page, frigateApp }) => {
+    await page.route("**/api/version", (route) =>
+      route.fulfill({ status: 500, body: "boom" }),
+    );
+    await frigateApp.goto("/");
+    await page.evaluate(() => fetch("/api/version").catch(() => {}));
+  });
+});

web/e2e/specs/_meta/mock-overrides.spec.ts

@@ -0,0 +1,73 @@
+/**
+ * Self-tests for the mock override helpers. Verifies each helper
+ * intercepts the matched URL and returns the expected payload/status.
+ */
+
+import { test, expect } from "../../fixtures/frigate-test";
+import { mockEmpty, mockError, mockDelay } from "../../helpers/mock-overrides";
+
+test.describe("Mock Overrides — empty @meta", () => {
+  test("mockEmpty returns []", async ({ page, frigateApp }) => {
+    await mockEmpty(page, "**/api/__meta_test__");
+    await frigateApp.goto("/");
+    const result = await page.evaluate(async () => {
+      const r = await fetch("/api/__meta_test__");
+      return { status: r.status, body: await r.json() };
+    });
+    expect(result.status).toBe(200);
+    expect(result.body).toEqual([]);
+  });
+});
+
+test.describe("Mock Overrides — error default @meta", () => {
+  // Match both the collected request error and the browser's console echo.
+  // Using a single alternation regex avoids Playwright's isFixtureTuple
+  // collision with multi-element RegExp arrays.
+  test.use({
+    expectedErrors: [/500.*__meta_test__|Failed to load resource.*500/],
+  });
+
+  test("mockError returns 500 by default", async ({ page, frigateApp }) => {
+    await mockError(page, "**/api/__meta_test__");
+    await frigateApp.goto("/");
+    const status = await page.evaluate(async () => {
+      const r = await fetch("/api/__meta_test__");
+      return r.status;
+    });
+    expect(status).toBe(500);
+  });
+});
+
+test.describe("Mock Overrides — error custom status @meta", () => {
+  // The browser emits a "Failed to load resource" console.error for 404s,
+  // which the error collector catches even though 404 is not a 5xx.
+  test.use({
+    expectedErrors: [/Failed to load resource.*404|404.*__meta_test_404__/],
+  });
+
+  test("mockError accepts a custom status", async ({ page, frigateApp }) => {
+    await mockError(page, "**/api/__meta_test_404__", 404);
+    await frigateApp.goto("/");
+    const status = await page.evaluate(async () => {
+      const r = await fetch("/api/__meta_test_404__");
+      return r.status;
+    });
+    expect(status).toBe(404);
+  });
+});
+
+test.describe("Mock Overrides — delay @meta", () => {
+  test("mockDelay delays response by the requested ms", async ({
+    page,
+    frigateApp,
+  }) => {
+    await mockDelay(page, "**/api/__meta_test_delay__", 300, ["delayed"]);
+    await frigateApp.goto("/");
+    const elapsed = await page.evaluate(async () => {
+      const start = performance.now();
+      await fetch("/api/__meta_test_delay__");
+      return performance.now() - start;
+    });
+    expect(elapsed).toBeGreaterThanOrEqual(250);
+  });
+});

web/package.json

@@ -7,7 +7,8 @@
     "dev": "vite --host",
     "postinstall": "patch-package",
     "build": "tsc && vite build --base=/BASE_PATH/",
-    "lint": "eslint --ext .jsx,.js,.tsx,.ts --ignore-path .gitignore .",
+    "lint": "eslint --ext .jsx,.js,.tsx,.ts --ignore-path .gitignore . && npm run e2e:lint",
+    "e2e:lint": "node e2e/scripts/lint-specs.mjs",
     "lint:fix": "eslint --ext .jsx,.js,.tsx,.ts --ignore-path .gitignore --fix .",
     "preview": "vite preview",
     "prettier:write": "prettier -u -w --ignore-path .gitignore \"*.{ts,tsx,js,jsx,css,html}\"",