`internal/fixture-registry`

Purpose

This module exposes the module-level fixtureRegistry Map<string, ServiceFixture<Record<string, unknown>>> that bridges createIntegrationSetup() and the Vitest global-setup.ts entry point. It exists because Vitest's global-setup hook cannot accept arguments across the configuration boundary — so the registration step (called from vitest.config.ts) and the consumption step (called by Vitest before any test file loads) must communicate via a shared, in-process singleton.

The registry is deliberately placed under src/internal/ and is not listed in package.json exports. It is private build-system plumbing. Consumers MUST NOT import it; doing so means relying on an unstable surface that the package may rearrange without a SemVer breaking change. The public surface remains createIntegrationSetup() + globalSetup + inject(); everything in internal/ is implementation detail.

Features

Singleton Map keyed by user-chosen fixture names.
Stores the ServiceFixture<Record<string, unknown>> instances; the variant fixtures (@suaveplan/testing-integration-redis, etc.) all conform to this contract.
Mutated by createIntegrationSetup() (writes) and by global-setup.ts (reads + clear).

Usage: Basic Example

// PRIVATE — internal/* is not a published subpath. Shown for documentation only.
import { fixtureRegistry } from "./internal/fixture-registry.js";

console.log(fixtureRegistry.size);

Usage: Advanced Example

global-setup.ts snapshot the registry into a plain object so the TestEnvironment constructor receives a stable view, then clears it so re-runs in watch mode start fresh:

import { fixtureRegistry } from "./internal/fixture-registry.js";
import { TestEnvironment } from "../environment/test-environment.js";

const fixtures = Object.fromEntries(fixtureRegistry);
const env = new TestEnvironment(fixtures);
const { configs, failed } = await env.setup();
context.provide("__integration_configs__", configs);
context.provide("__integration_failed__", failed);

API Reference

fixtureRegistry: Map<string, ServiceFixture<Record<string, unknown>>> — mutable singleton, lifetime equal to the Node process. Reads and writes are not synchronised because Vitest serialises setup vs test execution.

Implementation Notes

The registry uses Record<string, unknown> rather than the precise per-fixture config because the Vitest bridge erases the type at the cross-module boundary. The strongly-typed projection is restored at the inject() call site via the InferConfig<TFixtures[K]> mapping in IntegrationSetupResult.

2.6 KiB Raw Blame History

internal/fixture-registry