Initial Commit

packages/testkit/testing/testing-integration/src/internal/fixture-registry.md

@@ -0,0 +1,45 @@
+# `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
+
+```ts
+// 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:
+
+```ts
+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`.