livetest

A binary that points kaas-lib at a real Kafka cluster — shared, long-lived, not ours, running a build we did not choose, holding data produced by clients we did not write.

publish = false.

Not a replacement for the container acceptance suite, which owns the cases needing a broker configured a particular way, killed mid-request, or fed a damaged log segment. This is the other half: the cases that only appear when the cluster is somebody else's.

Module map

Four commands

livetest probe    # read-only inventory + version table. Touches nothing.
livetest smoke    # admin round trip, prefixed resources only
livetest read     # scan and tail, asserting the decoder against real data
livetest sweep    # delete anything this tool left behind

probe is a conformance check in disguise

Its output is a sorted, diffable report. Run it against two clusters and diff the results, and you have a typed parity check — which is exactly the conformance-harness idea made concrete. Point it at kaas and at Apache Kafka and the diff is the answer.

Notes go to stderr and facts go to stdout, so livetest probe > out.txt captures exactly the diffable body and nothing else.

The report comes first, even on failure

struct Outcome; 
fn emit(outcome: Outcome) {
    // notes to stderr, facts to stdout, then the pass/fail result
}

A partial report says how far the run got and what the cluster looked like on the way, which is the entire diagnostic value. A failure that discards what it learned before failing is a stack trace, and a stack trace from a protocol mismatch against a cluster you cannot attach a debugger to is worth very little.

read ranks topics by record count, so a run against a production-shaped cluster reads the topics most likely to exercise the decoder rather than whichever five sort first alphabetically.

Everything is namespaced and swept

Every resource livetest creates carries a prefix (kaaslib-live by default), and sweep refuses to touch a name without it. Running a tool that creates topics against a shared cluster is only acceptable if cleanup is mechanical and cannot over-reach.

KAAS_TEST_READ_ONLY=1 turns on the read-only gate and the target then refuses any operation that would need to create something, with a clear error naming the environment variable rather than a permission failure from the broker.

Configuration

The live-cluster skill resolves all of these from Kubernetes — see Testing against a real cluster.

Start reading at target.rs, which is where a cluster stops being an environment variable and becomes a configured Cluster.