@venturekit/testing 0.0.19 → 0.0.21

package/dist/playwright/fixtures.js

@@ -0,0 +1,46 @@
+/**
+ * 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 { existsSync } from 'node:fs';
+import { test as base, request } from '@playwright/test';
+import { DEFAULT_AUTH_DIR, storageStatePath } from './storage-state.js';
+/**
+ * Build a `test` object carrying the `asRole` fixture.
+ *
+ * ```ts
+ * // tests/api/fixtures.ts
+ * export const test = createVkTest();
+ * ```
+ */
+export function createVkTest(options = {}) {
+    const authDir = options.authDir ?? DEFAULT_AUTH_DIR;
+    return base.extend({
+        asRole: async ({ baseURL }, use) => {
+            const opened = [];
+            await use(async (role) => {
+                const storageState = storageStatePath(role, authDir);
+                if (!existsSync(storageState)) {
+                    throw new Error(`@venturekit/testing: no storage state for role "${role}" at ${storageState}. ` +
+                        'Establish it in the setup project (establishRoles) and make this project ' +
+                        "depend on it via `dependencies: ['setup']`.");
+                }
+                const context = await request.newContext({
+                    baseURL: options.baseURL ?? baseURL,
+                    storageState,
+                    extraHTTPHeaders: options.extraHTTPHeaders ?? { Accept: 'application/json' },
+                });
+                opened.push(context);
+                return context;
+            });
+            for (const context of opened)
+                await context.dispose();
+        },
+    });
+}
+//# sourceMappingURL=fixtures.js.map

package/dist/playwright/fixtures.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixtures.js","sourceRoot":"","sources":["../../src/playwright/fixtures.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,IAAI,IAAI,IAAI,EAAE,OAAO,EAA0B,MAAM,kBAAkB,CAAC;AACjF,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAuBxE;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,UAA+B,EAAE;IAC5D,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,gBAAgB,CAAC;IAEpD,OAAO,IAAI,CAAC,MAAM,CAAa;QAC7B,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,EAAE,GAAG,EAAE,EAAE;YACjC,MAAM,MAAM,GAAwB,EAAE,CAAC;YAEvC,MAAM,GAAG,CAAC,KAAK,EAAE,IAAY,EAAE,EAAE;gBAC/B,MAAM,YAAY,GAAG,gBAAgB,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;gBACrD,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;oBAC9B,MAAM,IAAI,KAAK,CACb,mDAAmD,IAAI,QAAQ,YAAY,IAAI;wBAC7E,2EAA2E;wBAC3E,6CAA6C,CAChD,CAAC;gBACJ,CAAC;gBAED,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,UAAU,CAAC;oBACvC,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,OAAO;oBACnC,YAAY;oBACZ,gBAAgB,EAAE,OAAO,CAAC,gBAAgB,IAAI,EAAE,MAAM,EAAE,kBAAkB,EAAE;iBAC7E,CAAC,CAAC;gBACH,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBACrB,OAAO,OAAO,CAAC;YACjB,CAAC,CAAC,CAAC;YAEH,KAAK,MAAM,OAAO,IAAI,MAAM;gBAAE,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC;QACxD,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}

package/dist/playwright/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @venturekit/testing/playwright
+ *
+ * Playwright-specific half of the harness. Import from here in
+ * `playwright.config.ts`, setup projects and specs:
+ *
+ * - `vkWebServers` — database creation + migration + `vk dev`, in the one
+ *   order that works, with crons off.
+ * - `establishRoles` / `wipeAuthDir` — log every role in once, persist the
+ *   cookie jars, and clear stale ones.
+ * - `storageStatePath` — where a role's jar lives.
+ * - `createVkTest` — `asRole()` fixture for authz specs.
+ *
+ * `@playwright/test` is an optional peer of the package as a whole, but it
+ * is required for this subpath.
+ */
+export { vkWebServers, ensureDbScriptPath, ENSURE_DB_ENV } from './web-servers.js';
+export type { VkWebServersOptions, VkWebServerConfig, VkWebServerSpec, VkApiServerSpec, } from './web-servers.js';
+export { storageStatePath, storageStatePaths, isSafeRoleKey, DEFAULT_AUTH_DIR, } from './storage-state.js';
+export { establishRoles, wipeAuthDir } from './auth-setup.js';
+export type { VkRoleSpec, EstablishRolesOptions } from './auth-setup.js';
+export { createVkTest } from './fixtures.js';
+export type { VkFixtures, CreateVkTestOptions } from './fixtures.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/playwright/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACnF,YAAY,EACV,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,EACf,eAAe,GAChB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,aAAa,EACb,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9D,YAAY,EAAE,UAAU,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAEzE,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,YAAY,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC"}

