library-testing

Library Testing

The testing doctrine for the strands-compose library (src/strands_compose/). It defines what is worth testing, what is not, and how, so the suite stays small, fast, trustworthy, and cheap to live with. It describes principles and shapes, not a file list — resolvers, providers, and orchestration modes come and go, the doctrine stays.

One sentence to internalise: a test exists to catch a real regression in behaviour, contract, or wiring — never to mirror the code, freeze its wording, or re-test strands. If a test can break when nothing a caller depends on changed, it is a liability, not an asset.

This library is a thin translator: YAML text → validated *Def data → live strands objects. That single fact decides everything below. We do not own Agent, Swarm, Graph, Model, MCPClient, or strands' hook events — so we never test them and never mock them. We test our translation: that the right config produces the right wired object, that bad config fails with the right error, and that our runtime edges (streaming, guards, manifest) behave.

Read references/test-patterns.md for the concrete, copy-paste templates (owned fakes, the resolve-seam patches, config builders, the wiring test, the contract snapshot, property tests). This file is the law; that file is the toolbox — load the toolbox only when you are actually writing a test.

---

Core Principles — NON-NEGOTIABLE

1. Test behaviour, contracts, and wiring — never implementation. Assert on what a caller observes: the type and wiring of the returned strands object, the raised error type, the emitted StreamEvent sequence, the manifest shape. Never on private methods (_on_*), private attributes (_started, _errored), mock call counts/order, log lines, or human-readable messages.
2. Never mock what we don't own. strands, Pydantic, PyYAML and MCP internals are off-limits as mock targets. Substitute a fake at our seam (a resolver, a factory) — see Mocking Policy. Hand-built MagicMock strands events are forbidden.
3. Confidence per line is the metric. Optimise for the most regressions caught per test maintained — not coverage percentage, not test count. A smaller suite people trust beats a large one they ignore.
4. A green suite means "safe to ship"; a red test means "something real broke." Anything that fails for innocuous reasons (a rename, a reorder, a reworded message) gets fixed or deleted, not tolerated.
5. Determinism is mandatory. No real network, no real model calls, no MCP subprocesses, no wall-clock waits, no sleep, no shared mutable state, no ordering assumptions. Flaky is treated as broken.
6. Tests are read more than written — favour DAMP over DRY. Each test reads top-to-bottom as a small story: arrange a config, resolve it, assert the wiring. Clarity beats cleverness and reuse.
7. Smallest reasonable test, at the lowest layer that can prove the rule. Pure transform → a unit/property test. Wiring → a resolver test. End-to-end shape → one pipeline test. Cover a rule once.