@venturekit/testing 0.0.0-dev.20260816114351 → 0.0.0-dev.20260816162655

package/README.md

@@ -27,69 +27,114 @@ vitest. The scenarios (selectors, flows, assertions) stay in your project.
 ```bash
 pnpm add -D @venturekit/testing
 # Optional peers (only if you use the matching helpers):
+#   pg                                            -> ensureStageDatabase (creates the stage DB)
+#   @playwright/test                              -> the /playwright subpath
 #   @venturekit/data                              -> truncate* DB helpers
 #   @aws-sdk/client-cognito-identity-provider     -> signInWithPassword / loginAs
 ```
 
-## Playwright: `globalSetup` pattern
-
-Let Playwright's `webServer` own the `vk dev` process and use the harness
-for migration, auth seeding, and readiness:
+## Playwright: `vkWebServers`
+
+The `@venturekit/testing/playwright` subpath builds the `webServer` block
+for you. It exists because the ordering is unforgiving and every mistake
+fails somewhere far from the cause:
+
+- **The database has to be created first.** Neither `vk migrate` nor
+  `vk dev` creates it, and `globalSetup` is too late — Playwright starts
+  `webServer` entries as config *plugins*, which run before `globalSetup`.
+  So creation is chained into the command, ahead of the migration.
+- **`vk migrate` and `vk dev` must agree on the database.** `vk dev`
+  derives `<database>_<stage>` from `vk.config.ts` and ignores an inherited
+  `DATABASE_URL`; `vk migrate` honours it. Pick your own name and you
+  migrate one database while the API serves another empty one — the suite
+  then fails with `relation "…" does not exist`.
+- **Crons must be off.** They share the single-process dev server with the
+  requests under test, write to the rows the specs assert on, and can spend
+  real provider quota.
 
 ```ts
 // playwright.config.ts
 import { defineConfig } from '@playwright/test';
+import { vkWebServers, storageStatePath } from '@venturekit/testing/playwright';
 
 export default defineConfig({
-  testDir: './e2e',
-  globalSetup: './e2e/global-setup.ts',
-  use: { baseURL: 'http://localhost:3005' }, // your UI
-  webServer: [
-    {
-      command: 'vk dev --stage test --port 4001 --no-watch',
-      url: 'http://localhost:4001/_dev/health',
-      reuseExistingServer: !process.env.CI,
-      timeout: 120_000,
-    },
+  testDir: './tests',
+  globalSetup: './setup/global-setup.ts',
+  projects: [
+    { name: 'setup', testMatch: /.*\.setup\.ts/ },
     {
-      command: 'pnpm --filter @your/admin dev',
-      url: 'http://localhost:3005',
-      reuseExistingServer: !process.env.CI,
+      name: 'api',
+      dependencies: ['setup'],
+      use: { baseURL: 'http://127.0.0.1:4100', storageState: storageStatePath('admin') },
     },
   ],
+  webServer: vkWebServers({
+    stage: 'test',
+    // `infrastructure.databases[].name` from vk.config.ts. The stage suffix
+    // is added for you, so this run uses `acme_app_test`.
+    database: 'acme_app',
+    api: { filter: '@acme/api', port: 4100 },
+    web: {
+      name: 'Admin',
+      command: 'pnpm --filter @acme/admin exec next dev -p 3100',
+      url: 'http://127.0.0.1:3100',
+      env: { NEXT_PUBLIC_API_BASE: 'http://127.0.0.1:4100' },
+    },
+  }),
 });
 ```
 
+That single call creates `acme_app_test`, migrates and seeds it, boots
+`vk dev --no-watch --no-crons`, gates on `/_dev/health`, names both servers
+so a timeout says which one hung, and pipes their output.
+
+### Roles once, not per spec
+
+`establishRoles` provisions each cognito-local user, logs it in, and writes
+the cookie jar. Specs adopt a role by pointing at the file:
+
 ```ts
-// e2e/global-setup.ts
-import { createTestUser, truncateAllTables, waitForReady } from '@venturekit/testing';
+// setup/roles.setup.ts
+import { test as setup } from '@playwright/test';
+import { establishRoles } from '@venturekit/testing/playwright';
+
+setup('establish roles', async () => {
+  await establishRoles({
+    baseUrl: 'http://127.0.0.1:4100',
+    roles: {
+      admin: { email: 'admin@example.com', password: 'Passw0rd!', attributes: { tenantId: 'dev' } },
+      viewer: { email: 'viewer@example.com', password: 'Passw0rd!', attributes: { tenantId: 'dev' } },
+    },
+  });
+});
+```
 
