43af35fd93
- Archiver 131 .md dans docs/archive/root-md/ - Archiver 22 .json dans docs/archive/root-json/ - Conserver 7 .md utiles (README, CONTRIBUTING, CHANGELOG, etc.) - Conserver package.json, package-lock.json, turbo.json - Ajouter README d'index dans chaque archive
113 lines
3.9 KiB
Markdown
113 lines
3.9 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|