feat(assert): Accept a status class, list or range in --assert-status

[korya]

Problem

Asking "did this request succeed" took either one run per acceptable status code or --assert-ok, which also passes on a 3xx.

--assert-status accepted exactly one integer, so a caller who meant any 2xx, either 200 or 204, or anything in 401-403 had no way to say it.

Separately, the flag accepted codes no response can carry. --assert-status 1000 exited 93 — the code that means the service answered and was wrong — when the real problem was a typo in the command line (#93).

Solution

Accept a spec instead of a code: a class, an inclusive range, a comma-separated list, or any mix of them.

$ http-assert --assert-status 2xx          https://example.com    # any 200-299
$ http-assert --assert-status 200,204      https://example.com    # either
$ http-assert --assert-status 401-403      https://example.com    # any of three
$ http-assert --assert-status 301,2xx,500-503 https://example.com # mixed

Every form reduces to a set of inclusive ranges, so one matcher serves all of them and an exact code is simply a range of one. The failure quotes the spec as written:

- status: expected 2xx, got 404 ("404 Not Found")

expected 2xx is the question the caller asked; expected 200-299 would be an answer they have to translate back.

The flag moves from int to string, which is what lets it carry the other forms. Nothing else about it changes — still single-valued, still command-line only, and an exact code behaves and reads exactly as it did.

#93's premise was wrong, and the plan changed because of it

#93 asks to reject "codes that can never match (-1, 999)" by bounding to 100-599. A probe says otherwise:

code 599   OK: client saw 599        code 0     server REFUSED: invalid WriteHeader code 0
code 600   OK: client saw 600        code 99    server REFUSED: invalid WriteHeader code 99
code 999   OK: client saw 999        code 1000  server REFUSED: invalid WriteHeader code 1000

A server can send 6xx-9xx and net/http reports them faithfully, so an assertion about one is answerable. Implementing the ticket as written would have made real responses unassertable. The bound enforced here is 100-999 — what a response can actually carry — so -1, 1000 and 099 exit 71 while 999 remains a legitimate assertion.

1xx and 6xx-9xx classes parse for the same reason and are deliberately not documented: answerable, but not useful, and advertising them would suggest otherwise.

Verification

Unit tests cover 12 accepted specs against matching and non-matching codes, and 17 rejected ones against the message each should produce. E2E covers every form end to end plus rejection before any request is made.

Mutation-checked — each of these fails the suite:

Mutation	Caught
range end exclusive instead of inclusive	✅
class spans 200 codes instead of 100	✅
out-of-range codes accepted	✅
reversed range accepted	✅

Manually verified against live endpoints: 2xx, 4xx, 404,410 and 400-499 against real 200 and 404 responses, plus 999 still assertable and 1000 still rejected.

Other Changes

• Failure.Expected for a status assertion is now the spec text rather than an int. No consumer exists yet (Feature: machine-readable output (--json) #45 is unbuilt); a type that varied by form would be worse for a future JSON consumer than one that is always a string.
• assertions_test.go used AssertStatusEqual(1) as its never-matching case; 1 is no longer expressible, so it is now 599.
• No visual change — CLI only.

Closes #93

🤖 Generated with Claude Code