@cosmicdrift/kumiko-testing 0.410.0 → 0.412.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cosmicdrift/kumiko-testing",
3
- "version": "0.410.0",
3
+ "version": "0.412.0",
4
4
  "description": "Test template for Kumiko apps: per-flow seedTenant, app test stack, canonical test preloads, bunfig generator and integration runner.",
5
5
  "license": "MIT",
6
6
  "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -26,6 +26,10 @@
26
26
  "types": "./src/stack/index.ts",
27
27
  "default": "./src/stack/index.ts"
28
28
  },
29
+ "./api-examples": {
30
+ "types": "./src/api-examples/index.ts",
31
+ "default": "./src/api-examples/index.ts"
32
+ },
29
33
  "./provider-env-keys": {
30
34
  "types": "./src/provider-env-keys.ts",
31
35
  "default": "./src/provider-env-keys.ts"
@@ -103,9 +107,9 @@
103
107
  "kumiko-testing": "./bin/kumiko-testing.ts"
104
108
  },
105
109
  "dependencies": {
106
- "@cosmicdrift/kumiko-framework": "0.410.0",
107
- "@cosmicdrift/kumiko-guards": "0.410.0",
108
- "@cosmicdrift/kumiko-types": "0.410.0",
110
+ "@cosmicdrift/kumiko-framework": "0.412.0",
111
+ "@cosmicdrift/kumiko-guards": "0.412.0",
112
+ "@cosmicdrift/kumiko-types": "0.412.0",
109
113
  "zod": "^4.6.7"
110
114
  },
111
115
  "peerDependencies": {
@@ -129,8 +133,8 @@
129
133
  }
130
134
  },
