Agent unit testing: exercise boundaries and repeated effects

Decision trace

What this lab demonstrates

A unit test isolates a small rule and supplies its dependencies as controlled inputs. This lab uses a synthetic agent tool boundary rather than pretending to execute ADK Java code. Four checks cover a valid argument object, a missing required field, a value just beyond a maximum, and a repeated request key. The visual run asks whether the selected assertions would reveal an injected bug. It makes a common blind spot visible: a happy-path pass says nothing about rejection behavior, boundary arithmetic, or duplicate side effects.

How to use each control

The Injected defect menu selects one deliberate bug in the fixture. Checks included sets how many assertions run, from the valid-argument case alone to all four. Press Play test run to inspect a sixty-second sequence with one card reached every fifteen seconds. Pause holds the current state. Drag the timeline to inspect a result without waiting, then use Restart for a clean comparison under unchanged inputs. A speed choice only changes viewing pace. Read the decision trace beneath the cards for each assertion and the final release decision; skipped checks are never counted as passes.

Try a controlled failure

Set Missing-field validation bug with one check included. The valid-input case passes, so the bad rejection rule escapes. Add the second check and replay: removing a required field should now make the selected assertion fail and block release. Try Off-by-one limit bug with two checks; it still escapes until Maximum-length boundary is included. Finally choose Duplicate effect on retry and compare depth three with depth four. The fourth check is the first one that makes the one-key, one-effect invariant observable. This is why a count of green tests is less useful than the behavior they cover.

What this model simplifies

The example fixtures have predetermined outcomes and no network, model, database, or clock dependency. They teach how selected assertions cover a known defect; they do not measure real code coverage or quality. In production, execute the relevant Java function with controlled fakes and assert both returned values and side effects. Boundary values should be derived from the real contract, and the idempotency test must inspect durable effects rather than relying only on a response string. Model-output quality belongs in separate evaluation datasets.

Use boundaries beyond the happy path

The unit-testing fixture separates valid arguments, a missing required field, a maximum-length boundary and a repeated request key. The first check has no defect detector in this model: a known-good input can still pass when validation or retry handling is broken. This is a coverage lesson over explicit associations between tests and faults. It does not execute the schema function, measure line coverage or prove that a real implementation enforces its contract.

Choose coverage deliberately

Injected defect selects one known fault, or a clean fixture. Checks included runs the first one, two, three or all four checks in their displayed order. This is prefix coverage, not a random sample and not a selection of arbitrary individual checks. A skipped check provides no evidence. The model uses an explicit mapping from defect identifiers to checks that detect them; it does not execute Java code, call an LLM, compile a package or infer semantic correctness. An escaped defect is visible because the simulator knows which fault you injected, whereas a real test runner would need independent evidence to discover that escape.

Reproduce a coverage gap

Choose Missing-field validation bug and include one check. The valid-arguments case passes while the injected defect escapes. Include two checks to catch it. Select Off-by-one limit bug with two checks and observe another escape; include three to exercise the boundary. Finally select Duplicate effect on retry with three checks, then include four. Only the repeated-key check detects this fault in the fixture. Keep the fault constant while changing coverage to isolate the cause of the result.

Interpret the failure boundary

A happy-path assertion is useful but cannot establish rejection behavior. The repeated-key example concerns effect conservation, not merely returning the same response twice. In a real unit test, inspect the effect ledger as well as the return value. This fixture has no concurrent requests, mutable database, clock or actual idempotency store. Its complete suite catches every listed defect because those relationships were authored explicitly; that does not establish completeness against defects that were never included.

Inspect the replay

Play starts the sixty-second inspection and becomes Pause while running. Pause holds the current stage; Restart returns to the beginning without changing the experiment settings. Speed changes viewing pace rather than model outcomes. Timeline seeks directly to a stage and pauses playback. Changing a scenario setting recomputes the deterministic fixture and rewinds it. The final decision appears at the end, so move Timeline to sixty to compare completed runs. Stage cards and the text trace describe the same selected fixture; their elapsed viewing time is not measured agent execution latency.