Spec

0002: Domain API POC - Unit & Integration Tests

Summary

This specification defines the unit and integration test requirements for the Domain API proof-of-concept. The focus is on completing the high-priority (H) test tasks identified in the implementation plan: unit tests for mock server functionality, integration tests for cross-API traversal, and unit tests for error handling.

Problem Statement

The Domain API POC has substantial implementation completed, including:

• Three OpenAPI specifications (Taxpayer, Income Tax, Payment APIs)
• Gateway Lambda function with aggregation and content negotiation
• Acceptance tests for gateway API functionality
• Basic unit tests for OpenAPI validation

However, several critical test categories remain incomplete:

1. Mock server functionality is untested - we cannot verify that Prism mock servers start correctly, return valid responses, or resolve relationship links
2. Cross-API traversal lacks integration tests - while acceptance tests verify gateway behavior, there are no dedicated integration tests for direct API-to-API link resolution
3. Error handling is implemented but not systematically unit tested for edge cases (404, 400, 502 responses)

Without these tests, we cannot confidently deploy or refactor the POC without risking regressions.

Goals

1. Unit tests for mock server functionality (Task 8.5)

   • Verify mock servers (Prism) start successfully and become healthy
   • Validate mock server responses conform to OpenAPI schemas
   • Confirm relationship links in mock responses are correctly formed URLs

2. Integration tests for cross-API traversal (Task 12.7)

   • Test link traversal from Taxpayer API to Income Tax API
   • Test link traversal from Taxpayer API to Payment API
   • Test link traversal from Income Tax API to Payment API
   • Validate bidirectional relationship links work correctly

3. Unit tests for error handling (Task 13.2)

   • Test 404 responses for non-existent resources across all three APIs
   • Test 400 responses for invalid request data (malformed IDs, invalid schemas)
   • Test 502 responses when upstream APIs are unavailable (gateway behavior)

Non-Goals

• Property-based tests (marked as optional in tasks.md)
• UI acceptance tests (already exist in tests/acceptance/ui/)
• Gateway acceptance tests (already exist in tests/acceptance/gateway/)
• OpenAPI specification validation tests (already exist in tests/unit/)
• Documentation completeness tests
• Kubernetes deployment testing

Technical Approach

Test Infrastructure

The project already has test infrastructure in place:

• Vitest for unit and integration tests
• Test helpers in tests/helpers/openapi-validator.ts for spec validation
• Directory structure: tests/unit/, tests/integration/, tests/property/ (empty)

1. Mock Server Unit Tests (tests/unit/mock-server.test.ts)

// Test areas:
// - Server startup: verify Prism processes launch without errors
// - Health checks: verify servers respond to requests
// - Schema conformance: verify responses match OpenAPI schemas
// - Link format: verify _links fields contain valid URLs with correct patterns

Implementation strategy:

• Use child process spawning to start Prism mock servers
• Use fetch to make requests and validate responses
• Use the existing loadSpec() helper to load schemas for validation
• Test link URL patterns (e.g., /taxpayers/{id}, /tax-returns/{id})

2. Cross-API Integration Tests (tests/integration/cross-api-traversal.test.ts)

// Test areas:
// - Taxpayer -> Income Tax: follow taxReturns link
// - Taxpayer -> Payment: follow payments link
// - Income Tax -> Taxpayer: follow taxpayer link
// - Income Tax -> Payment: follow payments link
// - Payment -> Taxpayer: follow taxpayer link
// - Bidirectional: verify A->B and B->A both resolve

Implementation strategy:

• Start all three mock servers before tests
• Fetch a resource from API A
• Extract relationship link from response
• Fetch the linked resource from API B
• Verify the response is valid and contains expected back-link

3. Error Handling Unit Tests (tests/unit/error-handling.test.ts)

// Test areas:
// - 404 Not Found: non-existent resource IDs
// - 400 Bad Request: invalid NINO format, invalid tax year, malformed JSON
// - 502 Bad Gateway: gateway behavior when backend unavailable

Implementation strategy:

• For 404/400: make requests to mock servers with invalid inputs
• For 502: test gateway Lambda handler directly with mocked unavailable backends
• Verify error response structure matches OpenAPI error schemas

Test Data

Use existing example data from OpenAPI specs:

• 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)

File Locations

Test Category	File Path
Mock server unit tests	tests/unit/mock-server.test.ts
Cross-API integration	tests/integration/cross-api-traversal.test.ts
Error handling unit	tests/unit/error-handling.test.ts

Success Criteria

1. Mock server tests pass - All three APIs start, respond correctly, and return valid links
2. Cross-API traversal tests pass - All relationship links can be followed and resolve to valid resources
3. Error handling tests pass - All error conditions return correct status codes and response formats
4. CI integration - Tests run as part of task test or equivalent
5. Coverage - New tests cover the H-priority task requirements (8.5, 12.7, 13.2)

Dependencies

• Existing infrastructure: Vitest, test helpers, OpenAPI specs
• Mock servers: Prism must be installed (npm install -g @stoplight/prism-cli or via npx)
• Gateway Lambda: For 502 error testing, need access to Lambda handler code
• Running services: Integration tests require all three mock servers running

Risks

Risk	Impact	Mitigation
Mock server startup flaky in CI	Tests fail intermittently	Add retry logic and health check waits
Port conflicts	Tests fail to start servers	Use dynamic port allocation or CI-specific ports
Test isolation	Tests interfere with each other	Ensure proper setup/teardown; use unique test data
Gateway Lambda testing complexity	Difficult to unit test 502 scenarios	Mock HTTP client in Lambda handler for controlled failures

Requirements Traceability

Task	Requirement	Description
8.5	8.3	Unit tests for mock server functionality
12.7	5.3, 5.4	Integration tests for cross-API traversal
13.2	2.3	Unit tests for error handling