131
135
  "devDependencies": {
132
- "@cosmicdrift/kumiko-bundled-features": "0.410.0",
133
- "@cosmicdrift/kumiko-dev-server": "0.410.0",
136
+ "@cosmicdrift/kumiko-bundled-features": "0.412.0",
137
+ "@cosmicdrift/kumiko-dev-server": "0.412.0",
134
138
  "@happy-dom/global-registrator": "^21.0.4",
135
139
  "@playwright/test": "^1.64.1",
136
140
  "@testing-library/dom": "^10.4.2",
@@ -0,0 +1,11 @@
1
+ export { normalizeApiExample, normalizeWebhookExample } from "./normalize.ts";
2
+ export {
3
+ RECORD_API_EXAMPLES_ENV,
4
+ type RecordApiExampleOptions,
5
+ recordApiExample,
6
+ } from "./record.ts";
7
+ export {
8
+ type RecordWebhookExampleOptions,
9
+ recordWebhookExample,
10
+ WEBHOOK_EXAMPLES_SUBDIR,
11
+ } from "./webhook-record.ts";
@@ -0,0 +1,76 @@
1
+ import {
2
+ type ApiExampleFile,
3
+ ApiExampleFileSchema,
4
+ type WebhookExampleFile,
5
+ WebhookExampleFileSchema,
6
+ } from "@cosmicdrift/kumiko-types/api-example";
7
+
8
+ export const EXAMPLE_TIMESTAMP = "2026-01-15T09:30:00.000Z";
9
+ export const EXAMPLE_REQUEST_ID = "11111111-1111-4111-8111-111111111111";
10
+ export const EXAMPLE_CURSOR = "CURSOR";
11
+ export const EXAMPLE_TOKEN = "kpat_EXAMPLE";
12
+ export const EXAMPLE_SECRET = "REDACTED";
13
+
14
+ // Recordings are committed and published, so credentials sent in a payload never reach the file.
15
+ const SECRET_KEY = /password|secret|mfaCode/i;
16
+
17
+ const UUID = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi;
18
+ const ISO_TIMESTAMP = /\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})/g;
19
+ const PAT_TOKEN = /kpat_[A-Za-z0-9_-]+/g;
20
+
21
+ function placeholderUuid(index: number): string {
22
+ return `00000000-0000-4000-8000-${String(index).padStart(12, "0")}`;
23
+ }
24
+
25
+ function isRecord(value: unknown): value is Record<string, unknown> {
26
+ return typeof value === "object" && value !== null && !Array.isArray(value);
27
+ }
28
+
29
+ /** One walker per recording: UUIDs are numbered by first occurrence across everything it walks. */
30
+ function createExampleWalker(): (value: unknown) => unknown {
31
+ const uuids = new Map<string, string>();
32
+ const normalizeString = (text: string): string =>
33
+ text
34
+ .replace(PAT_TOKEN, EXAMPLE_TOKEN)
35
+ .replace(UUID, (found) => {
36
+ const key = found.toLowerCase();
37
+ const known = uuids.get(key);
38
+ if (known !== undefined) return known;
39
+ const created = placeholderUuid(uuids.size + 1);
40
+ uuids.set(key, created);
41
+ return created;
42
+ })
43
+ .replace(ISO_TIMESTAMP, EXAMPLE_TIMESTAMP);
44
+
45
+ const walk = (value: unknown): unknown => {
46
+ if (typeof value === "string") return normalizeString(value);
47
+ if (Array.isArray(value)) return value.map(walk);
48
+ if (!isRecord(value)) return value;
49
+ return Object.fromEntries(
50
+ Object.entries(value).map(([key, entry]): [string, unknown] => {
51
+ if (SECRET_KEY.test(key) && typeof entry === "string") return [key, EXAMPLE_SECRET];
52
+ if (key === "requestId") return [key, EXAMPLE_REQUEST_ID];
53
+ if (key === "timestamp") return [key, EXAMPLE_TIMESTAMP];
54
+ if (key === "nextCursor" && entry !== null && entry !== undefined) {
55
+ return [key, EXAMPLE_CURSOR];
56
+ }
57
+ return [key, walk(entry)];
58
+ }),
59
+ );
60
+ };
61
+ return walk;
62
+ }
63
+
64
+ /** Makes a recording stable across runs: the same input shape always yields the same file. */
65
+ export function normalizeApiExample(example: ApiExampleFile): ApiExampleFile {
66
+ // Numbered by first occurrence, request before response; the same UUID keeps its number.
67
+ const walk = createExampleWalker();
68
+ const request = walk(example.request);
69
+ const response = walk(example.response);
70
+ return ApiExampleFileSchema.parse({ request, response });
71
+ }
72
+
73
+ export function normalizeWebhookExample(example: WebhookExampleFile): WebhookExampleFile {
74
+ const walk = createExampleWalker();
75
+ return WebhookExampleFileSchema.parse({ ...example, payload: walk(example.payload) });
76
+ }
@@ -0,0 +1,40 @@
1
+ import { join } from "node:path";
2
+ import type { ApiExampleEndpoint, ApiExampleFile } from "@cosmicdrift/kumiko-types/api-example";
3
+ import type { RequestHelper } from "../stack/request-helper.ts";
4
+ import { normalizeApiExample } from "./normalize.ts";
5
+
6
+ export const RECORD_API_EXAMPLES_ENV = "KUMIKO_RECORD_API_EXAMPLES";
7
+
8
+ export type RecordApiExampleOptions = {
9
+ /** File name without extension. */
10
+ readonly name: string;
11
+ readonly dir: string;
12
+ readonly endpoint: ApiExampleEndpoint;
13
+ readonly body: ApiExampleFile["request"]["body"];
14
+ /** Raw personal access token; sent as bearer token and never written to the file. */
15
+ readonly token: string;
16
+ };
17
+
18
+ /** Sends the request as an API client would and returns the result. The recording is only
19
+ * written when KUMIKO_RECORD_API_EXAMPLES=1, so ordinary test runs leave the files alone. */
20
+ export async function recordApiExample(
21
+ http: Pick<RequestHelper, "raw">,
22
+ options: RecordApiExampleOptions,
23
+ ): Promise<{ readonly status: number; readonly body: unknown }> {
24
+ const response = await http.raw("POST", options.endpoint, options.body, {
25
+ Authorization: `Bearer ${options.token}`,
26
+ });
27
+ const body: unknown = await response.json();
28
+ const result = { status: response.status, body };
29
+ if (process.env[RECORD_API_EXAMPLES_ENV] === "1") {
30
+ const file = normalizeApiExample({
31
+ request: { endpoint: options.endpoint, body: options.body },
32
+ response: result,
33
+ });
34
+ await Bun.write(
35
+ join(options.dir, `${options.name}.json`),
36
+ `${JSON.stringify(file, null, 2)}\n`,
37
+ );
38
+ }
39
+ return result;
40
+ }
@@ -0,0 +1,45 @@
1
+ import { join } from "node:path";
2
+ import {
3
+ formatWebhookPayloadIssues,
4
+ parseWebhookPayload,
5
+ } from "@cosmicdrift/kumiko-framework/engine";
6
+ import type { WebhookEventContract } from "@cosmicdrift/kumiko-types/feature";
7
+ import { normalizeWebhookExample } from "./normalize.ts";
8
+ import { RECORD_API_EXAMPLES_ENV } from "./record.ts";
9
+
10
+ export const WEBHOOK_EXAMPLES_SUBDIR = "webhooks";
11
+
12
+ export type RecordWebhookExampleOptions = {
13
+ /** File name without extension. */
14
+ readonly name: string;
15
+ /** The examples directory; the file lands in its `webhooks/` subdirectory. */
16
+ readonly dir: string;
17
+ readonly contract: WebhookEventContract;
18
+ readonly payload: unknown;
19
+ };
20
+
21
+ /** Checks the payload against its contract and returns what delivery would send. A recording
22
+ * can therefore never contradict the contract; the file is only written when
23
+ * KUMIKO_RECORD_API_EXAMPLES=1. */
24
+ export async function recordWebhookExample(
25
+ options: RecordWebhookExampleOptions,
26
+ ): Promise<Record<string, unknown>> {
27
+ const parsed = parseWebhookPayload(options.contract, options.payload);
28
+ if (!parsed.ok) {
29
+ throw new Error(
30
+ `Webhook example "${options.name}" violates the contract of ${options.contract.qn}: ${formatWebhookPayloadIssues(parsed.issues)}`,
31
+ );
32
+ }
33
+ if (process.env[RECORD_API_EXAMPLES_ENV] === "1") {
34
+ const file = normalizeWebhookExample({
35
+ event: options.contract.qn,
36
+ version: options.contract.version,
37
+ payload: parsed.payload,
38
+ });
39
+ await Bun.write(
40
+ join(options.dir, WEBHOOK_EXAMPLES_SUBDIR, `${options.name}.json`),
41
+ `${JSON.stringify(file, null, 2)}\n`,
42
+ );
43
+ }
44
+ return parsed.payload;
45
+ }
package/src/changes.json CHANGED
@@ -1,4 +1,28 @@
1
1
  [
2
+ {
3
+ "version": "0.412.0",
4
+ "type": "improvement",
5
+ "title": "recordApiExample records real API responses for the generated docs",
6
+ "detail": "`recordApiExample(http, { name, dir, endpoint, body, token })` from `@cosmicdrift/kumiko-testing/api-examples` sends the request with the token as Bearer and returns status and body. With `KUMIKO_RECORD_API_EXAMPLES=1` it also writes `<dir>/<name>.json` with ids, timestamps, tokens, request ids and cursors replaced by stable placeholders and values under password, secret and mfaCode keys redacted. `kumiko api-docs` uses a recording for the example request and the example response of the matching handler. The recipe `samples/recipes/api-docs` shows the whole flow."
7
+ },
8
+ {
9
+ "version": "0.412.0",
10
+ "type": "improvement",
11
+ "title": "recordWebhookExample records validated webhook payloads for the generated docs",
12
+ "detail": "`recordWebhookExample({ name, dir, contract, payload })` from `@cosmicdrift/kumiko-testing/api-examples` validates the payload with `parseWebhookPayload` and throws with the issues when it breaks the contract. With `KUMIKO_RECORD_API_EXAMPLES=1` it writes `<dir>/webhooks/<name>.json` with ids, timestamps and secrets normalized. It always returns the parsed payload. `WebhookExampleFileSchema` is exported from `@cosmicdrift/kumiko-types/api-example`."
13
+ },
14
+ {
15
+ "version": "0.411.0",
16
+ "type": "improvement",
17
+ "title": "renderTestSetup starter \"blank\"",
18
+ "detail": "`renderTestSetup({ starter: \"blank\" })` skips the tasks integration and e2e files, ships a boot validation unit test and a boot integration test, and runs Playwright with `--pass-with-no-tests`."
19
+ },
20
+ {
21
+ "version": "0.411.0",
22
+ "type": "fix",
23
+ "title": "runScreenshots finishes CSS transitions before the capture",
24
+ "detail": "`runScreenshots` captures with `animations: \"disabled\"` like `runMatrix`. A scenario flow that toggles the dark theme no longer catches `transition-all` buttons mid-fade with their light-theme colours."
25
+ },
2
26
  {
3
27
  "version": "0.409.0",
4
28
  "type": "fix",
@@ -274,7 +274,9 @@ export function runScreenshots(scenarios: readonly Scenario[], opts: FlatOptions
274
274
  presentIdentities: identities.register,
275
275
  });
276
276
  const path = `${outDir}/${s.name}.png`;
277
- await captureScenario(page, s, identities.mappings, { path });
277
+ // Same as runMatrix: a theme toggle in the flow starts transition-all fades that
278
+ // the settle fingerprint cannot see, so finish them at capture time.
279
+ await captureScenario(page, s, identities.mappings, { path, animations: "disabled" });
278
280
  expect.soft(statSync(path).size).toBeGreaterThan(MIN_BYTES);
279
281
  },
