@cosmicdrift/kumiko-testing 0.305.0 → 0.306.0

package/README.md

@@ -78,3 +78,21 @@ receives the seeded-tenant fixture too:
 right before the screenshot. `runMatrix` calls it once per theme × viewport for the same scenario, so
 it must be idempotent — hide or mask an element rather than a one-shot action like clicking a button,
 which would only succeed on the first capture and time out on every one after.
+
+`runMatrix` also supports real device emulation via Playwright projects named after a viewport id
+(`desktop`, `tablet`, `mobile`) with `use.isMobile: true`:
+
+```ts
+projects: [
+  { name: "desktop", use: { ...devices["Desktop Chrome"] } },
+  { name: "tablet", use: { ...devices["iPad Pro 11"] } }, // portrait, WebKit
+  { name: "mobile", use: { ...devices["iPhone 13"] } }, // portrait, WebKit
+]
+```
+
+A device project captures exactly `<name>.png` at the device's native size — no `setViewportSize`,
+which would destroy the emulation. Any other project (the desktop pass) still loops the remaining
+viewports via `setViewportSize`, skipping the ids a device project already covers. Without device
+projects, nothing changes: desktop, tablet and mobile all render through `setViewportSize` as before.
+`SCREENSHOT_VIEWPORTS` still filters both — a filtered-out device project's test is skipped, not run
+empty. CI needs `bunx playwright install webkit` to run device projects that use a WebKit device.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-testing",
-  "version": "0.305.0",
+  "version": "0.306.0",
   "description": "Test template for Kumiko apps: per-flow seedTenant, app test stack, canonical test preloads, bunfig generator and integration runner.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -63,9 +63,9 @@
     "kumiko-testing": "./bin/kumiko-testing.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.305.0",
