@cosmicdrift/kumiko-testing 0.320.0 → 0.322.0

package/bin/kumiko-testing.ts

@@ -5,15 +5,20 @@ import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { parseArgs } from "node:util";
 import { Glob } from "bun";
 import { BUNFIG_FILES, mergeBunfig, renderBunfigFiles } from "../src/bunfig";
-import { buildIntegrationTestArgs, selectIntegrationFiles } from "../src/integration-runner";
+import {
+  buildIntegrationTestArgs,
+  resolveRequestedIntegrationFiles,
+  selectIntegrationFiles,
+} from "../src/integration-runner";
 
 const USAGE = `kumiko-testing <command>
 
   bunfig [--dom] [--coverage] [--hoisted]  write bunfig.toml, bunfig.integration.toml and
                                            bunfig.real.toml (plus bunfig.dom.toml with --dom);
                                            --hoisted adds [install] linker = "hoisted"
-  integration [--parallel N]               run every *.integration.test.ts under the cwd
-              [--timings <file>] [--update-timings]
+  integration [--parallel N]               run every *.integration.test.ts under the cwd,
+              [--timings <file>] [--update-timings]  or only the given file(s) when passed
+              [file...]                               as positional args
 `;
 
 function runBunfig(args: readonly string[]): number {
@@ -53,25 +58,36 @@ function runBunfig(args: readonly string[]): number {
 }
 
 async function runIntegration(args: readonly string[]): Promise<number> {
-  const { values } = parseArgs({
+  const { values, positionals } = parseArgs({
     args: [...args],
     options: {
       parallel: { type: "string" },
       timings: { type: "string" },
       "update-timings": { type: "boolean" },
     },
+    allowPositionals: true,
     strict: true,
   });
   if (!existsSync(BUNFIG_FILES.integration)) {
     console.error(`${BUNFIG_FILES.integration} not found - run \`kumiko-testing bunfig\` first`);
     return 1;
   }
-  const files = selectIntegrationFiles(
-    await Array.fromAsync(new Glob("**/*.integration.test.ts").scan({ cwd: process.cwd() })),
-  );
-  if (files.length === 0) {
-    console.error("no *.integration.test.ts files found");
-    return 1;
+  let files: string[];
+  if (positionals.length > 0) {
+    try {
+      files = resolveRequestedIntegrationFiles(process.cwd(), positionals);
+    } catch (error) {
+      console.error(error instanceof Error ? error.message : String(error));
+      return 1;
+    }
+  } else {
+    files = selectIntegrationFiles(
+      await Array.fromAsync(new Glob("**/*.integration.test.ts").scan({ cwd: process.cwd() })),
+    );
+    if (files.length === 0) {
+      console.error("no *.integration.test.ts files found");
+      return 1;
+    }
   }
   const testArgs = buildIntegrationTestArgs({
     files,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-testing",
-  "version": "0.320.0",
+  "version": "0.322.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>",
@@ -75,9 +75,9 @@
     "kumiko-testing": "./bin/kumiko-testing.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.320.0",
-    "@cosmicdrift/kumiko-dev-server": "0.320.0",
-    "@cosmicdrift/kumiko-framework": "0.320.0",
+    "@cosmicdrift/kumiko-bundled-features": "0.322.0",
+    "@cosmicdrift/kumiko-dev-server": "0.322.0",
+    "@cosmicdrift/kumiko-framework": "0.322.0",
     "zod": "^4.4.3"
   },
   "peerDependencies": {

package/src/changes.json

@@ -1,4 +1,25 @@
 [
+  {
+    "version": "0.321.0",
+    "type": "improvement",
+    "title": "kumiko-testing integration accepts positional test-file args",
+    "detail": "`kumiko-testing integration` now runs only the given files/globs when\npositional args are passed, instead of always discovering every\n`*.integration.test.ts` file.",
+    "migration": "No action needed — omitting positional args keeps the previous full-discovery behavior."
+  },
+  {
+    "version": "0.321.0",
+    "type": "improvement",
+    "title": "defineAppE2eConfig reserves KUMIKO_TRUSTED_PROXY_HOPS; loginViaApi sends a synthetic per-user X-Forwarded-For",
+    "detail": "`defineAppE2eConfig`'s `webServer.env` now sets\n`KUMIKO_TRUSTED_PROXY_HOPS=1` and rejects that key in a consumer's own\n`env` (template-owned, added to `RESERVED_ENV_KEYS`). `loginViaApi` sends\n`x-forwarded-for: syntheticClientIpFor(credentials.email)`, a new\nexported helper deriving a deterministic private-range IP from\n`sha256(email)`, so each seeded user's login lands in its own\nrate-limit bucket instead of every ::1 client sharing one.\n`loginViaUi` is unchanged.",
+    "migration": "Consumers using `defineAppE2eConfig` + `loginViaApi` (incl. the\n`seedTenant` fixture) need no changes — each seeded user now logs in\nfrom its own bucket. Browser logins (`loginViaUi`, raw `fetch` to\n`/api/auth/login` from a page) still share the `::1` bucket. A consumer\nwith its own e2e login helper (bypassing `loginViaApi`) should send\n`x-forwarded-for: syntheticClientIpFor(email)` (exported from\n`@cosmicdrift/kumiko-testing`) themselves, and must not set\n`KUMIKO_TRUSTED_PROXY_HOPS` in `defineAppE2eConfig`'s `env` — it's now\nreserved."
+  },
+  {
+    "version": "0.321.0",
+    "type": "fix",
+    "title": "e2e test fixture gives every test its own synthetic client IP",
+    "detail": "`test` from `@cosmicdrift/kumiko-testing/e2e` overrides the `context`\nfixture with a `context.route(\"**/api/**\")` that adds\n`x-forwarded-for: syntheticClientIpFor(perTestClientIpKey(testInfo))` to\nsame-origin requests; an explicit `x-forwarded-for` wins. Cross-origin\nrequests stay untouched because an extra header would force a CORS\npreflight. Routing disables the HTTP cache of the test's context.\n`seedTenant`'s per-user API contexts send\n`syntheticClientIpFor(user.email)`. The built-in `request` fixture is not\ncovered.",
+    "migration": "Specs that import `test` from `@cosmicdrift/kumiko-testing/e2e` need no\nchange. Specs importing `test` straight from `@playwright/test` keep\nsharing the `::1` bucket; switch their import to kumiko-testing."
+  },
   {
     "version": "0.320.0",
     "type": "improvement",

package/src/e2e/auth-kit.ts

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { currentTotpCode } from "@cosmicdrift/kumiko-bundled-features/auth-mfa/testing";
 import type { WriteErrorInfo } from "@cosmicdrift/kumiko-framework/errors";
 import { type APIRequestContext, type APIResponse, expect, type Page } from "@playwright/test";
@@ -34,12 +35,23 @@ export async function csrfFetch(
   return request.post(path, { headers: csrfHeaderFromCookies(cookies), data });
 }
 
+// Deterministic IP in the RFC 1918 private range, so the same key (a seeded
+// user's email, a test's id) always lands in the same rate-limit bucket while
+// different keys get distinct buckets (3 varying bytes ~= 16M slots).
+export function syntheticClientIpFor(key: string): string {
+  const digest = createHash("sha256").update(key).digest();
+  return `10.${digest[0]}.${digest[1]}.${digest[2]}`;
+}
+
+export const CLIENT_IP_HEADER = "x-forwarded-for";
+
 export async function loginViaApi(
   request: APIRequestContext,
   credentials: LoginCredentials,
 ): Promise<void> {
   const response = await request.post("/api/auth/login", {
     data: { email: credentials.email, password: credentials.password },
+    headers: { [CLIENT_IP_HEADER]: syntheticClientIpFor(credentials.email) },
   });
   if (!response.ok()) {
     throw new Error(

package/src/e2e/constants.ts

@@ -24,6 +24,10 @@ export const STYLESHEET_WATCH_ENV = "KUMIKO_DEV_STYLESHEET_WATCH";
 // duplicated for the same Node/Bun-toolchain reason.
 export const PROD_BUNDLES_ENV = "KUMIKO_DEV_PROD_BUNDLES";
 
+// Same literal as kumiko-framework's client-ip.ts (TRUSTED_PROXY_HOPS_ENV),
+// duplicated for the same Node/Bun-toolchain reason.
+export const TRUSTED_PROXY_HOPS_ENV = "KUMIKO_TRUSTED_PROXY_HOPS";
+
 export const SEED_ROUTE_PREFIX = "/__test";
 
 export const SEED_ROUTES = {

package/src/e2e/define-app-e2e-config.ts

@@ -19,6 +19,7 @@ import {
   SEED_ENABLE_ENV,
   SEED_TOKEN_ENV,
   STYLESHEET_WATCH_ENV,
+  TRUSTED_PROXY_HOPS_ENV,
 } from "./constants";
 import { isScreenshotRun, requireScreenshotDir, screenshotSpecsIgnore } from "./screenshot-dir";
 import { E2E_TIMEOUT_MS } from "./timeouts";
@@ -61,6 +62,7 @@ const RESERVED_ENV_KEYS = [
   SEED_TOKEN_ENV,
   STYLESHEET_WATCH_ENV,
   PROD_BUNDLES_ENV,
+  TRUSTED_PROXY_HOPS_ENV,
 ] as const;
 
 type ProjectUse = Partial<PlaywrightTestOptions & PlaywrightWorkerOptions>;
@@ -205,6 +207,11 @@ export function defineAppE2eConfig(input: AppE2eConfigInput): PlaywrightTestConf
         // E2E runs against prod-shaped bundles: splitting, no sourcemap,
         // NODE_ENV=production — matches what actually ships.
         [PROD_BUNDLES_ENV]: "1",
+        // E2e clients all share ::1, so the default trustedProxyHops (0,
+        // socket-only) would collapse every seeded user into one rate-limit
+        // bucket. loginViaApi sends a synthetic per-user X-Forwarded-For, so
+        // trust exactly one hop to give each user its own bucket.
+        [TRUSTED_PROXY_HOPS_ENV]: "1",
       },
       reuseExistingServer: false,
       timeout: E2E_TIMEOUT_MS.webServer,

package/src/e2e/index.ts

@@ -15,6 +15,7 @@ export {
   type LoginCredentials,
   loginViaApi,
   loginViaUi,
+  syntheticClientIpFor,
   totpCode,
 } from "./auth-kit";
 export {

package/src/e2e/seeded-tenant-fixture.ts

@@ -1,11 +1,14 @@
 import { ROLES } from "@cosmicdrift/kumiko-framework/auth";
 import {
   type APIRequestContext,
+  type BrowserContext,
   test as base,
   type Page,
+  type Request as PlaywrightRequest,
   type PlaywrightTestArgs,
   type PlaywrightTestOptions,
   type PlaywrightWorkerArgs,
+  type TestInfo,
 } from "@playwright/test";
 import type * as z from "zod";
 import {
@@ -16,8 +19,14 @@ import {
   type SeedTenantOptions,
   withSession,
 } from "../seed-types";
-import { clearSession, createHttpApi, loginViaApi } from "./auth-kit";
-import { SEED_ROUTES } from "./constants";
+import {
+  CLIENT_IP_HEADER,
+  clearSession,
+  createHttpApi,
+  loginViaApi,
+  syntheticClientIpFor,
+} from "./auth-kit";
+import { SEED_ROUTES, SEED_TOKEN_ENV } from "./constants";
 import { seedRouteHeaders } from "./mail-capture";
 import {
   type ExtraSeedRequest,
@@ -77,7 +86,10 @@ export async function provideSeedTenant(
 
   // One cookie jar per user: two tenants (or admin + member) in one test must not clobber each other's session.
   const openLoggedInApi = async (user: SeededUser): Promise<BoundApi> => {
-    const ctx = await playwright.request.newContext({ baseURL });
+    const ctx = await playwright.request.newContext({
+      baseURL,
+      extraHTTPHeaders: { [CLIENT_IP_HEADER]: syntheticClientIpFor(user.email) },
+    });
     openedContexts.push(ctx);
     await loginViaApi(ctx, user);
     return createHttpApi(ctx);
@@ -166,6 +178,65 @@ export async function provideSeedTenant(
   await Promise.all(openedContexts.map((ctx) => ctx.dispose()));
 }
 
+// Every e2e client connects from ::1, and the e2e webServer trusts one proxy
+// hop (defineAppE2eConfig). Without a distinct X-Forwarded-For per test, all
+// browser pages of a run would share one `per: "ip"` rate-limit bucket and
+// 429 under parallel load. The run token keeps a rerun within the limiter
+// window out of the previous run's buckets; the retry index keeps a retry
+// out of the bucket its failed attempt already drained.
+export function perTestClientIpKey(
+  testInfo: Pick<TestInfo, "testId" | "repeatEachIndex" | "retry">,
+  runToken: string | undefined = process.env[SEED_TOKEN_ENV],
+): string {
+  return `${runToken ?? ""}:${testInfo.testId}:${testInfo.repeatEachIndex}:${testInfo.retry}`;
+}
+
+// Same-origin only: on a cross-origin fetch the extra header would force a
+// CORS preflight the target never agreed to (why extraHTTPHeaders is no option
+// here). An explicit X-Forwarded-For set by the test wins.
+export function headersWithClientIp(
+  request: { readonly url: string; readonly frameUrl: string | undefined },
+  headers: Readonly<Record<string, string>>,
+  clientIp: string,
+): Record<string, string> | undefined {
+  if (request.frameUrl === undefined) return undefined;
+  let sameOrigin: boolean;
+  try {
+    sameOrigin = new URL(request.frameUrl).origin === new URL(request.url).origin;
+  } catch {
+    return undefined;
+  }
+  return sameOrigin ? { [CLIENT_IP_HEADER]: clientIp, ...headers } : undefined;
+}
+
+function frameUrlOf(request: PlaywrightRequest): string | undefined {
+  try {
+    return request.frame().url();
+  } catch {
+    // Service-worker requests have no frame.
+    return undefined;
+  }
+}
+
+export async function providePerTestClientIpContext(
+  { context }: Pick<PlaywrightTestArgs, "context">,
+  use: (context: BrowserContext) => Promise<void>,
+  testInfo: Pick<TestInfo, "testId" | "repeatEachIndex" | "retry">,
+): Promise<void> {
+  const clientIp = syntheticClientIpFor(perTestClientIpKey(testInfo));
+  await context.route("**/api/**", (route) => {
+    const request = route.request();
+    const headers = headersWithClientIp(
+      { url: request.url(), frameUrl: frameUrlOf(request) },
+      request.headers(),
+      clientIp,
+    );
+    return headers === undefined ? route.fallback() : route.fallback({ headers });
+  });
+  await use(context);
+}
+
 export const test = base.extend<E2eFixtures>({
+  context: providePerTestClientIpContext,
   seedTenant: provideSeedTenant,
 });

package/src/integration-runner.ts

@@ -1,3 +1,5 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
 import { BUNFIG_FILES, TEST_TIMEOUT_MS } from "./bunfig";
 
 export type IntegrationRunOptions = {
@@ -16,6 +18,26 @@ export function selectIntegrationFiles(paths: readonly string[]): string[] {
     .sort();
 }
 
+/** Resolves `kumiko-testing integration`'s positional file args against `cwd`
+ *  into absolute paths — absolute (not glob-relative) so bun's own
+ *  `bun test <path>` treats them as files to run, not filter patterns.
+ *  `exists` is injectable so this stays unit-testable without touching the
+ *  real filesystem. Throws on the first missing file — the caller decides
+ *  how to report it (CLI: print + exit 1). */
+export function resolveRequestedIntegrationFiles(
+  cwd: string,
+  positionals: readonly string[],
+  exists: (path: string) => boolean = existsSync,
+): string[] {
+  return positionals.map((arg) => {
+    const resolved = resolve(cwd, arg);
+    if (!exists(resolved)) {
+      throw new Error(`kumiko-testing integration: file not found: ${arg}`);
+    }
+    return resolved;
+  });
+}
+
 const isPositiveInteger = (value: number): boolean => Number.isInteger(value) && value > 0;
 
 export function buildIntegrationTestArgs(opts: IntegrationRunOptions): string[] {