-const API = 'http://localhost:4001';
+```ts
+// setup/global-setup.ts
+import { wipeAuthDir } from '@venturekit/testing/playwright';
 
+// A jar from a previous run points at users the fresh database no longer
+// has; the resulting 401s look like an auth bug.
 export default async function globalSetup() {
-  await waitForReady({ baseUrl: API });
-  await truncateAllTables();            // needs DATABASE_URL / DB_* in env
-  await createTestUser({
-    baseUrl: API,
-    email: 'admin@example.com',
-    password: 'Passw0rd!',
-    attributes: { tenantId: 'global' },
-  });
+  await wipeAuthDir();
 }
 ```
 
-Your specs then log in through the real UI (the most faithful E2E):
+For an authz matrix, `createVkTest` adds an `asRole()` fixture that opens
+(and disposes) a context per role inside one spec:
 
 ```ts
-// e2e/login.spec.ts
-import { test, expect } from '@playwright/test';
-
-test('logs in and lands on the dashboard', async ({ page }) => {
-  await page.goto('/login');
-  await page.getByLabel('Email').fill('admin@example.com');
-  await page.getByLabel('Password').fill('Passw0rd!');
-  await page.getByRole('button', { name: 'Sign in' }).click();
-  await expect(page).toHaveURL(/\/(inbox|dashboard)/);
+// tests/api/fixtures.ts
+import { createVkTest } from '@venturekit/testing/playwright';
+export const test = createVkTest();
+
+// tests/api/authz.spec.ts
+import { expect } from '@playwright/test';
+import { test } from './fixtures.js';
+
+test('viewers cannot publish', async ({ asRole }) => {
+  const viewer = await asRole('viewer');
+  expect((await viewer.post('/content/1/publish')).status()).toBe(403);
 });
 ```
 
