42 lines
2.3 KiB
Markdown
42 lines
2.3 KiB
Markdown
# `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.
|