package/dist/playwright/index.js

@@ -0,0 +1,21 @@
+/**
+ * @venturekit/testing/playwright
+ *
+ * Playwright-specific half of the harness. Import from here in
+ * `playwright.config.ts`, setup projects and specs:
+ *
+ * - `vkWebServers` — database creation + migration + `vk dev`, in the one
+ *   order that works, with crons off.
+ * - `establishRoles` / `wipeAuthDir` — log every role in once, persist the
+ *   cookie jars, and clear stale ones.
+ * - `storageStatePath` — where a role's jar lives.
+ * - `createVkTest` — `asRole()` fixture for authz specs.
+ *
+ * `@playwright/test` is an optional peer of the package as a whole, but it
+ * is required for this subpath.
+ */
+export { vkWebServers, ensureDbScriptPath, ENSURE_DB_ENV } from './web-servers.js';
+export { storageStatePath, storageStatePaths, isSafeRoleKey, DEFAULT_AUTH_DIR, } from './storage-state.js';
+export { establishRoles, wipeAuthDir } from './auth-setup.js';
+export { createVkTest } from './fixtures.js';
+//# sourceMappingURL=index.js.map

package/dist/playwright/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/playwright/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAQnF,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,aAAa,EACb,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAG9D,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC"}

package/dist/playwright/storage-state.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Where per-role `storageState` files live.
+ *
+ * The pattern: a `setup` project logs each role in once and writes its
+ * cookie jar to disk; every other project points `storageState` at one of
+ * those files. Roles then cost nothing per spec, and the authz matrix is a
+ * matter of picking a file rather than re-authenticating.
+ *
+ * Pure path math, kept apart from the IO in ./auth-setup.ts so it is
+ * unit-testable.
+ */
+/** Default directory, relative to the Playwright config. Add it to .gitignore. */
+export declare const DEFAULT_AUTH_DIR = ".auth";
+/**
+ * True when `role` is safe to use as a filename. Role keys end up in a path,
+ * so anything that could escape the auth directory is refused.
+ */
+export declare function isSafeRoleKey(role: string): boolean;
+/**
+ * Path to a role's storage state, e.g. `.auth/adminDev.json`.
+ *
+ * Forward slashes on purpose: Playwright accepts them on every platform, and
+ * it keeps the value stable in snapshots and error messages.
+ */
+export declare function storageStatePath(role: string, dir?: string): string;
+/** Map every role key to its storage-state path. */
+export declare function storageStatePaths(roles: readonly string[], dir?: string): Record<string, string>;
+//# sourceMappingURL=storage-state.d.ts.map

package/dist/playwright/storage-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-state.d.ts","sourceRoot":"","sources":["../../src/playwright/storage-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,kFAAkF;AAClF,eAAO,MAAM,gBAAgB,UAAU,CAAC;AAExC;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,GAAE,MAAyB,GAAG,MAAM,CAOrF;AAED,oDAAoD;AACpD,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,GAAG,GAAE,MAAyB,GAC7B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAIxB"}

package/dist/playwright/storage-state.js

