JUnit 5 and Kotest

The JUnit 5 integration ships as io.varianz:varianz-junit — added to testImplementation automatically by the Gradle plugin (includeJunit, default true), or explicitly with Maven (setup).

import io.varianz.junit.VarianzExtension;
import io.varianz.junit.VarianzSession;
import static io.varianz.cel.Cel.cel;

@ExtendWith(VarianzExtension.class)
class PaymentFlowTest {

    @Test
    void chargeReturnsDeterministicTxnId(VarianzSession session) throws Exception {
        session.insert(cel("payment/charge",
            "ChargeResult { txn_id: \"test-txn-001\" }"));   // camelCase becomes snake_case in CEL

        session.awaitSyncOrFail();

        // Trigger the service with the session ID in gRPC metadata
        Metadata headers = new Metadata();
        headers.put(Metadata.Key.of("x-varianz-id", Metadata.ASCII_STRING_MARSHALLER),
                    session.sessionId());
        ChargeResponse resp = blockingStub
            .withInterceptors(MetadataUtils.newAttachHeadersInterceptor(headers))
            .charge(chargeRequest);

        assertThat(resp.getTransactionId()).isEqualTo("test-txn-001");

        session.assertSample("charge-result")
            .within(Duration.ofSeconds(10))
            .hasValue("txn_id", "test-txn-001");
    }
}

Endpoint resolution, in order: explicit configuration (@VarianzTest(endpoint = "…")) → system property -Dvarianz.endpoint → environment variable VARIANZ_COORDINATOR_ENDPOINT → endpoint in varianz.toml → default http://127.0.0.1:50051. For a plaintext local coordinator the JVM also needs VARIANZ_INSECURE_ALLOW_PLAINTEXT=true (see Configuration).

VARIANZ_COORDINATOR_ENDPOINT is the only environment variable the JVM reads. There is no alias and no warning for any other spelling. A suite exporting VARIANZ_ENDPOINT falls back to http://127.0.0.1:50051, insert() returns an id, awaitSyncOrFail() passes, and every stage silently no-ops — a green run that tested nothing. If you are upgrading a suite, check this first: see Releases.

Session API

Method	Returns	Description
`sessionId()`	`String`	32-char hex session ID
`insert(Stage)`	`String`	Insert a stage, returns its ID
`insertAwaitingVpd(CelStage, timeoutMs)`	`String`	Insert, waiting up to the timeout for the target VPoint’s schema to appear, and throw if it never does. Prefer this over `insert` in CI: it is the only method that fails a test when the target VPoint was never registered — a typo’d name, a build that dropped the aggregate, or a VPoint that bricked at class-init. Plain `insert` + `awaitSyncOrFail` stays green against zero subscribers. It does not catch a duplicate name, a session lost across a coroutine hop, or a wrong endpoint
`awaitSync(timeoutMs)`	`SessionSyncResult`	Wait for subscriber confirmation
`awaitSyncOrFail()` / `awaitSyncOrFail(timeoutMs)`	`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(Duration)`, `.exists()`, `.hasValue(path, v)`
`resolveStages(vpointNames...)`	`List<StageInfo>`	Inspect which stages are attached (diagnostics)

If a test starts its own in-process gRPC server, that server still needs CoordinatorBinding.init(...) and the agent — otherwise the test is connected to the coordinator but the server isn’t, and sync reports zero subscribers.

Kotest

io.varianz:varianz-kotest provides the same lifecycle for Kotest specs — client per spec, session per leaf test:

class PricingTests : FunSpec({
    val varianz = VarianzExtension()
    extension(varianz)

    test("stage overrides price") {
        val session = varianz.session()
        session.insert(cel("pricing/calculate", """Quote { price: 999.0, currency: "USD" }"""))
        session.awaitSyncOrFail()
        // trigger + assert
    }
})

Endpoint resolution is identical to JUnit’s — the two extensions share the same client lifecycle.

Getting started

Core concepts

Guides

SDK reference

Testing

Reference

JUnit 5 and Kotest

Session API

Kotest

​Session API

​Kotest

Session API

Kotest