Quickstart

This page takes you from zero to a passing Varianz test: a local registry, one instrumented function, and a test that overrides its result.

Prerequisites

Docker (to run the local registry)
One of the supported languages: Python 3.10+, Node.js 22+, Go, or JDK 17+ for Java/Kotlin
Access to the Varianz registry image (see Running the registry locally; the SDK packages need no credentials)

Run a local registry

The registry is the coordination service every SDK connects to. For local development, run it in-memory with plaintext enabled:

docker run --rm -p 50051:50051 \
  -e REGISTRY_INSECURE_PLAINTEXT=true \
  us-docker.pkg.dev/varianz-dist/registry/registry-server:v0.2.1

It logs LocalRegistry listening on http://[::]:50051 once ready. See Running the registry locally for TLS and Postgres-backed options.

Install the SDK

All Varianz packages are served from pkgs.varianz.io — no credentials needed. Pick your language:

pip install "varianz==0.2.1" "varianz-pytest==0.2.1" \
  --extra-index-url https://pkgs.varianz.io/python/simple/

echo '@varianz:registry=https://pkgs.varianz.io/npm/' >> .npmrc
npm install --save @varianz/node@0.2.1
npm install --save-dev @varianz/vitest@0.2.1

go get go.varianz.io/sdk@v0.2.1

// settings.gradle.kts
pluginManagement {
    repositories {
        maven { url = uri("https://pkgs.varianz.io/maven") }
        gradlePluginPortal()
    }
}

// build.gradle.kts
plugins { id("io.varianz.sdk") version "0.2.1" }
repositories {
    mavenCentral()
    maven { url = uri("https://pkgs.varianz.io/maven") }
}
varianz { sdkVersion.set("0.2.1") }

// build.gradle.kts — KSP must be applied before the Varianz plugin
plugins {
    id("com.google.devtools.ksp") version "2.1.10-1.0.29"
    id("io.varianz.sdk.kotlin")
}
dependencies {
    ksp("com.github.javaparser:javaparser-core:3.27.0")
}
configure<io.varianz.gradle.kotlin.VarianzKotlinExtension> {
    sdkVersion.set("0.2.1")
}

Full per-ecosystem details (Maven, Docker, platform notes) are on the Installation page.

Instrument a function

Give one function a VPoint name. The SDK derives its schema from the function’s types and registers it with the registry.

from varianz import Varianz

vz = Varianz("http://localhost:50051")

@vz.vpoint(name="pricing/calculate")
def calculate_price(amount: float, discount: float) -> float:
    return amount * (1 - discount)

vz.register(calculate_price)

import { createVPoints, initRegistry } from '@varianz/node';

initRegistry({
  endpoint: 'http://localhost:50051',
  applicationName: 'pricing-service',
});

const { instrumented } = createVPoints('pricing', {
  calculate(amount: number, discount: number): number {
    return amount * (1 - discount);
  },
});

// Call through `instrumented` so stages can intercept:
instrumented.calculate(100, 0.1);

var vz = varianz.New(varianz.WithEndpoint("http://localhost:50051"))

type PricingRequest struct {
    Amount   float64
    Discount float64
}

var CalculatePrice = varianz.VPoint(vz, "pricing/calculate",
    func(ctx context.Context, req PricingRequest) (float64, error) {
        return req.Amount * (1 - req.Discount), nil
    },
)

func main() {
    if err := vz.Init(); err != nil {
        log.Fatal(err)
    }
    defer vz.Close()
    // CalculatePrice is the instrumented function — call it normally.
}

import io.varianz.annotations.vpoint.VPoint;
import io.varianz.binding.RegistryBinding;

public class PricingService {
    @VPoint(name = "pricing/calculate")
    public double calculatePrice(double amount, double discount) {
        return amount * (1 - discount);
    }
}

// At startup, before serving traffic:
RegistryBinding.init("http://localhost:50051");
PricingService service = new PricingService();
PricingServiceVPoints.bind(service);  // generated by the annotation processor

import io.varianz.annotations.vpoint.VPoint
import io.varianz.binding.RegistryBinding

class PricingService {
    @VPoint(name = "pricing/calculate")   // named arguments required in Kotlin
    fun calculatePrice(amount: Double, discount: Double): Double =
        amount * (1 - discount)
}

// At startup:
RegistryBinding.init("http://localhost:50051")
PricingServiceVPoints.bind(PricingService())

Enable the SDK

The SDK is disabled by default — an instrumented service with no configuration behaves as if Varianz weren’t there. Clients are also secure by default: they always verify TLS unless you explicitly allow plaintext, so the second variable below is the opt-in for the local dev registry from step 1 and isn’t used in TLS setups:

export VARIANZ_ENABLED=true
export VARIANZ_INSECURE_ALLOW_PLAINTEXT=true  # local plaintext registry only

Set both variables on the service process and on the test process. On startup the SDK logs one line confirming its state, e.g. [varianz] ENABLED (source: env:VARIANZ_ENABLED).

Java and Kotlin additionally need the varianz-agent attached for interception — the Gradle/Maven plugins do this automatically for test and run tasks. See Configuration.

Override it from a test

Insert a CEL stage that replaces the function’s result, wait for the service to confirm delivery, then call the function.

# test_pricing.py — the `varianz` fixture comes from varianz-pytest
from varianz import Varianz, cel

def test_price_override(varianz):
    varianz.insert(cel("pricing/calculate", "42.0"))
    varianz.await_sync_or_fail(timeout_ms=5000)

    # In-process call: activate the session for this thread.
    # (Calls over HTTP/gRPC carry it in the x-varianz-id header instead.)
    Varianz.set_session(varianz.session_id)
    assert calculate_price(100.0, 0.1) == 42.0

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

const { test } = varianzVitest({
  endpoint: 'http://localhost:50051',
  applicationName: 'pricing-tests',
});

test('price override', async ({ varianz }) => {
  await varianz.insert(cel('pricing/calculate', '42.0'));
  await varianz.awaitSyncOrFail(5_000);

  expect(instrumented.calculate(100, 0.1)).toBe(42);
});

func TestPriceOverride(t *testing.T) {
    session := varianztest.NewSession(t, "http://localhost:50051")

    session.Insert(varianztest.Cel("pricing/calculate", "42.0"))
    session.AwaitSyncOrFail(5 * time.Second)

    // Call the service with the session ID in context:
    ctx := varianz.WithSession(context.Background(), session.SessionID())
    got, err := CalculatePrice(ctx, PricingRequest{Amount: 100, Discount: 0.1})
    if err != nil || got != 42.0 {
        t.Fatalf("got %v, err %v", got, err)
    }
}

@ExtendWith(VarianzExtension.class)
class PricingTest {
    @Test
    void priceOverride(VarianzSession session) {
        session.insert(cel("pricing/calculate", "42.0"));
        session.awaitSyncOrFail();

        // Trigger the service with session.sessionId() in the
        // x-varianz-id header / gRPC metadata, then assert.
    }
}

Run the test with your usual runner (pytest, vitest, go test, ./gradlew test). The override applies only inside this test’s session — every other caller still gets the real result.

What just happened

The VPoint made pricing/calculate interceptable without changing its behavior — see VPoints.
The CEL stage 42.0 replaced the return value for one session — see Stages and Sessions.
await_sync_or_fail blocked until the service confirmed it received the stage — see How tests work.

Next steps

Instrument a real service

Class methods, gRPC handlers, service registration, schemas.

Set up session propagation

One-time setup so the session ID flows through your whole service graph.

Override and observe

Conditional overrides, failure injection, and capturing samples.

Test across services

Multi-service flows, mixed-language harnesses.

Getting started

Core concepts

Guides

SDK reference

Testing

Reference

Prerequisites

What just happened

Next steps

Instrument a real service

Set up session propagation

Override and observe

Test across services

​Prerequisites

​What just happened

​Next steps

Instrument a real service

Set up session propagation

Override and observe

Test across services

Prerequisites

What just happened

Next steps