@@ -0,0 +1,40 @@
+/**
+ * Where per-role `storageState` files live.
+ *
+ * The pattern: a `setup` project logs each role in once and writes its
+ * cookie jar to disk; every other project points `storageState` at one of
+ * those files. Roles then cost nothing per spec, and the authz matrix is a
+ * matter of picking a file rather than re-authenticating.
+ *
+ * Pure path math, kept apart from the IO in ./auth-setup.ts so it is
+ * unit-testable.
+ */
+/** Default directory, relative to the Playwright config. Add it to .gitignore. */
+export const DEFAULT_AUTH_DIR = '.auth';
+/**
+ * True when `role` is safe to use as a filename. Role keys end up in a path,
+ * so anything that could escape the auth directory is refused.
+ */
+export function isSafeRoleKey(role) {
+    return /^[A-Za-z0-9_-]+$/.test(role);
+}
+/**
+ * Path to a role's storage state, e.g. `.auth/adminDev.json`.
+ *
+ * Forward slashes on purpose: Playwright accepts them on every platform, and
+ * it keeps the value stable in snapshots and error messages.
+ */
+export function storageStatePath(role, dir = DEFAULT_AUTH_DIR) {
+    if (!isSafeRoleKey(role)) {
+        throw new Error(`@venturekit/testing: unsafe role key "${role}" — use letters, digits, dashes or underscores.`);
+    }
+    return `${dir.replace(/\/+$/, '')}/${role}.json`;
+}
+/** Map every role key to its storage-state path. */
+export function storageStatePaths(roles, dir = DEFAULT_AUTH_DIR) {
+    const out = {};
+    for (const role of roles)
+        out[role] = storageStatePath(role, dir);
+    return out;
+}
+//# sourceMappingURL=storage-state.js.map

