test(e2e): add custom-auth-server HTTP smoke on :4001

Wire non-browser boot smoke for the Express example (AD-6): ui|http
example kind, serial runner entry, and spec-managed lifecycle on :4001.
Update testing-strategy and AD-6 as durable owners; defer Phase 5 auth
flags (no flakiness observed).

Author: mikehardy

developer-docs/architecture/testing-strategy.md

@@ -3,7 +3,7 @@ type: Reference
 title: Testing strategy
 description: Verification layers for firebaseui-web packages and examples.
 tags: [testing, ci, playwright]
-timestamp: 2026-07-01T00:00:00Z
+timestamp: 2026-07-03T00:00:00Z
 ---
 
 # Layers
@@ -13,18 +13,19 @@ timestamp: 2026-07-01T00:00:00Z
 | Package unit tests | `pnpm test` | [CONTRIBUTING.md](../../CONTRIBUTING.md) | Core/react/angular/shadcn/translations/styles logic |
 | Compile (packages + examples) | `pnpm build` | [CONTRIBUTING.md](../../CONTRIBUTING.md) | TS, bundler, framework build errors |
 | Lint / format | `pnpm lint:check`, `pnpm format:check` | [CONTRIBUTING.md](../../CONTRIBUTING.md) | Style regressions |
-| Example smoke (browser + HTTP) | `pnpm test:e2e` | [work-queues/playwright-e2e-smoke.md](../work-queues/playwright-e2e-smoke.md) | Example dev-server load + basic UI interactivity (five UI examples) and `custom-auth-server` HTTP boot |
+| Example smoke (browser + HTTP) | `pnpm test:e2e` | [AD-3](../decisions.md#ad-3-playwright-example-smoke-tests-mvp-scope-dev-server), [AD-4](../decisions.md#ad-4-playwright-managed-dev-servers-serial-shared-emulator), [AD-6](../decisions.md#ad-6-custom-auth-server-binds-4001-for-e2e) | Dev-server UI interactivity (five UI examples) and `custom-auth-server` HTTP boot |
 | Security audit | `pnpm audit` | [playbooks/dependency-update-verification.md](../playbooks/dependency-update-verification.md) | Known CVEs in lockfile |
 
 # CI today
 
-[`.github/workflows/test.yaml`](../../.github/workflows/test.yaml): `pnpm build`, Auth emulator start, `pnpm test`. **No browser smoke yet** — target of Playwright work queue. e2e will land as a **separate workflow** with broad path triggers — [AD-7](../decisions.md#ad-7-e2e-runs-in-a-separate-ci-workflow-with-broad-triggers).
+[`.github/workflows/test.yaml`](../../.github/workflows/test.yaml): `pnpm build`, Auth emulator start, `pnpm test`.
+
+[`.github/workflows/e2e.yaml`](../../.github/workflows/e2e.yaml): `pnpm test:e2e` (six examples), Auth emulator, Playwright Chromium — [AD-7](../decisions.md#ad-7-e2e-runs-in-a-separate-ci-workflow-with-broad-triggers).
 
 # Gaps
 
-* No example-level automated tests yet (Angular example `vitest` has no spec files) — closed by the Playwright work queue.
 * Skipped package integration tests (`describe.skip`).
-* `custom-auth-server` not built by root `build` (e2e builds it on demand).
+* `custom-auth-server` not built by root `pnpm build` (e2e builds it on demand).
 * Production build artifacts not exercised by e2e — deferred, [AD-8](../decisions.md#ad-8-production-artifact-e2e-deferred-future-phase).
 * `pnpm audit` not gated in CI.
 

developer-docs/decisions.md

@@ -42,7 +42,9 @@ Each example has a **unique e2e port** (react 5173, shadcn 5174, nextjs 3000, ne
 
 ## AD-6: custom-auth-server binds :4001 for e2e
 
-The Express `custom-auth-server` defaults to `:4000`, which collides with the **Firebase Emulator UI** (`:4000`). For e2e it binds **`:4001`** (via its `PORT` env) so it never conflicts with emulator services. Its smoke is a **non-browser boot + HTTP (`fetch`/`curl`) assertion** — start the built server, assert it responds, tear down — not a Playwright browser flow. This brings every monorepo example (including `custom-auth-server`) under automated e2e coverage.
+The Express `custom-auth-server` defaults to `:4000`, which collides with the **Firebase Emulator UI** (`:4000`). For e2e it binds **`:4001`** (via its `PORT` env) so it never conflicts with emulator services. Its smoke is a **non-browser boot + HTTP assertion** — build the example, start the built server, assert it responds, tear down — not a Playwright browser flow. This brings every monorepo example (including `custom-auth-server`) under automated e2e coverage.
+
+**Lifecycle:** Playwright's `webServer` readiness poll accepts only HTTP status `< 400`. Without credentials, `GET /auth/snapchat/config` returns `500`, so the HTTP smoke spec manages build/boot/poll/teardown itself (detached process group, `:4001` via `PORT`). UI examples continue to use Playwright `webServer` as in [AD-4](#ad-4-playwright-managed-dev-servers-serial-shared-emulator).
 
 ---
 

developer-docs/work-queues/playwright-e2e-smoke.md

@@ -14,28 +14,49 @@
  * limitations under the License.
  */
 
-/** Per-example routing and server metadata for Playwright smoke tests. */
-export type ExampleMeta = {
+/**
+ * Whether an example is exercised through the browser (UI smoke S1–S3) or as a
+ * non-browser HTTP boot smoke (custom-auth-server). See AD-6.
+ */
+export type ExampleKind = "ui" | "http";
+
+/** Shared server/startup metadata for every Playwright project. */
+type BaseExampleMeta = {
   /** Playwright project name (matches pnpm filter where applicable). */
   name: string;
-  /** Dev server origin used as Playwright baseURL. */
+  /** Server origin used as Playwright baseURL. */
   baseURL: string;
+  /** Optional server command for Playwright webServer. */
+  webServerCommand?: string;
+  /** Optional Playwright webServer startup timeout (ms). */
+  webServerTimeoutMs?: number;
+  /** URL Playwright polls until the server is ready (defaults to baseURL). */
+  webServerHealthURL?: string;
+};
+
+/** Browser example: rendered UI smoke over the sign-in-with-handlers flow. */
+export type UiExampleMeta = BaseExampleMeta & {
+  kind: "ui";
   /** Deep-link path for the sign-in-with-handlers smoke entry screen. */
   signInWithHandlersPath: string;
   /** Whether URLs for this example require a trailing slash (Next.js). */
   trailingSlash: boolean;
   /** Forgot-password route from sign-in-with-handlers (S3 asserts UI, not this path). */
   forgotPasswordPath: string;
-  /** Optional dev-server command for Playwright webServer. */
-  webServerCommand?: string;
-  /** Optional Playwright webServer startup timeout (ms). */
-  webServerTimeoutMs?: number;
-  /** URL Playwright polls until the dev server is ready (defaults to baseURL). */
-  webServerHealthURL?: string;
 };
 
+/** Non-browser example: boot the server and assert an HTTP response. */
+export type HttpExampleMeta = BaseExampleMeta & {
+  kind: "http";
+  /** Path probed by the HTTP smoke (relative to baseURL). */
+  smokePath: string;
+};
+
+export type ExampleMeta = UiExampleMeta | HttpExampleMeta;
+
 export const exampleMeta: Record<string, ExampleMeta> = {
   react: {
+    kind: "ui",
     name: "react",
     baseURL: "http://localhost:5173",
     signInWithHandlersPath: "/screens/sign-in-auth-screen-w-handlers",
@@ -44,6 +65,7 @@ export const exampleMeta: Record<string, ExampleMeta> = {
     webServerCommand: "pnpm --filter=react exec vite --port 5173 --strictPort",
   },
   shadcn: {
+    kind: "ui",
     name: "shadcn",
     baseURL: "http://localhost:5174",
     signInWithHandlersPath: "/screens/sign-in-auth-screen-w-handlers",
@@ -52,6 +74,7 @@ export const exampleMeta: Record<string, ExampleMeta> = {
     webServerCommand: "pnpm --filter=shadcn exec vite --port 5174 --strictPort",
   },
   nextjs: {
+    kind: "ui",
     name: "nextjs",
     baseURL: "http://localhost:3000",
     signInWithHandlersPath: "/screens/sign-in-auth-screen-w-handlers",
@@ -60,6 +83,7 @@ export const exampleMeta: Record<string, ExampleMeta> = {
     webServerCommand: "pnpm --filter=nextjs exec next dev --turbopack -p 3000",
   },
   "nextjs-ssr": {
+    kind: "ui",
     name: "nextjs-ssr",
     baseURL: "http://localhost:3001",
     signInWithHandlersPath: "/screens/sign-in-auth-screen-w-handlers",
@@ -69,17 +93,30 @@ export const exampleMeta: Record<string, ExampleMeta> = {
     webServerTimeoutMs: 180_000,
   },
   "angular-example": {
+    kind: "ui",
     name: "angular-example",
     baseURL: "http://localhost:4200",
     signInWithHandlersPath: "/screens/sign-in-auth-screen-w-handlers",
     trailingSlash: false,
     forgotPasswordPath: "/screens/forgot-password-auth-screen",
     webServerCommand: "pnpm --filter=angular-example run start --port 4200",
   },
+  // AD-6: non-browser HTTP smoke; lifecycle in custom-auth-server.spec.ts
+  "custom-auth-server": {
+    kind: "http",
+    name: "custom-auth-server",
+    baseURL: "http://localhost:4001",
+    smokePath: "/auth/snapchat/config",
+  },
 };
 
+/** UI examples (browser smoke S1–S3), narrowed by discriminant. */
+export const uiExampleEntries: [string, UiExampleMeta][] = Object.entries(exampleMeta).filter(
+  (entry): entry is [string, UiExampleMeta] => entry[1].kind === "ui"
+);
+
 /** Returns the sign-in-with-handlers path respecting per-example trailing-slash rules. */
-export function signInWithHandlersUrl(meta: ExampleMeta): string {
+export function signInWithHandlersUrl(meta: UiExampleMeta): string {
   const { signInWithHandlersPath, trailingSlash } = meta;
 
   if (trailingSlash) {

e2e/fixtures/example-meta.ts

@@ -39,23 +39,22 @@ function webServerForMeta(meta: ExampleMeta) {
 
 /** Playwright only reads top-level webServer (not per-project). Serial runner sets E2E_PROJECT. */
 function resolveWebServerMeta() {
-  const fromEnv = process.env.E2E_PROJECT ? exampleMeta[process.env.E2E_PROJECT] : undefined;
-
-  if (fromEnv?.webServerCommand) {
-    return fromEnv;
+  if (process.env.E2E_PROJECT) {
+    return exampleMeta[process.env.E2E_PROJECT];
   }
 
   return Object.values(exampleMeta).find((meta) => meta.webServerCommand);
 }
 
 const webServerMeta = resolveWebServerMeta();
+const webServer = webServerMeta ? webServerForMeta(webServerMeta) : undefined;
 
 export default defineConfig({
   testDir: "./tests",
   workers: 1,
   globalSetup: "./global-setup.ts",
   globalTeardown: "./global-teardown.ts",
-  ...(webServerMeta ? { webServer: webServerForMeta(webServerMeta) } : {}),
+  ...(webServer ? { webServer } : {}),
   projects: Object.values(exampleMeta).map((meta) => ({
     name: meta.name,
     timeout: meta.name === "angular-example" ? 90_000 : undefined,

e2e/playwright.config.ts

@@ -0,0 +1,116 @@
+/**
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { spawn, spawnSync, type ChildProcess } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { expect, request, test } from "@playwright/test";
+import { exampleMeta, type HttpExampleMeta } from "../fixtures/example-meta";
+
+/** HTTP boot smoke for custom-auth-server — AD-6. */
+const PROJECT = "custom-auth-server";
+const PORT = "4001";
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+const meta = exampleMeta[PROJECT];
+if (meta.kind !== "http") {
+  throw new Error(`Expected ${PROJECT} to be an http example, got kind "${meta.kind}"`);
+}
+const httpMeta: HttpExampleMeta = meta;
+
+let server: ChildProcess | undefined;
+
+function stopServer(): void {
+  if (!server || server.pid === undefined || server.exitCode !== null) {
+    return;
+  }
+  // Spawned detached so teardown can signal the process group (AD-6).
+  try {
+    process.kill(-server.pid, "SIGTERM");
+  } catch {
+    server.kill("SIGTERM");
+  }
+}
+
+async function waitForServer(url: string, timeoutMs = 60_000): Promise<void> {
+  const context = await request.newContext();
+  const deadline = Date.now() + timeoutMs;
+
+  try {
+    while (Date.now() < deadline) {
+      if (server?.exitCode != null) {
+        throw new Error(`custom-auth-server exited early with code ${server.exitCode}`);
+      }
+      try {
+        // Any HTTP response means the server is listening (AD-6).
+        await context.get(url, { timeout: 2_000 });
+        return;
+      } catch {
+        await new Promise((resolve) => setTimeout(resolve, 500));
+      }
+    }
+    throw new Error(`custom-auth-server did not respond at ${url} within ${timeoutMs}ms`);
+  } finally {
+    await context.dispose();
+  }
+}
+
+test.describe(`custom-auth-server HTTP smoke (${PROJECT})`, () => {
+  test.beforeAll(async ({}, testInfo) => {
+    test.skip(testInfo.project.name !== PROJECT, `runs only on the ${PROJECT} project`);
+    test.setTimeout(120_000);
+
+    const build = spawnSync("pnpm", ["--filter=custom-auth-server", "run", "build"], {
+      cwd: REPO_ROOT,
+      stdio: "inherit",
+    });
+    expect(build.status, "custom-auth-server build failed").toBe(0);
+
+    server = spawn("pnpm", ["--filter=custom-auth-server", "start"], {
+      cwd: REPO_ROOT,
+      stdio: "inherit",
+      detached: true,
+      env: { ...process.env, PORT },
+    });
+
+    await waitForServer(`${httpMeta.baseURL}${httpMeta.smokePath}`);
+  });
+
+  test.afterAll(async () => {
+    stopServer();
+  });
+
+  test("H1: server responds on the config route", async () => {
+    const context = await request.newContext({ baseURL: httpMeta.baseURL });
+
+    try {
+      const response = await context.get(httpMeta.smokePath);
+
+      // 500 without SNAPCHAT_CLIENT_ID (default env); 200 when credentials are present.
+      expect([200, 500]).toContain(response.status());
+
+      const body = await response.json();
+
+      if (response.status() === 500) {
+        expect(body).toMatchObject({ error: "Server missing Snapchat client ID" });
+      } else {
+        expect(body).toMatchObject({ clientId: expect.any(String) });
+      }
+    } finally {
+      await context.dispose();
+    }
+  });
+});

e2e/tests/custom-auth-server.spec.ts

@@ -15,7 +15,7 @@
  */
 
 import { enUs } from "@firebase-oss/ui-translations";
-import { exampleMeta, signInWithHandlersUrl } from "../fixtures/example-meta";
+import { signInWithHandlersUrl, uiExampleEntries } from "../fixtures/example-meta";
 import { expect, test } from "../fixtures/test-harness";
 
 const { labels, errors } = enUs.translations;
@@ -24,7 +24,7 @@ async function waitForSignInForm(page: import("@playwright/test").Page): Promise
   await page.waitForSelector('input[name="email"]', { state: "visible", timeout: 30_000 });
 }
 
-for (const [projectName, meta] of Object.entries(exampleMeta)) {
+for (const [projectName, meta] of uiExampleEntries) {
   test.describe(`sign-in with handlers smoke (${projectName})`, () => {
     test.beforeEach(({}, testInfo) => {
       test.skip(testInfo.project.name !== projectName, `runs only on the ${projectName} project`);

e2e/tests/sign-in-handlers.spec.ts

@@ -18,6 +18,7 @@
     "test:e2e:nextjs": "E2E_PROJECT=nextjs pnpm --filter=e2e exec playwright test --project=nextjs",
     "test:e2e:nextjs-ssr": "E2E_PROJECT=nextjs-ssr pnpm --filter=e2e exec playwright test --project=nextjs-ssr",
     "test:e2e:angular": "E2E_PROJECT=angular-example pnpm --filter=e2e exec playwright test --project=angular-example",
+    "test:e2e:custom-auth-server": "E2E_PROJECT=custom-auth-server pnpm --filter=e2e exec playwright test --project=custom-auth-server",
     "test:watch": "pnpm --filter=@firebase-oss/ui-core run test:unit:watch & pnpm --filter=@firebase-oss/ui-react run test:unit:watch & pnpm --filter=@firebase-oss/ui-angular run test:watch",
     "version:bump:all": "pnpm --filter=@firebase-oss/ui-core run version:bump && pnpm --filter=@firebase-oss/ui-translations run version:bump && pnpm --filter=@firebase-oss/ui-react run version:bump && pnpm --filter=@firebase-oss/ui-styles run version:bump && pnpm --filter=@firebase-oss/ui-angular run version:bump",
     "publish:tags:all": "pnpm i && pnpm --filter=@firebase-oss/ui-core run publish:tags && pnpm --filter=@firebase-oss/ui-translations run publish:tags && pnpm --filter=@firebase-oss/ui-react run publish:tags && pnpm --filter=@firebase-oss/ui-styles run publish:tags && pnpm --filter=@firebase-oss/ui-angular run publish:tags",

package.json

@@ -20,9 +20,14 @@ import { fileURLToPath } from "node:url";
 
 const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 
-/** UI examples exercised serially by `pnpm test:e2e`. */
+/** UI examples exercised serially by `pnpm test:e2e` (browser smoke S1–S3). */
 const E2E_UI_EXAMPLES = ["react", "shadcn", "nextjs", "nextjs-ssr", "angular-example"];
 
+/** Non-browser examples (HTTP boot smoke), run after the UI examples. AD-6. */
+const E2E_HTTP_EXAMPLES = ["custom-auth-server"];
+
+const E2E_EXAMPLES = [...E2E_UI_EXAMPLES, ...E2E_HTTP_EXAMPLES];
+
 function ensurePackagesBuilt() {
   console.log("\n[e2e-run] build:packages (once)…\n");
   const build = spawnSync("pnpm", ["build:packages"], { cwd: REPO_ROOT, stdio: "inherit" });
@@ -51,7 +56,7 @@ function runExample(example) {
 
 ensurePackagesBuilt();
 
-for (const example of E2E_UI_EXAMPLES) {
+for (const example of E2E_EXAMPLES) {
   runExample(example);
   if (process.exitCode) {
     break;