foxhunt/services/api_gateway/tests/README.md

# API Gateway Integration Tests

Comprehensive integration tests for the 8-layer authentication pipeline.

## Test Structure

```
tests/
├── integration_tests.rs      # Main test harness
├── auth_flow_tests.rs        # Authentication flow tests (11 tests)
├── rate_limiting_tests.rs    # Rate limiting tests (9 tests)
├── service_proxy_tests.rs    # Backend proxy tests (8 tests)
├── common/                   # Test utilities
│   └── mod.rs               # JWT generation, Redis helpers
├── docker-compose.yml        # Test dependencies (Redis, PostgreSQL)
└── README.md                # This file
```

## Prerequisites

### Start Test Dependencies

```bash
cd services/api_gateway/tests
docker-compose up -d
```

This starts:
- Redis on port 6380 (for JWT revocation and rate limiting)
- PostgreSQL on port 5433 (for configuration, if needed)

### Verify Services

```bash
# Check Redis
docker exec api_gateway_test_redis redis-cli ping

# Check PostgreSQL
docker exec api_gateway_test_postgres pg_isready
```

## Running Tests

### All Integration Tests

```bash
cargo test --test integration_tests
```

### Specific Test Modules

```bash
# Authentication flow tests only
cargo test --test integration_tests auth_flow

# Rate limiting tests only
cargo test --test integration_tests rate_limiting

# Service proxy tests only
cargo test --test integration_tests service_proxy
```

### Specific Tests

```bash
# Single test
cargo test --test integration_tests test_successful_authentication

# Tests matching pattern
cargo test --test integration_tests test_rate_limit
```

### With Output

```bash
# Show println! output
cargo test --test integration_tests -- --nocapture

# Show test names
cargo test --test integration_tests -- --show-output
```

## Test Coverage

### Authentication Flow Tests (11 tests)

1. `test_successful_authentication` - Complete 8-layer auth pipeline
2. `test_missing_jwt_rejected` - Missing Authorization header
3. `test_revoked_jwt_rejected` - Blacklisted JWT
4. `test_expired_jwt_rejected` - Expired token
5. `test_invalid_signature_rejected` - Wrong signature
6. `test_rbac_permission_denied` - Missing permissions
7. `test_rate_limit_exceeded` - Rate limiting
8. `test_8_layer_auth_performance` - Performance metrics (P50/P99)
9. `test_concurrent_authentication` - Concurrent requests
10. `test_user_context_injection` - Metadata enrichment
11. `test_malformed_authorization_header` - Invalid headers

### Rate Limiting Tests (9 tests)

1. `test_rate_limiter_basic` - Basic rate limiting
2. `test_rate_limiter_per_user` - Per-user isolation
3. `test_rate_limiter_concurrent_requests` - Concurrent handling
4. `test_rate_limiter_performance` - <50ns target
5. `test_rate_limiter_reset_behavior` - Window reset
6. `test_rate_limiter_multiple_users` - 10 independent users
7. `test_rate_limiter_burst_handling` - Burst requests
8. `test_rate_limiter_edge_cases` - Low/high limits
9. `test_rate_limiter_sustained_load` - 2-second load test

### Service Proxy Tests (8 tests)

1. `test_ml_training_proxy_config` - Default configuration
2. `test_ml_training_proxy_custom_config` - Custom settings
3. `test_circuit_breaker_config_validation` - CB validation
4. `test_connection_timeout_behavior` - Timeout handling
5. `test_service_proxy_error_handling` - Error scenarios
6. `test_backend_config_serialization` - Debug/Clone
7. `test_multiple_backend_configs` - Multi-environment
8. `test_proxy_performance_overhead` - Config creation <10μs

## Performance Targets

| Component | Target | Measured By |
|-----------|--------|-------------|
| Total auth overhead | <10μs | `test_8_layer_auth_performance` |
| JWT validation | <1μs | Included in total |
| Revocation check | <500ns | Redis in-memory |
| Authorization | <100ns | Cached permissions |
| Rate limiting | <50ns | `test_rate_limiter_performance` |
| Context injection | <100ns | Metadata write |

## Test Utilities

### JWT Generation

```rust
use common::{generate_test_token, generate_expired_token};

// Valid token
let (token, jti) = generate_test_token(
    "user123",
    vec!["trader".to_string()],
    vec!["api.access".to_string()],
    3600, // TTL in seconds
)?;

// Expired token
let expired = generate_expired_token("user456")?;
```

### Redis Cleanup

```rust
use common::{wait_for_redis, cleanup_redis};

// Wait for Redis to be ready
wait_for_redis("redis://localhost:6380", 50).await?;

// Clean up test data
cleanup_redis("redis://localhost:6380").await?;
```

## CI/CD Integration

### GitHub Actions

```yaml
- name: Start test dependencies
  run: |
    cd services/api_gateway/tests
    docker-compose up -d
    sleep 5

- name: Run integration tests
  run: cargo test --test integration_tests

- name: Stop test dependencies
  run: |
    cd services/api_gateway/tests
    docker-compose down -v
```

## Troubleshooting

### Redis Connection Failed

```bash
# Check if Redis is running
docker ps | grep api_gateway_test_redis

# View Redis logs
docker logs api_gateway_test_redis

# Restart Redis
docker-compose restart redis
```

### Port Conflicts

If ports 6380 or 5433 are already in use:

```bash
# Edit docker-compose.yml to use different ports
# Then restart
docker-compose down
docker-compose up -d
```

### Performance Tests Failing

Performance tests may fail in CI/CD environments due to:
- Shared CPU resources
- Network latency
- Docker overhead

Consider adjusting thresholds or using `#[ignore]` for strict performance tests.

## Adding New Tests

1. Create test file in `tests/`
2. Add module declaration to `integration_tests.rs`
3. Use `common::` utilities for setup
4. Document performance expectations

Example:

```rust
// tests/new_feature_tests.rs
mod common;

#[tokio::test]
async fn test_new_feature() -> Result<()> {
    println!("\n=== Test: New Feature ===");
    
    // Setup
    let auth = setup_auth_components().await?;
    
    // Test logic
    // ...
    
    println!("  ✓ Test passed");
    Ok(())
}
```

## Clean Up

```bash
# Stop and remove test containers
cd services/api_gateway/tests
docker-compose down -v

# Remove test data volumes
docker volume prune -f
```