@stardeck-customer-apps/testing 0.1.1

package/SKILL.md

@@ -0,0 +1,118 @@
+# @stardeck-customer-apps/testing
+
+Vitest harness for Stardeck apps. Tests run against an **in-process Postgres
+(PGlite)** and a **simulated control plane**, so the real Stardeck SDKs
+(`data-store-sdk`, `email-sdk`, `project-auth`) execute their production code
+paths with no network, no mocks to write, and full determinism.
+
+## Setup (once per project)
+
+1. `vitest.config.ts` in the project root:
+
+```ts
+import { defineStardeckTestConfig } from "@stardeck-customer-apps/testing/config";
+
+export default defineStardeckTestConfig();
+```
+
+2. `package.json` scripts: `"test": "vitest run"`.
+
+3. If the app uses a data store, regenerate the schema snapshot whenever the
+   schema changes (also emits Kysely types):
+
+```bash
+npx stardeck-data-store generate-types
+```
+
+This writes `src/generated/data-store-types.ts` and
+`src/generated/data-store-schema.sql`. The harness applies the SQL snapshot to
+PGlite at test boot. **Commit both files.**
+
+## Writing tests
+
+```ts
+import { beforeAll, beforeEach, afterAll, expect, it } from "vitest";
+import {
+  createTestApp,
+  callRoute,
+  describeWorkflow,
+  type TestApp,
+} from "@stardeck-customer-apps/testing";
+import { POST as checkout } from "@/app/api/checkout/route";
+
+let app: TestApp;
+
+beforeAll(async () => {
+  app = await createTestApp({
+    seed: async (db) => {
+      await db.exec(`INSERT INTO products (name, price, stock) VALUES ('Widget', 19.99, 10)`);
+    },
+  });
+});
+beforeEach(() => app.reset());
+afterAll(() => app.close());
+
+describeWorkflow("checkout", () => {
+  it("completes an order, decrements stock, and emails the customer", async () => {
+    const user = app.asUser({ email: "buyer@example.com" });
+
+    const res = await callRoute(checkout, { body: { items: [{ sku: "Widget", qty: 2 }] } });
+    expect(res.status).toBe(200);
+
+    const [product] = await app.query(`SELECT stock FROM products WHERE name = 'Widget'`);
+    expect(product.stock).toBe(8);
+
+    expect(app.inbox.latest(user.email!)?.subject).toMatch(/order confirmed/i);
+  });
+});
+```
+
+## API
+
+- `createTestApp(options)` — boots PGlite + the control-plane simulator and
+  sets all Stardeck env vars (`CONTROL_PLANE_URL`, `DEPLOYMENT_SECRET`,
+  `DATA_STORE_URL`, ids). One per test file, in `beforeAll`.
+  - `schema` — path to the DDL snapshot (default
+    `./src/generated/data-store-schema.sql`); `null` for apps without a store.
+  - `schemaSql` — inline DDL instead of a file.
+  - `seed(db)` — seed rows; re-runs on every `reset()`.
+  - `allowNetwork` — permit non-Stardeck outbound fetches (off by default).
+- `app.reset()` — wipe + re-apply schema + re-seed + clear inbox/sessions.
+  Call in `beforeEach`.
+- `app.asUser(partial?)` — sign in a test user; `getSession()` in app code
+  resolves to it. `app.signOut()` clears.
+- `app.issueSession(partial?)` — mint access/refresh tokens for cookie-based
+  auth flows (`__stardeck:sess`).
+- `app.inbox` — emails sent through the email-sdk: `.latest(addr?)`,
+  `.to(addr)`, `.all()`, `.count`, `.clear()`.
+- `app.query(sql, params?)` / `app.db` — direct database access for
+  assertions and seeding.
+- `callRoute(handler, opts)` — invoke an App Router route handler with a real
+  `NextRequest`. Options: `body`, `searchParams`, `params`, `headers`,
+  `cookies`, `method`, `path`, `user`. `redirect()` calls come back as a
+  redirect `Response` instead of throwing.
+- `describeWorkflow(name, fn)` — tag a suite as a critical business workflow
+  ("checkout", "booking", "inventory"). The platform reports these per
+  deployment — every critical workflow should have one.
+
+## What works out of the box
+
+- `DataStoreClient` (query/insert/update/delete/schema ops) — served by the
+  simulator against PGlite with production semantics.
+- `createDataStore()` / Kysely — the Neon HTTP driver speaks to PGlite through
+  the simulated wire protocol; generated types work unchanged.
+- `getSession()` / `requireAuth()` from project-auth — resolves the
+  `asUser(...)` user (header fast path) or issued session cookies.
+- `EmailClient.send()` — captured in `app.inbox`, never delivered.
+- `next/headers` (`headers()`/`cookies()`) inside handlers under `callRoute`.
+
+## Rules
+
+- Test **business logic and route handlers**, not framework plumbing. Focus on
+  the workflows the owner cares about: orders, bookings, inventory, payments.
+- Never weaken or skip a failing test to make a run pass — fix the code, or
+  report the failure.
+- Tests must not depend on real network, current time of day, or run order.
+  `reset()` in `beforeEach` is the supported isolation model.
+- Assert on outcomes (rows, status codes, captured emails), not on
+  implementation details.

