refactor(assert): Give assertions a kind and failures their parts

[korya]

Problem

A monitoring agent that wants to know which assertion failed has to parse English, because a failure is only ever a sentence.

Assertion is a func(*httpResponse) error, so everything a consumer might want — which check ran, what it wanted, what it got — exists solely inside a formatted string. That is why --json (#45) has been blocked: there is nothing to serialize.

The error return also conflates two answers that are not the same:

The response was read and disagreed	The assertion could not be evaluated
body: expected "zzz", got "boom"	body: response is br-encoded and was not decoded
jq[.n == 1]: expected true, got false	jq[.n == 1]: <gojq runtime fault>

"The service is wrong" and "we could not tell" are different operational conclusions, and today nothing downstream can distinguish them.

Note that this ticket's other half — making the pattern constructors return errors instead of panicking — shipped in 4d5dc06 three hours after #56 was filed, as part of closing #17. The ticket body has been rewritten to match.

Solution

Make Assertion an interface whose Check returns the failure's parts, not just its prose.

Before:

type Assertion func(res *httpResponse) error

After:

type Assertion interface {
	Kind() string                              // "ok", "nok", "status", "header", "body", "redirect", "jq"
	Check(res *httpResponse) (*Failure, error) // (nil, nil) when it holds
}

type Failure struct {
	Kind, Target   string
	Expected, Actual any
	Message        string
}

(nil, nil) holds, (*Failure, nil) disagreed, (nil, error) could not be evaluated. Both failure paths still collect into one list in doOnce and still exit 93 — the split is for #45, not for the exit codes.

No output changes, and that is checked rather than asserted

Both binaries were run against thirteen failing scenarios covering all seven kinds, and the output diffed:

IDENTICAL — 13 scenarios, every failure message and exit code byte-for-byte equal

The twelve distinct messages compared include every shape that does not decompose into expected/actual — header[X-Missing]: expected to match ".*", missing, redirect: wrong HTTP status: got 500 (…), jq[.missing]: expected true, got null. The end-to-end suite passes unchanged, which is the same check enforced in CI.

Two deliberate choices

Failure keeps Message rather than deriving it. Sentences like expected to be non-empty, got nothing and expected OK, got 500 ("500 Internal Server Error") do not reconstruct from Expected and Actual. A formatter that tried would drift the first time a wording changed, and the drift would surface as a failing end-to-end test rather than a compile error. The parts and the prose are written together, at the same site, and neither derives from the other.

Constructors stay closures behind a small adapter instead of becoming thirteen one-method structs — the functional style is what keeps each one readable as a single expression, and only the result ever needed structure. Check stamps the kind onto the failure, so Kind() and Failure.Kind cannot drift apart and no constructor repeats itself.

Other Changes

• The redirect precondition (wrong status / no Location) is now shared by both redirect assertions, which is what keeps their wording identical rather than merely equal today.
• Tests gain a check(a, res) helper flattening the two returns to the single error the existing tables compare against, so those tables are otherwise untouched.
• No new end-to-end test. This change is behaviour-preserving, and the one invariant it could have broken — an undecodable body failing the body assertions with exit 93 while status and header assertions still pass — is already covered end-to-end and passes unchanged.
• No visual change; this is a CLI with no rendered UI.

Related:

• Give assertions a structured result instead of an opaque error #56
• Feature: machine-readable output (--json) #45

🤖 Generated with Claude Code