@software-hardware-integration-lab/vitest-integration-test-harness

Vitest Integration Test Harness

Reusable Vitest fixtures for integration tests that call external services or mutate real resources. The harness provides readiness gating, resource cleanup, and failure diagnostics without imposing a cloud provider or test-suite structure.

Provider-Agnostic by Design

The package supplies mechanisms. Your application supplies everything specific to it: the profiles describing your dependencies, the credentials and how they are obtained, the clients that talk to your services, and any policy about which environments may be tested against. Nothing in this package names a vendor, and nothing in it ships a credential.

That boundary is what keeps the harness reusable across applications with completely different dependencies. See Ownership Boundary for where the line falls and how to decide which side a change belongs on.

Installation

Install this package and Vitest in the project containing your integration tests:

npm install --save-dev @software-hardware-integration-lab/vitest-integration-test-harness vitest

Usage

Use integrationTest in place of Vitest's test. The supplied fixtures are active for every test.

import { expect } from 'vitest';
import { integrationTest } from '@software-hardware-integration-lab/vitest-integration-test-harness';

integrationTest('creates and reads a widget', async ({ resources }) => {
    const widget = await resources.track(
        'example widget',
        (): Promise<Widget> => createWidget('example'),
        async (created): Promise<void> => { await deleteWidget(created.id); }
    );

    expect(await getWidget(widget.id)).toEqual(widget);
});

track creates the resource, registers its cleanup before resolving, and hands the resource back to the test body. Cleanup actions can be synchronous or asynchronous and should tolerate a resource that has already been removed.

Every test declares what it does. A test that creates nothing calls resources.markNoResources() instead; a test that does neither fails after its body passes.

That test runs with no configuration, because every environment is considered ready until a suite says otherwise.

Documentation

Full documentation lives in the wiki.

• Getting Started
• How-To Recipes
• AI-Assisted Test Authoring
• Test and Suite Lifecycle
• Resource Tracking and Cleanup
• Readiness and Environment Variables
• Environment Profiles
• Retry and Polling
• Worked example
• API Reference

Public API

Import everything from the package root. Paths under src are not a supported entry point.

Export	Kind	Purpose
integrationTest	Function	Vitest test API with automatic resource cleanup, failure diagnostics, and readiness gating.
integrationSuite	Function	Creates a test API with paired file-scoped setup and cleanup.
createSuiteRunner	Function	Attaches the file-scoped setup and cleanup lifecycle to a test API you supply.
createEnvironmentProfile	Function	Bundles environment variables, readiness checks, fixtures, and metadata into a reusable profile.
evaluateReadiness	Function	Runs readiness checks in order and returns a result containing the first failure reason, if any.
evaluateEnvironmentVariables	Function	Validates required environment variables and aggregates every failure into one reason.
retry	Function	Repeats a signal-aware operation until it succeeds, times out, hits the attempt limit, is cancelled, or shouldRetry rejects an error.
pollUntil	Function	Uses retry to repeat a signal-aware check until its value satisfies a predicate.
ResourceTracker	Class	Runs paired resource setup and cleanup, returns each resource, and cleans up in LIFO order.
ResourceCleanupError	Error class	Aggregates cleanup failures after every tracked callback has been attempted.
ResourceSetupError	Error class	Reports a failed resource setup and aborts the tracker's remaining setups.
RetryTimeoutError	Error class	Reports a retry or poll timeout with the attempt count and most recent error.
MaxRetryAttemptsReachedError	Error class	Reports that the retry attempt limit was reached before the timeout.
PollPredicateMismatchError	Error class	Holds the most recent value that did not satisfy a polling predicate.
EnvironmentReadiness	Type	A readiness result containing a boolean state and optional failure reason.
ReadinessCheck	Type	A named synchronous or asynchronous verification that returns true, false, or throws.
TestableEnvironmentVariable	Type	A required environment variable key with an optional value check.
EnvironmentVariableCheckResult	Type	The success flag and optional reason returned by a variable's check.
EnvironmentProfile	Type	A profile definition: metadata, readiness checks, variables, fixtures, tags, and readiness scope.
EnvironmentProfileResult	Type	The integrationTest, integrationSuite, and frozen profile returned by createEnvironmentProfile.
ProfileFixtures	Type	Custom fixture definitions for a profile, typed from Vitest's fixture extension API.
DependencyType	Type	Open union classifying a dependency, such as Database or BlobStorage.
RiskLevel	Type	Open union describing how a dependency's setup and teardown can affect other tests.
RetryOptions	Type	Configures retry timeout, intervals, backoff, jitter, cancellation, attempt limit, retry eligibility, and operation context.
PollResult<T>	Type	Contains a successful value of type T, attempt count, and elapsed time.
ResourceCleanupFailure	Type	A failed cleanup's resource description and error.
FailureDiagnosticsPayload	Type	Failure messages and recorded diagnostic entries emitted after a test fails.
Diagnostics	Type	Records diagnostic context, redaction rules, and failure reporters.
DiagnosticEntry	Type	A labeled diagnostic detail value.
DiagnosticRedactionRule	Type	A string or regular expression that identifies sensitive property names.
DiagnosticReporter	Type	Receives the diagnostic payload for a failed test.
IntegrationTestFixtures	Type	Fixtures supplied by integrationTest: environment, readiness gate, resources, and diagnostics.
IntegrationSuiteContext	Type	File-scoped resources available during integration suite setup.
IntegrationSuiteOptions	Type	Configures an integration suite's name and paired setup/cleanup.

ResourceTracker and createSuiteRunner are available for custom fixture composition. If you pass an external AbortSignal to the tracker's constructor, call detachAbortSignal() once the fixture lifecycle completes to remove the listener; it neither runs cleanup nor cancels tracked setup actions. Most suites should use the automatic resources and diagnostics fixtures provided by integrationTest.

Scripts

npm test
npm run lint
npm run build:Dev
npm run build:Prod

build:Dev emits JavaScript to bin. build:Prod emits JavaScript and declaration files to bin.