first commit

docs/testkit/testing/testing-integration/src/setup/global-setup.md

@@ -0,0 +1,73 @@
+# global-setup
+
+## Purpose
+
+`global-setup.ts` is the Vitest global-setup module that bridges the fixture registry populated by `createIntegrationSetup` with the test environment. It exports `setup()` and `teardown()` lifecycle hooks that Vitest calls before and after the test suite. During `setup()`, it starts all registered fixtures via `TestEnvironment` and makes their configs and failure list available to every test file through Vitest's `provide`/`inject` mechanism. This design means consumers never need to manage container startup/teardown in individual test files.
+
+## Features
+
+- **Automatic fixture orchestration** — reads from `_fixtureRegistry` (populated by `createIntegrationSetup`) and delegates to `TestEnvironment` for parallel startup and reverse-order teardown.
+- **Vitest `provide` bridge** — calls `provide("__integration_configs__", configs)` and `provide("__integration_failed__", failed)` so test files can access this data via `inject()` or the `skipIfUnavailable` helper.
+- **Graceful partial failure** — uses `TestEnvironment`'s `Promise.allSettled`-based startup so a single failing fixture does not abort the entire suite.
+- **Safe teardown** — wraps `env?.teardown()` so teardown is a no-op if `setup()` never ran (e.g. in degenerate configurations).
+- **Excluded from library build** — listed in `tsconfig.lib.json`'s `exclude` array and the Vite `external` list so it does not appear in the distributed package.
+
+## Usage: Basic Example
+
+```ts
+// vitest.config.ts
+import { createIntegrationSetup } from "@suaveplan/testing-integration/setup/create-integration-setup";
+import { redisFixture } from "./fixtures/redis.js";
+
+const { globalSetup } = createIntegrationSetup({ redis: redisFixture });
+
+export default {
+  test: {
+    globalSetup: [globalSetup], // <-- points to global-setup.js in the dist
+  },
+};
+```
+
+## Usage: Advanced Example
+
+The module is used indirectly via `createIntegrationSetup` in almost all cases. However, if you need to import it directly (e.g. for a custom global-setup wrapper), you can do so:
+
+```ts
+// custom-global-setup.ts
+import { setup as integrationSetup, teardown as integrationTeardown } from "@suaveplan/testing-integration/setup/global-setup";
+import { createIntegrationSetup } from "@suaveplan/testing-integration/setup/create-integration-setup";
+import { redisFixture } from "./fixtures/redis.js";
+
+createIntegrationSetup({ redis: redisFixture });
+
+export async function setup() {
+  await integrationSetup();
+  // additional custom setup...
+}
+
+export async function teardown() {
+  await integrationTeardown();
+  // additional custom teardown...
+}
+```
+
+## API Reference
+
+### `setup(): Promise<void>`
+
+Called by Vitest at the start of the test run.
+
+Reads all fixtures from `_fixtureRegistry`, constructs a `TestEnvironment`, calls `setup()`, then:
+
+- Calls `provide("__integration_configs__", configs)` — map of fixture key → config object.
+- Calls `provide("__integration_failed__", failed)` — array of fixture names that failed to start.
+
+### `teardown(): Promise<void>`
+
+Called by Vitest at the end of the test run. Delegates to `env.teardown()` if `env` was created. Safe to call when `setup()` was never called.
+
+## Implementation Notes
+
+The `env` variable is module-scoped rather than exported because Vitest loads global-setup modules as ES modules and re-uses the module instance between `setup` and `teardown` calls. This ensures `teardown` always references the same `TestEnvironment` that `setup` created.
+
+This file is intentionally excluded from `tsconfig.lib.json` because it imports `vitest/node` (a server-only Vitest API), which should not appear in a library's type definitions. It is still built by Vite as a separate output module because the Rollup `external` list excludes `vitest/node`, allowing it to be bundled independently and resolved at runtime.