package/dist/config.d.mts

@@ -0,0 +1,16 @@
+import { ViteUserConfig } from 'vitest/config';
+
+/**
+ * Vitest config for Stardeck customer apps. Aliases `next/headers` (and
+ * `server-only`) to harness shims so server code runs outside a Next request
+ * scope, and registers the harness setup file.
+ *
+ * ```ts
+ * // vitest.config.ts
+ * import { defineStardeckTestConfig } from "@stardeck-customer-apps/testing/config";
+ * export default defineStardeckTestConfig();
+ * ```
+ */
+declare function defineStardeckTestConfig(overrides?: ViteUserConfig): ViteUserConfig;
+
+export { defineStardeckTestConfig };

package/dist/config.d.ts

@@ -0,0 +1,16 @@
+import { ViteUserConfig } from 'vitest/config';
+
+/**
+ * Vitest config for Stardeck customer apps. Aliases `next/headers` (and
+ * `server-only`) to harness shims so server code runs outside a Next request
+ * scope, and registers the harness setup file.
+ *
+ * ```ts
+ * // vitest.config.ts
+ * import { defineStardeckTestConfig } from "@stardeck-customer-apps/testing/config";
+ * export default defineStardeckTestConfig();
+ * ```
+ */
+declare function defineStardeckTestConfig(overrides?: ViteUserConfig): ViteUserConfig;
+
+export { defineStardeckTestConfig };

package/dist/config.js

