Implementation:BerriAI Litellm Mock Client Factory

Attribute	Value
Sources	`litellm/integrations/mock_client_factory.py`
Domains	Testing, Mocking, HTTP Clients, Integration Testing
Last Updated	2026-02-15 16:00 GMT

Overview

The Mock Client Factory provides a configurable factory pattern for creating mock HTTP clients that intercept API calls and return mock responses, enabling integration testing without actual network calls.

Description

This module implements a factory function create_mock_client_factory() that, given a MockClientConfig, produces two functions: create_mock_client() (which monkey-patches HTTP handlers) and should_use_mock() (which checks environment variables). The factory supports patching AsyncHTTPHandler.post, httpx.Client.post, and HTTPHandler.post based on URL matching. When a request URL matches the configured matchers, the patched methods return a MockResponse object with configurable status codes, JSON data, and simulated latency (controlled by the {NAME}_MOCK_LATENCY_MS environment variable). Non-matching URLs are forwarded to the original HTTP handlers. The MockResponse class implements the standard httpx response interface (json(), text, content, raise_for_status(), etc.). Each integration (GCS, Langfuse, Braintrust, PostHog, etc.) creates its own mock client via this factory.

Usage

Import and use create_mock_client_factory() when building mock modes for logging integrations. Pass a MockClientConfig with the integration name, environment variable, URL matchers, and response defaults.

Code Reference

Source Location

litellm/integrations/mock_client_factory.py

Signature

@dataclass
class MockClientConfig:
    name: str
    env_var: str
    default_latency_ms: int = 100
    default_status_code: int = 200
    default_json_data: Optional[Dict] = None
    url_matchers: Optional[List[str]] = None
    patch_async_handler: bool = True
    patch_sync_client: bool = False
    patch_http_handler: bool = False

class MockResponse:
    def __init__(self, status_code: int = 200, json_data: Optional[Dict] = None, url: Optional[str] = None, elapsed_seconds: float = 0.0)

def create_mock_client_factory(config: MockClientConfig) -> Tuple[Callable, Callable]

Import

from litellm.integrations.mock_client_factory import (
    create_mock_client_factory,
    MockClientConfig,
    MockResponse,
)

I/O Contract

Inputs

Parameter	Type	Required	Description
`config`	`MockClientConfig`	Yes	Configuration specifying the mock behavior.

MockClientConfig fields:

Field	Type	Description
`name`	`str`	Integration name (e.g., "GCS", "LANGFUSE").
`env_var`	`str`	Environment variable to enable mock mode (e.g., "GCS_MOCK").
`default_latency_ms`	`int`	Simulated latency in milliseconds. Default 100.
`default_status_code`	`int`	HTTP status code for mock responses. Default 200.
`default_json_data`	`Optional[Dict]`	JSON body for mock responses.
`url_matchers`	`Optional[List[str]]`	Strings to match in request URLs.
`patch_async_handler`	`bool`	Whether to patch `AsyncHTTPHandler.post`. Default True.
`patch_sync_client`	`bool`	Whether to patch `httpx.Client.post`. Default False.
`patch_http_handler`	`bool`	Whether to patch `HTTPHandler.post`. Default False.

Outputs

Output	Type	Description
Return value	`Tuple[Callable, Callable]`	Returns `(create_mock_client, should_use_mock)` functions.

Usage Examples

from litellm.integrations.mock_client_factory import (
    create_mock_client_factory,
    MockClientConfig,
)

# Create a mock factory for a custom integration
config = MockClientConfig(
    name="MY_SERVICE",
    env_var="MY_SERVICE_MOCK",
    default_latency_ms=50,
    default_status_code=200,
    default_json_data={"status": "ok"},
    url_matchers=["api.myservice.com"],
    patch_async_handler=True,
    patch_http_handler=True,
)

create_mock_client, should_use_mock = create_mock_client_factory(config)

# Check if mock mode is enabled
if should_use_mock():
    create_mock_client()
    # Now all HTTP requests to api.myservice.com will be intercepted

Related Pages

BerriAI_Litellm_Braintrust_Logger - uses mock client factory for testing
BerriAI_Litellm_PostHog_Logger - uses mock client factory for testing

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment