Skip to main content
A session is the scope that keeps your test’s stages away from everyone else’s traffic. Stages are inserted into a session; only requests carrying that session’s ID trigger them. Two tests can override the same VPoint with different values, at the same time, against the same running services — each sees only its own behavior.

​
How it works

  1. Your test framework creates a session automatically (the pytest varianz fixture, the JUnit VarianzSession parameter, the Vitest/Playwright fixtures, Go’s varianztest.NewSession). The session ID is a 32-character hex string.
  2. The test inserts stages into the session.
  3. The test triggers the service, passing the ID in the x-varianz-id header (HTTP) or metadata key (gRPC).
  4. Inside the service, an interceptor extracts the ID and holds it in the request context; every VPoint the request touches applies that session’s stages.
  5. When the service calls other services, it forwards the header, so the session follows the request through the whole graph.
  6. When the test ends, the session is destroyed and its stages are removed automatically.
Requests without an x-varianz-id header see no stages at all — the default plan runs on a fast path. That’s what makes it safe to keep VPoints in production code.

​
Propagation is a one-time setup

Steps 4 and 5 — extracting the ID and forwarding it downstream — are a one-time setup per service, after which every future VPoint works automatically. The mechanics differ by language and framework (context vars in Python, AsyncLocalStorage in Node, context.Context in Go, a request-scoped carrier in Java), and OpenTelemetry Baggage can carry it for you if you already run OTel. Copy-paste interceptors for every supported framework are in Propagate sessions. Set this up before writing tests: a missing forwarding hop is the most common reason a stage “mysteriously” doesn’t apply.

​
Sessions synchronize before the test runs

Inserting a stage is asynchronous — services subscribed to the registry receive it a moment later. Test SDKs expose a barrier, await_sync_or_fail(timeout) / awaitSyncOrFail(timeout), that blocks until every currently-connected subscriber confirms it received your stages. Always call it between inserting stages and triggering the service. Details and edge cases (including what “0 of 0 subscribers” means) are in How tests work.

​
Security

Only test infrastructure should be able to set session IDs. At your API gateway, strip or override incoming x-varianz-id (and OTel baggage) headers from the public internet, and validate the format (32-char hex) where you accept it internally.