Plan

0002: Domain API POC - Unit & Integration Tests

Implementation Plan

Specification Reference: /home/coder/src/workspaces/codev/codev/specs/0002-domain-api-poc-tests.md

Tasks Reference: /home/coder/src/workspaces/codev/repos/domain-apis/.kiro/specs/domain-api-poc/tasks.md

Scope: H-priority tasks 8.5, 12.7, and 13.2

---

Phase 1: Mock Server Unit Tests (Task 8.5)

Objective: Create unit tests that verify Prism mock servers start correctly, respond with valid data, and generate correctly-formed relationship links.

Tasks

1. Create test file structure

   • Create tests/unit/mock-server.test.ts
   • Add test helper for spawning and managing Prism processes

2. Implement server startup tests

   • Test that Prism mock server can be spawned for Taxpayer API (port 8081)
   • Test that Prism mock server can be spawned for Income Tax API (port 8082)
   • Test that Prism mock server can be spawned for Payment API (port 8083)
   • Verify servers become healthy within timeout period

3. Implement schema conformance tests

   • Test GET /taxpayers returns response matching OpenAPI schema
   • Test GET /taxpayers/{id} returns valid Taxpayer resource
   • Test GET /tax-returns returns response matching OpenAPI schema
   • Test GET /tax-returns/{id} returns valid TaxReturn resource
   • Test GET /payments returns response matching OpenAPI schema
   • Test GET /payments/{id} returns valid Payment resource

4. Implement link format validation tests

   • Test that _links.self contains valid path-only URL for each resource type
   • Test that relationship links (taxReturns, payments, taxpayer) are correctly formed
   • Test that link URLs follow expected patterns (e.g., /taxpayers/{id}, /tax-returns/{id})

Files to Create/Modify

Action	File
Create	tests/unit/mock-server.test.ts
Create	tests/helpers/mock-server-manager.ts

Success Criteria

• All three mock servers (Taxpayer, Income Tax, Payment) can be started programmatically
• Health checks pass for all started servers
• Response bodies conform to their respective OpenAPI schemas
• All _links fields contain valid path-only URLs
• Tests pass with npm run test:unit

Dependencies

• None (first phase)

---

Phase 2: Cross-API Integration Tests (Task 12.7)

Objective: Create integration tests that verify relationship links between APIs can be traversed and resolve to valid resources.

Tasks

1. Create integration test file and setup

   • Create tests/integration/cross-api-traversal.test.ts
   • Create setup/teardown hooks to start all three mock servers before tests
   • Configure dynamic port allocation or fixed test ports

2. Implement Taxpayer to Income Tax traversal tests

   • Test fetching a Taxpayer resource
   • Extract taxReturns link from _links
   • Follow the link to Income Tax API
   • Verify response is a valid collection of TaxReturn resources
   • Verify each TaxReturn has a taxpayer back-link

3. Implement Taxpayer to Payment traversal tests

   • Test fetching a Taxpayer resource
   • Extract payments link from _links
   • Follow the link to Payment API
   • Verify response is a valid collection of Payment resources
   • Verify each Payment has a taxpayer back-link

4. Implement Income Tax to Taxpayer traversal tests

   • Test fetching a TaxReturn resource
   • Extract taxpayer link from _links
   • Follow the link to Taxpayer API
   • Verify response is a valid Taxpayer resource

5. Implement Income Tax to Payment traversal tests

   • Test fetching a TaxReturn resource
   • Extract payments link from _links (if present)
   • Follow the link to Payment API
   • Verify response is a valid collection of Payment resources

6. Implement Payment to Taxpayer traversal tests

   • Test fetching a Payment resource
   • Extract taxpayer link from _links
   • Follow the link to Taxpayer API
   • Verify response is a valid Taxpayer resource

7. Implement bidirectional relationship tests

   • Test that Taxpayer → TaxReturn → Taxpayer returns same resource
   • Test that Taxpayer → Payment → Taxpayer returns same resource
   • Verify resource IDs match in round-trip traversals

Files to Create/Modify

Action	File
Create	tests/integration/cross-api-traversal.test.ts
Modify	tests/helpers/mock-server-manager.ts (add multi-server support)

Success Criteria

• All three mock servers start successfully before integration tests
• Taxpayer → Income Tax link traversal works correctly
• Taxpayer → Payment link traversal works correctly
• Income Tax → Taxpayer link traversal works correctly
• Income Tax → Payment link traversal works correctly
• Payment → Taxpayer link traversal works correctly
• Bidirectional traversals return consistent resource IDs
• Tests pass with npm run test:integration

Dependencies

• Phase 1 (mock server management helper)

