@rawsql-ts/testkit-core

Pure TypeScript utilities for rewriting SELECT statements with fixture-backed CTEs, enabling deterministic unit tests without modifying original query structure.

Features

• Validates fixture rows against declarative schemas (or registry lookups)
• Injects rewritten WITH clauses without touching the original query shape
• Uses collision-aware internal aliases for schema-qualified tables and other conflicting source names
• Supports fail-fast, passthrough, or warn-on-missing fixture strategies
• Supplies building blocks for driver adapters (see @rawsql-ts/testkit-sqlite, @rawsql-ts/testkit-postgres)

Installation

npm install @rawsql-ts/testkit-core

Quick Start

import { SelectFixtureRewriter } from '@rawsql-ts/testkit-core';

const rewriter = new SelectFixtureRewriter({
  fixtures: [
    {
      tableName: 'users',
      rows: [{ id: 1, name: 'Alice' }],
      schema: {
        columns: {
          id: 'INTEGER',
          name: 'TEXT',
        },
      },
    },
  ],
});

const { sql } = rewriter.rewrite('SELECT id, name FROM users');

When a table name needs to be rewritten into an internal alias, the alias is chosen deterministically and may shift if it collides with an existing CTE name or source alias.

CatalogExecutor Adapter

When you want to test a QuerySpec end-to-end through @rawsql-ts/sql-contract, use createCatalogRewriter() to plug fixture injection into the catalog rewriter pipeline without writing a wrapper by hand.

import { createCatalogRewriter } from '@rawsql-ts/testkit-core';
import { createCatalogExecutor } from '@rawsql-ts/sql-contract';

const rewriter = createCatalogRewriter({
  fixtures: [
    {
      tableName: 'users',
      rows: [{ id: 1, name: 'Alice' }],
      schema: {
        columns: {
          id: 'INTEGER',
          name: 'TEXT',
        },
      },
    },
  ],
  formatterOptions: { preset: 'postgres' },
});

const catalog = createCatalogExecutor({
  loader: {
    load: async () => 'SELECT id, name FROM users WHERE id = $1',
  },
  executor: async (sql, params) => {
    const result = await pool.query(sql, params);
    return result.rows;
  },
  rewriters: [rewriter],
});

Connection Strategy Provider

When your tests need to execute multiple repository calls, createTestkitProvider keeps a single backend connection open by default while isolating each scenario. The shared strategy wraps every call in a transaction so session state never leaks between fixtures.

import { createTestkitProvider } from '@rawsql-ts/testkit-core';

const provider = await createTestkitProvider({
  connectionFactory: async () => pool.connect(),
  resourceFactory: async (connection, fixtures) =>
    createPgTestkitClient({
      connectionFactory: () => connection,
      tableRows: fixtures,
    }),
});

await provider.withRepositoryFixture(fixtures, async (client) => {
  await client.query('SELECT COUNT(*) FROM public.users');
});

await provider.close();

The default configuration uses the 'shared' strategy with reset: 'transaction' — BEGIN before each scenario and ROLLBACK afterward. For tests requiring persistent schema changes (temporary tables, SET commands, etc.), use provider.perTest() or pass { strategy: 'perTest' } to create a new connection per run.

Note: createTestkitProvider manages connections and transactions exclusively for test isolation. It is not intended as a production execution model. In production code, connection lifecycle and transaction boundaries are the caller's responsibility. See the Execution Scope guide for details.

License

MIT