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

// 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:

// 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.

3.8 KiB Raw Blame History