veza/docs/archive/root-md/API_CONTRACT_TESTS.md

API Contract Tests

INT-009: Add API contract tests

Date: 2025-12-25
Status: Completed

Summary

API contract tests have been added to verify that all API responses match the expected contract between frontend and backend, ensuring compatibility and preventing breaking changes.

Test Coverage

The contract tests verify the following aspects of the API:

1. Error Response Format (TestErrorResponseFormat)

• Verifies that error responses use the standard APIResponse envelope
• Checks that success: false is set
• Validates error object structure (code, message, details, request_id, timestamp, context)
• Ensures timestamp is in ISO 8601 (RFC3339) format

2. Success Response Format (TestSuccessResponseFormat)

• Verifies that success responses use the standard APIResponse envelope
• Checks that success: true is set
• Validates that data is present and error is null

3. Pagination Format (TestPaginationFormat)

• Verifies that paginated responses include standard pagination metadata
• Checks all pagination fields: page, limit, total, total_pages, has_next, has_prev
• Validates pagination structure matches frontend expectations

4. Date/Time Format (TestDateTimeFormat)

• Verifies that all date/time fields use ISO 8601 (RFC3339) format
• Ensures timestamps are parseable by frontend JavaScript Date constructor
• Validates UTC timezone usage

5. API Response Envelope (TestAPIResponseEnvelope)

• Verifies that all responses (success and error) use the APIResponse envelope
• Ensures consistent structure across all endpoints
• Validates envelope fields (success, data, error)

6. Snake Case Naming (TestSnakeCaseNaming)

• Verifies that all JSON field names use snake_case convention
• Ensures consistency with frontend expectations
• Validates naming convention compliance

Test Structure

All contract tests are located in veza-backend-api/tests/contract/api_contract_test.go.

Test Utilities

The tests use standard Go testing patterns:

• gin.TestMode for isolated router testing
• httptest.NewRecorder for HTTP response capture
• stretchr/testify for assertions
• JSON unmarshaling for response validation

Test Data Structures

The tests define contract structures that match frontend expectations:

• APIResponse: Standard response envelope
• ErrorResponse: Standard error structure
• PaginationData: Standard pagination structure

Running the Tests

# Run all contract tests
go test ./tests/contract/...

# Run specific test
go test ./tests/contract/... -run TestErrorResponseFormat

# Run with verbose output
go test -v ./tests/contract/...

Integration with CI/CD

These tests should be run:

• On every pull request
• Before merging to main branch
• As part of the integration test suite
• Before production deployments

Benefits

1. Prevents Breaking Changes: Tests catch API contract violations before they reach production
2. Frontend Compatibility: Ensures backend changes don't break frontend expectations
3. Documentation: Tests serve as executable documentation of the API contract
4. Regression Prevention: Catches regressions in API format standardization

Future Enhancements

1. OpenAPI Schema Validation: Validate responses against OpenAPI schema
2. Frontend Type Generation: Generate TypeScript types from contract tests
3. Contract Versioning: Support multiple API contract versions
4. Performance Testing: Add performance benchmarks to contract tests
5. End-to-End Contract Tests: Test actual frontend-backend integration

Files Created

• veza-backend-api/tests/contract/api_contract_test.go - Contract test suite
• API_CONTRACT_TESTS.md - This documentation

Related Documentation

• ERROR_RESPONSE_STANDARD.md - Error response format specification
• PAGINATION_STANDARD.md - Pagination format specification
• DATETIME_STANDARD.md - Date/time format specification
• API_ENDPOINT_AUDIT.md - Endpoint compatibility audit