first commit

docs/testkit/testing/testing-integration/src/internal/skip-if-unavailable-internal.md

@@ -0,0 +1,41 @@
+# `internal/skip-if-unavailable-internal`
+
+## Purpose
+
+This module exposes `createSkipIfUnavailableWithInject()` — the dependency-injected core of the public `skipIfUnavailable()` helper. Splitting the implementation lets the public façade (`../helpers/skip-if-unavailable.ts`) hold the only `import { inject } from "vitest"` runtime call site, while unit tests exercise this factory with a fake injector and verify the behaviour without booting Vitest's `provide`/`inject` infrastructure.
+
+It lives under `src/internal/` and is deliberately omitted from `package.json` `exports`. Consumers MUST NOT import it. The public surface is `skipIfUnavailable()` from the package barrel.
+
+## Features
+
+- Generic over `TName extends string` so consumers using a typed `createIntegrationSetup` registry get key auto-completion and compile-time errors when they typo a fixture name.
+- Pluggable `injectFn` so unit tests can pass a fake without `vitest`.
+- Treats `null` / `undefined` returns from `injectFn` as the empty failed-list (no skip).
+
+## Usage: Basic Example
+
+```ts
+// PRIVATE — shown for documentation only. Use skipIfUnavailable() in app code.
+import { createSkipIfUnavailableWithInject } from "./internal/skip-if-unavailable-internal.js";
+
+const cb = createSkipIfUnavailableWithInject("redis", (key) => ["redis"]);
+cb({ skip: () => console.log("skipped") });
+```
+
+## Usage: Advanced Example
+
+The public `skipIfUnavailable()` uses Vitest's `inject` internally. When paired with a typed `createIntegrationSetup` registry, the generic preserves key safety:
+
+```ts
+import { skipIfUnavailable } from "@suaveplan/testing-integration/helpers/skip-if-unavailable";
+beforeAll(skipIfUnavailable<"redis" | "postgres">("redis"));
+// skipIfUnavailable<"redis" | "postgres">("typeo") // compile error — typo caught
+```
+
+## API Reference
+
+- `createSkipIfUnavailableWithInject<TName extends string>(fixtureName, injectFn)` — returns `(ctx: { skip: () => void }) => void`. The returned callback reads the failed-fixture list via `injectFn("__integration_failed__")` and calls `ctx.skip()` if `fixtureName` is in it.
+
+## Implementation Notes
+
+The cast `null as unknown as string[]` in tests verifies the `?? []` guard. Production callers never pass a function that returns `null`, but Vitest's `inject` typing is loose, so the guard is load-bearing in real-world consumers.