Test Slice Boundaries

## What "calling the handler directly" means In most server-side web frameworks a **handler** is the function the framework invokes once it has decided that an incoming request belongs to a particular route. Testing it directly means the test calls that function itself: it constructs whatever the function declares — a request value, an already-decoded body object, path or query values, some context — and asserts on the value returned or the exception raised. Nothing framework-shaped happens. No route table is built, no hook or middleware chain runs, no body is decoded from bytes, no response is serialised, and no status line is produced. The handler is a function, and the test treats it as one. ## What it genuinely proves - **Branch logic**: every conditional path through the body, including the ones that are awkward to trigger over HTTP. - **Domain-level error behaviour**: that a missing entity leads to whatever the body does about it — raising, returning an error value, or returning an empty result. - **Collaboration**: that the handler calls its dependencies with the arguments you expect, in the order you expect, and does not call them when it should not. - **The returned value's shape**, as the handler sees it — not as the client sees it, which is a different thing. Because there is no startup, the cost is the cost of a function call. That property is the whole point of the tier: you can afford hundreds of cases, run them on every keystroke, and keep them deterministic. ## What it assumes rather than tests Everything the framework would have done sits outside the call, and each of those steps is a real source of defects: 1. **Route registration** — the path template, the method, and which of several overlapping routes wins. 2. **Binding** — decoding the body, mapping query and path values, type conversion, defaults for absent values, and whatever declarative validation runs before the body is entered. 3. **The hook chain** — anything the chain contributes or short-circuits before and after the handler. 4. **Response mapping** — how the returned value becomes a status code, which headers are attached, and how the payload is serialised, including field naming and omitted nulls. 5. **Wiring** — the handler under test received the collaborators the *test* chose, not the ones a real graph would have supplied. | Fault | Caught by a direct handler call? | |---|---| | Wrong branch or comparison inside the body | Yes | | Exception thrown for an invalid argument | Yes | | Path template registered with the wrong parameter name | No | | Route declared for the wrong method | No | | Body field that never binds because of a name mismatch | No | | Status code derived from metadata declared outside the body | No | | A response header that a hook was supposed to add | No | | Serialised payload missing or renaming a field | No | | Collaborator that has no registration in the real graph | No | ## Where the tier is the right tool Use it wherever the interesting variation is **inside** the function and has nothing to do with HTTP. A handler with eight validation branches does not need eight routed tests; it needs eight direct calls and one routed test proving the route exists and answers with the agreed status and body. Frameworks differ in how easy this is: where a handler is a plain function taking plain values, the direct call is trivial, while where a handler is written against a framework-owned request and response object, the test must construct or fake those objects, and the more of the framework you have to imitate to make the call work, the less the result is worth. ## How to keep the gap honest - Treat a green direct-call suite as evidence about **logic**, never as evidence that the endpoint is reachable. - Keep at least one routed test per route that asserts the contract a client depends on: status, the headers that matter, and the serialised body's shape. - Be suspicious of coverage reports here. Lines inside the handler are covered; the declarations that *register* it, the binding rules, and the response mapping are configuration the report happily shows as covered while nothing ever executed them against a real request. - When you find yourself building an elaborate fake request just to call the function, that is the signal to move the test up a tier rather than to build a better fake. The summary a strong candidate gives is short: a direct call tests the code you wrote, and a route is mostly code you *declared*. Declarations are only tested by something that reads them.