Skip to content
VentureKit

@venturekit/testing

@venturekit/testing owns the hard, framework-specific plumbing for integration and end-to-end tests so your project only has to write the actual scenarios (selectors, flows, assertions). It is UI-framework agnostic — pair it with Playwright, Cypress, or plain vitest.

Installation

Section titled “Installation”

It’s a dev dependency (once published):

Terminal window
pnpm add -D @venturekit/testing

Two peers are optional — install them only if you use the matching helpers:

Terminal window
# truncate* DB helpers
pnpm add -D @venturekit/data


# signInWithPassword / loginAs (mint real JWTs)
pnpm add -D @aws-sdk/client-cognito-identity-provider

What It Provides

Section titled “What It Provides”

Launch a real local stack

Section titled “Launch a real local stack”

startTestStack() runs vk migrate then vk dev, waits until the server is ready, and hands back a handle with a stop() for teardown:

import { startTestStack, type TestStack } from '@venturekit/testing';


const stack: TestStack = await startTestStack({ port: 4100, seed: true });
// stack.baseUrl, stack.port, await stack.stop()

By default it targets stage test (a separate <dbname>_test database) so tests never clobber your vk dev data. Pass migrate: false to skip the migration step, seed: true to also run seeds.

Gate on readiness

Section titled “Gate on readiness”

waitForReady() polls the dev server’s /_dev/health probe — the same liveness endpoint vk tooling uses. vkDevServerReady asserts the response really is a vk dev server:

import { waitForReady } from '@venturekit/testing';


await waitForReady({ baseUrl: 'http://localhost:4001' });

Drive the API with a typed client

Section titled “Drive the API with a typed client”

createApiClient() is a typed fetch wrapper that understands VentureKit’s { data } / { error } envelope: it unwraps the success payload and throws a typed ApiError on any non-2xx response.

import { createApiClient, ApiError } from '@venturekit/testing';


const api = createApiClient({ baseUrl: stack.baseUrl, token: idToken });
const res = await api.get<{ slug: string }>('/tenant');
// res.status, res.data.slug

Seed cognito-local users

Section titled “Seed cognito-local users”

createTestUser() provisions a cognito-local user with a permanent password over the vk dev admin API (no AWS SDK needed). It is idempotent:

import { createTestUser, setTestUserAttributes, deleteTestUser } from '@venturekit/testing';


await createTestUser({
  baseUrl: 'http://localhost:4001',
  email: 'admin@example.com',
  password: 'Passw0rd!',
  attributes: { tenantId: 'global' },
});

getDevPools() inspects the local user pools.

Mint real JWTs

Section titled “Mint real JWTs”

For API-level tests, loginAs() (and the lower-level signInWithPassword()) mint real Cognito tokens for a seeded user. These require the optional @aws-sdk/client-cognito-identity-provider peer:

import { loginAs } from '@venturekit/testing';


const { idToken } = await loginAs({
  baseUrl: stack.baseUrl,
  email: 'admin@example.com',
  password: 'Passw0rd!',
});

Reset the database

Section titled “Reset the database”

truncateAllTables() clears app tables between specs while preserving the VentureKit migration/seed bookkeeping tables. Requires @venturekit/data and the same DATABASE_URL / DB_* env the app uses:

import { truncateAllTables, truncateTables, listTables } from '@venturekit/testing';


await truncateAllTables();              // everything except __vk_migrations / __vk_seeds
await truncateTables(['posts', 'tags']); // a specific subset

Pure SQL builders

Section titled “Pure SQL builders”

The truncation logic is exposed as pure, dependency-free functions for reuse and unit testing:

import {
  buildTruncateSql,
  filterTruncatableTables,
  quoteIdent,
  VK_TRACKING_TABLES,   // ['__vk_migrations', '__vk_seeds']
} from '@venturekit/testing';

API Reference

Section titled “API Reference”
ExportPurpose
startTestStack(opts)Migrate + boot vk dev; returns { baseUrl, port, stop() }.
waitForReady(opts) / vkDevServerReadyPoll until ready (default /_dev/health); assert the vk discriminator.
createApiClient(opts) / buildUrlTyped fetch client; unwraps { data }, throws ApiError on non-2xx.
ApiErrorError class carrying status, code, message, and details from the VK error envelope.
createTestUser(opts)Idempotently create a cognito-local user with a permanent password.
setTestUserAttributes / deleteTestUser / getDevPoolsManage cognito-local users / inspect pools.
signInWithPassword(opts) / loginAs(opts)Mint real JWTs for a user (needs the Cognito SDK peer).
truncateAllTables(opts) / truncateTables / listTablesReset the DB between specs (needs @venturekit/data).
buildTruncateSql / filterTruncatableTables / quoteIdent / VK_TRACKING_TABLESPure SQL builders (reusable / testable).

Full types are exported alongside each function (e.g. TestStack, ApiClient, WaitForReadyOptions, CreateTestUserInput, TokenSet, TruncateOptions).

Requirements

Section titled “Requirements”
  • Docker — the local stack uses containerised Postgres / MinIO / cognito-local.
  • @venturekit/data (optional peer) — only for the truncate* / listTables helpers.
  • @aws-sdk/client-cognito-identity-provider (optional peer) — only for signInWithPassword / loginAs.
Section titled “Related”