# 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