Vitest

Install @varianz/vitest (instructions) and wire it up once:

// test/setup.ts
import { varianzVitest } from '@varianz/vitest';

export const { test } = varianzVitest({
  // endpoint omitted: falls back to VARIANZ_COORDINATOR_ENDPOINT, then the
  // deprecated VARIANZ_TEST_ENDPOINT / VARIANZ_COORDINATOR_ADDR / VARIANZ_ENDPOINT
  // (each with a one-time warning), then varianz.toml, then http://127.0.0.1:50051
  applicationName: 'my-service-tests',
});
export { describe, expect, beforeAll } from 'vitest';
export { cel } from '@varianz/vitest';

The re-exports above are deliberate. @varianz/vitest exports varianzVitest, cel and the matchers — not test or expect. Take test from varianzVitest({...}) and expect / describe from vitest itself. The example inside the package’s own shipped fixture.d.ts JSDoc says import { test, expect, cel } from "@varianz/vitest"; that line is wrong and does not resolve.

If your tsconfig has declaration: true — the default for anything emitting .d.ts — this snippet fails to compile:

test/setup.ts(8,16): error TS2742: The inferred type of 'test' cannot be named without a
reference to '../node_modules/@varianz/vitest/dist/fixture.js'. This is likely not portable.
A type annotation is necessary.

Exclude the test tsconfig from declaration emit ("declaration": false), which is what you almost certainly want for tests anyway.

// vitest.config.ts
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    setupFiles: ['@varianz/vitest/setup'],  // installs the custom matchers
    fileParallelism: false,                 // initCoordinator is process-global
  },
});

Run with the standard environment (VARIANZ_ENABLED=true, and VARIANZ_INSECURE_ALLOW_PLAINTEXT=true for a plaintext local coordinator) — the fixture throws a clear error if the SDK is disabled.

Writing tests

import { test, expect, cel, describe } from './setup.js';
import { PricingService } from '../src/service.js';

describe('pricing', () => {
  test('bulk discount applies at 10+', async ({ varianz }) => {
    await varianz.insert(cel(
      'pricing/calculate',
      'args.input.quantity >= 10 ' +
        '? PricingResult { totalPrice: args.input.basePrice * args.input.quantity * 0.9, discountApplied: true } ' +
        ': invoke()',
    ));

    await varianz.awaitSyncOrFail(5_000);

    // The fixture has already entered the session scope for the test body —
    // in-process calls match session stages without extra wiring.
    const out = new PricingService().calculate(input);

    expect(out.totalPrice).toBeCloseTo(108);
    await expect(varianz).toEventuallyHaveSample('price-result', { within: 5_000 });
  });
});

Fixtures:

varianz — per-test VarianzTestSession. It installs a session-ID fallback in AsyncLocalStorage for the whole test body, so in-process VPoint calls match your stages automatically.
varianzClient — worker-scoped client for advanced coordinator assertions (most tests don’t need it).

Custom matchers

Installed by the @varianz/vitest/setup file:

await expect(varianz).toEventuallyHaveSample('price-result', { within: 5_000 });
await expect(varianz).toHaveSampleValue('price-result', 108, { path: 'totalPrice', within: 10_000 });

Session API

Method / property	Returns	Description
`sessionId`	`string`	32-char hex session ID (for `x-varianz-id` when triggering over the network)
`insert(stage, anchor?)`	`Promise<string>`	Insert a CEL stage
`awaitSync(timeoutMs?)`	`Promise<SessionSyncResult>`	Wait for subscribers
`awaitSyncOrFail(timeoutMs?)`	`Promise<void>`	Wait; throw on timeout only — validation issues are advisory and do not fail the barrier (why); see zero-subscriber semantics
`assertSample(ident)`	`SampleAssert`	Fluent chain: `.within(ms)`, `.exists()`, `.hasCount(n)`, `.hasValue(path, v)`
`getSamples()`	`Record<string, unknown>[]`	Raw buffered samples

Concurrency

In describe.concurrent / it.concurrent blocks, the module-level session fallback is last-write-wins and races under true parallelism. Re-establish the scope locally:

await varianz.run(() => service.calculate(input));

And keep fileParallelism: false — the native initCoordinator binding can only initialize once per process.

Getting started

Core concepts

Guides

SDK reference

Testing

Reference

Writing tests

Custom matchers

Session API

Concurrency

​Writing tests

​Custom matchers

​Session API

​Concurrency

Writing tests

Custom matchers

Session API

Concurrency