package/dist/playwright/storage-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-state.js","sourceRoot":"","sources":["../../src/playwright/storage-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,kFAAkF;AAClF,MAAM,CAAC,MAAM,gBAAgB,GAAG,OAAO,CAAC;AAExC;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,OAAO,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACvC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,MAAc,gBAAgB;IAC3E,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CACb,yCAAyC,IAAI,iDAAiD,CAC/F,CAAC;IACJ,CAAC;IACD,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,IAAI,OAAO,CAAC;AACnD,CAAC;AAED,oDAAoD;AACpD,MAAM,UAAU,iBAAiB,CAC/B,KAAwB,EACxB,MAAc,gBAAgB;IAE9B,MAAM,GAAG,GAA2B,EAAE,CAAC;IACvC,KAAK,MAAM,IAAI,IAAI,KAAK;QAAE,GAAG,CAAC,IAAI,CAAC,GAAG,gBAAgB,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAClE,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/playwright/web-servers.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Playwright `webServer` wiring for a VentureKit stack.
+ *
+ * Encodes the ordering constraints that are easy to get wrong and fail
+ * confusingly when you do:
+ *
+ *  1. **Create the database first.** Nothing in the CLI creates it, and
+ *     `globalSetup` is too late: Playwright starts `webServer` entries as
+ *     config plugins, and plugin setup runs before `globalSetup`. So the
+ *     creation step is chained *into* the command, ahead of `vk migrate`.
+ *  2. **Migrate the database `vk dev` will actually serve.** `vk dev`
+ *     derives `<database>_<stage>` from `vk.config.ts` and ignores an
+ *     inherited `DATABASE_URL`; `vk migrate` honours it. Both therefore get
+ *     pointed at the same derived name — pick your own and you migrate one
+ *     database while the API serves another empty one.
+ *  3. **Disable crons.** Declared schedules share the single-process dev
+ *     server with the requests under test, write to the same rows the specs
+ *     assert on, and can spend real provider quota. `--no-crons` keeps them
+ *     dormant; drive the same handlers explicitly from a spec instead.
+ *
+ * Everything here is pure string/object assembly so it can be unit-tested —
+ * the assembled commands are what the regression tests assert on.
+ */
+import { type PgConnection } from '../stage-db.js';
+/**
+ * Structural mirror of Playwright's `TestConfigWebServer`.
+ *
+ * Declared locally rather than imported so this module carries no runtime
+ * dependency on `@playwright/test` and stays assignable across versions.
+ */
+export interface VkWebServerConfig {
+    /**
+     * Label for the entry. Without it, a readiness timeout reports only
+     * "Timed out waiting 180000ms from config.webServer", which is ambiguous
+     * as soon as there is more than one server.
+     * Ignored by Playwright < 1.53.
+     */
+    name?: string;
+    command: string;
+    url?: string;
+    port?: number;
+    cwd?: string;
+    timeout?: number;
+    reuseExistingServer?: boolean;
+    stdout?: 'pipe' | 'ignore';
+    stderr?: 'pipe' | 'ignore';
+    env?: Record<string, string>;
+    gracefulShutdown?: {
+        signal: 'SIGINT' | 'SIGTERM';
+        timeout: number;
+    };
+}
+/** Absolute path to the bundled database-creation script. */
+export declare function ensureDbScriptPath(): string;
+/** Env var names the bundled script reads. Also documented in bin/ensure-db.mjs. */
+export declare const ENSURE_DB_ENV: {
+    readonly name: "VK_TEST_DB_NAME";
+    readonly adminUrl: "VK_TEST_ADMIN_DATABASE_URL";
+};
+export interface VkApiServerSpec {
+    /**
+     * Workspace filter for the package holding `vk.config.ts`, e.g. `@acme/api`.
+     * The CLI must run with that package as its cwd so the config and its
+     * `.env(.local)` resolve. Supply this or `cwd`.
+     */
+    filter?: string;
+    /** Directory holding `vk.config.ts`. Used when `filter` is not set. */
+    cwd?: string;
+    /** Port for `vk dev`. */
+    port: number;
+    /** Base URL the specs use. Defaults to `http://127.0.0.1:<port>`. */
+    baseUrl?: string;
+    /** Readiness probe. Defaults to `<baseUrl>/_dev/health`. */
+    url?: string;
+    /** Run `vk migrate --seed`. On by default: E2E specs need the seed data. */
+    seed?: boolean;
+    /**
+     * Leave declared cron schedules running. Off by default — see the header.
+     * Requires `vk dev --no-crons`, i.e. @venturekit/cli >= 0.2.0.
+     */
+    crons?: boolean;
+    /** File watching. Off by default: a reload mid-run is pure flake. */
+    watch?: boolean;
+    /** Extra env for the migrate + dev processes. */
+    env?: Record<string, string>;
+    /** Command prefix used to invoke `vk`. Defaults to pnpm. */
+    execPrefix?: string;
+}
+export interface VkWebServersOptions extends PgConnection {
+    /** Stage label passed to `vk dev --stage` / `vk migrate --env`. */
+    stage: string;
+    /**
+     * Declared database name — `infrastructure.databases[].name` (or its `id`)
+     * from `vk.config.ts`. The stage suffix is added for you.
+     */
+    database: string;
+    api: VkApiServerSpec;
+    /** Additional servers (a Next.js admin, a marketing site, …). */
+    web?: VkWebServerSpec | VkWebServerSpec[];
+    /**
+     * Reuse an already-running server. Defaults to `!process.env.CI`: handy
+     * locally, never in CI where a stale server would silently serve the suite.
+     */
+    reuseExistingServer?: boolean;
+    /** Readiness timeout per server. Defaults to 180s (a cold migrate is slow). */
+    timeout?: number;
+    /** Base env for every spawned server. Defaults to `process.env`. */
+    baseEnv?: Record<string, string | undefined>;
+}
+export interface VkWebServerSpec {
+    name?: string;
+    command: string;
+    url?: string;
+    port?: number;
+    cwd?: string;
+    timeout?: number;
+    env?: Record<string, string>;
+}
+/**
+ * Build the `webServer` array for a VentureKit stack: database creation +
+ * migration + `vk dev`, followed by any extra servers.
+ *
+ * ```ts
+ * export default defineConfig({
+ *   webServer: vkWebServers({
+ *     stage: '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' },
+ *   }),
+ * });
+ * ```
+ */
+export declare function vkWebServers(options: VkWebServersOptions): VkWebServerConfig[];
+//# sourceMappingURL=web-servers.d.ts.map

