v0

2025-08-22 14:06:20 -04:00
commit 46264cb556
36 changed files with 7185 additions and 0 deletions
--- a/test/E2E_TESTING.md
+++ b/test/E2E_TESTING.md
@ -0,0 +1,247 @@
+# End-to-End Testing Guide
+
+This document describes how to run end-to-end tests for the KMS (Key Management Service) API using the provided bash script.
+
+## Overview
+
+The `e2e_test.sh` script provides comprehensive end-to-end testing of the KMS API using curl commands. It tests all major functionality including health checks, authentication, application management, and token operations.
+
+## Prerequisites
+
+- `curl` command-line tool installed
+- KMS server running (either locally or remotely)
+- Bash shell environment
+
+## Quick Start
+
+### 1. Start the KMS Server
+
+First, make sure your KMS server is running. You can start it using Docker Compose:
+
+```bash
+# From the project root directory
+docker-compose up -d
+```
+
+Or run it directly:
+
+```bash
+go run cmd/server/main.go
+```
+
+### 2. Run the E2E Tests
+
+```bash
+# Run with default settings (server at localhost:8080)
+./test/e2e_test.sh
+
+# Or run with custom configuration
+BASE_URL=http://localhost:8080 USER_EMAIL=admin@example.com ./test/e2e_test.sh
+```
+
+## Configuration
+
+The script supports several environment variables for configuration:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `BASE_URL` | `http://localhost:8080` | Base URL of the KMS server |
+| `USER_EMAIL` | `test@example.com` | User email for authentication headers |
+| `USER_ID` | `test-user-123` | User ID for authentication headers |
+
+### Examples
+
+```bash
+# Test against a remote server
+BASE_URL=https://kms-api.example.com ./test/e2e_test.sh
+
+# Use different user credentials
+USER_EMAIL=admin@company.com USER_ID=admin-456 ./test/e2e_test.sh
+
+# Test against local server on different port
+BASE_URL=http://localhost:3000 ./test/e2e_test.sh
+```
+
+## Test Coverage
+
+The script tests the following functionality:
+
+### Health Endpoints
+- `GET /health` - Basic health check
+- `GET /ready` - Readiness check with database connectivity
+
+### Authentication Endpoints
+- `POST /api/login` - User login (with and without auth headers)
+- `POST /api/verify` - Token verification
+- `POST /api/renew` - Token renewal
+
+### Application Management
+- `GET /api/applications` - List applications (with pagination)
+- `POST /api/applications` - Create new application
+- `GET /api/applications/:id` - Get application by ID
+- `PUT /api/applications/:id` - Update application
+- `DELETE /api/applications/:id` - Delete application
+
+### Token Management
+- `GET /api/applications/:id/tokens` - List tokens for application
+- `POST /api/applications/:id/tokens` - Create static token
+- `DELETE /api/tokens/:id` - Delete token
+
+### Error Handling
+- Invalid endpoints (404 errors)
+- Malformed JSON requests
+- Missing authentication headers
+- Invalid request formats
+
+### Documentation
+- `GET /api/docs` - API documentation endpoint
+
+## Output Format
+
+The script provides colored output with clear test results:
+
+- 🔵 **[INFO]** - General information and test progress
+- 🟢 **[PASS]** - Successful test cases
+- 🔴 **[FAIL]** - Failed test cases
+- 🟡 **[WARN]** - Warnings and non-critical issues
+
+### Sample Output
+
+```
+[INFO] Starting End-to-End Tests for KMS API
+[INFO] Base URL: http://localhost:8080
+[INFO] User Email: test@example.com
+[INFO] User ID: test-user-123
+
+[INFO] Waiting for server to be ready...
+[PASS] Server is ready!
+
+[INFO] === Testing Health Endpoints ===
+[INFO] Running test: Health Check
+[PASS] Health Check (Status: 200)
+Response: {"status":"healthy","timestamp":"2025-08-22T17:13:26Z"}
+
+[INFO] Running test: Readiness Check
+[PASS] Readiness Check (Status: 200)
+Response: {"status":"ready","timestamp":"2025-08-22T17:13:26Z","checks":{"database":"healthy"}}
+
+...
+
+[INFO] === Test Summary ===
+Tests Run: 25
+Tests Passed: 23
+Tests Failed: 2
+Some tests failed!
+```
+
+## Features
+
+### Automatic Server Detection
+The script waits for the server to be ready before running tests, with a configurable timeout.
+
+### Dynamic Test Data
+- Creates test applications and extracts their IDs for subsequent tests
+- Creates test tokens and uses them for deletion tests
+- Automatically cleans up test data after completion
+
+### Comprehensive Error Testing
+Tests various error conditions including:
+- Missing authentication
+- Invalid JSON payloads
+- Non-existent resources
+- Malformed requests
+
+### Robust Error Handling
+- Graceful handling of network errors
+- Automatic cleanup on script interruption
+- Clear error messages and status codes
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Server Not Ready**
+   ```
+   [FAIL] Server failed to start within timeout
+   ```
+   - Ensure the KMS server is running
+   - Check if the server is accessible at the configured URL
+   - Verify database connectivity
+
+2. **Authentication Failures**
+   ```
+   [FAIL] List applications with auth (Expected: 200, Got: 401)
+   ```
+   - Check if authentication middleware is properly configured
+   - Verify the authentication headers are being processed correctly
+
+3. **Database Connection Issues**
+   ```
+   [FAIL] Readiness Check (Expected: 200, Got: 503)
+   ```
+   - Ensure PostgreSQL database is running
+   - Check database connection configuration
+   - Verify database migrations have been applied
+
+### Debug Mode
+
+For more detailed output, you can modify the script to include verbose curl output:
+
+```bash
+# Add -v flag to curl commands for verbose output
+# Edit the run_test function in e2e_test.sh
+```
+
+### Manual Testing
+
+You can also run individual curl commands manually for debugging:
+
+```bash
+# Test health endpoint
+curl -v http://localhost:8080/health
+
+# Test authentication
+curl -v -X POST http://localhost:8080/api/login \
+  -H "Content-Type: application/json" \
+  -H "X-User-Email: test@example.com" \
+  -H "X-User-ID: test-user-123" \
+  -d '{"app_id": "test-app", "permissions": ["read"]}'
+```
+
+## Integration with CI/CD
+
+The script is designed to work well in CI/CD pipelines:
+
+```yaml
+# Example GitHub Actions workflow
+- name: Run E2E Tests
+  run: |
+    docker-compose up -d
+    sleep 10  # Wait for services to start
+    ./test/e2e_test.sh
+    docker-compose down
+  env:
+    BASE_URL: http://localhost:8080
+    USER_EMAIL: ci@example.com
+```
+
+## Extending the Tests
+
+To add new test cases:
+
+1. Create a new test function following the pattern `test_*`
+2. Use the `run_test` helper function for consistent output
+3. Add the function call to the `main()` function
+4. Update this documentation
+
+Example:
+
+```bash
+test_new_feature() {
+    log_info "=== Testing New Feature ==="
+    
+    run_test "New feature test" "200" \
+        -X GET "$API_BASE/new-endpoint" \
+        -H "X-User-Email: $USER_EMAIL" \
+        -H "X-User-ID: $USER_ID"
+}