280
282
  );
@@ -0,0 +1,48 @@
1
+ // @runtime tooling
2
+ export type ScaffoldTestStarter = "demo" | "blank";
3
+
4
+ export const BLANK_E2E_PLAYWRIGHT_FLAG = "--pass-with-no-tests";
5
+
6
+ export const BLANK_TEST_FILES: Readonly<Record<string, string>> = {
7
+ "src/__tests__/run-config.test.ts": [
8
+ 'import { describe, expect, test } from "bun:test";',
9
+ 'import { validateBoot } from "@cosmicdrift/kumiko-framework/engine";',
10
+ 'import { composeFeatures } from "@cosmicdrift/kumiko-server-runtime/compose-features";',
11
+ 'import { APP_FEATURES, HAS_AUTH } from "../run-config";',
12
+ "",
13
+ 'describe("run-config", () => {',
14
+ ' test("the mounted features pass boot validation", () => {',
15
+ " const features = composeFeatures([...APP_FEATURES], { includeBundled: HAS_AUTH });",
16
+ " expect(() => validateBoot(features)).not.toThrow();",
17
+ " });",
18
+ "});",
19
+ "",
20
+ ].join("\n"),
21
+ "src/__tests__/boot.integration.test.ts": [
22
+ 'import { afterAll, beforeAll, describe, expect, test } from "bun:test";',
23
+ 'import { setupAppTestStack } from "@cosmicdrift/kumiko-dev-server/testing";',
24
+ 'import type { TestStack } from "@cosmicdrift/kumiko-testing/stack";',
25
+ 'import { APP_FEATURES } from "../run-config";',
26
+ "",
27
+ "let stack: TestStack;",
28
+ "",
29
+ "beforeAll(async () => {",
30
+ " stack = await setupAppTestStack([...APP_FEATURES]);",
31
+ "});",
32
+ "",
33
+ "afterAll(async () => {",
34
+ " await stack?.cleanup();",
35
+ "});",
36
+ "",
37
+ 'describe("boot", () => {',
38
+ ' test("the mounted features boot and refuse an unknown login", async () => {',
39
+ ' const res = await stack.http.raw("POST", "/api/auth/login", {',
40
+ ' email: "nobody@example.com",',
41
+ ' password: "not-a-real-password",',
42
+ " });",
43
+ " expect(res.status).toBeGreaterThanOrEqual(400);",
44
+ " });",
45
+ "});",
46
+ "",
47
+ ].join("\n"),
48
+ };
package/src/scaffold.ts CHANGED
@@ -1,6 +1,11 @@
1
1
  // @runtime tooling
