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.

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.

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

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.

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

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

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.

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.