test(axum-rest-api-server): [#2637] cover the v1 routes, the router layers and the health check

docs/issues/open/1347-overhaul-packages-testing/EPIC.md

@@ -6,7 +6,7 @@ epic: null
 github-issue: 1347
 spec-path: docs/issues/open/1347-overhaul-packages-testing/EPIC.md
 epic-owner: josecelano
-last-updated-utc: "2026-10-27 08:07"
+last-updated-utc: "2026-10-28 16:55"
 semantic-links:
   skill-links:
     - create-issue
@@ -95,7 +95,7 @@ Status values: `TODO`, `IN_PROGRESS`, `BLOCKED`, `DONE`.
 | 7     | #2283 - Increase UDP server package coverage      | `docs/issues/closed/2283-1347-increase-udp-server-package-coverage/ISSUE.md`      | DONE   | Every package source file processed through a reviewed per-file plan; unit-only lines 96.18% → 98.18%; bounded mutation sample and manual verification recorded; merged via PR #2381. |
 | 8     | #2301 - Review package coverage rollout           | `docs/issues/open/2301-1347-review-package-coverage-rollout/ISSUE.md`             | TODO   | After the EPIC completes, review real rollout evidence before retaining, revising, or proposing a required coverage check. |
 | 9     | #2361 - Keep the report-only package coverage summary from failing on a discovery failure | `docs/issues/open/2361-1347-package-coverage-summary-discovery-failure/ISSUE.md` | TODO | Bug follow-up of #2347 (`review-finding:pr-2293-f1`): the #2222 summary check goes red with a JSON parse error when discovery fails. |
-| 10    | #2637 - Add tests to the axum-rest-api-server package | `docs/issues/open/2637-1347-add-tests-axum-rest-api-server/ISSUE.md` | IN_PROGRESS | S0 (spec and T1 baseline) merged through #2638; S1 (authentication and shared responses) is in review in #2667; slices S2-S6 follow. Replaces the former draft that was misfiled under #1349. |
+| 10    | #2637 - Add tests to the axum-rest-api-server package | `docs/issues/open/2637-1347-add-tests-axum-rest-api-server/ISSUE.md` | IN_PROGRESS | S0 (spec and T1 baseline) merged through #2638; S1 (authentication and shared responses) merged through #2667; S2 (routes) is in review in #2687; S3-S6 follow. Replaces the former draft that was misfiled under #1349. |
 | 11    | Additional package-testing subissues              | Create a folder-style spec when a concrete package need is identified             | TODO   | Permitted but not required upfront; retain scope in this EPIC.                                                       |
 
 ## Package Coverage Tracking
@@ -119,7 +119,7 @@ level or determine whether unit coverage is adequate.
 | `torrust-tracker-udp-server`       | [#2283](../../closed/2283-1347-increase-udp-server-package-coverage/ISSUE.md) | Lines: 97.86%; regions: 96.64%; functions: 97.64% | Lines: 98.58%; regions: 97.62%; functions: 98.56% | Lines: +0.72 pp; regions: +0.98 pp; functions: +0.92 pp | [Coverage evidence](../../closed/2283-1347-increase-udp-server-package-coverage/coverage-evidence.md) |
 | `torrust-tracker-udp-core`         | [#1348](../../closed/1348-1347-add-tests-udp-core/ISSUE.md) | Lines: 72.49%; regions: 78.56%; functions: 71.27% | Lines: 98.04%; regions: 98.15%; functions: 97.61% | Lines: +25.55 pp; regions: +19.58 pp; functions: +26.34 pp | [Coverage evidence](../../closed/1348-1347-add-tests-udp-core/coverage-evidence.md) |
 | `torrust-tracker-http-core`        | [#1349](../../closed/1349-1347-add-tests-http-core/ISSUE.md) | Lines: 88.88%; regions: 90.41%; functions: 84.29% | Lines: 99.28%; regions: 99.25%; functions: 99.74% | Lines: +10.40 pp; regions: +8.84 pp; functions: +15.45 pp | [Coverage evidence](../../closed/1349-1347-add-tests-http-core/coverage-evidence.md) |
-| `torrust-tracker-axum-rest-api-server` | [#2637](../2637-1347-add-tests-axum-rest-api-server/ISSUE.md) | Lines: 87.98%; regions: 84.10%; functions: 83.42% | Lines: 88.97%; regions: 85.24%; functions: 85.20% | Lines: +0.99 pp; regions: +1.14 pp; functions: +1.78 pp | [Coverage evidence](../2637-1347-add-tests-axum-rest-api-server/coverage-evidence.md) |
+| `torrust-tracker-axum-rest-api-server` | [#2637](../2637-1347-add-tests-axum-rest-api-server/ISSUE.md) | Lines: 87.98%; regions: 84.10%; functions: 83.42% | Lines: 91.32%; regions: 88.23%; functions: 89.13% | Lines: +3.34 pp; regions: +4.13 pp; functions: +5.71 pp | [Coverage evidence](../2637-1347-add-tests-axum-rest-api-server/coverage-evidence.md) |
 
 ### Unit-Only Coverage
 
@@ -133,7 +133,7 @@ weak unit-only result with aggregate, integration, example, or end-to-end covera
 | `torrust-tracker-udp-server` | [#2283](../../closed/2283-1347-increase-udp-server-package-coverage/ISSUE.md) | Lines: 96.18%; regions: 95.34%; functions: 94.93% | Lines: 98.18%; regions: 97.04%; functions: 97.70% | Lines: +2.00 pp; regions: +1.70 pp; functions: +2.77 pp | [Coverage evidence](../../closed/2283-1347-increase-udp-server-package-coverage/coverage-evidence.md) |
 | `torrust-tracker-udp-core` | [#1348](../../closed/1348-1347-add-tests-udp-core/ISSUE.md) | Lines: 72.49%; regions: 78.56%; functions: 71.27% | Lines: 98.04%; regions: 98.15%; functions: 97.61% | Lines: +25.55 pp; regions: +19.58 pp; functions: +26.34 pp | [Coverage evidence](../../closed/1348-1347-add-tests-udp-core/coverage-evidence.md) |
 | `torrust-tracker-http-core` | [#1349](../../closed/1349-1347-add-tests-http-core/ISSUE.md) | Lines: 88.88%; regions: 90.41%; functions: 84.29% | Lines: 99.28%; regions: 99.25%; functions: 99.74% | Lines: +10.40 pp; regions: +8.84 pp; functions: +15.45 pp | [Coverage evidence](../../closed/1349-1347-add-tests-http-core/coverage-evidence.md) |
-| `torrust-tracker-axum-rest-api-server` | [#2637](../2637-1347-add-tests-axum-rest-api-server/ISSUE.md) | Lines: 63.87%; regions: 63.98%; functions: 51.34% | Lines: 70.57%; regions: 69.44%; functions: 58.16% | Lines: +6.70 pp; regions: +5.46 pp; functions: +6.82 pp | [Coverage evidence](../2637-1347-add-tests-axum-rest-api-server/coverage-evidence.md) |
+| `torrust-tracker-axum-rest-api-server` | [#2637](../2637-1347-add-tests-axum-rest-api-server/ISSUE.md) | Lines: 63.87%; regions: 63.98%; functions: 51.34% | Lines: 83.87%; regions: 80.58%; functions: 79.13% | Lines: +20.00 pp; regions: +16.60 pp; functions: +27.79 pp | [Coverage evidence](../2637-1347-add-tests-axum-rest-api-server/coverage-evidence.md) |
 
 ## Delivery Strategy
 
@@ -319,6 +319,10 @@ For each subissue implementation, the completion policy is:
 - 2026-10-27 07:16 UTC - GitHub Copilot - #2637 S1 (authentication and shared responses) finished: unit-only lines
   63.87% to 70.57% (46 unit tests), aggregate 87.98% to 88.97%; both tables carry the interim figures against the
   S1 baseline until the final measurement.
+- 2026-10-28 16:39 UTC - GitHub Copilot - #2637 S2 (routes, the router layers and the health check) finished: unit-only lines
+  70.57% to 83.87% (76 unit tests), aggregate 88.97% to 91.32%; both tables carry the interim figures against the S1
+  baseline until the final measurement. Part of the rise comes from a `develop` change to `server.rs` (the configured
+  drain timeout and its test), not from S2.
 
 ## Acceptance Criteria
 

docs/issues/open/2637-1347-add-tests-axum-rest-api-server/ISSUE.md

@@ -7,9 +7,9 @@ priority: p2
 epic: 1347
 github-issue: 2637
 spec-path: docs/issues/open/2637-1347-add-tests-axum-rest-api-server/ISSUE.md
-branch: "2637-1347-add-tests-axum-rest-api-server-auth"
-related-pr: 2667
-last-updated-utc: "2026-10-27 08:07"
+branch: "2637-1347-add-tests-axum-rest-api-server-routes"
+related-pr: 2687
+last-updated-utc: "2026-10-28 16:55"
 semantic-links:
   skill-links:
     - create-issue
@@ -242,7 +242,9 @@ is:
 ### Out of Scope
 
 - Production behavior changes in `packages/axum-rest-api-server/src/`. A bug fix or production
-  clean-up found here goes to a separate issue through the findings procedure.
+  clean-up found here goes to a separate issue through the findings procedure. One exception, approved by the
+  maintainer on 2026-10-28: the behavior-preserving testability refactor of `routes.rs` (plan R0), in its own
+  `refactor` commit.
 - Tracker business rules and persistence owned by `tracker-core`, use-case orchestration and port
   traits owned by `rest-api-application`, adapters and container wiring owned by
   `rest-api-runtime-adapter`, DTOs and their serialization owned by `rest-api-protocol`, the HTTP
@@ -403,8 +405,8 @@ ledger order inside each slice is still confirmed with the first plan (T3).
 | Slice | Content | Ledger rows | Branch | PR | Status |
 | --- | --- | --- | --- | --- | --- |
 | S0 | This specification, the T1 coverage evidence and inventory, and the EPIC registration with the baseline | - | `2637-1347-add-tests-axum-rest-api-server-spec` | #2638 | DONE |
-| S1 | T2-T3, then authentication and the shared response contract (ranks 1 and 3) | 1, 5 | `2637-1347-add-tests-axum-rest-api-server-auth` | #2667 | IN_PROGRESS |
-| S2 | Route composition, transport layers and the health check (rank 2) | 2-4 | `2637-1347-add-tests-axum-rest-api-server-routes` | TBD | PENDING |
+| S1 | T2-T3, then authentication and the shared response contract (ranks 1 and 3) | 1, 5 | `2637-1347-add-tests-axum-rest-api-server-auth` | #2667 | DONE |
+| S2 | Route composition, transport layers and the health check (rank 2) | 2-4 | `2637-1347-add-tests-axum-rest-api-server-routes` | #2687 | IN_PROGRESS |
 | S3 | State-changing contexts: auth keys and whitelist (rank 4) | 6-11 | `2637-1347-add-tests-axum-rest-api-server-commands` | TBD | PENDING |
 | S4 | Read-only contexts: torrents and statistics (rank 5) | 12-17 | `2637-1347-add-tests-axum-rest-api-server-queries` | TBD | PENDING |
 | S5 | Server lifecycle (rank 6) | 18 | `2637-1347-add-tests-axum-rest-api-server-lifecycle` | TBD | PENDING |
@@ -533,9 +535,9 @@ declaration-only rows have no executable entries.
 | Order | Source module | Rank | Slice | Unit-only lines | Tests | Initial hypothesis | State | Plan |
 | ---: | --- | ---: | --- | ---: | ---: | --- | --- | --- |
 | 1 | `v1/middlewares/auth.rs` | 1 | S1 | 71 / 103 (68.93%) | 4 | Property candidate | DONE | [v1-middlewares-auth-tests.md](test-refactor-plans/v1-middlewares-auth-tests.md) (done; 142 / 142 lines after, 27 test cases, 8 mutants killed, property test declined) |
-| 2 | `v1/routes.rs` | 2 | S2 | 27 / 45 (60.00%) | 0 | Test candidate | PENDING | - |
-| 3 | `routes.rs` | 2 | S2 | 58 / 67 (86.57%) | 0 | Test candidate | PENDING | - |
-| 4 | `v1/context/health_check/handlers.rs` | 2 | S2 | 4 / 4 (100.00%) | 0 | Test candidate (small) | PENDING | - |
+| 2 | `v1/routes.rs` | 2 | S2 | 27 / 45 (60.00%) | 0 | Test candidate | DONE | [v1-routes-tests.md](test-refactor-plans/v1-routes-tests.md) (done; 111 / 111 lines after, 19 test cases, 6 mutants killed, private test_support helper) |
+| 3 | `routes.rs` | 2 | S2 | 58 / 67 (86.57%) | 0 | Test candidate | DONE | [routes-tests.md](test-refactor-plans/routes-tests.md) (done; 169 / 169 lines after, 9 test cases, 8 of 10 mutants killed, the 2 survivors recorded, R0 refactor) |
+| 4 | `v1/context/health_check/handlers.rs` | 2 | S2 | 4 / 4 (100.00%) | 0 | Test candidate (small) | DONE | [v1-context-health-check-handlers-tests.md](test-refactor-plans/v1-context-health-check-handlers-tests.md) (done; 16 / 16 lines after, 1 test, mutant killed; protection not coverage) |
 | 5 | `v1/responses.rs` | 3 | S1 | 8 / 40 (20.00%) | 0 | Test candidate | DONE | [v1-responses-tests.md](test-refactor-plans/v1-responses-tests.md) (done; 66 / 66 lines after, 8 test cases, 8 mutants killed) |
 | 6 | `v1/context/auth_key/handlers.rs` | 4 | S3 | 0 / 56 (0.00%) | 0 | Test candidate | PENDING | - |
 | 7 | `v1/context/auth_key/responses.rs` | 4 | S3 | 0 / 26 (0.00%) | 0 | Test candidate | PENDING | - |
@@ -658,6 +660,51 @@ once. If the slicing changes, the Slice column changes with it.
   again: unit-only lines 921 / 1,305 (70.57%), aggregate 1,161 / 1,305 (88.97%), integration-only 674 / 908
   (74.23%); 46 unit tests. Updated the EPIC "Latest" values.
 - 2026-10-27 08:07 UTC - GitHub Copilot - Recorded S1 pull request #2667 (<https://github.com/torrust/torrust-tracker/pull/2667>) with `Related to #2637`, opened at 07:32 UTC after both independent reviews; recorded its number in the frontmatter and the slice table after Copilot's review (finding F1 of the PR #2667 audit).
+- 2026-10-27 14:58 UTC - GitHub Copilot - S1 merged through #2667 (11:47 UTC, with your ACK at 10:23 UTC;
+  Copilot's one nit F1 was fixed before the merge). Closed the loop on the late #2638 findings F5 to F9: the
+  fixes are on `develop`, I replied to and resolved the five threads (14:55 UTC) and set their audit rows to
+  `FIXED`/`RESOLVED` in the first commit of this branch. Started S2 on branch
+  `2637-1347-add-tests-axum-rest-api-server-routes` from `develop` at the merge of #2672. The package is
+  byte-identical to the S1 head, so the S1 measurement is the S2 baseline (unit-only lines 921 / 1,305,
+  70.57%). Row 2 (`v1/routes.rs`) is `IN_PROGRESS`; its plan is proposed and awaits the maintainer.
+- 2026-10-28 12:20 UTC - Jose Celano - Approved the row 2 plan (`v1/routes.rs`) with these decisions: the
+  crate-private container helper is a `#[cfg(test)] mod test_support` (ADR `20261021190318`, rule C; `src/testing/`
+  is for code shared outside the crate); the cases with `private` or `listed` set but no persistence are kept as the
+  second line of defense, linked to the first line (`validate_persistence_requirements` in
+  `src/bootstrap/persistence.rs`, called by `setup` in `src/bootstrap/app.rs`); the design question (making that
+  state unrepresentable) and a stale module comment are recorded in `lessons.md` only.
+- 2026-10-28 13:22 UTC - GitHub Copilot - Jose Celano questioned whether `src/testing/` should hold only shared test
+  code or all test-only code outside a test module. The repository evidence (history of the `src/environment.rs`
+  moves, ADR `20261021190318` rule C, `tracker-core`'s crate-root helpers) is in the routes plan. Decision: the helper
+  stays a private `#[cfg(test)] mod test_support` and its file gets an inner `#![cfg(test)]`; the convention, including
+  the `test_` file prefix for files that contain only test code, goes to `lessons.md` for a separate ADR
+  clarification after this issue.
+- 2026-10-28 13:25 UTC - GitHub Copilot - S2 row 2 (`v1/routes.rs`) is done: unit-only lines 27 / 45 (60.00%) to 111 / 111
+  (100.00%), 19 test cases, six named mutations killed, a crate-private `test_support` helper; the maintainer approved
+  the completed file (2026-10-28). Proposed the row 3 plan (`routes.rs`: the authentication layer wiring, request id,
+  compression), with two questions for the maintainer (the `408` timeout has no test seam; asserting log events
+  needs a new dev-dependency).
+- 2026-10-28 13:27 UTC - Jose Celano - Approved the row 3 plan (`routes.rs`) and answered its two questions: do not
+  assert log events at unit level, and make the `408` timeout testable with a small behavior-preserving refactor
+  (R0) in this issue. This extends the scope with one exception to the production-change exclusion, recorded in
+  Out of Scope; the refactor is its own `refactor` commit before any test.
+- 2026-10-28 16:24 UTC - GitHub Copilot - S2 row 3 (`routes.rs`) is done: unit-only lines 58 / 67 (86.57%) to 174 / 174
+  (100.00%), 9 test cases, eight of ten named mutations killed (two survive by design and are recorded), and the
+  behavior-preserving `with_layers` refactor in its own commit; the maintainer approved the completed file (16:22 UTC).
+  Proposed the plan for row 4 (`v1/context/health_check/handlers.rs`), the last file of S2.
+- 2026-10-28 16:39 UTC - GitHub Copilot - S2 close: rows 2 to 4 are `DONE` (`v1/routes.rs` 111 / 111, `routes.rs` 169 / 169 and the
+  health check handler 16 / 16 unit-only lines), with the behavior-preserving `with_layers` refactor in its own commit
+  and the crate-private `test_support` helper. Correction to the 16:24 UTC entry above: `routes.rs` is 169 / 169 lines,
+  not 174 / 174, because the earlier figure was measured before the timeout assertion was simplified; the ledger,
+  evidence and plan now say 169 / 169. Rebased onto `develop`, which changed the package meanwhile (the configured
+  drain timeout in `server.rs` and its test environment), and measured again: unit-only lines 1,305 / 1,556
+  (83.87%), aggregate 1,421 / 1,556 (91.32%), integration-only 682 / 916 (74.45%); 76 unit tests. Updated the EPIC
+  "Latest" values.
+- 2026-10-28 16:52 UTC - GitHub Copilot - Added the missing approvals of row 4 (`v1/context/health_check/handlers.rs`): the maintainer approved the plan on
+  2026-10-28 after the plan commit of 16:24 UTC and before its test was written (the answer to the plan question, with no
+  change requested), and approved the completed file at 16:35 UTC. The independent S2 review found that the log did
+  not record them. Also fixed the other records items of that review (see `agent-review-reports.md`).
+- 2026-10-28 16:55 UTC - GitHub Copilot - Recorded S2 pull request #2687 (<https://github.com/torrust/torrust-tracker/pull/2687>, `Related to #2637`, opened at 16:55 UTC) in the frontmatter, the slice table and the EPIC row.
 
 ## Acceptance Criteria
 

docs/issues/open/2637-1347-add-tests-axum-rest-api-server/agent-review-reports.md

@@ -54,3 +54,20 @@ semantic-links:
 - Verdict: REVIEW PASSED
 - Follow-up actions:
   - None.
+
+### 2026-10-28 16:50 UTC - Task Reviewer (slice S2, first review)
+
+- Invocation scope: slice S2 of #2637 on branch `2637-1347-add-tests-axum-rest-api-server-routes`: the commits above `torrust/develop`, including `refactor(axum-rest-api-server): [#2637] separate the router layers from the routes` and the test commits for `v1/routes.rs`, `routes.rs` and the health check handler.
+- Inputs: the issue folder, the EPIC, the subissue guidelines, the `write-unit-test` skill, ADR `20261021190318` rule C, and the changed Rust files.
+- Evidence: the reviewer recomputed the three coverage scopes with clean `cargo llvm-cov` runs (stable Rust 1.99.1, `cargo-llvm-cov 0.6.16`) and every recorded figure matched, including the "before" figures rebuilt from a `develop` snapshot and the six EPIC deltas; the production refactor commit is a pure move (same chain and order, same 5 s default, same `#[instrument]`); eight mutations (G1, G5, L1, L5, L8, H1, L6, L10) behaved as the plans say, L6 and L10 surviving by design; `cargo +nightly fmt --all -- --check` (nightly Rust toolchain), `cargo clippy --all-targets`, `cargo machete --with-metadata`, `git diff --check`, `linter markdown` and `linter cspell` passed; no closing keyword and no cited branch SHA; every log stamp was at or before its commit.
+- Findings:
+  - MEDIUM: the row 4 plan approval and completed-file approval were recorded in the plan index and plan but not in the progress log.
+  - LOW: package-level figures in two plans were measured before the rebase onto `develop` and were not labelled as such.
+  - LOW: the routes plan's case table expected a content type that the tests do not assert.
+  - LOW: the timeout test bound a variable named like the helper that reads the response (`received`).
+  - LOW: one rejection test name was narrower than its cases (a wrong token).
+  - LOW: the note on log coverage did not say that the integration test most likely protects only the server-error response event and not the `on_failure` closure.
+  - LOW (declined): `v1/routes.rs`'s helper returns a content type that three tests ignore; the two `409` tables assert it, so the helper stays as it is.
+- Verdict: REVIEW PASSED
+- Follow-up actions:
+  - The approvals were added to the progress log, the figures were labelled, the table and the log note were corrected, and the helper and the test were renamed: `test(axum-rest-api-server): [#2637] stop shadowing the response reader in the router tests` and `docs(issues): [#2637] fix the records items of the S2 independent review`.