package/dist/playwright/web-servers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-servers.d.ts","sourceRoot":"","sources":["../../src/playwright/web-servers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,EAAyD,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE1G;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC3B,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,gBAAgB,CAAC,EAAE;QAAE,MAAM,EAAE,QAAQ,GAAG,SAAS,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CACtE;AAED,6DAA6D;AAC7D,wBAAgB,kBAAkB,IAAI,MAAM,CAI3C;AAED,oFAAoF;AACpF,eAAO,MAAM,aAAa;;;CAGhB,CAAC;AAEX,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,qEAAqE;IACrE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,iDAAiD;IACjD,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,4DAA4D;IAC5D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,mBAAoB,SAAQ,YAAY;IACvD,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,eAAe,CAAC;IACrB,iEAAiE;IACjE,GAAG,CAAC,EAAE,eAAe,GAAG,eAAe,EAAE,CAAC;IAC1C;;;OAGG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;CAC9C;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B;AAaD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,iBAAiB,EAAE,CAqE9E"}

package/dist/playwright/web-servers.js

@@ -0,0 +1,122 @@
+/**
+ * Playwright `webServer` wiring for a VentureKit stack.
+ *
+ * Encodes the ordering constraints that are easy to get wrong and fail
+ * confusingly when you do:
+ *
+ *  1. **Create the database first.** Nothing in the CLI creates it, and
+ *     `globalSetup` is too late: Playwright starts `webServer` entries as
+ *     config plugins, and plugin setup runs before `globalSetup`. So the
+ *     creation step is chained *into* the command, ahead of `vk migrate`.
+ *  2. **Migrate the database `vk dev` will actually serve.** `vk dev`
+ *     derives `<database>_<stage>` from `vk.config.ts` and ignores an
+ *     inherited `DATABASE_URL`; `vk migrate` honours it. Both therefore get
+ *     pointed at the same derived name — pick your own and you migrate one
+ *     database while the API serves another empty one.
+ *  3. **Disable crons.** Declared schedules share the single-process dev
+ *     server with the requests under test, write to the same rows the specs
+ *     assert on, and can spend real provider quota. `--no-crons` keeps them
+ *     dormant; drive the same handlers explicitly from a spec instead.
+ *
+ * Everything here is pure string/object assembly so it can be unit-tested —
+ * the assembled commands are what the regression tests assert on.
+ */
+import { fileURLToPath } from 'node:url';
+import { stageDatabaseName, stageDatabaseUrl, adminDatabaseUrl } from '../stage-db.js';
+/** Absolute path to the bundled database-creation script. */
+export function ensureDbScriptPath() {
+    // Two levels below the package root from both `src/playwright/` and the
+    // compiled `dist/playwright/`, so the same specifier works either way.
+    return fileURLToPath(new URL('../../bin/ensure-db.mjs', import.meta.url));
+}
+/** Env var names the bundled script reads. Also documented in bin/ensure-db.mjs. */
+export const ENSURE_DB_ENV = {
+    name: 'VK_TEST_DB_NAME',
+    adminUrl: 'VK_TEST_ADMIN_DATABASE_URL',
+};
+const DEFAULT_TIMEOUT = 180_000;
+/** Drop `undefined` values so the result satisfies `Record<string, string>`. */
+function stringEnv(env) {
+    const out = {};
+    for (const [key, value] of Object.entries(env)) {
+        if (value !== undefined)
+            out[key] = value;
+    }
+    return out;
+}
+/**
+ * Build the `webServer` array for a VentureKit stack: database creation +
+ * migration + `vk dev`, followed by any extra servers.
+ *
+ * ```ts
+ * export default defineConfig({
+ *   webServer: vkWebServers({
+ *     stage: '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' },
+ *   }),
+ * });
+ * ```
+ */
+export function vkWebServers(options) {
+    const { stage, database, api } = options;
+    if (!api.filter && !api.cwd) {
+        throw new Error('@venturekit/testing: vkWebServers needs `api.filter` or `api.cwd` so the CLI runs where vk.config.ts lives.');
+    }
+    const baseEnv = options.baseEnv ?? process.env;
+    const reuseExistingServer = options.reuseExistingServer ?? !baseEnv.CI;
+    const timeout = options.timeout ?? DEFAULT_TIMEOUT;
+    const baseUrl = api.baseUrl ?? `http://127.0.0.1:${api.port}`;
+    const exec = api.execPrefix ?? (api.filter ? `pnpm --filter ${api.filter} exec` : 'pnpm exec');
+    const migrateFlags = [`--env ${stage}`, api.seed === false ? '' : '--seed'].filter(Boolean);
+    const devFlags = [
+        `--stage ${stage}`,
+        `--port ${api.port}`,
+        api.watch === true ? '' : '--no-watch',
+        api.crons === true ? '' : '--no-crons',
+    ].filter(Boolean);
+    // Chained with `&&` so a failure in creation or migration aborts the run
+    // instead of booting an API against a database that is not ready.
+    const command = [
+        `node ${JSON.stringify(ensureDbScriptPath())}`,
+        `${exec} vk migrate ${migrateFlags.join(' ')}`,
+        `${exec} vk dev ${devFlags.join(' ')}`,
+    ].join(' && ');
+    const apiServer = {
+        name: `API (vk dev --stage ${stage})`,
+        command,
+        url: api.url ?? `${baseUrl}/_dev/health`,
+        cwd: api.filter ? undefined : api.cwd,
+        reuseExistingServer,
+        timeout,
+        stdout: 'pipe',
+        stderr: 'pipe',
+        env: stringEnv({
+            ...baseEnv,
+            // Pins `vk migrate` to the database `vk dev` derives for itself.
+            DATABASE_URL: stageDatabaseUrl({ ...options, database, stage }),
+            // Read by bin/ensure-db.mjs, which runs under bare node.
+            [ENSURE_DB_ENV.name]: stageDatabaseName(database, stage),
+            [ENSURE_DB_ENV.adminUrl]: adminDatabaseUrl(options),
+            ...api.env,
+        }),
+    };
+    const extra = options.web === undefined ? [] : Array.isArray(options.web) ? options.web : [options.web];
+    return [
+        apiServer,
+        ...extra.map((spec) => ({
+            name: spec.name,
+            command: spec.command,
+            url: spec.url,
+            port: spec.port,
+            cwd: spec.cwd,
+            reuseExistingServer,
+            timeout: spec.timeout ?? timeout,
+            stdout: 'pipe',
+            stderr: 'pipe',
+            env: stringEnv({ ...baseEnv, ...spec.env }),
+        })),
+    ];
+}
+//# sourceMappingURL=web-servers.js.map

