Org Skills

Fixtures, isolation, contracts and flaky tests

Supporting material for nodejs-testing. Agents load it on demand; it ships inside the skill folder.

RawSource

Verified 2026-09 against https://node.testcontainers.org/, https://www.prisma.io/docs/orm/more/upgrade-guides/upgrading-versions/upgrading-to-prisma-7, https://mswjs.io/docs/, https://docs.pact.io/ and https://stryker-mutator.io/docs/stryker-js/introduction/.

1. Global setup with Testcontainers and Prisma 7

// tests/global-setup.ts — runs once per test run
import { PostgreSqlContainer, type StartedPostgreSqlContainer } from '@testcontainers/postgresql';
import { execFile } from 'node:child_process';
import { promisify } from 'node:util';

const run = promisify(execFile);
let container: StartedPostgreSqlContainer;

export async function setup() {
  container = await new PostgreSqlContainer('postgres:17-alpine').start();
  process.env.DATABASE_URL = container.getConnectionUri();

  // Prisma 7 reads prisma.config.ts and does NOT auto-load .env,
  // so the URL must be in the environment of the CLI process.
  await run('npx', ['prisma', 'migrate', 'deploy'], {
    env: { ...process.env, DATABASE_URL: process.env.DATABASE_URL },
  });
}

export async function teardown() {
  await container.stop();
}

One container per run, migrations once. Starting a container per file multiplies start-up by the number of workers and is the single biggest cause of slow Node integration suites.

Redis for a BullMQ worker works the same way with @testcontainers/redis.

2. Isolation strategies

Strategy How Trade-off
Truncate between tests TRUNCATE "orders", "order_lines" RESTART IDENTITY CASCADE Works with any code, including code that opens its own transactions. Slightly slower than a rollback
Transaction per test Begin in beforeEach, roll back in afterEach, inject the transaction as the connection Fastest, but breaks as soon as the code under test manages its own transaction (which production code does)
Schema per worker search_path=test_${process.env.VITEST_POOL_ID}, migrate each on first use Real parallelism with total isolation; setup cost per worker
Database per worker One container, several databases Strongest, slowest to set up

Default to truncation; move to a schema per worker when parallel files start interfering. Whichever you pick, no test may depend on rows another test created.

// tests/setup.ts
afterEach(async () => {
  await db.$executeRawUnsafe(
    'TRUNCATE "orders", "order_lines", "outbox" RESTART IDENTITY CASCADE',
  );
});

3. Factories

// tests/factories/order.ts
import { faker } from '@faker-js/faker';

faker.seed(1234);   // deterministic: a failure reproduces

export function buildOrder(overrides: Partial<Order> = {}): Order {
  return {
    id: faker.string.uuid(),
    sku: faker.string.alphanumeric(6).toUpperCase(),
    qty: 1,
    status: 'pending',
    createdAt: new Date('2026-01-01T00:00:00Z'),
    ...overrides,
  };
}

Every field has a default; the test overrides only what it asserts on. That is what makes a test readable ("an order that is already paid") and what keeps a new required column from breaking two hundred tests.

4. Testing a BullMQ worker

import { Queue, Worker } from 'bullmq';
import { expect, it } from 'vitest';

it('marks the order as invoiced', async () => {
  const connection = { host: redisHost, port: redisPort };
  const queue = new Queue('invoices', { connection });
  const worker = new Worker('invoices', processInvoice, { connection });

  const completed = new Promise<void>((resolve) =>
    worker.once('completed', () => resolve()));

  await queue.add('invoice', { orderId });
  await completed;

  expect(await db.order.findUnique({ where: { id: orderId } })).toMatchObject({ status: 'invoiced' });

  await worker.close();
  await queue.close();
});

Await the completed event, never a sleep. Close both the worker and the queue, or the Redis connections keep the process alive and the run hangs at the end.

Test the two behaviours messaging-patterns asks for: the same job delivered twice produces one effect, and a permanent failure ends up in the failed set rather than retrying forever.

5. Contract tests

From an OpenAPI document, when one team owns both ends — cheap and catches most drift:

import { OpenApiValidator } from 'express-openapi-validator';   // or openapi-response-validator

Validate every integration-test response against the published schema, and lint the document itself in CI with Spectral (extends: ["spectral:oas"]). A response that no longer matches the document fails the build instead of a consumer.

Pact, when separate teams own consumer and provider: the consumer generates a pact from its tests, the provider verifies it against provider states in its own pipeline, and the broker's can-i-deploy gates the release. It is real infrastructure — take it on when independent deployment is real, not before.

6. Mutation testing

npm i -D @stryker-mutator/core @stryker-mutator/vitest-runner
npx stryker run

Coverage says a line ran; mutation testing says an assertion would have caught it being wrong. Point it at the domain and application code, not the whole repository, and run it on a schedule rather than per pull request — it runs the suite once per mutant. The surviving mutants are your assertion-free tests, which is exactly the list you want.

7. Flaky test triage

Symptom Likely cause Fix
"Jest did not exit" / hanging run Server, pool, Redis client or interval left open await app.close(), close pools in afterAll, .unref() intervals. Diagnose with the runner's own flag (runner-setup.md §6)
Passes alone, fails in the suite Shared rows or module-level state Truncate per test, schema per worker, restoreMocks: true
Random timeouts A missing await, a real network call, a container started per test Await everything, onUnhandledRequest: 'error', containers in global setup
Fails only in CI Time zone, locale, a slower machine, parallel database access TZ=UTC, InvariantCulture-equivalent formatting, schema per worker, no wall-clock assertions
Fails when files run in a different order Hidden ordering dependency Run with --sequence.shuffle regularly so it surfaces early
Fails right after a dependency bump A behaviour change, not flakiness Read the changelog before touching the test

Two rules keep the suite trustworthy: never add a retry to make a test green — it hides a real intermittent bug and slows every run — and give every skipped test an owner, an issue link and a date by which it is fixed or deleted.