first commit

docs/testkit/testing/testing-integration/src/internal/create-integration-setup-internal.md

@@ -0,0 +1,49 @@
+# `internal/create-integration-setup-internal`
+
+## Purpose
+
+This module exposes `createIntegrationSetupWithInject()` — the dependency-injected core of the public `createIntegrationSetup()` factory. Splitting the implementation into a wired core plus a thin public facade keeps the `vitest` runtime import isolated to one file (`../setup/create-integration-setup.ts`) and lets the unit tests cover the registration / inject hand-off without booting Vitest's global-setup machinery.
+
+It is deliberately under `src/internal/` and not listed in `package.json` `exports`. Consumers MUST NOT import it; the public contract is `createIntegrationSetup()` from the package barrel. Tests in this package import this module directly because they own the implementation; downstream packages do not.
+
+## Features
+
+- Generic over the fixture map; preserves precise per-fixture config types end-to-end via `InferConfig`.
+- Pluggable `injectFn` so unit tests can verify the indirection through Vitest's `inject` without importing `vitest` from the test file under inspection.
+- Side-effect: mutates `fixtureRegistry` so the Vitest global-setup module sees the fixtures at boot.
+
+## Usage: Basic Example
+
+```ts
+// PRIVATE — shown for documentation only. Use createIntegrationSetup() in app code.
+import { createIntegrationSetupWithInject } from "./internal/create-integration-setup-internal.js";
+
+const { globalSetup, inject } = createIntegrationSetupWithInject(
+    { redis: redisFixture },
+    (key) => ({ redis: { url: "redis://injected" } })
+);
+```
+
+## Usage: Advanced Example
+
+The public `createIntegrationSetup` (in `../setup/create-integration-setup.ts`) is exactly this with Vitest's real `inject` wired in:
+
+```ts
+import { inject as vitestInject } from "vitest";
+import { createIntegrationSetupWithInject } from "../internal/create-integration-setup-internal.js";
+
+export function createIntegrationSetup<TFixtures>(fixtures: TFixtures) {
+    return createIntegrationSetupWithInject(
+        fixtures,
+        vitestInject as (key: string) => Record<string, Record<string, unknown>>
+    );
+}
+```
+
+## API Reference
+
+- `createIntegrationSetupWithInject<TFixtures>(fixtures, injectFn)` — returns `{ globalSetup: string; inject: <K extends keyof TFixtures>(key: K) => InferConfig<TFixtures[K]> }`. Writes every entry of `fixtures` into the shared `fixtureRegistry`.
+
+## Implementation Notes
+
+Resolves the global-setup path via `new URL("../setup/global-setup.js", import.meta.url).pathname`. This path is what consumers feed into `test.globalSetup` in their `vitest.config.ts`; using `import.meta.url` makes the reference robust to workspace layout differences.