> ## Documentation Index
> Fetch the complete documentation index at: https://docs.archal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# archal/vitest SDK

> API reference for the archal/vitest subpath: config helpers, runtime getters, webhook utilities, and types.

Import from the published `archal` package:

```ts theme={null}
import { withArchal, resetArchalClones } from 'archal/vitest';
```

Peer dependency: `vitest >= 2.1.0`. See the [Vitest integration guide](/guides/vitest)
for setup walkthrough and the [route-mode example](https://github.com/Archal-Labs/archal/tree/main/examples/vitest-route-mode)
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`.

```ts theme={null}
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`.

```ts theme={null}
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.

```ts theme={null}
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

| Export                              | Description                                                    |
| ----------------------------------- | -------------------------------------------------------------- |
| `ArchalVitestProjectOptions`        | `{ name?, services, testIsolation? }`                          |
| `ArchalVitestProjectTestOptions`    | Vitest test overrides (`include`, `exclude`, timeouts, env, …) |
| `ArchalVitestBuiltTestConfig`       | Shape returned by config builders                              |
| `ArchalVitestPublicSessionSnapshot` | Redacted session snapshot type                                 |
| `ArchalWebhookDelivery`             | Queued webhook delivery shape                                  |
| `WaitForWebhookOptions`             | Options for `waitForArchalWebhook`                             |

## Environment variables

| Variable                                 | Purpose                                  |
| ---------------------------------------- | ---------------------------------------- |
| `ARCHAL_TOKEN`                           | Auth for hosted session provisioning     |
| `ARCHAL_VITEST_API_URL`                  | Override hosted API base URL             |
| `ARCHAL_VITEST_SESSION_READY_TIMEOUT_MS` | Session ready timeout (default 5 min)    |
| `ARCHAL_REPORTER_STRICT`                 | Set to `1` to throw on reporter warnings |