Skip to main content
Import from the published archal package: 
import { withArchal, resetArchalClones } from 'archal/vitest';
Peer dependency: vitest >= 2.1.0. See the Vitest integration guide for setup walkthrough and the route-mode example in the repository.

​
Config helpers

​
withArchal(existingTest, options)

Merge hosted clone routing into an existing Vitest test block. Preserves coverage, alias, globals, custom reporters, and other fields you already set; appends Archal setup files, session env, and ArchalReporter. 
test: withArchal(
  { globals: true, setupFiles: ['./test/setup.ts'] },
  {
    name: 'my-suite',
    services: {
      stripe: { mode: 'route', seed: 'small-business' },
    },
  },
)
options.services: map of clone name → { mode: 'route', seed?: string }. Omit seed for the clone default. File seeds (.json / .sql) are supported. options.testIsolation: 'shared' (default) or 'serial'. Serial sets maxWorkers: 1 and fileParallelism: false.

​
archalVitestProject(options, testOptions?)

Returns a Vitest workspace project for vitest.workspace.ts. Pair with archalVitestRootConfig() in a root vitest.config.ts. 
archalVitestProject(
  { name: 'hosted', services: { github: { mode: 'route' } } },
  { include: ['__tests__/hosted/**/*.test.ts'] },
)
Do not wrap the result in defineConfig({ test: archalVitestProject(...) }). Use withArchal() for single-config projects.

​
archalVitestRootConfig()

Root-level reporters config for workspace mode. Vitest only honors reporters from the root config. 
export default defineConfig(archalVitestRootConfig());

​
archalVitestWorkspace(projects)

Typed identity wrapper for workspace project arrays. Installs workspace reporter safety checks.

​
Runtime helpers

​
resetArchalClones()

Restore every provisioned clone to its post-seed baseline and drain pending webhook queues. Call in beforeEach, not beforeAll.

​
getInstalledArchalVitestSession()

Redacted public snapshot of the active hosted session: resolved services, seeds, manifest versions. Does not expose routed auth headers.

​
getInstalledArchalVitestRuntime()

Installed NodeRouteRuntime instance (route events, manifest state). Prefer getInstalledArchalVitestSession() for most assertions.

​
bootstrapArchalVitestRouting()

Manual bootstrap entry. Normally invoked automatically via Archal setup files.

​
classifySeed(value)

Classify a seed string as { type: 'named', name } or { type: 'file', path, format }.

​
Webhook helpers

Route-mode clones queue webhook deliveries instead of POSTing to localhost.

​
waitForArchalWebhook(service, matcher, options?)

Poll until a delivery matches. matcher is an event type string or { eventType, where?, timeout?, consume? }.

​
listArchalWebhooks(service)

Snapshot pending deliveries without consuming.

​
clearArchalWebhooks(service)

Drain the service’s webhook queue.

​
ArchalReporter

Vitest reporter class. Installed automatically by withArchal() and archalVitestRootConfig(). Observes lifecycle health; legacy /api/test-results upload is retired.

​
Types

ExportDescription
ArchalVitestProjectOptions{ name?, services, testIsolation? }
ArchalVitestProjectTestOptionsVitest test overrides (include, exclude, timeouts, env, …)
ArchalVitestBuiltTestConfigShape returned by config builders
ArchalVitestPublicSessionSnapshotRedacted session snapshot type
ArchalWebhookDeliveryQueued webhook delivery shape
WaitForWebhookOptionsOptions for waitForArchalWebhook

​
Environment variables

VariablePurpose
ARCHAL_TOKENAuth for hosted session provisioning
ARCHAL_VITEST_API_URLOverride hosted API base URL
ARCHAL_VITEST_SESSION_READY_TIMEOUT_MSSession ready timeout (default 5 min)
ARCHAL_REPORTER_STRICTSet to 1 to throw on reporter warnings