What does injecting a test principal into a request skip, and when must a test drive the real credential path?

## Two ways a web-layer test can be authenticated A test that exercises a protected route has to get an identity attached to the request, and there are two fundamentally different ways to do it. **Injection.** The test tells the framework, before dispatch, that this call runs as a given principal - a user id, a set of roles or permissions, whatever the application's identity object holds. The request arrives at the chain with that identity already established. Nothing in the request itself carries proof. **The real path.** The test puts an actual credential on the request - in the header the mechanism uses, or as a session-bearing cookie obtained from a real login call - and lets the framework's own machinery find it, decode it, verify it and turn it into a principal. They prove different things, and mixing them up is how a suite ends up green while the credential handling is broken. ## What injection skips - **Extraction** - locating the credential on the request at all: the right header or cookie, the expected prefix, the handling of a header that is absent, empty, or present twice. - **Decoding** - parsing the credential's structure and rejecting one that is truncated, wrongly encoded, or shaped differently than expected. - **Verification** - signature or lookup checks, issuer and audience constraints, and the decision to fail closed when a key is unknown. - **Time handling** - expiry and not-before evaluation, which is the branch most likely to be untested and most likely to break with a clock or key rotation. - **The refusal response** - the challenge and the error body a rejection emits, which never happens on a request that was handed an identity. Frameworks differ in how much of the chain still runs on an injected identity: some short-circuit only the resolution step and let later stages, including permission evaluation, run normally, while others install a fully resolved context and skip more. Check which one you are in before claiming a stage is covered. ## Where each belongs | Test subject | Use injection | Use a real credential | |---|---|---| | Handler behaviour for a given identity | Yes - fastest, no key or clock coupling | Unnecessary | | Permission rule on a route | Yes, with the principal's attributes set | Only if attributes are derived from the credential | | Credential extraction and decoding | No - never exercised | Yes | | Expiry, signature, issuer checks | No | Yes | | The rejection's status, body and challenge | No | Yes | The practical split most teams settle on: a handful of real-credential cases per authentication mechanism - valid, expired, malformed, missing - plus injection everywhere else. The real-credential cases are the ones that tie the mechanism to the wire; the injected ones are the ones that let you write dozens of route tests without paying for a signing step each time. ## The failure mode of an inject-only suite A suite that injects everywhere reports full coverage of authenticated behaviour while every line that reads a request and decides whether to believe it is untested. Such a defect is invisible in the suite and immediately visible in production: a verifier that accepts an unsigned credential, a header parser that silently accepts a missing prefix, an expiry comparison with the wrong sign. None of those change the behaviour of a test that never presented a credential. A second, subtler failure: the injected principal is built by hand with fields the real path could never produce - a role string that the real mapping never emits, an identifier in a different format. The handler is then tested against an identity that cannot exist. The defence is to construct test principals through the same factory or mapping the production path uses, giving it the claims or record it would have received, so an incompatible change breaks the tests rather than hiding in them. ## What to assert in each style On injected tests, assert the handler's outcome and the permission decision. On real-credential tests, assert the branch you came for: that an expired credential yields the refusal status and the contracted error body rather than an internal failure, that a wrongly signed one is refused and not merely logged, and that the refusal carries the response elements the mechanism requires. Keep those few cases deterministic by controlling the time source and the key material from the test rather than reaching for real infrastructure; otherwise they become the flaky cases everyone eventually deletes, which lands the suite back at inject-only.