skybridge/test/E2E_TESTING.md

# 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"
}