@podosoft/podokit 1.6.0 → 1.6.2

package/dist/templates/fullstack/tests/README.md

@@ -45,16 +45,26 @@ Tag a test when it changes a server-wide setting (a feature flag, the
 authentication configuration such as SMTP, social providers, or sign-up
 approval, the site settings, or a module's settings) or the profile of a seeded
 account. Each project has an `<name>-exclusive` twin, such as `ui-exclusive`,
-that runs only the tagged tests, one at a time. With more than one worker the
-twins wait for every other test, so an exclusive test never runs alongside
-another one. Never empty the shared mail catcher or SMS sink in a test: send to
-an address or number of the test's own instead.
-
-More than one worker suits the whole suite. When a run selects exclusive tests
-with a file name, `--grep`, or `--project`, Playwright also runs every other test
-first, because the twins depend on them, and a test that fails there marks the
-exclusive tests as not run. Use the default single worker for a few files, and
-do not combine `--no-deps` with `E2E_WORKERS` above 1.
+that runs only the tagged tests, one at a time. Never empty the shared mail
+catcher or SMS sink in a test: send to an address or number of the test's own
+instead.
+
+The `test:e2e` scripts run `run-e2e.ts`, which hands its arguments (a file,
+`--grep`, `--project`) to Playwright. With more than one worker it runs
+Playwright twice: first every test not tagged `@exclusive` on those workers,
+then the tagged tests on one worker, even when a test failed in the first run.
+The suite fails when either run fails. The second run reports to
+`playwright-report/exclusive` and `test-results/exclusive`:
+
+```bash
+bunx playwright show-report playwright-report/exclusive
+```
+
+A plain `bunx playwright test` with `E2E_WORKERS` above 1 makes one run in which
+the twins depend on every other test: a failing test there leaves the exclusive
+tests not run, and selecting an exclusive test runs every other test first. Use
+`{{rootRun}} test:e2e` on more workers, and do not combine `--no-deps` with
+`E2E_WORKERS` above 1.
 
 Application-owned projects in `playwright.projects.cjs` get twins too. A project
 that another project depends on is a setup project and keeps a single copy.

package/dist/templates/fullstack/tests/helpers/paths.ts

@@ -20,9 +20,15 @@ export interface AppPaths {
    * `AccountMenu` for a signed-in user, or null when none does.
    */
   accountMenu: string | null;
+  /**
+   * A page that renders the managed `ThemeToggle` for the signed-in
+   * administrator, or null when none does. Defaults to `accountMenu`, and to
+   * the admin console, whose header renders the toggle, when that is null.
+   */
+  themeToggle: string | null;
 }
 
-const defaults: AppPaths = {
+const defaults: Omit<AppPaths, "themeToggle"> = {
   home: "/",
   homeReady: (page) => page.getByRole("heading", { level: 1 }),
   indexable: ["/"],
@@ -30,4 +36,9 @@ const defaults: AppPaths = {
   accountMenu: "/",
 };
 
-export const paths: AppPaths = { ...defaults, ...appPaths };
+const merged = { ...defaults, ...appPaths };
+
+export const paths: AppPaths = {
+  ...merged,
+  themeToggle: appPaths.themeToggle === undefined ? (merged.accountMenu ?? "/admin") : appPaths.themeToggle,
+};

package/dist/templates/fullstack/tests/helpers/seeded-admin.ts

@@ -0,0 +1,15 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * The administrator the admin-dashboard Playwright setup seeds, with the address
+ * and password `accounts.ts` reads from `E2E_*` variables and the application's
+ * `app-accounts.ts`, or null in an app without that module. Specs of modules
+ * that do not require admin-dashboard sign in with this instead of importing
+ * `accounts.ts`, which only admin-dashboard installs.
+ */
+export async function seededAdmin(): Promise<{ email: string; password: string } | null> {
+  if (!existsSync(join(__dirname, "accounts.ts"))) return null;
+  const { ADMIN } = await import("./accounts");
+  return { email: ADMIN.email, password: ADMIN.password };
+}

package/dist/templates/fullstack/tests/package.json

@@ -3,9 +3,9 @@
   "version": "0.0.0",
   "private": true,
   "scripts": {
-    "test:e2e": "bunx playwright test",
-    "test:e2e:ui": "bunx playwright test --project=ui --project=ui-exclusive",
-    "test:e2e:api": "bunx playwright test --project=api --project=api-exclusive",
+    "test:e2e": "bun run-e2e.ts",
+    "test:e2e:ui": "bun run-e2e.ts --project=ui --project=ui-exclusive",
+    "test:e2e:api": "bun run-e2e.ts --project=api --project=api-exclusive",
     "test:e2e:report": "bunx playwright show-report"
   },
   "devDependencies": {

package/dist/templates/fullstack/tests/playwright.config.ts

@@ -1,14 +1,15 @@
 import { defineConfig, devices } from "@playwright/test";
-import { e2eWorkers, loadPlaywrightProjects, withExclusivePhase } from "./playwright.extensions";
+import { e2eRunSettings, loadPlaywrightProjects, withExclusivePhase } from "./playwright.extensions";
 
 // The suite runs against a live stack: web on E2E_BASE_URL (proxying /api/* to
 // the API). Start it first (see docs/testing.md) — locally via the dev harness,
 // in CI via scripts/e2e-ci.mjs. Two projects: `api` (request-only, backend e2e)
 // and `ui` (chromium, pages). Files are routed by suffix (*.api/*.ui.spec.ts).
 // E2E_WORKERS sets the worker count (default 1); tests tagged @exclusive run in
-// `<project>-exclusive` twins after the others (see playwright.extensions.ts).
+// `<project>-exclusive` twins after the others, in a second run when run-e2e.ts
+// starts the suite on more workers (see playwright.extensions.ts).
 const baseURL = process.env.E2E_BASE_URL ?? "http://localhost:5001";
-const workers = e2eWorkers();
+const run = e2eRunSettings();
 const coreProjects = [
   { name: "api", testMatch: /.*\.api\.spec\.ts/ },
   { name: "ui", testMatch: /.*\.ui\.spec\.ts/, use: { ...devices["Desktop Chrome"] } },
@@ -19,13 +20,14 @@ export default defineConfig({
   fullyParallel: true,
   forbidOnly: !!process.env.CI,
   retries: process.env.CI ? 2 : 0,
-  workers,
+  workers: run.workers,
+  outputDir: run.outputDir,
   globalSetup: "./playwright.extensions.ts",
-  reporter: [["list"], ["html", { open: "never" }]],
+  reporter: [["list"], ["html", { open: "never", outputFolder: run.reportFolder }]],
   use: {
     baseURL,
     trace: "on-first-retry",
     screenshot: "only-on-failure",
   },
-  projects: withExclusivePhase([...coreProjects, ...loadPlaywrightProjects(coreProjects)], workers),
+  projects: withExclusivePhase([...coreProjects, ...loadPlaywrightProjects(coreProjects)], run.workers, run.phase),
 });

package/dist/templates/fullstack/tests/playwright.extensions.ts

@@ -17,6 +17,13 @@ const requireFromTests = createRequire(__filename);
 // the test's tags, separated by spaces.
 const TAGGED = /(?:^|\s)@exclusive(?=\s|$)/;
 const UNTAGGED = /^(?![\s\S]*(?:^|\s)@exclusive(?=\s|$))/;
+const EVERY_FILE = /.*/;
+
+/**
+ * One of the two Playwright runs `run-e2e.ts` makes with more than one worker:
+ * `shared` runs the tests not tagged `@exclusive`, `exclusive` the tagged ones.
+ */
+export type E2ePhase = "shared" | "exclusive";
 
 function projectName(project: unknown): string | null {
   if (typeof project !== "object" || project === null || !("name" in project)) return null;
@@ -69,29 +76,74 @@ export function e2eWorkers(value = process.env.E2E_WORKERS): number {
   return workers;
 }
 
+/** The run `run-e2e.ts` started, from `E2E_PHASE`, or undefined for a single run. */
+export function e2ePhase(value = process.env.E2E_PHASE): E2ePhase | undefined {
+  if (value === undefined || value === "") return undefined;
+  if (value === "shared" || value === "exclusive") return value;
+  throw new Error(`E2E_PHASE must be "shared" or "exclusive", got "${value}".`);
+}
+
+/**
+ * Workers and output folders for this Playwright run. The exclusive phase runs
+ * on one worker and keeps its results and HTML report in `exclusive/` folders,
+ * because each run empties its own.
+ */
+export function e2eRunSettings(
+  phase = e2ePhase(),
+  workers = e2eWorkers(),
+): { phase: E2ePhase | undefined; workers: number; outputDir: string; reportFolder: string } {
+  return phase === "exclusive"
+    ? { phase, workers: 1, outputDir: "test-results/exclusive", reportFolder: "playwright-report/exclusive" }
+    : { phase, workers, outputDir: "test-results", reportFolder: "playwright-report" };
+}
+
+/**
+ * The Playwright runs for `run-e2e.ts` with these command-line arguments. One
+ * worker needs a single run. With more workers, the tests not tagged
+ * `@exclusive` run first and the tagged ones second, in a run of their own that
+ * starts even when the first one failed. Either run may find no tests: a filter
+ * can select tests of one kind only, and an app may have no exclusive tests.
+ */
+export function e2eRuns(args: string[], workers = e2eWorkers()): Array<{ phase?: E2ePhase; args: string[] }> {
+  if (workers === 1) return [{ args }];
+  return [
+    { phase: "shared", args: args.length > 0 ? ["--pass-with-no-tests", ...args] : args },
+    { phase: "exclusive", args: ["--pass-with-no-tests", ...args] },
+  ];
+}
+
 /**
  * Splits each test project into one that skips tests tagged `@exclusive` and an
  * `<name>-exclusive` twin that runs only them on one worker. Projects that
  * another project depends on, or that tear one down, are setup and cleanup
  * projects and stay as they are.
  *
- * With more than one worker the twins depend on every other test project, and
- * each twin on the one before it, so an exclusive test never runs alongside
- * another test. A dependency runs in full, though: a run that selects only
- * exclusive tests, with a file, `--grep`, or `--project`, then also runs every
- * other test first, and a test that fails there skips the exclusive tests. Use
- * more than one worker for the whole suite. With one worker no dependency is
- * needed, so filtered runs stay small.
+ * With one worker no ordering is needed. With more, `run-e2e.ts` runs
+ * Playwright twice: in the `shared` phase the twins find no tests, and in the
+ * `exclusive` phase, on one worker, the other test projects find none. A single
+ * run with more than one worker (no phase) makes the twins depend on every
+ * other test project, and each twin on the one before it, so an exclusive test
+ * still never runs alongside another test; but there a failing test skips every
+ * twin after it, and a filter that selects exclusive tests runs all other tests
+ * first.
  */
-export function withExclusivePhase(projects: Projects, workers: number): Projects {
+export function withExclusivePhase(projects: Projects, workers: number, phase?: E2ePhase): Projects {
   const support = new Set(
     projects.flatMap((project) => [...(project.dependencies ?? []), ...(project.teardown ? [project.teardown] : [])]),
   );
   const tested = projects.filter((project) => !support.has(projectName(project) ?? ""));
   const shared = new Map(
-    tested.map((project) => [project, { ...project, grepInvert: [...patterns(project.grepInvert), TAGGED] }]),
+    tested.map((project) => [
+      project,
+      {
+        ...project,
+        grepInvert: [...patterns(project.grepInvert), TAGGED],
+        ...(phase === "exclusive" ? { testIgnore: EVERY_FILE } : {}),
+      },
+    ]),
   );
 
+  const chained = workers > 1 && phase === undefined;
   let before = [...shared.values()].map((project) => projectName(project) ?? "");
   const twins = tested.map((project) => {
     const name = `${projectName(project) ?? ""}-exclusive`;
@@ -100,7 +152,8 @@ export function withExclusivePhase(projects: Projects, workers: number): Project
       name,
       grepInvert: [...patterns(project.grepInvert), UNTAGGED],
       workers: 1,
-      dependencies: workers > 1 ? [...(project.dependencies ?? []), ...before] : project.dependencies,
+      dependencies: chained ? [...(project.dependencies ?? []), ...before] : project.dependencies,
+      ...(phase === "shared" ? { testIgnore: EVERY_FILE } : {}),
     };
     before = [name];
     return twin;
@@ -119,13 +172,21 @@ export function withExclusivePhase(projects: Projects, workers: number): Project
 /**
  * Global setup: refuses more workers than `E2E_WORKERS` allows for. `--workers`
  * changes the count after the projects were built, so with it the exclusive
- * twins would run alongside the other tests.
+ * twins would run alongside the other tests. Warns when more than one worker
+ * runs without `run-e2e.ts`, where a failing test skips the exclusive tests.
  */
-export default function checkWorkers(config: FullConfig): void {
+export default function checkWorkers(config: FullConfig, warn = console.warn): void {
   if (config.workers > 1 && e2eWorkers() === 1) {
     throw new Error(
       `Set the worker count with E2E_WORKERS=${config.workers} instead of --workers. ` +
         "Tests tagged @exclusive run after the others only when E2E_WORKERS is above 1.",
     );
   }
+  if (config.workers > 1 && e2ePhase() === undefined) {
+    warn(
+      "E2E_WORKERS is above 1 in a single Playwright run: a failing test makes Playwright skip " +
+        "the tests tagged @exclusive. Run the suite with `bun run test:e2e` (run-e2e.ts), which " +
+        "runs them in a second run instead.",
+    );
+  }
 }

package/dist/templates/fullstack/tests/run-e2e.ts

@@ -0,0 +1,28 @@
+import { spawnSync } from "node:child_process";
+import { e2eRuns } from "./playwright.extensions";
+
+// Runs the suite with the arguments it is given, such as `--grep` or a file.
+// With E2E_WORKERS above 1, Playwright runs twice: the tests not tagged
+// @exclusive on that many workers, then the tagged ones on one worker. The
+// second run starts even when the first one failed, so a failing test cannot
+// hide the exclusive tests, and the exit code is that of the first failed run.
+const runs = e2eRuns(process.argv.slice(2));
+let status = 0;
+for (const run of runs) {
+  if (run.phase) {
+    console.log(
+      run.phase === "shared"
+        ? "\nRunning the tests not tagged @exclusive\n"
+        : "\nRunning the tests tagged @exclusive on one worker (report: playwright-report/exclusive)\n",
+    );
+  }
+  const result = spawnSync("bunx", ["playwright", "test", ...run.args], {
+    stdio: "inherit",
+    env: run.phase ? { ...process.env, E2E_PHASE: run.phase } : process.env,
+  });
+  if (result.error) throw result.error;
+  // Playwright exits with 130 when it is interrupted: stop instead of starting the next run.
+  if (result.signal !== null || result.status === 130) process.exit(result.status ?? 130);
+  if (status === 0) status = result.status ?? 1;
+}
+process.exit(status);

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/admin/nav.test.ts

@@ -13,8 +13,20 @@ vi.mock("./app-nav", async () => {
   };
 });
 
+// Stands in for the entries installed modules add to registry.svelte.ts, so the
+// expected order does not depend on which modules an application installs.
+vi.mock("./registry.svelte.js", async () => {
+  const { default: icon } = await import("@lucide/svelte/icons/newspaper");
+  return {
+    moduleNavEntries: [
+      { href: "/admin/blog", label: () => "Blog", icon, adminOnly: true },
+      { href: "/admin/reports", label: () => "Reports", icon },
+    ],
+  };
+});
+
 describe("admin navigation", () => {
-  it("places the application's entries before Settings", () => {
+  it("places the application's entries, then module entries, before Settings", () => {
     const hrefs = adminNavEntries({ auditLog: true }, "admin").map((entry) => entry.href);
 
     expect(hrefs).toEqual([
@@ -24,6 +36,8 @@ describe("admin navigation", () => {
       "/admin/audit",
       "/admin/specs",
       "/admin/help",
+      "/admin/blog",
+      "/admin/reports",
       "/admin/settings",
     ]);
     expect(adminNavEntries(undefined, "admin").find((entry) => entry.href === "/admin/specs")?.icon).toBe(
@@ -31,9 +45,9 @@ describe("admin navigation", () => {
     );
   });
 
-  it("hides admin-only application entries from other roles", () => {
+  it("hides admin-only application and module entries from other roles", () => {
     const hrefs = adminNavEntries(undefined, "moderator").map((entry) => entry.href);
 
-    expect(hrefs).toEqual(["/admin", "/admin/help"]);
+    expect(hrefs).toEqual(["/admin", "/admin/help", "/admin/reports"]);
   });
 });

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/components/theme-toggle.svelte

@@ -13,7 +13,7 @@
 <DropdownMenu.Root>
   <DropdownMenu.Trigger>
     {#snippet child({ props })}
-      <Button {...props} variant="ghost" size="icon" aria-label={i18n.t.theme.toggle}>
+      <Button {...props} variant="ghost" size="icon" aria-label={i18n.t.theme.toggle} data-testid="theme-toggle">
         <SunIcon class="size-4 dark:hidden" />
         <MoonIcon class="hidden size-4 dark:block" />
       </Button>

package/dist/templates/modules/admin-dashboard/files/tests/api/audit.api.spec.ts

@@ -1,10 +1,21 @@
+import type { APIRequestContext } from "@playwright/test";
 import { expect, test } from "../helpers/disposable-users";
 import { ADMIN, USER } from "../helpers/accounts";
+import { mailpitReachable, waitForOtp } from "../helpers/mailpit";
+import { totpCode } from "../helpers/totp";
 
 const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
 const origin = { origin: base };
+const PASSWORD = "Podokit3e-Str0ng!pw";
 
-type Entry = { id: string; action: string; actorEmail: string | null; targetLabel: string | null; createdAt: string };
+type Entry = {
+  id: string;
+  action: string;
+  actorEmail: string | null;
+  targetLabel: string | null;
+  metadata: Record<string, unknown> | null;
+  createdAt: string;
+};
 
 async function signedIn(
   playwright: import("@playwright/test").PlaywrightWorkerArgs["playwright"],
@@ -19,6 +30,13 @@ function auditQuery(params: Record<string, string>): string {
   return `/api/audit-logs?${new URLSearchParams(params).toString()}`;
 }
 
+// Sign-in methods recorded for the account, oldest first.
+async function signInMethods(admin: APIRequestContext, email: string): Promise<unknown[]> {
+  const entries = (await (await admin.get(auditQuery({ action: "auth.login", target: email, order: "asc" }))).json()) as Entry[];
+  expect(entries.every((entry) => entry.actorEmail === email)).toBe(true);
+  return entries.map((entry) => entry.metadata?.method);
+}
+
 test("audit log records auth/admin actions", async ({ playwright, disposableUsers }) => {
   const admin = await signedIn(playwright, ADMIN);
   const probe = await admin.get("/api/audit-logs");
@@ -58,13 +76,22 @@ test("sending a verification email is audited", async ({ playwright, disposableU
   const admin = await signedIn(playwright, ADMIN);
   test.skip((await admin.get("/api/audit-logs")).status() === 404, "audit-log module not installed");
   const email = `verif-audit-${Date.now()}@example.com`;
-  const created = await admin.post("/api/auth/admin/create-user", {
-    data: { email, password: "Podokit3e-Str0ng!pw", name: "VA", role: "user" },
-  });
-  await disposableUsers.trackResponse(created);
-  await admin.post("/api/auth/send-verification-email", { data: { email, callbackURL: `${base}/admin` } });
-  const entries = (await (await admin.get(auditQuery({ action: "auth.verification_sent", target: email }))).json()) as Entry[];
+  await disposableUsers.create({ email, password: PASSWORD, name: "VA" });
+  const sent = async (): Promise<Entry[]> =>
+    (await (await admin.get(auditQuery({ action: "auth.verification_sent", target: email }))).json()) as Entry[];
+
+  // Better Auth sends a signed-in user's verification email only to their own address.
+  const refused = await admin.post("/api/auth/send-verification-email", { data: { email, callbackURL: `${base}/admin` } });
+  expect(refused.status()).toBe(400);
+  expect(await sent(), "a refused send is not audited").toEqual([]);
+
+  const user = await signedIn(playwright, { email, password: PASSWORD });
+  const own = await user.post("/api/auth/send-verification-email", { data: { email, callbackURL: `${base}/account` } });
+  expect(own.ok()).toBeTruthy();
+  const entries = await sent();
   expect(entries, "verification send should be audited").toHaveLength(1);
+  expect(entries[0]?.actorEmail).toBe(email);
+  await user.dispose();
   await admin.dispose();
 });
 
@@ -126,6 +153,68 @@ test("the audit log rejects bad paging parameters", async ({ playwright }) => {
   await admin.dispose();
 });
 
+test("a wrong password is not audited as a sign-in", async ({ playwright, disposableUsers }) => {
+  const admin = await signedIn(playwright, ADMIN);
+  test.skip((await admin.get("/api/audit-logs")).status() === 404, "audit-log module not installed");
+  const email = `audit-password-${Date.now()}@example.com`;
+  await disposableUsers.create({ email, password: PASSWORD });
+
+  const visitor = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+  const wrong = await visitor.post("/api/auth/sign-in/email", { data: { email, password: "Wrong-password-1" } });
+  expect(wrong.status()).toBe(401);
+  expect(await signInMethods(admin, email), "a failed sign-in leaves no auth.login").toEqual([]);
+
+  expect((await visitor.post("/api/auth/sign-in/email", { data: { email, password: PASSWORD } })).ok()).toBeTruthy();
+  expect(await signInMethods(admin, email)).toEqual(["password"]);
+  await visitor.dispose();
+  await admin.dispose();
+});
+
+test("an email code sign-in is audited once", async ({ playwright, disposableUsers }) => {
+  test.skip(!(await mailpitReachable()), "Mailpit not available");
+  const admin = await signedIn(playwright, ADMIN);
+  test.skip((await admin.get("/api/audit-logs")).status() === 404, "audit-log module not installed");
+  const caps = await (await admin.get("/api/account/capabilities")).json();
+  test.skip(!caps?.emailOtp, "email OTP not enabled");
+  const email = `audit-otp-${Date.now()}@example.com`;
+  await disposableUsers.create({ email, password: PASSWORD });
+
+  const visitor = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+  const sent = await visitor.post("/api/auth/email-otp/send-verification-otp", { data: { email, type: "sign-in" } });
+  expect(sent.ok()).toBeTruthy();
+  const otp = await waitForOtp(email);
+  expect((await visitor.post("/api/auth/sign-in/email-otp", { data: { email, otp } })).ok()).toBeTruthy();
+  expect(await signInMethods(admin, email)).toEqual(["email-otp"]);
+  await visitor.dispose();
+  await admin.dispose();
+});
+
+test("a two-factor sign-in is audited when the code completes it", async ({ playwright, disposableUsers }) => {
+  const admin = await signedIn(playwright, ADMIN);
+  test.skip((await admin.get("/api/audit-logs")).status() === 404, "audit-log module not installed");
+  const caps = await (await admin.get("/api/account/capabilities")).json();
+  test.skip(!caps?.twoFactor, "two-factor not enabled");
+  const email = `audit-2fa-${Date.now()}@example.com`;
+  await disposableUsers.create({ email, password: PASSWORD });
+
+  const owner = await signedIn(playwright, { email, password: PASSWORD });
+  const enable = await (await owner.post("/api/auth/two-factor/enable", { data: { password: PASSWORD } })).json();
+  expect((await owner.post("/api/auth/two-factor/verify-totp", { data: { code: totpCode(enable.totpURI) } })).ok()).toBeTruthy();
+  expect(await signInMethods(admin, email), "turning on two-factor is not a sign-in").toEqual(["password"]);
+
+  const challenged = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+  const pending = await (await challenged.post("/api/auth/sign-in/email", { data: { email, password: PASSWORD } })).json();
+  expect(pending.twoFactorRedirect).toBe(true);
+  expect(await signInMethods(admin, email), "the password step alone is not a sign-in").toEqual(["password"]);
+
+  const verified = await challenged.post("/api/auth/two-factor/verify-totp", { data: { code: totpCode(enable.totpURI) } });
+  expect(verified.ok()).toBeTruthy();
+  expect(await signInMethods(admin, email)).toEqual(["password", "two-factor-totp"]);
+  await owner.dispose();
+  await challenged.dispose();
+  await admin.dispose();
+});
+
 // Audit logging is a DB-backed on/off toggle (auth_config `server`, applied live).
 // Runs after the recording tests and restores the flag so nothing else is affected.
 test("audit logging honours the DB on/off toggle @smoke", { tag: "@exclusive" }, async ({ playwright, disposableUsers }) => {

package/dist/templates/modules/admin-dashboard/files/tests/api/auth.api.spec.ts

@@ -339,6 +339,17 @@ test("a user can create, list and delete an organization @smoke", async ({ playw
   const list = (await (await ctx.get("/api/auth/organization/list")).json()) as Array<{ id: string; slug: string }>;
   expect(list.some((o) => o.slug === slug)).toBeTruthy();
 
+  // A filter or a page that matches no member is an empty list, not a server error.
+  const userId = ((await (await ctx.get("/api/auth/get-session")).json()) as { user: { id: string } }).user.id;
+  const members = async (query: string): Promise<unknown> => {
+    const response = await ctx.get(`/api/auth/organization/list-members?organizationId=${orgId}&${query}`);
+    expect(response.status(), query).toBe(200);
+    return response.json();
+  };
+  expect(await members(`filterField=userId&filterValue=${userId}`)).toMatchObject({ members: [{ userId }], total: 1 });
+  expect(await members("filterField=userId&filterValue=not-a-member")).toEqual({ members: [], total: 0 });
+  expect(await members("offset=1")).toEqual({ members: [], total: 1 });
+
   const del = await ctx.post("/api/auth/organization/delete", { data: { organizationId: orgId } });
   expect(del.ok()).toBeTruthy();
   await ctx.dispose();

package/dist/templates/modules/admin-dashboard/files/tests/helpers/hydration.ts

@@ -1,9 +1,18 @@
 import type { Page } from "@playwright/test";
 
-// Wait for SvelteKit to attach client event handlers before driving forms. The
-// root layout adds this marker from onMount, so no fixed timing assumption is
-// needed even while the development server compiles a route for the first time.
+/**
+ * Waits until SvelteKit has attached the current document's event handlers. The
+ * root layout adds this marker from onMount, so no fixed timing assumption is
+ * needed even while the development server compiles a route for the first time.
+ * Call it after `page.reload()` too: the reloaded document is visible, and
+ * clickable, before its handlers exist, so an early click does nothing.
+ */
+export async function hydrated(page: Page): Promise<void> {
+  await page.locator('html[data-hydrated="true"]').waitFor();
+}
+
+/** Opens `path` and waits for hydration before a test drives the page. */
 export async function ready(page: Page, path: string): Promise<void> {
   await page.goto(path);
-  await page.locator('html[data-hydrated="true"]').waitFor();
+  await hydrated(page);
 }

package/dist/templates/modules/admin-dashboard/files/tests/playwright.config.ts

@@ -1,5 +1,5 @@
 import { defineConfig, devices } from "@playwright/test";
-import { e2eWorkers, loadPlaywrightProjects, withExclusivePhase } from "./playwright.extensions";
+import { e2eRunSettings, loadPlaywrightProjects, withExclusivePhase } from "./playwright.extensions";
 
 // admin-dashboard overlay: adds a `setup` project that seeds admin/user sessions
 // (storageState) which the `ui` project reuses, and a `cleanup` project that
@@ -7,9 +7,10 @@ import { e2eWorkers, loadPlaywrightProjects, withExclusivePhase } from "./playwr
 // E2E_BASE_URL. Tests share one backend and database: E2E_WORKERS sets the
 // worker count (default 1), and tests tagged @exclusive, which change state the
 // others rely on, run one at a time in `<project>-exclusive` twins after the
-// others (see playwright.extensions.ts). Each file runs on one worker in order.
+// others, in a second run when run-e2e.ts starts the suite on more workers (see
+// playwright.extensions.ts). Each file runs on one worker in order.
 const baseURL = process.env.E2E_BASE_URL ?? "http://localhost:5001";
-const workers = e2eWorkers();
+const run = e2eRunSettings();
 const coreProjects = [
   { name: "api", testMatch: /.*\.api\.spec\.ts/, dependencies: ["setup"] },
   { name: "setup", testMatch: /.*\.setup\.ts/, teardown: "cleanup" },
@@ -27,9 +28,10 @@ export default defineConfig({
   fullyParallel: false,
   forbidOnly: !!process.env.CI,
   retries: process.env.CI ? 2 : 0,
-  workers,
+  workers: run.workers,
+  outputDir: run.outputDir,
   globalSetup: "./playwright.extensions.ts",
-  reporter: [["list"], ["html", { open: "never" }]],
+  reporter: [["list"], ["html", { open: "never", outputFolder: run.reportFolder }]],
   use: { baseURL, trace: "on-first-retry", screenshot: "only-on-failure" },
-  projects: withExclusivePhase([...coreProjects, ...loadPlaywrightProjects(coreProjects)], workers),
+  projects: withExclusivePhase([...coreProjects, ...loadPlaywrightProjects(coreProjects)], run.workers, run.phase),
 });

package/dist/templates/modules/admin-dashboard/files/tests/ui/theme-mode.ui.spec.ts

@@ -1,29 +1,35 @@
-import { expect, test } from "@playwright/test";
-import { ready } from "../helpers/hydration";
+import { expect, test, type Page } from "@playwright/test";
+import { hydrated, ready } from "../helpers/hydration";
+import { paths } from "../helpers/paths";
+
+async function chooseTheme(page: Page, mode: "Light" | "Dark" | "System"): Promise<void> {
+  await page.getByTestId("theme-toggle").click();
+  await page.getByRole("menuitem", { name: mode }).click();
+}
 
 // mode-watcher marks <html> with `.dark` or `.light`, so component libraries
 // that follow either class, and fall back to the OS setting otherwise, match the
-// theme the visitor chose rather than the system one.
+// theme the visitor chose rather than the system one. The managed ThemeToggle
+// renders on the page app-paths.ts names as themeToggle.
 test("the chosen theme is named on <html> in both modes", async ({ page }) => {
+  test.skip(paths.themeToggle === null, "no page renders the theme toggle (tests/helpers/app-paths.ts)");
   await page.emulateMedia({ colorScheme: "dark" });
-  await ready(page, "/account");
+  await ready(page, paths.themeToggle ?? "/");
   const html = page.locator("html");
 
-  await page.getByRole("button", { name: "Toggle theme" }).click();
-  await page.getByRole("menuitem", { name: "Light" }).click();
+  await chooseTheme(page, "Light");
   await expect(html).toHaveClass(/(^|\s)light(\s|$)/);
   await expect(html).not.toHaveClass(/(^|\s)dark(\s|$)/);
 
   // The class is set before the page renders, not only after a choice.
   await page.reload();
   await expect(html).toHaveClass(/(^|\s)light(\s|$)/);
+  await hydrated(page);
 
-  await page.getByRole("button", { name: "Toggle theme" }).click();
-  await page.getByRole("menuitem", { name: "Dark" }).click();
+  await chooseTheme(page, "Dark");
   await expect(html).toHaveClass(/(^|\s)dark(\s|$)/);
   await expect(html).not.toHaveClass(/(^|\s)light(\s|$)/);
 
-  await page.getByRole("button", { name: "Toggle theme" }).click();
-  await page.getByRole("menuitem", { name: "System" }).click();
+  await chooseTheme(page, "System");
   await expect(html).toHaveClass(/(^|\s)dark(\s|$)/);
 });