-    "@cosmicdrift/kumiko-dev-server": "0.305.0",
-    "@cosmicdrift/kumiko-framework": "0.305.0",
+    "@cosmicdrift/kumiko-bundled-features": "0.306.0",
+    "@cosmicdrift/kumiko-dev-server": "0.306.0",
+    "@cosmicdrift/kumiko-framework": "0.306.0",
     "zod": "^4.4.3"
   },
   "peerDependencies": {

package/src/changes.json

@@ -1,4 +1,21 @@
 [
+  {
+    "version": "0.306.0",
+    "type": "improvement",
+    "title": "clearSession(page) for race-free session switches in E2E"
+  },
+  {
+    "version": "0.306.0",
+    "type": "breaking",
+    "title": "mailCapture and the /__test/inbox route read tenantless mail via a new mailOutbox option",
+    "detail": "Apps sending Dev/E2E mail through a raw createInMemoryTransport() (signup,\nforgot-password, magic-link — flows with no tenant) had no way to read it\nthrough the seed inbox route, which required tenantId and only checked\nmailTransportInMemoryFeature's per-tenant buffer. createE2eSeedRoutes()\nnow accepts mailOutbox: { sent: readonly EmailMessage[] } (the raw\ntransport's own array); inboxQuerySchema's tenantId is optional. The route\nreads whichever source(s) are configured, filters by to, and returns each\nsource newest-first instead of oldest-first.",
+    "migration": "mailCapture(request, tenantId, to) -> mailCapture(request, to, { tenantId }),\nand it now resolves to a single CapturedMail (the newest match) instead of\na readonly CapturedMail[]. Pass match: (mail) => boolean to pick a mail\nother than the newest at that address. Apps with their own ungated debug\nroute for a raw transport (e.g. /_debug/mails.json) pass that transport as\ncreateE2eSeedRoutes({ mailOutbox: transport }) and delete the app-local\nroute; tenantId becomes optional wherever only mailOutbox is used. Any\ndirect reader of GET /__test/inbox must expect newest-first ordering."
+  },
+  {
+    "version": "0.306.0",
+    "type": "improvement",
+    "title": "runMatrix supports device-emulation Playwright projects for real native-size screenshots"
+  },
   {
     "version": "0.305.0",
     "type": "fix",

package/src/e2e/auth-kit.ts

@@ -48,9 +48,16 @@ export async function loginViaApi(
   }
 }
 
+// Leaves the app page first: an app page still open while its cookies vanish redirects itself
+// to /login?next=… on its next request, racing whatever the test navigates to next.
+export async function clearSession(page: Page): Promise<void> {
+  await page.goto("about:blank");
+  await page.context().clearCookies();
+}
+
 export async function loginViaUi(page: Page, credentials: LoginCredentials): Promise<void> {
   // seedTenant already logged the context in, and an authenticated session never renders /login.
-  await page.context().clearCookies();
+  await clearSession(page);
   await page.goto("/login");
   await page.locator("#login-email").fill(credentials.email);
   await page.locator("#login-password").fill(credentials.password);

package/src/e2e/index.ts

@@ -3,6 +3,7 @@ export {
   apiCommand,
   apiQuery,
   apiWrite,
+  clearSession,
   createHttpApi,
   csrfFetch,
   csrfHeaderFromCookies,
@@ -26,7 +27,7 @@ export {
   type E2eProject,
   resolveE2eWorkers,
 } from "./define-app-e2e-config";
-export { mailCapture } from "./mail-capture";
+export { type MailCaptureOptions, mailCapture } from "./mail-capture";
 export { pinEnglishLocale } from "./pin-english-locale";
 export { pollForRow, waitForProjection } from "./poll";
 export {

package/src/e2e/mail-capture.ts

@@ -15,12 +15,12 @@ export function seedRouteHeaders(): Record<string, string> {
 
 async function readInbox(
   request: APIRequestContext,
-  tenantId: string,
   to: string,
+  tenantId: string | undefined,
 ): Promise<readonly CapturedMail[]> {
   const response = await request.get(SEED_ROUTES.inbox, {
     headers: seedRouteHeaders(),
-    params: { tenantId, to },
+    params: tenantId === undefined ? { to } : { tenantId, to },
   });
   if (!response.ok()) {
     throw new Error(
@@ -30,14 +30,30 @@ async function readInbox(
   return inboxResponseSchema.parse(await response.json()).messages;
 }
 
-export function mailCapture(
+export type MailCaptureOptions = {
+  readonly tenantId?: string;
+  readonly match?: (mail: CapturedMail) => boolean;
+};
+
+// The inbox route returns the tenant buffer before the mailOutbox, each
+// newest-first; `.find` keeps that order because mails carry no timestamp.
+// With both sources mounted, a tenant-buffer match wins over a newer outbox one.
+export async function mailCapture(
   request: APIRequestContext,
-  tenantId: string,
   to: string,
-): Promise<readonly CapturedMail[]> {
-  return waitForProjection(
-    () => readInbox(request, tenantId, to),
-    (messages) => messages.length > 0,
-    `mailCapture: no mail arrived for ${to} in tenant ${tenantId}`,
+  opts: MailCaptureOptions = {},
+): Promise<CapturedMail> {
+  const { tenantId, match } = opts;
+  const isCandidate = (mail: CapturedMail) => match === undefined || match(mail);
+  const description = tenantId === undefined ? `for ${to}` : `for ${to} in tenant ${tenantId}`;
+  const message = `mailCapture: no mail arrived ${description}`;
+
+  const messages = await waitForProjection(
+    () => readInbox(request, to, tenantId),
+    (candidates) => candidates.some(isCandidate),
+    message,
   );
+  const mail = messages.find(isCandidate);
+  if (mail === undefined) throw new Error(message);
+  return mail;
 }

package/src/e2e/screenshots.ts

@@ -166,7 +166,7 @@ export function runScreenshots(scenarios: readonly Scenario[], opts: FlatOptions
 }
 
 const VIEWPORT_IDS = ["desktop", "tablet", "mobile"] as const;
-type ViewportId = (typeof VIEWPORT_IDS)[number];
+export type ViewportId = (typeof VIEWPORT_IDS)[number];
 const VIEWPORTS: Record<ViewportId, { readonly width: number; readonly height: number }> = {
   // 1920×1080 instead of the earlier 1280×900: these shots land in the
   // handbook and doc pages, where a 1280 image visibly softens on a HiDPI
@@ -245,6 +245,49 @@ export function findIdenticalThemeScreenshots<T extends string>(
   return violations;
 }
 
+export interface MatrixProjectInfo {
+  readonly name: string;
+  readonly isMobile: boolean;
+}
+
+export type MatrixViewportPlan =
+  | { readonly mode: "device"; readonly viewports: readonly [ViewportId] }
+  | { readonly mode: "desktop"; readonly viewports: readonly ViewportId[] }
+  | { readonly mode: "skip"; readonly reason: string };
+
+function isViewportId(name: string): name is ViewportId {
+  return VIEWPORT_IDS.some((id) => id === name);
+}
+
+// A device project (name === a ViewportId, use.isMobile === true) already
+// renders at its emulated device size, so setViewportSize would destroy that
+// emulation — it captures exactly its own viewport instead of looping. Every
+// other project runs the desktop pass, skipping ids a device project already
+// covers so the same image isn't produced twice.
+export function resolveMatrixViewports(
+  projectName: string,
+  isMobileProject: boolean,
+  projects: readonly MatrixProjectInfo[],
+  allowedViewports: readonly ViewportId[],
+): MatrixViewportPlan {
+  if (isMobileProject && isViewportId(projectName)) {
+    if (!allowedViewports.includes(projectName)) {
+      return {
+        mode: "skip",
+        reason: `SCREENSHOT_VIEWPORTS excludes device project "${projectName}"`,
+      };
+    }
+    return { mode: "device", viewports: [projectName] };
+  }
+  const deviceProjectIds = new Set(
+    projects.filter((p) => p.isMobile && isViewportId(p.name)).map((p) => p.name),
+  );
+  return {
+    mode: "desktop",
+    viewports: allowedViewports.filter((id) => !deviceProjectIds.has(id)),
+  };
+}
+
 export function runMatrix<T extends string>(
   scenarios: readonly Scenario[],
   opts: MatrixOptions<T>,
@@ -273,6 +316,19 @@ export function runMatrix<T extends string>(
       for (const s of scenarios) {
         if (only !== undefined && only !== s.name) continue;
         test(s.name, async ({ page, seedTenant }) => {
+          const info = test.info();
+          const plan = resolveMatrixViewports(
+            info.project.name,
+            info.project.use.isMobile === true,
+            info.config.projects.map((p) => ({ name: p.name, isMobile: p.use.isMobile === true })),
+            viewports,
+          );
+          if (plan.mode === "skip") {
+            test.skip(true, plan.reason);
+            // skip: test.skip() throws; the return only narrows `plan` for TypeScript.
+            return;
+          }
+
           // kumiko:locale drives the boot-time language (before goto); kumiko:theme
           // is cleared so the mode is decided solely by applyTheme.
           await page.addInitScript((lng) => {
@@ -286,8 +342,8 @@ export function runMatrix<T extends string>(
 
           for (const theme of themes) {
             await opts.applyTheme(page, theme);
-            for (const vp of viewports) {
-              await page.setViewportSize(VIEWPORTS[vp]);
+            for (const vp of plan.viewports) {
+              if (plan.mode === "desktop") await page.setViewportSize(VIEWPORTS[vp]);
               await waitForSettledPage(page, inFlightDataRequests);
               if (s.beforeCapture) await s.beforeCapture(page);
               const dir = `${baseDir}/${s.name}/${locale}/${theme}`;

package/src/e2e/seed-contract.ts

@@ -65,7 +65,7 @@ export const seedUserRequestSchema = createSeedUserRequestSchema();
 export const seedUserResponseSchema = seededCredentialsSchema;
 
 export const inboxQuerySchema = z.strictObject({
-  tenantId: z.uuid(),
+  tenantId: z.uuid().optional(),
   to: z.string().min(1).max(MAX_EMAIL_LENGTH),
 });
 

package/src/e2e/seed-route.ts

@@ -1,4 +1,5 @@
 import { createHash, timingSafeEqual } from "node:crypto";
+import type { EmailMessage } from "@cosmicdrift/kumiko-bundled-features/channel-email";
 import {
   getInbox,
   mailTransportInMemoryFeature,
@@ -19,6 +20,7 @@ import {
 } from "../seed-tenant";
 import { SEED_ENABLE_ENV, SEED_ROUTES, SEED_TOKEN_ENV, SEED_TOKEN_HEADER } from "./constants";
 import {
+  type CapturedMail,
   createSeedUserRequestSchema,
   inboxQuerySchema,
   seedTenantRequestSchema,
@@ -89,8 +91,24 @@ function assertGateOpen(request: SignatureExtraRouteVerifyRequest): void {
 
 export type E2eSeedRoutesOptions = {
   readonly extraRoles?: readonly string[];
+  // Apps that send tenantless mail (signup/forgot-password/magic-link) via
+  // their own raw createInMemoryTransport() pass its `sent` array here so
+  // the inbox route can read it without a tenantId. Independent of
+  // mailTransportInMemoryFeature — both sources may be present at once.
+  readonly mailOutbox?: { readonly sent: readonly EmailMessage[] };
 };
 
+function toCapturedMail(message: EmailMessage): CapturedMail {
+  return {
+    to: message.to,
+    subject: message.subject,
+    html: message.html,
+    ...(message.from !== undefined ? { from: message.from } : {}),
+    ...(message.replyTo !== undefined ? { replyTo: message.replyTo } : {}),
+    ...(message.headers !== undefined ? { headers: message.headers } : {}),
+  };
+}
+
 // Builds the route definitions unconditionally (extraRoles validation must
 // still throw in every environment) — the *mounting* decision is the
 // caller's: use isE2eSeedingEnabled() to keep prod from ever registering
@@ -168,16 +186,37 @@ export function createE2eSeedRoutes(
       );
     },
     handler: async (c, verified, deps) => {
-      if (!deps.registry.features.has(mailTransportInMemoryFeature.name)) {
+      const recipient = verified.to.toLowerCase();
+      const isRecipient = (message: { readonly to: string }) =>
+        message.to.toLowerCase() === recipient;
+
+      const tenantId = verified.tenantId;
+      const mailOutbox = options.mailOutbox;
+      const hasTenantSource =
+        tenantId !== undefined && deps.registry.features.has(mailTransportInMemoryFeature.name);
+      if (!hasTenantSource && mailOutbox === undefined) {
         return c.json(
-          { error: `${mailTransportInMemoryFeature.name} is not mounted; no inbox to read` },
+          {
+            error:
+              `no inbox to read: neither ${mailTransportInMemoryFeature.name} is mounted with a ` +
+              "tenantId nor was mailOutbox passed to createE2eSeedRoutes()",
+          },
           501,
         );
       }
-      const recipient = verified.to.toLowerCase();
-      const messages = getInbox(verified.tenantId).filter(
-        (message) => message.to.toLowerCase() === recipient,
-      );
+
+      // Both sources may be present; concatenation order between them is
+      // undefined (neither carries a timestamp). Within each source, newest
+      // first — that ordering is what mailCapture and its tests rely on.
+      const tenantMessages =
+        hasTenantSource && tenantId !== undefined
+          ? [...getInbox(tenantId)].filter(isRecipient).reverse().map(toCapturedMail)
+          : [];
+      const outboxMessages =
+        mailOutbox !== undefined
+          ? [...mailOutbox.sent].filter(isRecipient).reverse().map(toCapturedMail)
+          : [];
+      const messages: readonly CapturedMail[] = [...tenantMessages, ...outboxMessages];
       return c.json({ messages });
     },
   });