#1166 Engineer Integration Test Coverage for the Health Drain Readine…

[veloura-dev]

CLOSE #1166

1. Detailed Findings

• Missing Integration Test Coverage: The route handler in apps/backend/src/app/api/health/drain/route.ts exposes the readiness endpoint GET /api/health/drain for container orchestrators and load balancers during rolling deployments. It fronts the isDraining() and inFlightCount() state from apps/backend/src/lib/shutdown-manager.ts. However, no integration test suite existed to verify that HTTP requests to this route properly reflect internal shutdown manager state transitions.
• Risk of Silent Regression: Without automated integration tests, any regression in the response payload structure (e.g., property renaming, type mismatch), status codes, or state synchronization between the route and the shutdown manager could cause rolling deployments to terminate in-flight deployment tasks prematurely without warning.
• Test State Isolation Need: In apps/backend/src/lib/shutdown-manager.ts, state variables (draining, inFlight, realtimeCleanups) are module-level singletons. In order to run multiple lifecycle integration tests in sequence without module pollution, a state reset mechanism was required.

---

2. Implemented Fix Features

1. Pre-Drain State Coverage:

   • Idle State: Validates that GET /api/health/drain returns HTTP 200 with { inFlightCount: 0, draining: false } on an idle server before any drain signal.
   • Active Operations Tracking: Tests that calling trackOperation(id) increments the inFlightCount reflected in the GET response while keeping draining: false.
   • Pre-Drain Completion: Verifies that resolving operations via their returned done() callbacks decrements inFlightCount dynamically back to 0 prior to draining.

2. Mid-Drain State (In-Flight Operations Active):

   • Drain Initiation State: Tests that invoking drain() immediately transitions the route's response to draining: true while preserving the exact count of active in-flight operations.
   • Real-Time Stepdown: Verifies that as active operations complete during the drain window, successive GET calls to /api/health/drain reflect the decreasing inFlightCount in real time (2 → 1 → 0).
   • Drain Timeout & Force-Fail: Validates the drain timeout mechanism using fake timers (vi.useFakeTimers()). Confirms that stuck operations that fail to complete within the 30-second window are force-failed via Supabase, clearing the in-flight count (inFlightCount: 0, draining: true).

3. Post-Drain State Coverage:

   • Idle Drain Initiation: Confirms that initiating drain() when inFlightCount === 0 transitions the route directly to { inFlightCount: 0, draining: true }.
   • State Persistence & Idempotency: Verifies that repeated consecutive GET requests post-drain consistently return { inFlightCount: 0, draining: true }.
   • Realtime Cleanup Execution: Validates that registered Supabase realtime cleanup callbacks (registerRealtimeCleanup) are executed during the drain lifecycle.

4. Response Contract & Schema Validation:

   • Confirms the endpoint returns HTTP 200 OK.
   • Validates that the Content-Type header contains application/json.
   • Asserts the exact response data types (inFlightCount as number, draining as boolean).

5. Test Isolation Hook (_resetState):

   • Added and exported _resetState() in apps/backend/src/lib/shutdown-manager.ts to clear draining, empty inFlight, and reset realtimeCleanups between test runs.

[drips-wave]

@veloura-dev Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits