v0

test/README.md

@@ -0,0 +1,250 @@
+# Integration Tests for API Key Management Service
+
+This directory contains comprehensive end-to-end integration tests for the API Key Management Service.
+
+## Test Coverage
+
+The integration tests cover:
+
+### 1. **Health Check Endpoints**
+- Basic health check (`/health`)
+- Readiness check with database connectivity (`/ready`)
+
+### 2. **Application CRUD Operations**
+- Create new applications
+- List applications with pagination
+- Get specific applications by ID
+- Update application details
+- Delete applications
+
+### 3. **Static Token Workflow**
+- Create static tokens for applications
+- Verify static token permissions
+- Token validation and permission checking
+
+### 4. **User Token Authentication Flow**
+- User login process
+- Token generation for users
+- Permission-based access control
+
+### 5. **Authentication Middleware**
+- Header-based authentication validation
+- Unauthorized access handling
+- User context management
+
+### 6. **Error Handling**
+- Invalid JSON request handling
+- Non-existent resource handling
+- Proper HTTP status codes
+
+### 7. **Concurrent Load Testing**
+- Multiple simultaneous health checks
+- Concurrent application listing requests
+- Database connection pooling under load
+
+## Prerequisites
+
+Before running the integration tests, ensure you have:
+
+1. **PostgreSQL Database**: Running on localhost:5432
+2. **Test Database**: Create a test database named `kms_test`
+3. **Go Dependencies**: All required Go modules installed
+
+### Database Setup
+
+```bash
+# Connect to PostgreSQL
+psql -U postgres -h localhost
+
+# Create test database
+CREATE DATABASE kms_test;
+
+# Grant permissions
+GRANT ALL PRIVILEGES ON DATABASE kms_test TO postgres;
+```
+
+## Running the Tests
+
+### Option 1: Run All Integration Tests
+
+```bash
+# From the project root directory
+go test -v ./test/...
+```
+
+### Option 2: Run with Coverage
+
+```bash
+# Generate coverage report
+go test -v -coverprofile=coverage.out ./test/...
+go tool cover -html=coverage.out -o coverage.html
+```
+
+### Option 3: Run Specific Test Suites
+
+```bash
+# Run only health endpoint tests
+go test -v ./test/ -run TestHealthEndpoints
+
+# Run only application CRUD tests
+go test -v ./test/ -run TestApplicationCRUD
+
+# Run only token workflow tests
+go test -v ./test/ -run TestStaticTokenWorkflow
+
+# Run concurrent load tests
+go test -v ./test/ -run TestConcurrentRequests
+```
+
+### Option 4: Run with Docker/Podman
+
+```bash
+# Start the services first
+podman-compose up -d
+
+# Wait for services to be ready
+sleep 10
+
+# Run the tests
+go test -v ./test/...
+
+# Clean up
+podman-compose down
+```
+
+## Test Configuration
+
+The tests use a separate test configuration that:
+
+- Uses a dedicated test database (`kms_test`)
+- Disables rate limiting for testing
+- Disables metrics collection
+- Uses debug logging level
+- Configures shorter timeouts
+
+## Test Data Management
+
+The integration tests:
+
+- **Clean up after themselves**: Each test cleans up its test data
+- **Use isolated data**: Test data is prefixed with `test-` to avoid conflicts
+- **Reset state**: Database state is reset between test runs
+- **Use transactions**: Where possible, tests use database transactions
+
+## Expected Test Results
+
+When all tests pass, you should see output similar to:
+
+```
+=== RUN   TestIntegrationSuite
+=== RUN   TestIntegrationSuite/TestHealthEndpoints
+=== RUN   TestIntegrationSuite/TestApplicationCRUD
+=== RUN   TestIntegrationSuite/TestApplicationCRUD/CreateApplication
+=== RUN   TestIntegrationSuite/TestApplicationCRUD/ListApplications
+=== RUN   TestIntegrationSuite/TestApplicationCRUD/GetApplication
+=== RUN   TestIntegrationSuite/TestStaticTokenWorkflow
+=== RUN   TestIntegrationSuite/TestStaticTokenWorkflow/CreateStaticToken
+=== RUN   TestIntegrationSuite/TestStaticTokenWorkflow/VerifyStaticToken
+=== RUN   TestIntegrationSuite/TestUserTokenWorkflow
+=== RUN   TestIntegrationSuite/TestUserTokenWorkflow/UserLogin
+=== RUN   TestIntegrationSuite/TestAuthenticationMiddleware
+=== RUN   TestIntegrationSuite/TestAuthenticationMiddleware/MissingAuthHeader
+=== RUN   TestIntegrationSuite/TestAuthenticationMiddleware/ValidAuthHeader
+=== RUN   TestIntegrationSuite/TestErrorHandling
+=== RUN   TestIntegrationSuite/TestErrorHandling/InvalidJSON
+=== RUN   TestIntegrationSuite/TestErrorHandling/NonExistentApplication
+=== RUN   TestIntegrationSuite/TestConcurrentRequests
+=== RUN   TestIntegrationSuite/TestConcurrentRequests/ConcurrentHealthChecks
+=== RUN   TestIntegrationSuite/TestConcurrentRequests/ConcurrentApplicationListing
+--- PASS: TestIntegrationSuite (2.34s)
+PASS
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Database Connection Failed**
+   ```
+   Error: failed to connect to database
+   ```
+   - Ensure PostgreSQL is running
+   - Check database credentials
+   - Verify test database exists
+
+2. **Migration Errors**
+   ```
+   Error: failed to run migrations
+   ```
+   - Ensure migration files are in the correct location
+   - Check database permissions
+   - Verify migration file format
+
+3. **Port Already in Use**
+   ```
+   Error: bind: address already in use
+   ```
+   - The test server uses random ports, but check if other services are running
+   - Stop any running instances of the API service
+
+4. **Test Timeouts**
+   ```
+   Error: test timed out
+   ```
+   - Increase test timeout values
+   - Check database performance
+   - Verify network connectivity
+
+### Debug Mode
+
+To run tests with additional debugging:
+
+```bash
+# Enable debug logging
+LOG_LEVEL=debug go test -v ./test/...
+
+# Run with race detection
+go test -race -v ./test/...
+
+# Run with memory profiling
+go test -memprofile=mem.prof -v ./test/...
+```
+
+## Test Architecture
+
+The integration tests use:
+
+- **testify/suite**: For organized test suites with setup/teardown
+- **httptest**: For HTTP server testing
+- **testify/assert**: For test assertions
+- **testify/require**: For test requirements
+
+The test structure follows the same clean architecture as the main application:
+
+```
+test/
+├── integration_test.go    # Main integration test suite
+├── test_helpers.go        # Test utilities and mocks
+└── README.md             # This documentation
+```
+
+## Contributing
+
+When adding new integration tests:
+
+1. Follow the existing test patterns
+2. Clean up test data properly
+3. Use descriptive test names
+4. Add appropriate assertions
+5. Update this README if needed
+
+## Performance Benchmarks
+
+The concurrent load tests provide basic performance benchmarks:
+
+- **Health Check Load**: 50 concurrent requests
+- **Application Listing Load**: 20 concurrent requests
+- **Expected Response Time**: < 100ms for health checks
+- **Expected Throughput**: > 100 requests/second
+
+These benchmarks help ensure the service can handle reasonable concurrent load.