@venturekit/testing 0.0.20 → 0.0.22

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"}

package/dist/stage-db.js

@@ -0,0 +1,96 @@
+/**
+ * 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 const LOCAL_PG = {
+    host: 'localhost',
+    port: 5432,
+    user: 'postgres',
+    password: 'postgres',
+    /** Maintenance database — `CREATE DATABASE` cannot run inside the target. */
+    maintenanceDatabase: 'postgres',
+};
+/**
+ * Derive the local Postgres database name for a declared database + stage.
+ *
+ * Mirrors the CLI's `pgName()` exactly — keep the two in step.
+ */
+export function stageDatabaseName(database, stage) {
+    return `${database.replace(/-/g, '_')}_${stage.replace(/-/g, '_')}`;
+}
+/**
+ * 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 function isSafeDatabaseName(name) {
+    return /^[A-Za-z0-9_]+$/.test(name);
+}
+/** Build a Postgres URL for an arbitrary database, filling in local defaults. */
+export function pgConnectionString(conn, database) {
+    const host = conn.host ?? LOCAL_PG.host;
+    const port = conn.port ?? LOCAL_PG.port;
+    const user = conn.user ?? LOCAL_PG.user;
+    const password = conn.password ?? LOCAL_PG.password;
+    return `postgresql://${user}:${password}@${host}:${port}/${database}`;
+}
+/**
+ * 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 function stageDatabaseUrl(target) {
+    return pgConnectionString(target, stageDatabaseName(target.database, target.stage));
+}
+/**
+ * Connection string for the maintenance database, used to issue
+ * `CREATE DATABASE`.
+ */
+export function adminDatabaseUrl(conn = {}) {
+    return pgConnectionString(conn, LOCAL_PG.maintenanceDatabase);
+}
+/** Hide the password before a connection string reaches a log. */
+export function redactUrl(url) {
+    return url.replace(/\/\/([^:/@]+):[^@]*@/, '//$1:***@');
+}
+/**
+ * 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 function resolveStageDatabaseName(options) {
+    const name = options.name ??
+        (options.database && options.stage
+            ? stageDatabaseName(options.database, options.stage)
+            : undefined);
+    if (!name) {
+        throw new Error('@venturekit/testing: needs either `name`, or both `database` and `stage`, to resolve the stage database.');
+    }
+    if (!isSafeDatabaseName(name)) {
+        throw new Error(`@venturekit/testing: refusing to use an unsafe database name: ${name}`);
+    }
+    return name;
+}
+//# sourceMappingURL=stage-db.js.map

package/dist/stage-db.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stage-db.js","sourceRoot":"","sources":["../src/stage-db.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,iFAAiF;AACjF,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,IAAI,EAAE,WAAW;IACjB,IAAI,EAAE,IAAI;IACV,IAAI,EAAE,UAAU;IAChB,QAAQ,EAAE,UAAU;IACpB,6EAA6E;IAC7E,mBAAmB,EAAE,UAAU;CACvB,CAAC;AAoBX;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAgB,EAAE,KAAa;IAC/D,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC;AACtE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,OAAO,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACtC,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,kBAAkB,CAAC,IAAkB,EAAE,QAAgB;IACrE,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,QAAQ,CAAC,IAAI,CAAC;IACxC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,QAAQ,CAAC,IAAI,CAAC;IACxC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,QAAQ,CAAC,IAAI,CAAC;IACxC,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,QAAQ,CAAC;IACpD,OAAO,gBAAgB,IAAI,IAAI,QAAQ,IAAI,IAAI,IAAI,IAAI,IAAI,QAAQ,EAAE,CAAC;AACxE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAA0C;IACzE,OAAO,kBAAkB,CAAC,MAAM,EAAE,iBAAiB,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;AACtF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAqB,EAAE;IACtD,OAAO,kBAAkB,CAAC,IAAI,EAAE,QAAQ,CAAC,mBAAmB,CAAC,CAAC;AAChE,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,SAAS,CAAC,GAAW;IACnC,OAAO,GAAG,CAAC,OAAO,CAAC,sBAAsB,EAAE,WAAW,CAAC,CAAC;AAC1D,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,wBAAwB,CAAC,OAIxC;IACC,MAAM,IAAI,GACR,OAAO,CAAC,IAAI;QACZ,CAAC,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,KAAK;YAChC,CAAC,CAAC,iBAAiB,CAAC,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC,KAAK,CAAC;YACpD,CAAC,CAAC,SAAS,CAAC,CAAC;IAEjB,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,IAAI,KAAK,CACb,0GAA0G,CAC3G,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,iEAAiE,IAAI,EAAE,CAAC,CAAC;IAC3F,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/package.json

@@ -1,13 +1,17 @@
 {
   "name": "@venturekit/testing",
-  "version": "0.0.20",
+  "version": "0.0.22",
   "description": "Integration & end-to-end test harness for VentureKit apps — launch the local API stack, mint cognito-local users, reset the database, and drive a typed API client.",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "bin"
   ],
+  "bin": {
+    "vk-ensure-db": "./bin/ensure-db.mjs"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/venturekit-dev/venturekit.private.git",
@@ -22,6 +26,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./playwright": {
+      "types": "./dist/playwright/index.d.ts",
+      "import": "./dist/playwright/index.js"
     }
   },
   "keywords": [
@@ -33,8 +41,10 @@
   ],
   "dependencies": {},
   "peerDependencies": {
-    "@venturekit/data": "0.0.20",
-    "@aws-sdk/client-cognito-identity-provider": "^3.1091.0"
+    "@venturekit/data": "0.0.22",
+    "@aws-sdk/client-cognito-identity-provider": "^3.1091.0",
+    "@playwright/test": ">=1.40.0",
+    "pg": "^8.11.0"
   },
   "peerDependenciesMeta": {
     "@venturekit/data": {
@@ -42,12 +52,21 @@
     },
     "@aws-sdk/client-cognito-identity-provider": {
       "optional": true
+    },
+    "@playwright/test": {
+      "optional": true
+    },
+    "pg": {
+      "optional": true
     }
   },
   "devDependencies": {
-    "@venturekit/data": "0.0.20",
+    "@venturekit/data": "0.0.22",
     "@aws-sdk/client-cognito-identity-provider": "^3.1091.0",
-    "@types/node": "^26.1.0",
+    "@playwright/test": "^1.49.0",
+    "pg": "^8.13.0",
+    "@types/pg": "^8.11.10",
+    "@types/node": "^26.1.2",
     "typescript": "^5.3.0"
   },
   "scripts": {