@@ -0,0 +1,57 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/config.ts
+var config_exports = {};
+__export(config_exports, {
+  defineStardeckTestConfig: () => defineStardeckTestConfig
+});
+module.exports = __toCommonJS(config_exports);
+function defineStardeckTestConfig(overrides = {}) {
+  return {
+    ...overrides,
+    resolve: {
+      ...overrides.resolve,
+      alias: {
+        "next/headers": "@stardeck-customer-apps/testing/next-headers",
+        "server-only": "@stardeck-customer-apps/testing/server-only",
+        ...overrides.resolve?.alias
+      }
+    },
+    test: {
+      environment: "node",
+      globals: true,
+      include: ["src/**/*.test.{ts,tsx}", "tests/**/*.test.{ts,tsx}"],
+      // One test file per isolated fork: harness state (PGlite, fetch
+      // interceptor, sessions) is process-global by design, so files must
+      // not share a live process.
+      pool: "forks",
+      isolate: true,
+      ...overrides.test,
+      setupFiles: [
+        "@stardeck-customer-apps/testing/setup",
+        ...overrides.test?.setupFiles ? Array.isArray(overrides.test.setupFiles) ? overrides.test.setupFiles : [overrides.test.setupFiles] : []
+      ]
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  defineStardeckTestConfig
+});

package/dist/config.mjs

@@ -0,0 +1,32 @@
+// src/config.ts
+function defineStardeckTestConfig(overrides = {}) {
+  return {
+    ...overrides,
+    resolve: {
+      ...overrides.resolve,
+      alias: {
+        "next/headers": "@stardeck-customer-apps/testing/next-headers",
+        "server-only": "@stardeck-customer-apps/testing/server-only",
+        ...overrides.resolve?.alias
+      }
+    },
+    test: {
+      environment: "node",
+      globals: true,
+      include: ["src/**/*.test.{ts,tsx}", "tests/**/*.test.{ts,tsx}"],
+      // One test file per isolated fork: harness state (PGlite, fetch
+      // interceptor, sessions) is process-global by design, so files must
+      // not share a live process.
+      pool: "forks",
+      isolate: true,
+      ...overrides.test,
+      setupFiles: [
+        "@stardeck-customer-apps/testing/setup",
+        ...overrides.test?.setupFiles ? Array.isArray(overrides.test.setupFiles) ? overrides.test.setupFiles : [overrides.test.setupFiles] : []
+      ]
+    }
+  };
+}
+export {
+  defineStardeckTestConfig
+};

package/dist/index.d.mts

@@ -0,0 +1,143 @@
+import { PGlite } from '@electric-sql/pglite';
+
+/**
+ * The user shape returned by project-auth's `getSession()`. Mirrors the
+ * `UserSchema` in @stardeck-customer-apps/project-auth — keep in sync.
+ */
+interface TestUser {
+    id: string;
+    email?: string | null;
+    name?: string | null;
+    role?: string | null;
+    permissions?: string[];
+    organizationId?: string | null;
+    projectId?: string | null;
+}
+interface CapturedEmail {
+    resendId: string;
+    fromAddress: string;
+    from: {
+        name: string;
+        prefix: string;
+    };
+    to: string[];
+    cc: string[];
+    bcc: string[];
+    subject: string;
+    html?: string;
+    text?: string;
+    replyTo?: string;
+    attachments: Array<{
+        filename: string;
+        contentType?: string;
+    }>;
+    sentAt: Date;
+}
+interface TestInbox {
+    /** All captured emails, oldest first. */
+    all(): CapturedEmail[];
+    /** Emails addressed to (to/cc/bcc) the given address. */
+    to(address: string): CapturedEmail[];
+    /** Most recent email, optionally filtered by recipient address. */
+    latest(address?: string): CapturedEmail | undefined;
+    clear(): void;
+    get count(): number;
+}
+interface TestAppOptions {
+    /**
+     * Path to the schema.sql snapshot generated by
+     * `npx stardeck-data-store generate-types` (relative to the project root).
+     * Set to `null` for apps without a data store.
+     */
+    schema?: string | null;
+    /** Inline DDL instead of a schema file (useful for harness-level tests). */
+    schemaSql?: string;
+    /** Seed data after the schema is applied. Runs again on every `reset()`. */
+    seed?: (db: PGlite) => Promise<void>;
+    /**
+     * Allow real network access for hosts other than the simulated Stardeck
+     * services. Defaults to false: unexpected outbound fetches fail the test
+     * with a descriptive error so tests stay deterministic.
+     */
+    allowNetwork?: boolean;
+}
+interface SessionTokens {
+    accessToken: string;
+    refreshToken: string;
+}
+interface TestApp {
+    /** The in-process Postgres instance backing all simulated data stores. */
+    db: PGlite;
+    /** Captured outbound email. */
+    inbox: TestInbox;
+    /** Convenience for raw SQL: `app.query("SELECT ...", [param])`. */
+    query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
+    /**
+     * Sign in a test user for subsequent requests. `getSession()` in app code
+     * will resolve to this user. Returns the full user object.
+     */
+    asUser(user?: Partial<TestUser>): TestUser;
+    /** Clear the active test user. */
+    signOut(): void;
+    /**
+     * Mint access/refresh tokens for cookie-based auth flows. The simulated
+     * control-plane verify endpoint resolves these tokens back to the user.
+     */
+    issueSession(user?: Partial<TestUser>): SessionTokens;
+    /** Drop all tables, re-apply the schema, re-run the seed, clear inbox/user. */
+    reset(): Promise<void>;
+    /** Tear down the app and restore global fetch. */
+    close(): Promise<void>;
+}
+
+/**
+ * Boots the test harness: in-process Postgres, simulated control plane, and
+ * test env vars. Call once per test file (typically in `beforeAll`), and use
+ * `app.reset()` in `beforeEach` for a clean slate per test.
+ */
+declare function createTestApp(options?: TestAppOptions): Promise<TestApp>;
+
+type RouteHandler<Req extends Request, P> = (request: Req, context: {
+    params: Promise<P>;
+}) => Promise<Response> | Response;
+interface CallRouteOptions {
+    /** Request path, e.g. "/api/orders". Defaults to "/api/test-route". */
+    path?: string;
+    method?: string;
+    /** JSON body. Implies POST unless `method` is set. */
+    body?: unknown;
+    searchParams?: Record<string, string>;
+    /** Next.js dynamic segment params, e.g. { id: "123" }. */
+    params?: Record<string, string | string[]>;
+    headers?: Record<string, string>;
+    cookies?: Record<string, string>;
+    /** Override the active test user for this call only. */
+    user?: TestUser | null;
+}
+declare function callRoute<Req extends Request = Request, P = Record<string, string | string[]>>(handler: RouteHandler<Req, P>, options?: CallRouteOptions): Promise<Response>;
+
+/**
+ * Tags a describe block as covering a named critical workflow ("checkout",
+ * "booking", "inventory"). The platform parses the `workflow:` prefix out of
+ * test reporter output to show per-workflow pass/fail on deployments — use
+ * one block per workflow the app's owner cares about.
+ */
+declare function describeWorkflow(name: string, fn: () => void): void;
+declare const WORKFLOW_NAME_PREFIX = "workflow:";
+/** Extracts the workflow name from a tagged describe block title, if any. */
+declare function parseWorkflowName(describeTitle: string): string | null;
+
+declare const CONTROL_PLANE_TEST_URL = "https://control-plane.stardeck.test";
+declare const DATA_STORE_TEST_HOST = "db.stardeck.test";
+declare const TEST_ENV_DEFAULTS: {
+    readonly CONTROL_PLANE_URL: "https://control-plane.stardeck.test";
+    readonly DEPLOYMENT_SECRET: "stardeck-test-deployment-secret";
+    readonly ORGANIZATION_ID: "00000000-0000-4000-8000-00000000000a";
+    readonly PROJECT_ID: "00000000-0000-4000-8000-00000000000b";
+    readonly DEPLOYMENT_ID: "00000000-0000-4000-8000-00000000000c";
+    readonly DATA_STORE_URL: "postgresql://test:test@db.stardeck.test/main";
+};
+/** Default location of the DDL snapshot written by `generate-types`. */
+declare const DEFAULT_SCHEMA_PATH = "./src/generated/data-store-schema.sql";
+
+export { CONTROL_PLANE_TEST_URL, type CallRouteOptions, type CapturedEmail, DATA_STORE_TEST_HOST, DEFAULT_SCHEMA_PATH, type SessionTokens, TEST_ENV_DEFAULTS, type TestApp, type TestAppOptions, type TestInbox, type TestUser, WORKFLOW_NAME_PREFIX, callRoute, createTestApp, describeWorkflow, parseWorkflowName };

package/dist/index.d.ts

@@ -0,0 +1,143 @@
+import { PGlite } from '@electric-sql/pglite';
+
+/**
+ * The user shape returned by project-auth's `getSession()`. Mirrors the
+ * `UserSchema` in @stardeck-customer-apps/project-auth — keep in sync.
+ */
+interface TestUser {
+    id: string;
+    email?: string | null;
+    name?: string | null;
+    role?: string | null;
+    permissions?: string[];
+    organizationId?: string | null;
+    projectId?: string | null;
+}
+interface CapturedEmail {
+    resendId: string;
+    fromAddress: string;
+    from: {
+        name: string;
+        prefix: string;
+    };
+    to: string[];
+    cc: string[];
+    bcc: string[];
+    subject: string;
+    html?: string;
+    text?: string;
+    replyTo?: string;
+    attachments: Array<{
+        filename: string;
+        contentType?: string;
+    }>;
+    sentAt: Date;
+}
+interface TestInbox {
+    /** All captured emails, oldest first. */
+    all(): CapturedEmail[];
+    /** Emails addressed to (to/cc/bcc) the given address. */
+    to(address: string): CapturedEmail[];
+    /** Most recent email, optionally filtered by recipient address. */
+    latest(address?: string): CapturedEmail | undefined;
+    clear(): void;
+    get count(): number;
+}
+interface TestAppOptions {
+    /**
+     * Path to the schema.sql snapshot generated by
+     * `npx stardeck-data-store generate-types` (relative to the project root).
+     * Set to `null` for apps without a data store.
+     */
+    schema?: string | null;
+    /** Inline DDL instead of a schema file (useful for harness-level tests). */
+    schemaSql?: string;
+    /** Seed data after the schema is applied. Runs again on every `reset()`. */
+    seed?: (db: PGlite) => Promise<void>;
+    /**
+     * Allow real network access for hosts other than the simulated Stardeck
+     * services. Defaults to false: unexpected outbound fetches fail the test
+     * with a descriptive error so tests stay deterministic.
+     */
+    allowNetwork?: boolean;
+}
+interface SessionTokens {
+    accessToken: string;
+    refreshToken: string;
+}
+interface TestApp {
+    /** The in-process Postgres instance backing all simulated data stores. */
+    db: PGlite;
+    /** Captured outbound email. */
+    inbox: TestInbox;
+    /** Convenience for raw SQL: `app.query("SELECT ...", [param])`. */
+    query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
+    /**
+     * Sign in a test user for subsequent requests. `getSession()` in app code
+     * will resolve to this user. Returns the full user object.
+     */
+    asUser(user?: Partial<TestUser>): TestUser;
+    /** Clear the active test user. */
+    signOut(): void;
+    /**
+     * Mint access/refresh tokens for cookie-based auth flows. The simulated
+     * control-plane verify endpoint resolves these tokens back to the user.
+     */
+    issueSession(user?: Partial<TestUser>): SessionTokens;
+    /** Drop all tables, re-apply the schema, re-run the seed, clear inbox/user. */
+    reset(): Promise<void>;
+    /** Tear down the app and restore global fetch. */
+    close(): Promise<void>;
+}
+
+/**
+ * Boots the test harness: in-process Postgres, simulated control plane, and
+ * test env vars. Call once per test file (typically in `beforeAll`), and use
+ * `app.reset()` in `beforeEach` for a clean slate per test.
+ */
+declare function createTestApp(options?: TestAppOptions): Promise<TestApp>;
+
+type RouteHandler<Req extends Request, P> = (request: Req, context: {
+    params: Promise<P>;
+}) => Promise<Response> | Response;
+interface CallRouteOptions {
+    /** Request path, e.g. "/api/orders". Defaults to "/api/test-route". */
+    path?: string;
+    method?: string;
+    /** JSON body. Implies POST unless `method` is set. */
+    body?: unknown;
+    searchParams?: Record<string, string>;
+    /** Next.js dynamic segment params, e.g. { id: "123" }. */
+    params?: Record<string, string | string[]>;
+    headers?: Record<string, string>;
+    cookies?: Record<string, string>;
+    /** Override the active test user for this call only. */
+    user?: TestUser | null;
+}
+declare function callRoute<Req extends Request = Request, P = Record<string, string | string[]>>(handler: RouteHandler<Req, P>, options?: CallRouteOptions): Promise<Response>;
+
+/**
+ * Tags a describe block as covering a named critical workflow ("checkout",
+ * "booking", "inventory"). The platform parses the `workflow:` prefix out of
+ * test reporter output to show per-workflow pass/fail on deployments — use
+ * one block per workflow the app's owner cares about.
+ */
+declare function describeWorkflow(name: string, fn: () => void): void;
+declare const WORKFLOW_NAME_PREFIX = "workflow:";
+/** Extracts the workflow name from a tagged describe block title, if any. */
+declare function parseWorkflowName(describeTitle: string): string | null;
+
+declare const CONTROL_PLANE_TEST_URL = "https://control-plane.stardeck.test";
+declare const DATA_STORE_TEST_HOST = "db.stardeck.test";
+declare const TEST_ENV_DEFAULTS: {
+    readonly CONTROL_PLANE_URL: "https://control-plane.stardeck.test";
+    readonly DEPLOYMENT_SECRET: "stardeck-test-deployment-secret";
+    readonly ORGANIZATION_ID: "00000000-0000-4000-8000-00000000000a";
+    readonly PROJECT_ID: "00000000-0000-4000-8000-00000000000b";
+    readonly DEPLOYMENT_ID: "00000000-0000-4000-8000-00000000000c";
+    readonly DATA_STORE_URL: "postgresql://test:test@db.stardeck.test/main";
+};
+/** Default location of the DDL snapshot written by `generate-types`. */
+declare const DEFAULT_SCHEMA_PATH = "./src/generated/data-store-schema.sql";
+
+export { CONTROL_PLANE_TEST_URL, type CallRouteOptions, type CapturedEmail, DATA_STORE_TEST_HOST, DEFAULT_SCHEMA_PATH, type SessionTokens, TEST_ENV_DEFAULTS, type TestApp, type TestAppOptions, type TestInbox, type TestUser, WORKFLOW_NAME_PREFIX, callRoute, createTestApp, describeWorkflow, parseWorkflowName };