@podosoft/podokit 1.4.2 → 1.6.0

package/dist/templates/modules/admin-dashboard/files/tests/ui/settings-dialogs.ui.spec.ts

@@ -1,60 +1,57 @@
 import { expect, test } from "@playwright/test";
 import { ready } from "../helpers/hydration";
-import { exclusive } from "../helpers/exclusive";
 
 // admin storageState (project default)
 
-test("settings: add and remove a social login provider", async ({ page }) => {
+test("settings: add and remove a social login provider", { tag: "@exclusive" }, async ({ page }) => {
   test.slow();
-  await exclusive("social-providers", async () => {
-    const dialog = page.getByRole("dialog");
-    const addBtn = dialog.getByRole("button", { name: "Add provider" });
-    const openConfigure = async (): Promise<void> => {
-      await page.waitForLoadState("networkidle");
-      await page.getByRole("tab", { name: "Authentication" }).click();
-      const socialCard = page
-        .getByText("Social login", { exact: true })
-        .locator('xpath=ancestor::div[@data-slot="card"]');
-      await socialCard.getByRole("button", { name: "Configure" }).click();
-    };
+  const dialog = page.getByRole("dialog");
+  const addBtn = dialog.getByRole("button", { name: "Add provider" });
+  const openConfigure = async (): Promise<void> => {
+    await page.waitForLoadState("networkidle");
+    await page.getByRole("tab", { name: "Authentication" }).click();
+    const socialCard = page
+      .getByText("Social login", { exact: true })
+      .locator('xpath=ancestor::div[@data-slot="card"]');
+    await socialCard.getByRole("button", { name: "Configure" }).click();
+  };
 
-    await ready(page, "/admin/settings");
-    // The auth-config catalog can be momentarily unavailable right after another
-    // spec toggles auth config (the auth instance rebuilds). Reload until the
-    // catalog is loaded (Add provider becomes enabled).
-    await expect(async () => {
-      await page.reload();
-      await openConfigure();
-      await expect(addBtn).toBeEnabled({ timeout: 3000 });
-    }).toPass({ timeout: 25000 });
+  await ready(page, "/admin/settings");
+  // The auth-config catalog can be momentarily unavailable right after another
+  // spec toggles auth config (the auth instance rebuilds). Reload until the
+  // catalog is loaded (Add provider becomes enabled).
+  await expect(async () => {
+    await page.reload();
+    await openConfigure();
+    await expect(addBtn).toBeEnabled({ timeout: 3000 });
+  }).toPass({ timeout: 25000 });
 
-    await addBtn.click();
-    const provider = dialog.locator("#social-provider");
-    await expect(provider).toBeVisible();
-    const callback = await dialog.locator("code").textContent();
-    const providerId = callback?.trim().split("/").pop() ?? ""; // first addable provider (not hard-coded)
-    expect(providerId).not.toBe("");
-    const expectedCallback = new URL(`/api/auth/callback/${providerId}`, page.url()).toString();
-    expect(callback?.trim()).toBe(expectedCallback);
-    try {
-      await dialog.locator("#social-id").fill("test-client-id");
-      await dialog.locator("#social-secret").fill("test-secret");
-      await dialog.getByRole("button", { name: "Save", exact: true }).click();
-      // Save returns to the list view, where the new provider row has an enable switch.
-      await expect(dialog.getByRole("switch").first()).toBeVisible();
-      const saved = await (await page.request.get("/api/account/auth-config")).json();
-      expect(saved.social[providerId].redirectURI).toBe(expectedCallback);
-    } finally {
-      if (providerId) {
-        await page.request
-          .put("/api/account/auth-config", { data: { social: { [providerId]: { delete: true } } } })
-          .catch(() => undefined);
-      }
+  await addBtn.click();
+  const provider = dialog.locator("#social-provider");
+  await expect(provider).toBeVisible();
+  const callback = await dialog.locator("code").textContent();
+  const providerId = callback?.trim().split("/").pop() ?? ""; // first addable provider (not hard-coded)
+  expect(providerId).not.toBe("");
+  const expectedCallback = new URL(`/api/auth/callback/${providerId}`, page.url()).toString();
+  expect(callback?.trim()).toBe(expectedCallback);
+  try {
+    await dialog.locator("#social-id").fill("test-client-id");
+    await dialog.locator("#social-secret").fill("test-secret");
+    await dialog.getByRole("button", { name: "Save", exact: true }).click();
+    // Save returns to the list view, where the new provider row has an enable switch.
+    await expect(dialog.getByRole("switch").first()).toBeVisible();
+    const saved = await (await page.request.get("/api/account/auth-config")).json();
+    expect(saved.social[providerId].redirectURI).toBe(expectedCallback);
+  } finally {
+    if (providerId) {
+      await page.request
+        .put("/api/account/auth-config", { data: { social: { [providerId]: { delete: true } } } })
+        .catch(() => undefined);
     }
-  });
+  }
 });
 
-test("settings: open and save the SMTP dialog", async ({ page }) => {
+test("settings: open and save the SMTP dialog", { tag: "@exclusive" }, async ({ page }) => {
   await ready(page, "/admin/settings");
   await page.getByRole("tab", { name: "Authentication" }).click();
   await page.getByRole("button", { name: "SMTP settings" }).click();
@@ -74,35 +71,32 @@ test("settings: open and save the SMTP dialog", async ({ page }) => {
   }
 });
 
-test("settings: configure automatic logout", async ({ page }) => {
-  test.slow();
-  await exclusive("session-idle-timeout", async () => {
-    await page.request.put("/api/account/auth-config", {
-      data: { server: { sessionIdleTimeoutMinutes: null } },
-    });
-    await ready(page, "/admin/settings");
-    await page.getByRole("tab", { name: "Authentication" }).click();
+test("settings: configure automatic logout", { tag: "@exclusive" }, async ({ page }) => {
+  await page.request.put("/api/account/auth-config", {
+    data: { server: { sessionIdleTimeoutMinutes: null } },
+  });
+  await ready(page, "/admin/settings");
+  await page.getByRole("tab", { name: "Authentication" }).click();
 
-    const toggle = page.getByRole("switch", { name: "Automatic logout" });
-    await expect(toggle).not.toBeChecked();
-    await toggle.click();
-    await expect(toggle).toBeChecked();
+  const toggle = page.getByRole("switch", { name: "Automatic logout" });
+  await expect(toggle).not.toBeChecked();
+  await toggle.click();
+  await expect(toggle).toBeChecked();
 
-    const card = page
-      .getByText("Automatic logout", { exact: true })
-      .locator('xpath=ancestor::div[@data-slot="card"]');
-    await card.getByRole("button", { name: "Configure" }).click();
-    const dialog = page.getByRole("dialog");
-    await dialog.getByLabel("Idle time (minutes)").fill("45");
-    await dialog.getByRole("button", { name: "Save", exact: true }).click();
-    await expect(page.getByText("45 min", { exact: true })).toBeVisible();
+  const card = page
+    .getByText("Automatic logout", { exact: true })
+    .locator('xpath=ancestor::div[@data-slot="card"]');
+  await card.getByRole("button", { name: "Configure" }).click();
+  const dialog = page.getByRole("dialog");
+  await dialog.getByLabel("Idle time (minutes)").fill("45");
+  await dialog.getByRole("button", { name: "Save", exact: true }).click();
+  await expect(page.getByText("45 min", { exact: true })).toBeVisible();
 
-    const saved = await (await page.request.get("/api/account/auth-config")).json();
-    expect(saved.server.sessionIdleTimeoutMinutes).toBe(45);
-    const caps = await (await page.request.get("/api/account/capabilities")).json();
-    expect(caps.sessionIdleTimeoutMinutes).toBe(45);
+  const saved = await (await page.request.get("/api/account/auth-config")).json();
+  expect(saved.server.sessionIdleTimeoutMinutes).toBe(45);
+  const caps = await (await page.request.get("/api/account/capabilities")).json();
+  expect(caps.sessionIdleTimeoutMinutes).toBe(45);
 
-    await toggle.click();
-    await expect(toggle).not.toBeChecked();
-  });
+  await toggle.click();
+  await expect(toggle).not.toBeChecked();
 });

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

@@ -1,6 +1,6 @@
 import { expect, test, type Page } from "@playwright/test";
 import { ready } from "../helpers/hydration";
-import { exclusive } from "../helpers/exclusive";
+import { paths } from "../helpers/paths";
 
 // admin storageState (project default)
 
@@ -30,20 +30,17 @@ test("general settings: shows the favicon uploader", async ({ page }) => {
   await expect(page.locator('input[type="file"]')).toBeVisible();
 });
 
-test("general settings: edit the site name, save, and apply live", async ({ page }) => {
-  test.slow();
-  await exclusive("site-general", async () => {
-    await ready(page, "/admin/settings");
-    const name = page.getByLabel("Site name");
-    const original = await name.inputValue();
-    await name.fill("PodoKit Test Site");
-    await saveGeneral(page);
-    // the browser tab title reflects the new name live (no reload)
-    await expect(page).toHaveTitle("PodoKit Test Site");
-    // restore so other specs start clean
-    await name.fill(original);
-    await saveGeneral(page);
-  });
+test("general settings: edit the site name, save, and apply live", { tag: "@exclusive" }, async ({ page }) => {
+  await ready(page, "/admin/settings");
+  const name = page.getByLabel("Site name");
+  const original = await name.inputValue();
+  await name.fill("PodoKit Test Site");
+  await saveGeneral(page);
+  // the browser tab title reflects the new name live (no reload)
+  await expect(page).toHaveTitle("PodoKit Test Site");
+  // restore so other specs start clean
+  await name.fill(original);
+  await saveGeneral(page);
 });
 
 test("settings lists the auth features under the Authentication tab", async ({ page }) => {
@@ -62,8 +59,8 @@ test("sidebar: back-to-home link returns to the landing page", async ({ page })
   // the home link lives in the sidebar footer, above the user menu
   await page.getByRole("link", { name: "Back to home" }).click();
   await expect(page).toHaveURL(/\/$/);
-  // Landing routes are app-owned, so only verify the shared page shell.
-  await expect(page.locator("main").first()).toBeVisible();
+  // The landing page is app-owned; tests/helpers/app-paths.ts says what shows it rendered.
+  await expect(paths.homeReady(page)).toBeVisible();
 });
 
 test("settings is reachable from the sidebar", async ({ page }) => {
@@ -72,22 +69,18 @@ test("settings is reachable from the sidebar", async ({ page }) => {
   await expect(page).toHaveURL(/\/admin\/settings/);
 });
 
-test("admin can toggle a feature flag and it applies live @smoke", async ({ page }) => {
-  test.slow();
-  await exclusive("magic-link", async () => {
-    await ready(page, "/admin/settings");
-    await page.getByRole("tab", { name: "Authentication" }).click();
-    const toggle = page.getByRole("switch", { name: "Magic link" });
-    test.skip((await toggle.count()) === 0, "magic link toggle not present");
-    // The magic-link lock keeps the API spec that toggles the same flag out.
-    await expect(toggle).toBeChecked();
-    await toggle.click();
-    await expect(page.getByText("Setting updated")).toBeVisible();
-    await expect(toggle).not.toBeChecked(); // capabilities refreshed live
-    // restore so the shared magic-link/2FA specs keep their expected state
-    await toggle.click();
-    await expect(toggle).toBeChecked();
-  });
+test("admin can toggle a feature flag and it applies live @smoke", { tag: "@exclusive" }, async ({ page }) => {
+  await ready(page, "/admin/settings");
+  await page.getByRole("tab", { name: "Authentication" }).click();
+  const toggle = page.getByRole("switch", { name: "Magic link" });
+  test.skip((await toggle.count()) === 0, "magic link toggle not present");
+  await expect(toggle).toBeChecked();
+  await toggle.click();
+  await expect(page.getByText("Setting updated")).toBeVisible();
+  await expect(toggle).not.toBeChecked(); // capabilities refreshed live
+  // restore so the shared magic-link/2FA specs keep their expected state
+  await toggle.click();
+  await expect(toggle).toBeChecked();
 });
 
 test("settings: the require-two-factor toggle is available", async ({ page }) => {
@@ -101,72 +94,70 @@ test("settings: the require-two-factor toggle is available", async ({ page }) =>
   await expect(page.getByRole("switch", { name: "Automatic logout" })).toBeVisible();
 });
 
-test("inactive browser sessions are signed out automatically @smoke", async ({ browser, page: adminPage }) => {
+test("inactive browser sessions are signed out automatically @smoke", { tag: "@exclusive" }, async ({ browser, page: adminPage }) => {
   test.slow();
-  await exclusive("session-idle-timeout", async () => {
-    // Idle sign-out revokes the active server session. Use a dedicated login so
-    // this test cannot invalidate the shared admin storageState used by later specs.
-    const context = await browser.newContext({ baseURL: base });
-    const page = await context.newPage();
-    const email = `idle-admin-${Date.now()}@example.com`;
-    let signOutRequests = 0;
-    let userId = "";
-    try {
-      const created = await adminPage.request.post("/api/auth/admin/create-user", {
-        headers: { origin: base },
-        data: { email, password: "Podokit3e-Str0ng!pw", name: "Idle Admin", role: "admin" },
-      });
-      expect(created.ok()).toBeTruthy();
-      userId = ((await created.json()).user?.id ?? "") as string;
-      expect(userId).toBeTruthy();
+  // Idle sign-out revokes the active server session. Use a dedicated login so
+  // this test cannot invalidate the shared admin storageState used by later specs.
+  const context = await browser.newContext({ baseURL: base });
+  const page = await context.newPage();
+  const email = `idle-admin-${Date.now()}@example.com`;
+  let signOutRequests = 0;
+  let userId = "";
+  try {
+    const created = await adminPage.request.post("/api/auth/admin/create-user", {
+      headers: { origin: base },
+      data: { email, password: "Podokit3e-Str0ng!pw", name: "Idle Admin", role: "admin" },
+    });
+    expect(created.ok()).toBeTruthy();
+    userId = ((await created.json()).user?.id ?? "") as string;
+    expect(userId).toBeTruthy();
+
+    const signIn = await context.request.post("/api/auth/sign-in/email", {
+      headers: { origin: base },
+      data: { email, password: "Podokit3e-Str0ng!pw" },
+    });
+    expect(signIn.ok()).toBeTruthy();
+
+    const configured = await context.request.put("/api/account/auth-config", {
+      data: { server: { sessionIdleTimeoutMinutes: 5 } },
+    });
+    expect(configured.ok()).toBeTruthy();
+    await page.route("**/api/auth/sign-out", async (route) => {
+      signOutRequests += 1;
+      await route.fulfill({ status: 200, contentType: "application/json", body: '{"success":true}' });
+    });
+    await page.clock.install();
 
-      const signIn = await context.request.post("/api/auth/sign-in/email", {
-        headers: { origin: base },
-        data: { email, password: "Podokit3e-Str0ng!pw" },
+    try {
+      await ready(page, "/admin");
+      await expect(page.getByRole("heading", { name: "Dashboard" })).toBeVisible();
+    } finally {
+      // Keep the loaded page policy at five minutes while restoring the shared
+      // DB policy before the isolated session is revoked.
+      const restored = await context.request.put("/api/account/auth-config", {
+        data: { server: { sessionIdleTimeoutMinutes: null } },
       });
-      expect(signIn.ok()).toBeTruthy();
+      expect(restored.ok()).toBeTruthy();
+    }
 
-      const configured = await context.request.put("/api/account/auth-config", {
-        data: { server: { sessionIdleTimeoutMinutes: 5 } },
-      });
-      expect(configured.ok()).toBeTruthy();
-      await page.route("**/api/auth/sign-out", async (route) => {
-        signOutRequests += 1;
-        await route.fulfill({ status: 200, contentType: "application/json", body: '{"success":true}' });
-      });
-      await page.clock.install();
-
-      try {
-        await ready(page, "/admin");
-        await expect(page.getByRole("heading", { name: "Dashboard" })).toBeVisible();
-      } finally {
-        // Keep the loaded page policy at five minutes while restoring the shared
-        // DB policy before the isolated session is revoked.
-        const restored = await context.request.put("/api/account/auth-config", {
-          data: { server: { sessionIdleTimeoutMinutes: null } },
-        });
-        expect(restored.ok()).toBeTruthy();
-      }
-
-      const removed = await adminPage.request.post("/api/auth/admin/remove-user", {
+    const removed = await adminPage.request.post("/api/auth/admin/remove-user", {
+      headers: { origin: base },
+      data: { userId },
+    });
+    expect(removed.ok()).toBeTruthy();
+    userId = "";
+
+    await page.clock.fastForward(5 * 60_000 + 1_000);
+    await expect.poll(() => signOutRequests).toBe(1);
+    await expect(page).toHaveURL(/\/login\?reason=idle$/);
+    await expect(page.getByTestId("session-timeout-message")).toBeVisible();
+  } finally {
+    if (userId) {
+      await adminPage.request.post("/api/auth/admin/remove-user", {
         headers: { origin: base },
         data: { userId },
       });
-      expect(removed.ok()).toBeTruthy();
-      userId = "";
-
-      await page.clock.fastForward(5 * 60_000 + 1_000);
-      await expect.poll(() => signOutRequests).toBe(1);
-      await expect(page).toHaveURL(/\/login\?reason=idle$/);
-      await expect(page.getByTestId("session-timeout-message")).toBeVisible();
-    } finally {
-      if (userId) {
-        await adminPage.request.post("/api/auth/admin/remove-user", {
-          headers: { origin: base },
-          data: { userId },
-        });
-      }
-      await context.close();
     }
-  });
+    await context.close();
+  }
 });

package/dist/templates/modules/admin-dashboard/files/tests/ui/table-toolbar.ui.spec.ts

@@ -1,4 +1,5 @@
 import { expect, test } from "@playwright/test";
+import { ADMIN, USER } from "../helpers/accounts";
 import { ready } from "../helpers/hydration";
 
 // The shared toolbar: filters + search both commit on the Search button; the
@@ -6,10 +7,10 @@ import { ready } from "../helpers/hydration";
 test("users toolbar searches only when Search is pressed", async ({ page }) => {
   await ready(page, "/admin/users");
   const main = page.getByRole("main");
-  await page.locator("#toolbar-search").fill("admin@example.com");
+  await page.locator("#toolbar-search").fill(ADMIN.email);
   await page.getByRole("button", { name: "Search", exact: true }).click();
-  await expect(main.getByRole("cell", { name: "admin@example.com" })).toBeVisible();
-  await expect(main.getByRole("cell", { name: "user@example.com" })).toHaveCount(0);
+  await expect(main.getByRole("cell", { name: ADMIN.email })).toBeVisible();
+  await expect(main.getByRole("cell", { name: USER.email })).toHaveCount(0);
 });
 
 test("users toolbar applies filter + search together on Search", async ({ page }) => {
@@ -24,8 +25,8 @@ test("users toolbar applies filter + search together on Search", async ({ page }
   });
   await page.getByRole("button", { name: "Search", exact: true }).click();
   expect((await filtered).ok()).toBeTruthy();
-  await expect(main.getByRole("cell", { name: "admin@example.com" })).toBeVisible();
-  await expect(main.getByRole("cell", { name: "user@example.com" })).toHaveCount(0);
+  await expect(main.getByRole("cell", { name: ADMIN.email })).toBeVisible();
+  await expect(main.getByRole("cell", { name: USER.email })).toHaveCount(0);
 });
 
 test("users toolbar combines the role and status filters", async ({ page }) => {
@@ -48,8 +49,8 @@ test("users toolbar combines the role and status filters", async ({ page }) => {
   });
   await page.getByRole("button", { name: "Search", exact: true }).click();
   expect((await filtered).ok()).toBeTruthy();
-  await expect(main.getByRole("cell", { name: "admin@example.com" })).toBeVisible();
-  await expect(main.getByRole("cell", { name: "user@example.com" })).toHaveCount(0);
+  await expect(main.getByRole("cell", { name: ADMIN.email })).toBeVisible();
+  await expect(main.getByRole("cell", { name: USER.email })).toHaveCount(0);
 });
 
 test("users toolbar can pick the search field", async ({ page }) => {
@@ -59,3 +60,28 @@ test("users toolbar can pick the search field", async ({ page }) => {
   await page.getByRole("option", { name: "Name", exact: true }).click();
   await expect(fieldSelect).toContainText("Name");
 });
+
+test("users toolbar keeps the search box usable at phone width", async ({ page }) => {
+  await page.setViewportSize({ width: 390, height: 844 });
+  await ready(page, "/admin/users");
+  const input = await page.locator("#toolbar-search").boundingBox();
+  const field = await page.locator('button[data-slot="select-trigger"]').last().boundingBox();
+  const button = await page.getByRole("button", { name: "Search", exact: true }).boundingBox();
+  if (!input || !field || !button) throw new Error("expected the toolbar to render");
+  // The input wraps below the field select instead of shrinking beside it.
+  expect(input.width).toBeGreaterThanOrEqual(192);
+  expect(input.y).toBeGreaterThan(field.y + field.height);
+  expect(Math.abs(input.y + input.height / 2 - (button.y + button.height / 2))).toBeLessThan(1);
+  expect(await page.evaluate(() => document.documentElement.scrollWidth - document.documentElement.clientWidth))
+    .toBe(0);
+});
+
+test("users toolbar keeps the desktop search box on one row", async ({ page }) => {
+  await page.setViewportSize({ width: 1280, height: 800 });
+  await ready(page, "/admin/users");
+  const input = await page.locator("#toolbar-search").boundingBox();
+  const field = await page.locator('button[data-slot="select-trigger"]').last().boundingBox();
+  if (!input || !field) throw new Error("expected the toolbar to render");
+  expect(input.width).toBe(320);
+  expect(Math.abs(input.y + input.height / 2 - (field.y + field.height / 2))).toBeLessThan(1);
+});

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

@@ -0,0 +1,29 @@
+import { expect, test } from "@playwright/test";
+import { ready } from "../helpers/hydration";
+
+// 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.
+test("the chosen theme is named on <html> in both modes", async ({ page }) => {
+  await page.emulateMedia({ colorScheme: "dark" });
+  await ready(page, "/account");
+  const html = page.locator("html");
+
+  await page.getByRole("button", { name: "Toggle theme" }).click();
+  await page.getByRole("menuitem", { name: "Light" }).click();
+  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 page.getByRole("button", { name: "Toggle theme" }).click();
+  await page.getByRole("menuitem", { name: "Dark" }).click();
+  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 expect(html).toHaveClass(/(^|\s)dark(\s|$)/);
+});

package/dist/templates/modules/admin-dashboard/files/tests/ui/two-factor.ui.spec.ts

@@ -1,7 +1,6 @@
 import { expect, test, type Page } from "@playwright/test";
 import { ADMIN, USER, anonState } from "../helpers/accounts";
 import { totpCode } from "../helpers/totp";
-import { exclusive } from "../helpers/exclusive";
 
 test.use({ storageState: anonState });
 
@@ -85,62 +84,60 @@ test("two-factor: sign in with an authenticator code from the login page", async
   await expectAccountPage(page);
 });
 
-test("require-2fa: a new sign-up is forced through the enrolment page", async ({ page, playwright }) => {
+test("require-2fa: a new sign-up is forced through the enrolment page", { tag: "@exclusive" }, async ({ page, playwright }) => {
   test.slow();
-  await exclusive("require2fa", async () => {
-    const admin = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
-    const caps = await (await admin.get("/api/account/capabilities")).json();
-    test.skip(!caps?.twoFactor, "two-factor not enabled");
-    await admin.post("/api/auth/sign-in/email", { data: { email: ADMIN.email, password: ADMIN.password } });
-
-    const email = `rq-ui-${Date.now()}@example.com`;
-    const pw = "Podokit3e-Str0ng!pw";
-    try {
-      await admin.put("/api/account/settings", { data: { require2fa: true } });
-      // A fresh un-enrolled user; poll (via API) until the guard cache picks up the policy.
+  const admin = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+  const caps = await (await admin.get("/api/account/capabilities")).json();
+  test.skip(!caps?.twoFactor, "two-factor not enabled");
+  await admin.post("/api/auth/sign-in/email", { data: { email: ADMIN.email, password: ADMIN.password } });
+
+  const email = `rq-ui-${Date.now()}@example.com`;
+  const pw = "Podokit3e-Str0ng!pw";
+  try {
+    await admin.put("/api/account/settings", { data: { require2fa: true } });
+    // A fresh un-enrolled user; poll (via API) until the guard cache picks up the policy.
+    const probe = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+    await probe.post("/api/auth/sign-up/email", { data: { email, password: pw, name: "RQUI" } });
+    await expect(async () => {
+      expect((await probe.get("/api/account/me")).status()).toBe(403);
+    }).toPass({ timeout: 8000 });
+    await probe.dispose();
+
+    // Signing in toward a protected route lands on the mandatory enrolment page.
+    await openHydratedLogin(page, "/account");
+    await page.getByLabel("Email").fill(email);
+    await page.getByLabel("Password").fill(pw);
+    await page.getByRole("button", { name: "Sign in", exact: true }).click();
+    await expect(page).toHaveURL(/\/setup-2fa/);
+
+    // Complete enrolment entirely through the UI: password → QR + backup codes →
+    // authenticator code → activate. The code is computed from the on-page URI.
+    await page.getByLabel("Confirm your password").fill(pw);
+    await page.getByRole("button", { name: "Continue" }).click();
+    await expect(page.getByTestId("backup-codes")).toBeVisible();
+    await expect(page.getByRole("button", { name: "Download" })).toBeVisible();
+    const uri = (await page.locator("code").first().innerText()).trim();
+    await page.getByRole("checkbox").click();
+    await page.getByLabel("3. Enter the 6-digit code").fill(totpCode(uri));
+    await page.getByRole("button", { name: "Activate and continue" }).click();
+
+    // Enrolled → the gate lets the regular user into their account page.
+    await expectAccountPage(page);
+
+    // An enrolled user who revisits setup is returned to the same non-admin page.
+    await page.goto("/setup-2fa");
+    await expectAccountPage(page);
+  } finally {
+    await admin.put("/api/account/settings", { data: { require2fa: false } });
+    await expect(async () => {
       const probe = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
-      await probe.post("/api/auth/sign-up/email", { data: { email, password: pw, name: "RQUI" } });
-      await expect(async () => {
-        expect((await probe.get("/api/account/me")).status()).toBe(403);
-      }).toPass({ timeout: 8000 });
+      await probe.post("/api/auth/sign-in/email", { data: { email: USER.email, password: USER.password } });
+      const status = (await probe.get("/api/account/me")).status();
       await probe.dispose();
-
-      // Signing in toward a protected route lands on the mandatory enrolment page.
-      await openHydratedLogin(page, "/account");
-      await page.getByLabel("Email").fill(email);
-      await page.getByLabel("Password").fill(pw);
-      await page.getByRole("button", { name: "Sign in", exact: true }).click();
-      await expect(page).toHaveURL(/\/setup-2fa/);
-
-      // Complete enrolment entirely through the UI: password → QR + backup codes →
-      // authenticator code → activate. The code is computed from the on-page URI.
-      await page.getByLabel("Confirm your password").fill(pw);
-      await page.getByRole("button", { name: "Continue" }).click();
-      await expect(page.getByTestId("backup-codes")).toBeVisible();
-      await expect(page.getByRole("button", { name: "Download" })).toBeVisible();
-      const uri = (await page.locator("code").first().innerText()).trim();
-      await page.getByRole("checkbox").click();
-      await page.getByLabel("3. Enter the 6-digit code").fill(totpCode(uri));
-      await page.getByRole("button", { name: "Activate and continue" }).click();
-
-      // Enrolled → the gate lets the regular user into their account page.
-      await expectAccountPage(page);
-
-      // An enrolled user who revisits setup is returned to the same non-admin page.
-      await page.goto("/setup-2fa");
-      await expectAccountPage(page);
-    } finally {
-      await admin.put("/api/account/settings", { data: { require2fa: false } });
-      await expect(async () => {
-        const probe = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
-        await probe.post("/api/auth/sign-in/email", { data: { email: USER.email, password: USER.password } });
-        const status = (await probe.get("/api/account/me")).status();
-        await probe.dispose();
-        expect(status).toBe(200);
-      }).toPass({ timeout: 8000 });
-      await admin.dispose();
-    }
-  });
+      expect(status).toBe(200);
+    }).toPass({ timeout: 8000 });
+    await admin.dispose();
+  }
 });
 
 test("account: regenerate backup codes shows a fresh set", async ({ page, playwright }) => {