2
2
  import { BUNFIG_FILES, renderBunfigFiles, TEST_TIMEOUT_MS } from "./bunfig";
3
3
  import { REAL_PROVIDERS_ENV } from "./helpers/real-providers";
4
+ import {
5
+ BLANK_E2E_PLAYWRIGHT_FLAG,
6
+ BLANK_TEST_FILES,
7
+ type ScaffoldTestStarter,
8
+ } from "./scaffold-blank";
4
9
 
5
10
  export type ScaffoldTestSetup = {
6
11
  readonly files: Readonly<Record<string, string>>;
@@ -13,6 +18,7 @@ export type RenderTestSetupInput = {
13
18
  readonly appName: string;
14
19
  readonly frameworkVersion: string;
15
20
  readonly port?: number;
21
+ readonly starter?: ScaffoldTestStarter;
16
22
  };
17
23
 
18
24
  // One above the scaffold's `bun dev` default (4173) so both can run side by side.
@@ -202,19 +208,25 @@ function renderIntegrationTest(): string {
202
208
  }
203
209
 
204
210
  export function renderTestSetup(input: RenderTestSetupInput): ScaffoldTestSetup {
205
- const { appName, frameworkVersion, port = SCAFFOLD_E2E_PORT } = input;
211
+ const { appName, frameworkVersion, port = SCAFFOLD_E2E_PORT, starter = "demo" } = input;
212
+ const isBlank = starter === "blank";
213
+ const playwrightRun = `bunx --bun playwright test${isBlank ? ` ${BLANK_E2E_PLAYWRIGHT_FLAG}` : ""}`;
206
214
  const unitTestScript = `bun --config=${BUNFIG_FILES.unit} test --timeout=${TEST_TIMEOUT_MS.unit} --dots`;
207
215
  const integrationTestScript = `bun kumiko-testing integration --parallel ${SCAFFOLD_INTEGRATION_PARALLEL}`;
208
216
  return {
209
217
  files: {
210
218
  ...renderBunfigFiles({ install: { linker: "hoisted" }, dom: true }),
211
219
  "playwright.config.ts": renderPlaywrightConfig(port),
212
- "e2e/_helpers/index.ts": renderE2eHelpers(),
213
220
  "e2e/server.ts": renderE2eServer(appName),
214
- "e2e/smoke.spec.ts": renderE2eSmokeSpec(),
215
- "src/__tests__/_setup.ts": renderIntegrationSetup(),
216
- "src/__tests__/run-config.test.ts": renderUnitTest(),
217
- "src/__tests__/tasks.integration.test.ts": renderIntegrationTest(),
221
+ ...(isBlank
222
+ ? BLANK_TEST_FILES
223
+ : {
224
+ "e2e/_helpers/index.ts": renderE2eHelpers(),
225
+ "e2e/smoke.spec.ts": renderE2eSmokeSpec(),
226
+ "src/__tests__/_setup.ts": renderIntegrationSetup(),
227
+ "src/__tests__/run-config.test.ts": renderUnitTest(),
228
+ "src/__tests__/tasks.integration.test.ts": renderIntegrationTest(),
229
+ }),
218
230
  },
219
231
  scripts: {
220
232
  test: unitTestScript,
@@ -231,9 +243,9 @@ export function renderTestSetup(input: RenderTestSetupInput): ScaffoldTestSetup
231
243
  // picks up the unit suite.
232
244
  "test:real": `${REAL_PROVIDERS_ENV}=1 bun --config=${BUNFIG_FILES.real} test --timeout=${TEST_TIMEOUT_MS.real} .real.test.ts`,
233
245
  "test:bunfig": "bun kumiko-testing bunfig --hoisted",
234
- e2e: "bunx --bun playwright test",
235
- "e2e:real": `${REAL_PROVIDERS_ENV}=1 bunx --bun playwright test`,
236
- screenshots: "SCREENSHOT_DIR=docs/screenshots bunx --bun playwright test",
246
+ e2e: playwrightRun,
247
+ "e2e:real": `${REAL_PROVIDERS_ENV}=1 ${playwrightRun}`,
248
+ screenshots: `SCREENSHOT_DIR=docs/screenshots ${playwrightRun}`,
237
249
  },
238
250
  devDependencies: {
239
251
  "@cosmicdrift/kumiko-testing": frameworkVersion,