Vitest integration

Use archal/vitest when you want hosted clones inside an existing Vitest suite. Your tests keep using normal SDK clients; Archal supplies the clone session and routes supported service traffic during the test run. For the full API surface, see the archal/vitest SDK reference. For a runnable Stripe route-mode project, see examples/vitest-route-mode in the repository.

archal/vitest needs an auth token. Run archal login locally, or set ARCHAL_TOKEN in CI. For CI, use a workspace API key (archal_ws_...); for local dev, archal login works too. The first hosted session takes about 30 seconds; later runs within the TTL reuse it.

Install

pnpm add -D vitest archal
archal login

In CI, set ARCHAL_TOKEN instead of running archal login. Use a workspace API key (archal_ws_...). See the CI integration guide for full details. Route mode supports Discord, GitHub, Google Workspace, Jira, Linear, Ramp’s primary API domain, Slack, Stripe, and Supabase.

Add Archal to your existing `vitest.config.ts`

If your project already has a vitest.config.ts, wrap test: with withArchal. It preserves your existing test config and adds Archal’s setup, and session env.

import { defineConfig } from 'vitest/config';
import { withArchal } from 'archal/vitest';

export default defineConfig({
  test: withArchal(
    {
      // everything you already had in test:, unchanged
      globals: true,
      setupFiles: ['./test/my-setup.ts'],
      coverage: { provider: 'v8' },
    },
    {
      services: {
        github: { mode: 'route', seed: 'small-project' },
        stripe: { mode: 'route' },
      },
    },
  ),
});

If you’re starting from scratch, pass {} as the first argument: withArchal({}, { services: { ... } }).

Or add a separate project in `vitest.workspace.ts`

For monorepos or when only a subset of tests should hit clones, use a workspace:

// vitest.workspace.ts
import { archalVitestProject } from 'archal/vitest';

export default [
  './vitest.config.ts', // your existing unit-test project untouched
  archalVitestProject(
    {
      name: 'hosted-clones',
      services: {
        github: { mode: 'route', seed: 'small-project' },
        stripe: { mode: 'route' },
      },
    },
    { include: ['__tests__/hosted/**/*.test.ts'] },
  ),
];

Only tests matching the include glob will provision hosted clones; the rest run as normal Vitest.

Write a test

Your test code uses normal SDK clients or direct HTTP calls. Route mode redirects supported service traffic to clones, so there is no SDK mock or base URL setup.

import { Octokit } from '@octokit/rest';
import { describe, it, expect } from 'vitest';

describe('issue triage', () => {
  it('creates and labels an issue', async () => {
    // route mode redirects api.github.com calls to the clone automatically
    const github = new Octokit();
    const { data: issue } = await github.issues.create({
      owner: 'acme',
      repo: 'webapp',
      title: 'Bug report',
    });
    expect(issue.title).toBe('Bug report');
  });
});

First run takes about 30 seconds. Subsequent runs reuse the cached session.

Seeds

Seeds control starting state. Omit seed: for the default state, or pass a named seed such as small-project. See Seeds.

Reset state between tests

import { beforeEach } from 'vitest';
import { resetArchalClones } from 'archal/vitest';

beforeEach(async () => {
  await resetArchalClones();
});

This restores each clone to its post-seed state and drains the webhook queue. No cold-start - it’s a local state snapshot reapplied to the existing session.

Inspect the session

If you need to check which services, seeds, or versions the backend resolved:

import { getInstalledArchalVitestSession } from 'archal/vitest';

const session = getInstalledArchalVitestSession();
console.log(session?.resolvedRuntime.resolvedServices);
console.log(session?.resolvedRuntime.resolvedSeeds);

Troubleshooting

Real API responses instead of clone responses - your test file isn’t matched by the project’s include glob.
401 at setup - ARCHAL_TOKEN isn’t set (or archal login wasn’t run).
Test hangs for 30+ seconds on first run - that’s the ECS cold-start, not a hang.
Reset isn’t working - call resetArchalClones() in beforeEach, not beforeAll.
CI credential race - when multiple jobs run in parallel, export ARCHAL_TOKEN directly instead of relying on ~/.archal/credentials.json.

Start here

Test agents

Run anywhere

Advanced

Vitest integration

Install

Add Archal to your existing `vitest.config.ts`

Or add a separate project in `vitest.workspace.ts`

Write a test

Seeds

Reset state between tests

Inspect the session

Troubleshooting

​Install

​Add Archal to your existing vitest.config.ts

​Or add a separate project in vitest.workspace.ts

​Write a test

​Seeds

​Reset state between tests

​Inspect the session

​Troubleshooting

Install

Add Archal to your existing `vitest.config.ts`

Or add a separate project in `vitest.workspace.ts`

Write a test

Seeds

Reset state between tests

Inspect the session

Troubleshooting