AI-assisted test generation

The registry’s VPoint catalog — every name, schema, and type — is machine-readable, which makes Varianz tests a natural fit for coding agents. The Varianz MCP server (varianz-mcp) exposes the catalog and generation tools over the Model Context Protocol, so agents like Claude Code can discover what’s instrumented and produce validated stages and tests.

varianz-mcp is distributed alongside the other Varianz components (like the registry server) rather than through a public package index — it’s included with your team’s Varianz distribution.

Setup

varianz-mcp is a stdio adapter that connects to the Varianz services endpoint (--services-addr, default http://[::1]:50052), which runs alongside the registry in the full Varianz stack. Register it with your agent:

{
  "mcpServers": {
    "varianz": {
      "command": "varianz-mcp",
      "args": ["--services-addr", "http://localhost:50052"]
    }
  }
}

The tools

Discovery and inspection:

Tool	Purpose
`list_vpoints`	All registered VPoints
`search_vpoints`	Semantic search over the catalog (“payment”, “things that send email”)
`get_vpoint_detail`	A VPoint’s full schema: types, fields, examples

Generation and validation:

Tool	Purpose
`generate_cel`	Produce a CEL expression for a VPoint + scenario description
`validate_cel`	Compile-check an expression against the schema before it ever runs
`suggest_overrides`	Propose useful override scenarios for a VPoint
`generate_test`	Produce a complete test (pytest, JUnit, …) for a scenario across one or more VPoints
`ask_varianz`	Free-form agent queries with session support, for multi-service reasoning

Rules for agents

If you’re pointing a coding agent at Varianz (or writing prompts for one), four rules prevent almost all failures:

Call get_vpoint_detail before writing any CEL. It shows the exact type and field names. Never guess — ChargeResult is not ChargeResponse, and struct fields are case-sensitive.
Run every expression through validate_cel before putting it in test code. Fix validation errors first; they’re cheaper than runtime failures.
Use the schema’s exact types. Missing required fields in struct literals are runtime errors.
Always include await_sync_or_fail(timeout) between stage insertion and the trigger. Without it, stages may not have reached the service.

These same rules apply to humans — the tools just make following them cheap.

What good agent output looks like

A generated test should follow the standard lifecycle — insert, sync, trigger with the session header, assert:

def test_payment_decline_blocks_email(varianz):
    varianz.insert(cel("payment/charge",
        'ChargeResult { txnId: "", declined: true }'))     # validated via validate_cel
    varianz.insert(cel("email/send-confirmation",
        'sample("email-sent", invoke())'))

    varianz.await_sync_or_fail(timeout_ms=5000)

    http = requests.Session()
    http.headers["x-varianz-id"] = varianz.session_id
    resp = http.post("http://localhost:8080/checkout", json=payload)

    assert resp.status_code == 200
    with pytest.raises(AssertionError):
        varianz.assert_sample("email-sent").within(timedelta(seconds=3)).exists()

For the underlying concepts an agent (or you) needs, the canonical pages are Stages, How tests work, and the CEL reference.

Getting started

Core concepts

Guides

SDK reference

Testing

Reference

AI-assisted test generation

Setup

The tools

Rules for agents

What good agent output looks like

​Setup

​The tools

​Rules for agents

​What good agent output looks like

Setup

The tools

Rules for agents

What good agent output looks like