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:

# From the project root directory
docker-compose up -d

Or run it directly:

go run cmd/server/main.go

2. Run the E2E Tests

# 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

# 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:

# 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:

# 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:

# 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:

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