package/dist/playwright/web-servers.js.map

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

package/dist/stack.d.ts

@@ -19,6 +19,19 @@ export interface StartTestStackOptions {
     cwd?: string;
     /** Stage name — flows into the local DB name. Default `test`. */
     stage?: string;
+    /**
+     * Declared database name — `infrastructure.databases[].name` (or its `id`)
+     * from `vk.config.ts`.
+     *
+     * Set this and the harness creates `<database>_<stage>` before migrating,
+     * and pins `DATABASE_URL` to it (overriding any inherited value). Without
+     * it, nothing creates the database — a cold run then fails with
+     * `database "…" does not exist` — and an inherited `DATABASE_URL` can send
+     * `vk migrate` somewhere `vk dev` will not serve.
+     *
+     * Requires the optional peer `pg`.
+     */
+    database?: string;
     /** Port for the API server. Default `4100`. */
     port?: number;
     /** Host to build the base URL from. Default `localhost`. */
@@ -31,6 +44,13 @@ export interface StartTestStackOptions {
     seed?: boolean;
     /** Enable file watching / hot reload (usually off for tests). Default `false`. */
     watch?: boolean;
+    /**
+     * Leave declared cron schedules running. Default `false` — they share the
+     * dev server with the requests under test, write to the same rows specs
+     * assert on, and can spend real provider quota. Requires
+     * `@venturekit/cli` >= 0.2.0 for `vk dev --no-crons`.
+     */
+    crons?: boolean;
     /** Max time to wait for readiness, in ms. Default 120_000. */
     readyTimeoutMs?: number;
     /** Override the resolved `vk` binary path. */

package/dist/stack.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stack.d.ts","sourceRoot":"","sources":["../src/stack.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAOH,MAAM,WAAW,qBAAqB;IACpC,4EAA4E;IAC5E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4DAA4D;IAC5D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,mEAAmE;IACnE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,sDAAsD;IACtD,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,kFAAkF;IAClF,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,8DAA8D;IAC9D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,8CAA8C;IAC9C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,KAAK,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;CAC9B;AAED,MAAM,WAAW,SAAS;IACxB,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAoED;;GAEG;AACH,wBAAsB,cAAc,CAAC,OAAO,GAAE,qBAA0B,GAAG,OAAO,CAAC,SAAS,CAAC,CAuD5F"}
+{"version":3,"file":"stack.d.ts","sourceRoot":"","sources":["../src/stack.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AASH,MAAM,WAAW,qBAAqB;IACpC,4EAA4E;IAC5E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4DAA4D;IAC5D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,mEAAmE;IACnE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,sDAAsD;IACtD,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,kFAAkF;IAClF,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,8DAA8D;IAC9D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,8CAA8C;IAC9C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,KAAK,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;CAC9B;AAED,MAAM,WAAW,SAAS;IACxB,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAoED;;GAEG;AACH,wBAAsB,cAAc,CAAC,OAAO,GAAE,qBAA0B,GAAG,OAAO,CAAC,SAAS,CAAC,CAiE5F"}

package/dist/stack.js

@@ -17,7 +17,9 @@
 import { spawn } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
+import { ensureStageDatabase } from './ensure-database.js';
 import { waitForReady, vkDevServerReady } from './ready.js';
+import { stageDatabaseUrl } from './stage-db.js';
 /** Resolve the `vk` binary from the nearest `node_modules/.bin`, else PATH. */
 function resolveVkBin(cwd, override) {
     if (override)
@@ -98,6 +100,14 @@ export async function startTestStack(options = {}) {
     const stdio = options.stdio ?? 'inherit';
     const vk = resolveVkBin(cwd, options.vkBin);
     const env = { ...process.env, ...options.env, VENTURE_STAGE: stage };
+    // Nothing in the CLI creates the database, so do it here — before the
+    // migration that would otherwise fail on a cold machine. Pinning
+    // DATABASE_URL to the derived name keeps `vk migrate` on the database
+    // `vk dev` picks for itself.
+    if (options.database) {
+        await ensureStageDatabase({ database: options.database, stage });
+        env.DATABASE_URL = stageDatabaseUrl({ database: options.database, stage });
+    }
     // `vk dev` does NOT auto-migrate — apply schema (and optionally seeds) first.
     if (options.migrate !== false) {
         const migrateArgs = ['migrate', '--env', stage];
@@ -108,6 +118,8 @@ export async function startTestStack(options = {}) {
     const devArgs = ['dev', '--stage', stage, '--port', String(port)];
     if (options.watch !== true)
         devArgs.push('--no-watch');
+    if (options.crons !== true)
+        devArgs.push('--no-crons');
     const child = spawn(vk, devArgs, {
         cwd,
         env,

package/dist/stack.js.map

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

package/dist/stage-db.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Stage database naming + creation.
+ *
+ * `vk dev --stage <s>` and `vk migrate --env <s>` both derive their local
+ * Postgres database from the *declared database intent*, not from the
+ * environment: `<databases[].name ?? id>_<stage>`, with dashes folded to
+ * underscores so the result is a valid unquoted identifier. An inherited
+ * `DATABASE_URL` does **not** override that choice.
+ *
+ * Two consequences bite every test harness, and both are silent:
+ *
+ *  1. Point `vk migrate` at a name you picked yourself and the API will
+ *     happily serve a *different*, unmigrated database — the suite fails
+ *     with `relation "…" does not exist` rather than a connection error.
+ *  2. Nothing creates the database. `vk migrate` connects to it and fails
+ *     with `database "…" does not exist` on any cold machine or CI runner.
+ *
+ * `stageDatabaseName` mirrors the CLI's derivation so a harness never has
+ * to hardcode the name; `ensureStageDatabase` (./ensure-database.ts) closes
+ * the creation gap.
+ *
+ * Everything here is pure so it can be unit-tested — the one piece that
+ * talks to Postgres lives in its own module.
+ */
+/** Local Postgres defaults used by `vk dev`'s generated docker-compose stack. */
+export declare const LOCAL_PG: {
+    readonly host: "localhost";
+    readonly port: 5432;
+    readonly user: "postgres";
+    readonly password: "postgres";
+    /** Maintenance database — `CREATE DATABASE` cannot run inside the target. */
+    readonly maintenanceDatabase: "postgres";
+};
+export interface StageDatabaseTarget {
+    /**
+     * The declared database name — `infrastructure.databases[].name` (falling
+     * back to its `id`) from `vk.config.ts`. NOT the project name: the CLI
+     * deliberately does not prefix it.
+     */
+    database: string;
+    /** Stage label, e.g. `test`. Matches `vk dev --stage` / `vk migrate --env`. */
+    stage: string;
+}
+export interface PgConnection {
+    host?: string;
+    port?: number;
+    user?: string;
+    password?: string;
+}
+/**
+ * Derive the local Postgres database name for a declared database + stage.
+ *
+ * Mirrors the CLI's `pgName()` exactly — keep the two in step.
+ */
+export declare function stageDatabaseName(database: string, stage: string): string;
+/**
+ * True when `name` is a safe unquoted Postgres identifier. Database names
+ * reach `CREATE DATABASE` as literal DDL (they cannot be parameterized), so
+ * anything else is refused rather than escaped.
+ */
+export declare function isSafeDatabaseName(name: string): boolean;
+/** Build a Postgres URL for an arbitrary database, filling in local defaults. */
+export declare function pgConnectionString(conn: PgConnection, database: string): string;
+/**
+ * Connection string for the stage database — the one `vk dev` will serve.
+ * Point `vk migrate` and any harness-side pool at this exact URL.
+ */
+export declare function stageDatabaseUrl(target: StageDatabaseTarget & PgConnection): string;
+/**
+ * Connection string for the maintenance database, used to issue
+ * `CREATE DATABASE`.
+ */
+export declare function adminDatabaseUrl(conn?: PgConnection): string;
+/** Hide the password before a connection string reaches a log. */
+export declare function redactUrl(url: string): string;
+/**
+ * Resolve the database name from either an explicit `name` or a
+ * `database` + `stage` pair, and refuse anything unsafe as DDL.
+ *
+ * Shared by `ensureStageDatabase` so its validation is unit-testable
+ * without a live Postgres.
+ */
+export declare function resolveStageDatabaseName(options: {
+    name?: string;
+    database?: string;
+    stage?: string;
+}): string;
+//# sourceMappingURL=stage-db.d.ts.map

package/dist/stage-db.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stage-db.d.ts","sourceRoot":"","sources":["../src/stage-db.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,iFAAiF;AACjF,eAAO,MAAM,QAAQ;;;;;IAKnB,6EAA6E;;CAErE,CAAC;AAEX,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB,+EAA+E;IAC/E,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAEzE;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAExD;AAED,iFAAiF;AACjF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAM/E;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,mBAAmB,GAAG,YAAY,GAAG,MAAM,CAEnF;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,GAAE,YAAiB,GAAG,MAAM,CAEhE;AAED,kEAAkE;AAClE,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE;IAChD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GAAG,MAAM,CAgBT"}