---

Phase 3: Error Handling Unit Tests (Task 13.2)

Objective: Create unit tests that verify error responses (404, 400, 502) are returned correctly for various error conditions.

Tasks

1. Create error handling test file

   • Create tests/unit/error-handling.test.ts
   • Import existing test helpers and mock server manager

2. Implement 404 Not Found tests

   • Test 404 for non-existent Taxpayer ID (e.g., /taxpayers/TP999999)
   • Test 404 for non-existent TaxReturn ID (e.g., /tax-returns/TR99999999)
   • Test 404 for non-existent Payment ID (e.g., /payments/PM99999999)
   • Verify error response structure matches OpenAPI error schema

3. Implement 400 Bad Request tests

   • Test 400 for invalid NINO format in request body
   • Test 400 for invalid tax year format
   • Test 400 for malformed resource IDs (wrong pattern)
   • Test 400 for missing required fields in POST/PUT requests
   • Verify error response includes validation details

4. Implement 502 Bad Gateway tests (Lambda handler)

   • Create dedicated test file tests/unit/gateway-error-handling.test.ts
   • Test 502 when Taxpayer API is unavailable (mock fetch rejection)
   • Test 502 when Income Tax API is unavailable
   • Test 502 when Payment API is unavailable
   • Test partial failure handling (one backend unavailable during include)
   • Verify error response structure includes code, message, and details

5. Verify error response format consistency

   • Test that all error responses include error object
   • Test that error object has code, message fields
   • Test that 400 errors include validation details when applicable

Files to Create/Modify

Action	File
Create	tests/unit/error-handling.test.ts
Create	tests/unit/gateway-error-handling.test.ts
Modify	tests/helpers/openapi-validator.ts (add error schema validation)

Success Criteria

• 404 responses returned for non-existent resources across all three APIs
• 400 responses returned for invalid request data with appropriate details
• 502 responses returned when backend APIs are unavailable
• Error response format matches OpenAPI error schema
• Partial failures in includes are handled gracefully (200 with partial _included)
• Tests pass with npm run test:unit

Dependencies

• Phase 1 (mock server management helper)

---

Phase 4: Test Infrastructure Enhancements

Objective: Ensure all new tests integrate properly with existing CI/CD and can be run via standard commands.

Tasks

1. Verify test runner configuration

   • Confirm Jest is configured to find new test files
   • Verify test:unit, test:integration scripts work correctly
   • Add any necessary Jest configuration for async operations and timeouts

2. Add retry logic for flaky server startup

   • Implement health check retries in mock-server-manager.ts
   • Configure appropriate timeouts for CI environment
   • Add graceful shutdown to prevent port conflicts

3. Update package.json scripts if needed

   • Ensure npm run test includes all new test categories
   • Add script for running just the new tests if helpful for debugging

4. Document test execution

   • Add comments in test files explaining prerequisites
   • Document any environment variables needed for tests

Files to Create/Modify

Action	File
Modify	package.json (verify scripts)
Modify	jest.config.js or jest.config.ts (if exists, verify configuration)
Modify	tests/helpers/mock-server-manager.ts (add retry logic)

Success Criteria

• npm run test:unit runs all unit tests including new ones
• npm run test:integration runs all integration tests including new ones
• npm run test runs complete test suite
• Tests are stable in CI (no flaky failures from server startup)
• Test files include clear documentation

Dependencies

• Phases 1, 2, 3

---

Summary

Phase	Task ID	Description	New Files
1	8.5	Mock server unit tests	tests/unit/mock-server.test.ts, tests/helpers/mock-server-manager.ts
2	12.7	Cross-API integration tests	tests/integration/cross-api-traversal.test.ts
3	13.2	Error handling unit tests	tests/unit/error-handling.test.ts, tests/unit/gateway-error-handling.test.ts
4	-	Test infrastructure	Updates to existing files

Test Data Reference

From the spec:

• Taxpayer ID pattern: TP[0-9]{6} (e.g., TP123456)
• Tax Return ID pattern: TR[0-9]{8} (e.g., TR20230001)
• Payment ID pattern: PM[0-9]{8} (e.g., PM20230001)
• NINO pattern: [A-Z]{2}[0-9]{6}[A-Z] (e.g., AB123456C)

Existing Test Infrastructure

• Test Framework: Jest with ts-jest
• Test Helpers: tests/helpers/openapi-validator.ts - provides loadSpec(), hasRequiredFields(), validateRefs()
• Acceptance Tests: Exist in tests/acceptance/ (Playwright-based, separate from this scope)
• Lambda Tests: gateway/lambda/src/index.test.ts - provides patterns for mocking fetch