Test a streamlet¶
Each SDK has a Harness that runs a streamlet's process over records held in memory: in Scala
com.thinkmorestupidless.ankka.flow.sdk.testkit.Harness, in Python ankka_flow.testkit.Harness. It
builds batches the way the sidecar would, one partition at a time and in offset order, applies the
protocol's rules, and records what reached each outlet, which records were skipped, and which batches
failed. There is no Kafka, no sidecar and no gRPC, so a test runs in milliseconds with the language's
own test runner: munit or any other in Scala, pytest in Python. The two harnesses have the same
members and the same rules.
Route and assert¶
test("routes by total") {
val h = Harness(new CartRouter, Map("review-threshold" -> "50"))
h.inlet("in")
.put(
event("cart-1", 10),
key = Some(bytes("cart-1")),
headers = Seq("ce_type" -> bytes("ItemAdded"))
)
h.inlet("in").put(event("cart-2", 99), key = Some(bytes("cart-2")))
h.run()
assertEquals(h.outlet("valid").records.flatMap(_.keyString), Vector("cart-1"))
assertEquals(h.outlet("review").records.flatMap(_.keyString), Vector("cart-2"))
assertEquals(
h.outlet("valid").records.head.headers.map((k, v) => k -> new String(v, UTF_8)),
Seq("ce_type" -> "ItemAdded")
)
}
def test_routes_by_total() -> None:
h = Harness(CartRouter(), config={"review-threshold": 50})
h.inlet("in").put(key=b"cart-1", value=event("cart-1", 10), headers=[("ce_type", b"ItemAdded")])
h.inlet("in").put(key=b"cart-2", value=event("cart-2", 99))
h.run()
assert [r.key for r in h.outlet("valid").records] == [b"cart-1"]
assert [r.key for r in h.outlet("review").records] == [b"cart-2"]
assert h.outlet("valid").records[0].headers == [("ce_type", b"ItemAdded")]
event is a helper in the test file that encodes a cart event as JSON bytes.
- The harness is given the streamlet and its parameter values, as the sidecar's
Startwould give them. A key the streamlet does not declare is refused; a parameter left out takes its default. inlet(name).put(...)queues a record on a declared inlet: a value, and optionally a key and headers. Naming an undeclared inlet or outlet is refused, listing the declared ones.run()processes everything queued so far. It can be called again after moreputs; offsets carry on from where they stopped.outlet(name).recordslists the records emitted to that outlet, in order, asRecordvalues.
Partitions and batch sizes¶
By default every record goes to partition 0 and each partition's records form one batch. Two arguments
to run change that, to test what a streamlet assumes about ordering:
partitionsis a function from a key to a partition number. The hash partitioner (Harness.hashPartitioner(n)in Scala,hash_partitioner(n)in Python) spreads keys overnpartitions by the CRC-32 of the key, as Kafka keeps one key on one partition. Both SDKs place a key on the same partition.- The batch size cap (
maxRecordsin Scala,max_recordsin Python) bounds a batch, so one partition's records arrive over several batches.
test("each cart stays in order") {
val h = Harness(new CartRouter)
(0 until 50).foreach { i =>
val cart = s"cart-${i % 10}"
h.inlet("in").put(event(cart, i * 5), key = Some(bytes(cart)))
}
h.run(partitions = Harness.hashPartitioner(3), maxRecords = Some(7))
assert(h.failures.isEmpty && h.skipped.isEmpty)
val everything = h.outlet("valid").records ++ h.outlet("review").records
assertEquals(everything.size, 50)
everything.groupBy(_.keyString).values.foreach { ofOneCart =>
val totals =
ofOneCart.map(r => Json.parse(r.valueString).toOption.flatMap(_.field("total")).get)
assertEquals(totals.distinct.size, totals.size)
}
}
def test_each_cart_stays_in_order() -> None:
h = Harness(CartRouter())
for i in range(50):
cart = f"cart-{i % 10}"
h.inlet("in").put(key=cart.encode(), value=event(cart, i * 5))
h.run(partitions=hash_partitioner(3), max_records=7)
assert h.failures == [] and h.skipped == []
everything = h.outlet("valid").records + h.outlet("review").records
assert len(everything) == 50
for cart in {r.key for r in everything}:
totals = [json.loads(r.value)["total"] for r in everything if r.key == cart]
assert sorted(totals) == sorted(set(totals))
The Harness runs batches one after another. It does not reproduce concurrency between partitions, rebalances or redelivery; those belong to the sidecar and are proven by the platform's own suites.
Skips and failures¶
The Harness applies the same rules as a running pipeline:
- A batch whose
processthrows or raises, or emits to an undeclared outlet, fails. Its emits are discarded and aFailure(batch, error)is added tofailures. - A record of a successful batch that no emit was derived from is added to
skipped. An emit is derived from a record when it was made from that record:outlet.emit(record), or in Scalaoutlet.emit(record.copy(...))and in Pythonoutlet.emit(record, ...). An emit built from a value alone is not, so its source record counts as skipped. batcheslists every batchprocesswas given, in order.
Assert on failures and skipped as well as on the outlets, so that a record dropped or a batch
failed by mistake does not pass unnoticed. For a Python streamlet meant to skip records it cannot
decode:
h.inlet("in").put(key=b"cart-3", value=b"not json")
h.run()
assert h.failures == [] # skipped, not raised on
assert [r.key for r in h.skipped] == [b"cart-3"]
The same test in Scala asserts h.failures.isEmpty and h.skipped.flatMap(_.keyString) ==
Vector("cart-3"). Neither cart router is such a streamlet: both fail the batch on a value that is
not JSON, so for them this test finds one failure.
Check the descriptor in CI¶
A streamlet whose committed descriptor is stale will be refused by flow verify or by the sidecar.
Run the check beside the tests:
sbt test
sbt "runMain com.thinkmorestupidless.ankka.flow.sdk.Descriptor cart.CartRouter flow/descriptor.json --check"
In the ankka-flow repository the Scala sample has the two as tasks: sbt cartRouterScala/test
cartRouterScala/descriptorCheck.
uv run pytest -q
uv run descriptor --check # exits 1 when flow/descriptor.json differs from the declaration