zai-proxy/notes/bf-3zp.md

# Test Infrastructure for Mock Upstream Server (bf-3zp)

## Summary

Created comprehensive test infrastructure for retry/response-validation tests in the proxy package. This provides a solid foundation for testing retry logic, response validation, and error handling without hitting the real `api.z.ai` upstream.

## Changes Made

### 1. New File: `proxy/helpers_test.go`

Created a comprehensive test helper package with:

#### Test Mode Configuration
- `IsTestMode()` - Detects when running in test mode
- `GetTestMaxRetries()` - Returns reduced retry count (1) for fast tests
- `ConfigureTestEnv(t *testing.T)` - Sets up environment for fast test execution
- Environment variables: `ZAI_PROXY_TEST_MODE`, `MAX_RETRIES`

#### Mock Upstream Server (`MockUpstream`)
- `NewMockUpstream(scenario string)` - Creates configurable mock upstream server
- Scenarios supported:
  - `429-with-retry-after-then-success` - Rate limiting with Retry-After header
  - `429-no-header-then-429` - Rate limiting without header
  - `empty-json-body` - Returns 200 OK with empty body
  - `invalid-json-body` - Returns 200 OK with malformed JSON
  - `empty-streaming` - Returns empty streaming response
  - `422-no-retry` - Unprocessable entity (no retry)
  - `500-no-retry` - Internal server error (no retry)
  - `404-no-retry` - Not found (no retry)
  - `network-error-then-success` - Simulates connection issues
  - `success` - Immediate success response

- Configuration methods:
  - `SetFailUntilCount(count)` - Configure number of initial failures
  - `SetRetryAfter(seconds)` - Set Retry-After header value
  - `SetDelayMs(ms)` - Add response delay
  - `SetCustomHandler(handler)` - Override with custom logic
  - `ResetCounters()` - Reset request tracking
  - `GetRequestCount()` - Get number of requests received
  - `Close()` - Shutdown the server
  - `URL()` - Get server URL for testing

#### Request Builders
- `CreateProxyRequest(method, url, body)` - Generic HTTP request builder
- `CreateMessagesRequest(body)` - POST /v1/messages request
- `CreateStreamingRequestBody()` - Streaming request JSON body
- `CreateNonStreamingRequestBody()` - Non-streaming request JSON body
- `CreateStreamingMessagesRequest()` - Complete streaming request
- `CreateNonStreamingMessagesRequest()` - Complete non-streaming request
- `CreateTestRequestBody(model, messages, stream)` - Custom request body builder

#### Response Assertions
- `AssertStatusCode(t, resp, expected)` - Verify HTTP status code
- `AssertJSONBody(t, resp)` - Verify response is valid JSON
- `AssertResponseField(t, resp, field, value)` - Verify JSON field value
- `AssertEmptyBody(t, resp)` - Verify empty response body
- `AssertHeader(t, resp, header, value)` - Verify header value
- `AssertContentType(t, resp, contentType)` - Verify Content-Type header
- `AssertDurationAtLeast(t, actual, minimum, msg)` - Verify minimum duration
- `AssertDurationInRange(t, actual, min, max, msg)` - Verify duration range

#### Proxy Handler Factory
- `CreateTestProxyHandler(t, upstreamURL, maxRetries)` - Creates configured ProxyHandler for testing
- Automatically disables token counting and sets high rate limits

#### Test Execution Helpers
- `ExecuteProxyRequest(t, handler, req)` - Execute request through handler
- `ExecuteProxyRequestWithBody(t, handler, url, body)` - Execute POST request
- `ExecuteMessagesRequest(t, handler, body)` - Execute /v1/messages request
- `AssertUpstreamCallCount(t, mock, expected)` - Verify upstream request count

#### Response Reader Helpers
- `ReadResponseBody(t, resp)` - Read and return response body
- `ReadJSONResponse(t, resp)` - Parse response as JSON map

#### Backoff Delay Helpers
- `CalculateBackoffDelay(attempt)` - Calculate exponential backoff delay
- `CalculateTotalMaxDelay(maxRetries)` - Calculate total maximum delay

#### Mock Server Helpers
- `CreateCountingMockServer(t)` - Simple counting mock server
- `CountingMockServer` - Mock server with request counting

### 2. Test Configuration

Tests now run with fast configuration:
- `MAX_RETRIES=1` by default (reduced from production 3)
- `ZAI_PROXY_TEST_MODE=true` for test detection
- High rate limits (1000 req/s) to avoid rate limiting in tests
- Token counting disabled for simplicity

### 3. Test Coverage

Added comprehensive tests:
- `TestHelperFunctions` - Validates all helper functions work correctly
- `TestMockUpstreamBasic` - Validates mock server scenarios

### 4. Acceptance Criteria Met

✅ New test helpers in `proxy/helpers_test.go` that create httptest servers
✅ Helper functions for building test requests and asserting responses
✅ Test-mode flag/env var that reduces delays for retry tests
✅ `go test ./proxy/ -run TestHelper` passes (basic smoke test)

## Usage Example

```go
func TestMyRetryLogic(t *testing.T) {
    // Configure test environment
    ConfigureTestEnv(t)

    // Create mock upstream that returns 429 twice, then success
    mock := NewMockUpstream("429-with-retry-after-then-success")
    defer mock.Close()
    mock.SetFailUntilCount(2)
    mock.SetRetryAfter("1")

    // Create test proxy handler
    handler := CreateTestProxyHandler(t, mock.URL, 2)

    // Execute request
    req := CreateNonStreamingMessagesRequest()
    resp := ExecuteProxyRequest(t, handler, req)

    // Assert result
    AssertStatusCode(t, resp, http.StatusOK)
    AssertUpstreamCallCount(t, mock, 3) // 1 initial + 2 retries
}
```

## Benefits

1. **Fast Tests**: Reduced retry count (1 instead of 3) means tests run in ~1s instead of ~7s
2. **No External Dependencies**: Tests never hit real `api.z.ai`
3. **Comprehensive Coverage**: All error scenarios (429, 422, 500, 404, empty body, invalid JSON, etc.)
4. **Easy to Use**: Simple helper functions for common operations
5. **Consistent**: Reusable infrastructure across all proxy tests

## Integration

The test infrastructure is fully compatible with existing tests in `retry_test.go` and can be used for:
- Retry logic tests
- Response validation tests
- Rate limiter tests
- Error handling tests
- Performance benchmarks