# Testing Guide for KMS API

This directory contains comprehensive testing for the Key Management Service (KMS) API, including both Go integration tests and end-to-end bash script tests.

## Test Types

### 1. Go Integration Tests (`integration_test.go`)
Comprehensive Go-based integration tests using the testify framework.

### 2. End-to-End Bash Tests (`e2e_test.sh`)
Curl-based end-to-end tests that can be run against any running KMS server instance.

---

## Go Integration Tests

### Test Coverage

The Go integration tests cover:

#### **Health Check Endpoints**
- Basic health check (`/health`)
- Readiness check with database connectivity (`/ready`)

#### **Application CRUD Operations**
- Create new applications
- List applications with pagination
- Get specific applications by ID
- Update application details
- Delete applications

#### **Static Token Workflow**
- Create static tokens for applications
- Verify static token permissions
- Token validation and permission checking

#### **User Token Authentication Flow**
- User login process
- Token generation for users
- Permission-based access control

#### **Authentication Middleware**
- Header-based authentication validation
- Unauthorized access handling
- User context management

#### **Error Handling**
- Invalid JSON request handling
- Non-existent resource handling
- Proper HTTP status codes

#### **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 Go Integration Tests

#### Run All Integration Tests

```bash
# From the project root directory
go test -v ./test/...
```

#### Run with Coverage

```bash
# Generate coverage report
go test -v -coverprofile=coverage.out ./test/...
go tool cover -html=coverage.out -o coverage.html
```

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

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

---

## End-to-End Bash Tests

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

### E2E Test Coverage

The bash 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

---

## Test Configuration

### Go Integration Tests Configuration
The Go 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

Both test suites:

- **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

## 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. **Server Not Ready (E2E Tests)**
   ```
   [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

### Debug Mode

#### For Go Tests
```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/...
```

#### For E2E Tests
For more detailed output, you can modify the script to include verbose curl output by adding `-v` flag to curl commands.

## Integration with CI/CD

Both test suites work well in CI/CD pipelines:

```yaml
# Example GitHub Actions workflow
- name: Run Integration Tests
  run: |
    docker-compose up -d
    sleep 10  # Wait for services to start
    go test -v ./test/...
    ./test/e2e_test.sh
    docker-compose down
  env:
    BASE_URL: http://localhost:8080
    USER_EMAIL: ci@example.com
```

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

## Test Architecture

### Go Integration Tests
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

### E2E Bash Tests
The bash script provides:

- **Automatic Server Detection**: Waits for server readiness
- **Dynamic Test Data**: Creates and cleans up test resources
- **Comprehensive Error Testing**: Tests various error conditions
- **Robust Error Handling**: Graceful cleanup and clear error messages

## Contributing

When adding new 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 documentation if needed

## File Structure

```
test/
├── integration_test.go    # Go integration test suite
├── test_helpers.go        # Test utilities and mocks
├── mock_repositories.go   # Mock implementations for testing
├── e2e_test.sh           # Bash end-to-end test script
└── README.md             # This comprehensive testing guide