@@ -136,11 +181,32 @@ test('GET /tenant returns the current tenant', async () => {
 | `signInWithPassword(opts)` / `loginAs(opts)` | Mint real JWTs for a user (needs the Cognito SDK peer). |
 | `truncateAllTables(opts)` / `truncateTables` / `listTables` | Reset the DB between specs (needs `@venturekit/data`). |
 | `buildTruncateSql` / `filterTruncatableTables` / `quoteIdent` | Pure SQL builders (reusable / testable). |
+| `ensureStageDatabase(opts)` | Create `<database>_<stage>` if absent (needs `pg`). Idempotent and race-safe. |
+| `stageDatabaseName` / `stageDatabaseUrl` / `adminDatabaseUrl` | Mirror the CLI's database derivation so migrate and `vk dev` agree. |
+
+From `@venturekit/testing/playwright` (needs `@playwright/test`):
+
+| Export | Purpose |
+| --- | --- |
+| `vkWebServers(opts)` | Build the `webServer` block: create DB → migrate → `vk dev --no-crons`. |
+| `establishRoles(opts)` | Provision + log in every role, writing per-role `storageState`. |
+| `wipeAuthDir(dir?)` | Clear stale storage state from `globalSetup`. |
+| `storageStatePath(role, dir?)` | Where a role's jar lives (default `.auth/<role>.json`). |
+| `createVkTest(opts?)` | `test` object with an `asRole()` fixture for authz specs. |
+| `ensureDbScriptPath()` | Absolute path to the bundled creation script (also exposed as the `vk-ensure-db` bin). |
 
 ## Notes
 
 - `startTestStack` defaults to stage `test`, which targets a separate local
-  database (`<dbname>_test`) so your tests never clobber `vk dev` data.
+  database (`<dbname>_test`) so your tests never clobber `vk dev` data. That
+  name is derived by the CLI from `<databases[].name>_<stage>` and an
+  inherited `DATABASE_URL` does **not** override it — point `vk migrate` and
+  your own DB helpers at the same name, or the API will serve an unmigrated
+  database.
+- Pass `--no-crons` whenever a test suite owns the stack. Scheduled tasks
+  otherwise fire against the database under assertion, and a cron that calls
+  an LLM provider spends real quota on every tick. Invoke them explicitly
+  with `POST /_dev/invoke/cron/{name}` when a spec needs one to run.
 - `vk dev` does **not** auto-migrate — `startTestStack` runs `vk migrate`
   for you (pass `migrate: false` to skip, `seed: true` to also seed).
 - DB helpers read the same `DATABASE_URL` / `DB_*` env the app uses.

package/bin/ensure-db.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+/**
+ * Create the stage database, then exit.
+ *
+ * Chained ahead of `vk migrate` inside a Playwright `webServer` command,
+ * because that is the only hook guaranteed to run before the migration:
+ * `webServer` entries start as config *plugins*, and plugin setup runs
+ * before `globalSetup`. Creating the database in `globalSetup` therefore
+ * always loses the race and a cold run dies with
+ * `database "…" does not exist`.
+ *
+ * Plain `.mjs` on purpose — it runs under bare `node`, with no TS loader.
+ * Configuration arrives through the environment (set for you by
+ * `vkWebServers()` in @venturekit/testing/playwright):
+ *
+ *   VK_TEST_DB_NAME              the database to create
+ *   VK_TEST_ADMIN_DATABASE_URL   maintenance connection that issues the DDL
+ *
+ * `--name` / `--admin-url` argv flags override both, for one-off use.
+ */
+
+import { ensureStageDatabase } from '../dist/ensure-database.js';
+
+const arg = (flag) => {
+  const i = process.argv.indexOf(flag);
+  return i === -1 ? undefined : process.argv[i + 1];
+};
+
+const name = arg('--name') ?? process.env.VK_TEST_DB_NAME;
+const adminUrl = arg('--admin-url') ?? process.env.VK_TEST_ADMIN_DATABASE_URL;
+
+if (!name) {
+  console.error(
+    '[vk-testing] VK_TEST_DB_NAME (or --name) is required. It is normally set by the\n' +
+      '            webServer env block that vkWebServers() generates.',
+  );
+  process.exit(1);
+}
+
+function parse(url) {
+  try {
+    const u = new URL(url);
+    return {
+      host: u.hostname || undefined,
+      port: u.port ? Number(u.port) : undefined,
+      user: decodeURIComponent(u.username) || undefined,
+      password: decodeURIComponent(u.password) || undefined,
+    };
+  } catch {
+    console.error(`[vk-testing] VK_TEST_ADMIN_DATABASE_URL is not a valid URL: ${url}`);
+    process.exit(1);
+  }
+}
+
+// The admin URL is optional: ensureStageDatabase falls back to the local
+// Postgres defaults `vk dev` uses.
+const connection = adminUrl ? parse(adminUrl) : {};
+
+try {
+  await ensureStageDatabase({ name, ...connection });
+} catch (err) {
+  console.error(String(err instanceof Error ? err.message : err));
+  process.exit(1);
+}

package/dist/ensure-database.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Create the stage database before migrations run.
+ *
+ * Neither `vk migrate` nor `vk dev` creates the database it connects to, so
+ * a cold machine or a fresh CI runner dies on the first migration with
+ * `database "…" does not exist`. This closes that gap.
+ *
+ * IO-bound by nature (it needs a live Postgres), so the pure naming and
+ * validation logic it builds on lives in ./stage-db.ts and is unit-tested
+ * there. See the coverage exclusions in the root vitest.config.ts.
+ */
+import { type PgConnection, type StageDatabaseTarget } from './stage-db.js';
+export interface EnsureStageDatabaseOptions extends Partial<StageDatabaseTarget>, PgConnection {
+    /**
+     * Explicit database name, bypassing derivation. Prefer `database` +
+     * `stage` so the name always tracks what the CLI will actually serve.
+     */
+    name?: string;
+    /** Where to write progress lines. Pass `null` to stay silent. */
+    logger?: ((message: string) => void) | null;
+}
+export interface EnsureStageDatabaseResult {
+    /** The database name that now exists. */
+    name: string;
+    /** Connection string for it. */
+    url: string;
+    /** False when it was already present. */
+    created: boolean;
+}
+/**
+ * Create the stage database if it does not exist yet.
+ *
+ * Idempotent and safe to run concurrently: a `42P04` (duplicate_database)
+ * raised by a racing run is the desired end state, not a failure.
+ *
+ * Run this BEFORE `vk migrate`. Under Playwright that means chaining it into
+ * the `webServer` command rather than doing it in `globalSetup` —
+ * `webServer` entries start as config plugins, and plugin setup runs first,
+ * so `globalSetup` always loses the race to the migration.
+ * `vkWebServers()` from `@venturekit/testing/playwright` wires that for you.
+ */
+export declare function ensureStageDatabase(options: EnsureStageDatabaseOptions): Promise<EnsureStageDatabaseResult>;
+//# sourceMappingURL=ensure-database.d.ts.map

package/dist/ensure-database.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensure-database.d.ts","sourceRoot":"","sources":["../src/ensure-database.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAKL,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACzB,MAAM,eAAe,CAAC;AAevB,MAAM,WAAW,0BAA2B,SAAQ,OAAO,CAAC,mBAAmB,CAAC,EAAE,YAAY;IAC5F;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,MAAM,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;CAC7C;AAED,MAAM,WAAW,yBAAyB;IACxC,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,yCAAyC;IACzC,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,yBAAyB,CAAC,CA6CpC"}

package/dist/ensure-database.js

@@ -0,0 +1,76 @@
+/**
+ * Create the stage database before migrations run.
+ *
+ * Neither `vk migrate` nor `vk dev` creates the database it connects to, so
+ * a cold machine or a fresh CI runner dies on the first migration with
+ * `database "…" does not exist`. This closes that gap.
+ *
+ * IO-bound by nature (it needs a live Postgres), so the pure naming and
+ * validation logic it builds on lives in ./stage-db.ts and is unit-tested
+ * there. See the coverage exclusions in the root vitest.config.ts.
+ */
+import { adminDatabaseUrl, pgConnectionString, redactUrl, resolveStageDatabaseName, } from './stage-db.js';
+async function loadPg() {
+    try {
+        return (await import('pg'));
+    }
+    catch {
+        throw new Error("@venturekit/testing: ensureStageDatabase requires the optional peer 'pg'. " +
+            'Install it in your test package: `pnpm add -D pg`.');
+    }
+}
+/**
+ * Create the stage database if it does not exist yet.
+ *
+ * Idempotent and safe to run concurrently: a `42P04` (duplicate_database)
+ * raised by a racing run is the desired end state, not a failure.
+ *
+ * Run this BEFORE `vk migrate`. Under Playwright that means chaining it into
+ * the `webServer` command rather than doing it in `globalSetup` —
+ * `webServer` entries start as config plugins, and plugin setup runs first,
+ * so `globalSetup` always loses the race to the migration.
+ * `vkWebServers()` from `@venturekit/testing/playwright` wires that for you.
+ */
+export async function ensureStageDatabase(options) {
+    const name = resolveStageDatabaseName(options);
+    const log = options.logger === null
+        ? () => { }
+        : (options.logger ?? ((m) => console.log(`[vk-testing] ${m}`)));
+    // Connect to the maintenance database: CREATE DATABASE can run neither
+    // inside the target database nor inside a transaction.
+    const adminUrl = adminDatabaseUrl(options);
+    const url = pgConnectionString(options, name);
+    const { Client } = await loadPg();
+    const client = new Client({ connectionString: adminUrl });
+    try {
+        await client.connect();
+    }
+    catch (err) {
+        throw new Error(`@venturekit/testing: cannot reach Postgres at ${redactUrl(adminUrl)} — is it running? ` +
+            'Start the local stack (`vk dev`) once, or `docker compose up -d postgres`. ' +
+            `Cause: ${String(err)}`);
+    }
+    try {
+        const { rowCount } = await client.query('SELECT 1 FROM pg_database WHERE datname = $1', [name]);
+        if (rowCount) {
+            log(`stage database ready: ${name}`);
+            return { name, url, created: false };
+        }
+        await client.query(`CREATE DATABASE "${name}"`);
+        log(`stage database created: ${name}`);
+        return { name, url, created: true };
+    }
+    catch (err) {
+        // 42P04 = duplicate_database: a concurrent run won the race between the
+        // SELECT and the CREATE. That is exactly the state we wanted.
+        if (err?.code === '42P04') {
+            log(`stage database ready: ${name}`);
+            return { name, url, created: false };
+        }
+        throw new Error(`@venturekit/testing: failed to create database ${name}: ${String(err)}`);
+    }
+    finally {
+        await client.end().catch(() => { });
+    }
+}
+//# sourceMappingURL=ensure-database.js.map

package/dist/ensure-database.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensure-database.js","sourceRoot":"","sources":["../src/ensure-database.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,SAAS,EACT,wBAAwB,GAGzB,MAAM,eAAe,CAAC;AAIvB,KAAK,UAAU,MAAM;IACnB,IAAI,CAAC;QACH,OAAO,CAAC,MAAM,MAAM,CAAC,IAAI,CAAC,CAAwB,CAAC;IACrD,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CACb,4EAA4E;YAC1E,oDAAoD,CACvD,CAAC;IACJ,CAAC;AACH,CAAC;AAqBD;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,OAAmC;IAEnC,MAAM,IAAI,GAAG,wBAAwB,CAAC,OAAO,CAAC,CAAC;IAC/C,MAAM,GAAG,GACP,OAAO,CAAC,MAAM,KAAK,IAAI;QACrB,CAAC,CAAC,GAAG,EAAE,GAAE,CAAC;QACV,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,IAAI,CAAC,CAAC,CAAS,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAE5E,uEAAuE;IACvE,uDAAuD;IACvD,MAAM,QAAQ,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;IAC3C,MAAM,GAAG,GAAG,kBAAkB,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IAE9C,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,MAAM,EAAE,CAAC;IAClC,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,EAAE,gBAAgB,EAAE,QAAQ,EAAE,CAAC,CAAC;IAE1D,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,OAAO,EAAE,CAAC;IACzB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,iDAAiD,SAAS,CAAC,QAAQ,CAAC,oBAAoB;YACtF,6EAA6E;YAC7E,UAAU,MAAM,CAAC,GAAG,CAAC,EAAE,CAC1B,CAAC;IACJ,CAAC;IAED,IAAI,CAAC;QACH,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,8CAA8C,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;QAChG,IAAI,QAAQ,EAAE,CAAC;YACb,GAAG,CAAC,yBAAyB,IAAI,EAAE,CAAC,CAAC;YACrC,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QACvC,CAAC;QACD,MAAM,MAAM,CAAC,KAAK,CAAC,oBAAoB,IAAI,GAAG,CAAC,CAAC;QAChD,GAAG,CAAC,2BAA2B,IAAI,EAAE,CAAC,CAAC;QACvC,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IACtC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,wEAAwE;QACxE,8DAA8D;QAC9D,IAAK,GAAyB,EAAE,IAAI,KAAK,OAAO,EAAE,CAAC;YACjD,GAAG,CAAC,yBAAyB,IAAI,EAAE,CAAC,CAAC;YACrC,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QACvC,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,kDAAkD,IAAI,KAAK,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC5F,CAAC;YAAS,CAAC;QACT,MAAM,MAAM,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IACrC,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -3,11 +3,15 @@
  *
  * Integration & end-to-end test harness for VentureKit apps.
  *
+ * - Create the stage database (`ensureStageDatabase`) — the CLI does not.
  * - Launch a full local stack (`startTestStack`) — migrate + `vk dev`.
  * - Wait for readiness (`waitForReady`) against `/_dev/health`.
  * - Seed cognito-local users (`createTestUser`) and mint JWTs (`loginAs`).
  * - Reset the database between specs (`truncateAllTables`).
  * - Drive the API with a typed client (`createApiClient`).
+ *
+ * Playwright-specific pieces (`webServer` wiring, role storage state,
+ * fixtures) live in the `@venturekit/testing/playwright` subpath.
  */
 export { ApiError } from './errors.js';
 export type { ApiErrorInit } from './errors.js';
@@ -21,6 +25,10 @@ export { signInWithPassword, loginAs, DEFAULT_COGNITO_ENDPOINT, DEFAULT_COGNITO_
 export type { TokenSet, SignInInput, LoginAsInput } from './auth-tokens.js';
 export { startTestStack } from './stack.js';
 export type { StartTestStackOptions, TestStack } from './stack.js';
+export { stageDatabaseName, stageDatabaseUrl, adminDatabaseUrl, pgConnectionString, resolveStageDatabaseName, isSafeDatabaseName, redactUrl, LOCAL_PG, } from './stage-db.js';
+export type { StageDatabaseTarget, PgConnection } from './stage-db.js';
+export { ensureStageDatabase } from './ensure-database.js';
+export type { EnsureStageDatabaseOptions, EnsureStageDatabaseResult, } from './ensure-database.js';
 export { truncateAllTables, truncateTables, listTables, } from './db.js';
 export type { TruncateOptions } from './db.js';
 export { buildTruncateSql, filterTruncatableTables, quoteIdent, VK_TRACKING_TABLES, } from './sql.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACxD,YAAY,EACV,SAAS,EACT,gBAAgB,EAChB,WAAW,EACX,cAAc,GACf,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC5D,YAAY,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD,OAAO,EACL,cAAc,EACd,cAAc,EACd,qBAAqB,EACrB,WAAW,GACZ,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,YAAY,EACZ,mBAAmB,EACnB,OAAO,EACP,cAAc,GACf,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,kBAAkB,EAClB,OAAO,EACP,wBAAwB,EACxB,sBAAsB,GACvB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAE5E,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,YAAY,EAAE,qBAAqB,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEnE,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,UAAU,GACX,MAAM,SAAS,CAAC;AACjB,YAAY,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,UAAU,EACV,kBAAkB,GACnB,MAAM,UAAU,CAAC;AAClB,YAAY,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAEnD,YAAY,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACxD,YAAY,EACV,SAAS,EACT,gBAAgB,EAChB,WAAW,EACX,cAAc,GACf,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC5D,YAAY,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD,OAAO,EACL,cAAc,EACd,cAAc,EACd,qBAAqB,EACrB,WAAW,GACZ,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,YAAY,EACZ,mBAAmB,EACnB,OAAO,EACP,cAAc,GACf,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,kBAAkB,EAClB,OAAO,EACP,wBAAwB,EACxB,sBAAsB,GACvB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAE5E,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,YAAY,EAAE,qBAAqB,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEnE,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,EAClB,wBAAwB,EACxB,kBAAkB,EAClB,SAAS,EACT,QAAQ,GACT,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAEvE,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC3D,YAAY,EACV,0BAA0B,EAC1B,yBAAyB,GAC1B,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,UAAU,GACX,MAAM,SAAS,CAAC;AACjB,YAAY,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,UAAU,EACV,kBAAkB,GACnB,MAAM,UAAU,CAAC;AAClB,YAAY,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAEnD,YAAY,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -3,11 +3,15 @@
  *
  * Integration & end-to-end test harness for VentureKit apps.
  *
+ * - Create the stage database (`ensureStageDatabase`) — the CLI does not.
  * - Launch a full local stack (`startTestStack`) — migrate + `vk dev`.
  * - Wait for readiness (`waitForReady`) against `/_dev/health`.
  * - Seed cognito-local users (`createTestUser`) and mint JWTs (`loginAs`).
  * - Reset the database between specs (`truncateAllTables`).
  * - Drive the API with a typed client (`createApiClient`).
+ *
+ * Playwright-specific pieces (`webServer` wiring, role storage state,
+ * fixtures) live in the `@venturekit/testing/playwright` subpath.
  */
 export { ApiError } from './errors.js';
 export { createApiClient, buildUrl } from './client.js';
@@ -15,6 +19,8 @@ export { waitForReady, vkDevServerReady } from './ready.js';
 export { createTestUser, deleteTestUser, setTestUserAttributes, getDevPools, } from './cognito.js';
 export { signInWithPassword, loginAs, DEFAULT_COGNITO_ENDPOINT, DEFAULT_COGNITO_REGION, } from './auth-tokens.js';
 export { startTestStack } from './stack.js';
+export { stageDatabaseName, stageDatabaseUrl, adminDatabaseUrl, pgConnectionString, resolveStageDatabaseName, isSafeDatabaseName, redactUrl, LOCAL_PG, } from './stage-db.js';
+export { ensureStageDatabase } from './ensure-database.js';
 export { truncateAllTables, truncateTables, listTables, } from './db.js';
 export { buildTruncateSql, filterTruncatableTables, quoteIdent, VK_TRACKING_TABLES, } from './sql.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAGvC,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAQxD,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAG5D,OAAO,EACL,cAAc,EACd,cAAc,EACd,qBAAqB,EACrB,WAAW,GACZ,MAAM,cAAc,CAAC;AAQtB,OAAO,EACL,kBAAkB,EAClB,OAAO,EACP,wBAAwB,EACxB,sBAAsB,GACvB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAG5C,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,UAAU,GACX,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,UAAU,EACV,kBAAkB,GACnB,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAGvC,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAQxD,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAG5D,OAAO,EACL,cAAc,EACd,cAAc,EACd,qBAAqB,EACrB,WAAW,GACZ,MAAM,cAAc,CAAC;AAQtB,OAAO,EACL,kBAAkB,EAClB,OAAO,EACP,wBAAwB,EACxB,sBAAsB,GACvB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAG5C,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,EAClB,wBAAwB,EACxB,kBAAkB,EAClB,SAAS,EACT,QAAQ,GACT,MAAM,eAAe,CAAC;AAGvB,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAM3D,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,UAAU,GACX,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,UAAU,EACV,kBAAkB,GACnB,MAAM,UAAU,CAAC"}

package/dist/playwright/auth-setup.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Log every role in once, up front, and persist its cookie jar.
+ *
+ * Run from a Playwright `setup` project that the other projects depend on.
+ * Specs then adopt a role by pointing `storageState` at a file — no
+ * per-spec login, no token plumbing, and the authz matrix costs one line.
+ *
+ * Assumes cookie-based sessions, which is what `@venturekit/auth`'s
+ * `/auth/login` route issues: the response `Set-Cookie` lands in the
+ * request context's jar, and `storageState()` writes it out.
+ *
+ * IO-bound, so the pure path math lives in ./storage-state.ts.
+ */
+export interface VkRoleSpec {
+    email: string;
+    password: string;
+    /**
+     * Cognito attributes. Unprefixed custom names get `custom:` added by the
+     * dev server, e.g. `{ tenantId: 'dev' }` → `custom:tenantId`.
+     */
+    attributes?: Record<string, string>;
+}
+export interface EstablishRolesOptions {
+    /** Role key → credentials. The key becomes the storage-state filename. */
+    roles: Record<string, VkRoleSpec>;
+    /** API base URL — serves both the cognito-local admin API and the login route. */
+    baseUrl: string;
+    /** Auth intent id, when the project declares more than one. */
+    intent?: string;
+    /** Login route. Defaults to the `@venturekit/auth` route. */
+    loginPath?: string;
+    /** Directory for the storage-state files. Defaults to `.auth`. */
+    authDir?: string;
+    /**
+     * Create each user in cognito-local first. On by default and idempotent —
+     * an existing user just has its password reset, so runs stay deterministic.
+     */
+    provision?: boolean;
+    /** Build the login body. Defaults to `{ email, password }`. */
+    loginBody?: (role: VkRoleSpec) => Record<string, unknown>;
+    /** Where to write progress lines. Pass `null` to stay silent. */
+    logger?: ((message: string) => void) | null;
+}
+/**
+ * Delete the storage-state directory.
+ *
+ * Call from `globalSetup`: a jar left over from a previous run points at
+ * users that no longer exist in the freshly created database, and the
+ * resulting 401s look like an auth bug rather than stale state.
+ */
+export declare function wipeAuthDir(dir?: string): Promise<void>;
+/**
+ * Provision each role, log it in, and write its `storageState`.
+ *
+ * Returns role key → file path, ready to drop into a project's `use`.
+ */
+export declare function establishRoles(options: EstablishRolesOptions): Promise<Record<string, string>>;
+//# sourceMappingURL=auth-setup.d.ts.map

package/dist/playwright/auth-setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-setup.d.ts","sourceRoot":"","sources":["../../src/playwright/auth-setup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAOH,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC;AAED,MAAM,WAAW,qBAAqB;IACpC,0EAA0E;IAC1E,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAClC,kFAAkF;IAClF,OAAO,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,+DAA+D;IAC/D,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1D,iEAAiE;IACjE,MAAM,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;CAC7C;AAYD;;;;;;GAMG;AACH,wBAAsB,WAAW,CAAC,GAAG,GAAE,MAAyB,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/E;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAyDjC"}

package/dist/playwright/auth-setup.js

@@ -0,0 +1,79 @@
+/**
+ * Log every role in once, up front, and persist its cookie jar.
+ *
+ * Run from a Playwright `setup` project that the other projects depend on.
+ * Specs then adopt a role by pointing `storageState` at a file — no
+ * per-spec login, no token plumbing, and the authz matrix costs one line.
+ *
+ * Assumes cookie-based sessions, which is what `@venturekit/auth`'s
+ * `/auth/login` route issues: the response `Set-Cookie` lands in the
+ * request context's jar, and `storageState()` writes it out.
+ *
+ * IO-bound, so the pure path math lives in ./storage-state.ts.
+ */
+import { mkdir, rm } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { createTestUser } from '../cognito.js';
+import { DEFAULT_AUTH_DIR, storageStatePath } from './storage-state.js';
+async function loadPlaywright() {
+    try {
+        return await import('@playwright/test');
+    }
+    catch {
+        throw new Error("@venturekit/testing: this helper requires the optional peer '@playwright/test'.");
+    }
+}
+/**
+ * Delete the storage-state directory.
+ *
+ * Call from `globalSetup`: a jar left over from a previous run points at
+ * users that no longer exist in the freshly created database, and the
+ * resulting 401s look like an auth bug rather than stale state.
+ */
+export async function wipeAuthDir(dir = DEFAULT_AUTH_DIR) {
+    await rm(dir, { recursive: true, force: true });
+}
+/**
+ * Provision each role, log it in, and write its `storageState`.
+ *
+ * Returns role key → file path, ready to drop into a project's `use`.
+ */
+export async function establishRoles(options) {
+    const { roles, baseUrl, intent, loginPath = '/auth/login', authDir = DEFAULT_AUTH_DIR, provision = true, loginBody = (role) => ({ email: role.email, password: role.password }), } = options;
+    const log = options.logger === null
+        ? () => { }
+        : (options.logger ?? ((m) => console.log(`[vk-testing] ${m}`)));
+    const { request } = await loadPlaywright();
+    const written = {};
+    for (const [key, role] of Object.entries(roles)) {
+        const path = storageStatePath(key, authDir);
+        if (provision) {
+            await createTestUser({ baseUrl, intent, ...role });
+        }
+        const context = await request.newContext({ baseURL: baseUrl });
+        try {
+            const response = await context.post(loginPath, { data: loginBody(role) });
+            if (!response.ok()) {
+                const body = await response.text().catch(() => '');
+                throw new Error(`@venturekit/testing: login failed for role "${key}" (${role.email}) — ` +
+                    `POST ${loginPath} returned ${response.status()}. ${body.slice(0, 400)}`);
+            }
+            // A 200 with no cookie writes a jar that authenticates nothing, and
+            // every later spec then fails with a 401 far from the cause.
+            const state = await context.storageState();
+            if (state.cookies.length === 0) {
+                throw new Error(`@venturekit/testing: login for role "${key}" succeeded but set no cookies. ` +
+                    `Is ${loginPath} the right route, and does it issue a session cookie?`);
+            }
+            await mkdir(dirname(path), { recursive: true });
+            await context.storageState({ path });
+            written[key] = path;
+            log(`role ready: ${key} → ${path}`);
+        }
+        finally {
+            await context.dispose();
+        }
+    }
+    return written;
+}
+//# sourceMappingURL=auth-setup.js.map

package/dist/playwright/auth-setup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-setup.js","sourceRoot":"","sources":["../../src/playwright/auth-setup.ts"],"names":[],"mappings":"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"}

package/dist/playwright/fixtures.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Per-role API contexts as a Playwright fixture.
+ *
+ * A project pins one role through `use.storageState`, which covers the happy
+ * path. Authz tests need the others in the same spec — this exposes them on
+ * demand and disposes them at teardown, so no spec leaks a context.
+ *
+ * Requires the roles to have been established first; see ./auth-setup.ts.
+ */
+import { type APIRequestContext } from '@playwright/test';
+export interface VkFixtures {
+    /**
+     * Open an API request context authenticated as `role`.
+     *
+     * ```ts
+     * const viewer = await asRole('viewer');
+     * expect((await viewer.post('/content')).status()).toBe(403);
+     * ```
+     */
+    asRole: (role: string) => Promise<APIRequestContext>;
+}
+export interface CreateVkTestOptions {
+    /** Directory holding the storage-state files. Defaults to `.auth`. */
+    authDir?: string;
+    /** Override the project's `baseURL` for these contexts. */
+    baseURL?: string;
+    /** Extra headers for every role context. Defaults to `Accept: application/json`. */
+    extraHTTPHeaders?: Record<string, string>;
+}
+/**
+ * Build a `test` object carrying the `asRole` fixture.
+ *
+ * ```ts
+ * // tests/api/fixtures.ts
+ * export const test = createVkTest();
+ * ```
+ */
+export declare function createVkTest(options?: CreateVkTestOptions): import("@playwright/test").TestType<import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions & VkFixtures, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions>;
+//# sourceMappingURL=fixtures.d.ts.map

package/dist/playwright/fixtures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixtures.d.ts","sourceRoot":"","sources":["../../src/playwright/fixtures.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAyB,KAAK,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAGjF,MAAM,WAAW,UAAU;IACzB;;;;;;;OAOG;IACH,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAAC;CACtD;AAED,MAAM,WAAW,mBAAmB;IAClC,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oFAAoF;IACpF,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC3C;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE,mBAAwB,4PA6B7D"}