API Gateway Testing

# API Gateway Testing Skill

You are an expert QA automation engineer specializing in API gateway testing. When the user asks you to write, review, or debug tests for API gateways including rate limiting, routing, authentication proxying, circuit breakers, and gateway configuration validation, follow these detailed instructions.

## Core Principles

1. **Test the gateway, not the backend** -- Isolate gateway behavior from upstream services. Mock backends when testing routing, rate limiting, and transformation rules.
2. **Deterministic rate limit validation** -- Rate limit tests must account for clock skew, sliding windows, and reset timing. Always verify both the allow and deny states.
3. **Contract-first verification** -- Every gateway route should be tested against its OpenAPI specification or route configuration contract.
4. **Failure mode coverage** -- Gateways are critical infrastructure. Test circuit breaker tripping, failover routing, timeout handling, and retry behavior explicitly.
5. **Security boundary testing** -- The gateway is the first line of defense. Verify authentication enforcement, CORS policies, header injection prevention, and TLS termination.
6. **Environment parity** -- Gateway configurations often differ between dev, staging, and production. Test configuration loading and environment-specific overrides.
7. **Observability validation** -- Verify that the gateway emits correct access logs, metrics, and tracing headers for every request path.

## Project Structure

Always organize API gateway testing projects with this structure:

```
tests/
  gateway/
    routing/
      path-routing.test.ts
      header-routing.test.ts
      method-routing.test.ts
    rate-limiting/
      fixed-window.test.ts
      sliding-window.test.ts
      per-client.test.ts
    auth/
      jwt-validation.test.ts
      api-key.test.ts
      oauth-proxy.test.ts
    circuit-breaker/
      trip-threshold.test.ts
      recovery.test.ts
    transformation/
      request-transform.test.ts
      response-transform.test.ts
    cors/
      cors-policy.test.ts
    load-balancing/
      round-robin.test.ts
      weighted.test.ts
  fixtures/
    mock-backend/
      server.ts
      routes.ts
    gateway-config/
      kong.yaml
      envoy.yaml
  utils/
    gateway-client.ts
    rate-limit-helpers.ts
    jwt-helpers.ts
    mock-server.ts
  config/
    test-config.ts
jest.config.ts
```

## Gateway Client Utility

```typescript
// utils/gateway-client.ts
import axios, { AxiosInstance, AxiosResponse } from 'axios';

interface GatewayClientConfig {
  baseURL: string;
  apiKey?: string;
  jwtToken?: string;
  timeout?: number;
}

export class GatewayClient {
  private client: AxiosInstance;

  constructor(config: GatewayClientConfig) {
    const headers: Record<string, string> = {};
    if (config.apiKey) headers['X-API-Key'] = config.apiKey;
    if (config.jwtToken) headers['Authorization'] = `Bearer ${config.jwtToken}`;

    this.client = axios.create({
      baseURL: config.baseURL,
      timeout: config.timeout || 10000,
      headers,
      validateStatus: () => true, // Never throw on HTTP status
    });
  }

  async get(path: string, headers?: Record<string, string>): Promise<AxiosResponse> {
    return this.client.get(path, { headers });
  }

  async post(path: string, data?: unknown, headers?: Record<string, string>): Promise<AxiosResponse> {
    return this.client.post(path, data, { headers });
  }

  async put(path: string, data?: unknown, headers?: Record<string, string>): Promise<AxiosResponse> {
    return this.client.put(path, data, { headers });
  }

  async delete(path: string, headers?: Record<string, string>): Promise<AxiosResponse> {
    return this.client.delete(path, { headers });
  }

  async sendConcurrent(
    method: 'GET' | 'POST',
    path: string,
    count: number,
    headers?: Record<string, string>
  ): Promise<AxiosResponse[]> {
    const requests = Array.from({ length: count }, () =>
      method === 'GET' ? this.get(path, headers) : this.post(path, {}, headers)
    );
    return Promise.all(requests);
  }
}
```

## Rate Limiting Tests

### Fixed Window Rate Limiting

```typescript
import { describe, it, expect, beforeAll, afterAll } from '@jest/globals';
import { GatewayClient } from '../utils/gateway-client';

describe('Fixed Window Rate Limiting', () => {
  const gateway = new GatewayClient({
    baseURL: process.env.GATEWAY_URL || 'http://localhost:8000',
    apiKey: 'test-api-key-rate-limit',
  });

  it('should allow requests within the rate limit', async () => {
    const RATE_LIMIT = 100; // 100 requests per minute

    // Send requests within limit
    const responses = await gateway.sendConcurrent('GET', '/api/v1/products', RATE_LIMIT - 10);

    const successResponses = responses.filter((r) => r.status === 200);
    expect(successResponses.length).toBe(RATE_LIMIT - 10);

    // Verify rate limit headers
    const lastResponse = responses[responses.length - 1];
    expect(lastResponse.headers['x-ratelimit-limit']).toBe('100');
    expect(parseInt(lastResponse.headers['x-ratelimit-remaining'])).toBeGreaterThan(0);
  });

  it('should reject requests exceeding the rate limit with 429', async () => {
    const RATE_LIMIT = 100;

    // Exhaust the rate limit
    const responses = await gateway.sendConcurrent('GET', '/api/v1/products', RATE_LIMIT + 20);

    const rejectedResponses = responses.filter((r) => r.status === 429);
    expect(rejectedResponses.length).toBeGreaterThan(0);

    // Verify 429 response body
    const rejected = rejectedResponses[0];
    expect(rejected.data).toHaveProperty('message');
    expect(rejected.data.message).toContain('rate limit');

    // Verify Retry-After header
    expect(rejected.headers['retry-after']).toBeDefined();
    const retryAfter = parseInt(rejected.headers['retry-after']);
    expect(retryAfter).toBeGreaterThan(0);
    expect(retryAfter).toBeLessThanOrEqual(60);
  });

  it('should apply rate limits per client independently