Feature proposal: official scripted HTTP test client for offline SDK tests

Proposal

Add a small official scripted/test HttpClient implementation so Java applications can test OpenAI SDK integration deterministically without making live network/API calls or standing up a local HTTP server.

The SDK already has a core HttpClient abstraction underneath the OkHttp implementation. A test-focused implementation could use that same boundary while remaining separate from generated resource/model code.

Conceptually:

ScriptedHttpClient http = ScriptedHttpClient.builder()
    .expectRequest(request -> {
        assertEquals("POST", request.method().name());
        assertEquals("/v1/responses", request.path());
    })
    .respondJson(200, fixture("response.json"))
    .build();

OpenAIClient client = OpenAIClient.builder()
    .httpClient(http)
    .apiKey("test")
    .build();

A deliberately small first version could support:

• queueing scripted HTTP responses;
• capturing requests and asserting method/path/query/headers/body;
• ordinary JSON responses;
• SSE/streaming response fixtures;
• scripted HTTP error responses and transport failures;
• cancellation/async completion behaviour where applicable;
• request history plus a final assertion that all expected interactions occurred;
• no network access and no dependency on a real API key.

Why this is useful

SDK users often need to test their own integration logic around request construction, streaming, retries/errors, cancellation, and response handling. Today that generally requires a third-party HTTP mock server, custom fake transport, or live API calls.

A first-party scripted transport would let tests exercise the real generated OpenAI client and serialization/parsing layers while replacing only the HTTP boundary. It would also provide a stable testing primitive that follows SDK changes rather than forcing applications to maintain their own transport doubles.

Scope / compatibility

This should be Java 8-compatible and can live in a small optional testing module/package so normal runtime users do not pay for additional dependencies or custom-code surface unnecessarily.

This is not a production traffic recorder/replayer. Responses and expected requests are explicitly authored test fixtures, which avoids accidentally capturing prompts, credentials, or production data.

I searched current issues for mock/test transports, offline testing, fixtures, record/replay, and MockWebServer-style support and did not find an equivalent proposal.

Given that much of this SDK is generated and the custom-code budget is intentionally limited, I am proposing this as a bounded helper around the existing HttpClient abstraction rather than changes throughout the generated API surface.

Start by inspecting the existing core HttpClient abstraction and its OkHttp implementation to understand the boundary available for a test transport. The proposal describes a broad first version covering scripted responses, request assertions, streaming, failures, cancellation, and interaction completion; done would require an agreed scope and tests for the selected behaviors without network access.