anthropic/testing

Testing utilities for Anthropic API client

This module provides mock responses, test fixtures, and helpers for testing code that uses the anthropic_gleam library.

Two Categories of Test Helpers

This module provides two distinct categories of testing utilities:

1. HTTP Response Mocks (`mock_*` functions)

These functions return Response(String) - raw HTTP responses with JSON bodies. Use these when testing code that handles HTTP responses directly, such as custom HTTP clients or sans-io patterns.

// Returns Response(String) - an HTTP response
let http_response = mock_text_response("Hello!")

// To get a CreateMessageResponse, parse it:
let assert Ok(parsed) = http.parse_messages_response(http_response)

2. Fixture Responses (`fixture_*` functions)

These functions return CreateMessageResponse - pre-parsed domain objects. Use these when testing business logic that works with parsed responses.

// Returns CreateMessageResponse directly
let response = fixture_simple_response()
let text = request.response_text(response)

Quick Reference

Function	Returns	Use Case
`mock_response(text)`	`CreateMessageResponse`	Simple testing with custom text
`mock_text_response(text)`	`Response(String)`	HTTP layer testing
`mock_tool_use_response(...)`	`Response(String)`	HTTP layer testing
`mock_error_response(...)`	`Response(String)`	HTTP error handling
`fixture_simple_response()`	`CreateMessageResponse`	Business logic testing
`fixture_tool_use_response()`	`CreateMessageResponse`	Tool use testing

Example: Testing Business Logic

import anthropic/testing.{mock_response, fixture_tool_use_response}
import anthropic/request

pub fn test_response_handling() {
  // Use mock_response for simple custom text
  let response = mock_response("The answer is 42")
  let text = request.response_text(response)
  assert text == "The answer is 42"

  // Use fixtures for specific scenarios
  let tool_response = fixture_tool_use_response()
  assert request.needs_tool_execution(tool_response) == True
}

Example: Testing HTTP Handling

import anthropic/testing.{mock_text_response, mock_rate_limit_error}
import anthropic/http

pub fn test_http_parsing() {
  // Test successful response parsing
  let http_response = mock_text_response("Hello!")
  let assert Ok(parsed) = http.parse_messages_response(http_response)

  // Test error handling
  let error_response = mock_rate_limit_error()
  let assert Error(err) = http.parse_messages_response(error_response)
}

Values

fixture_conversation_response

</>

pub fn fixture_conversation_response() -> request.CreateMessageResponse

A multi-turn conversation response fixture

Returns a CreateMessageResponse simulating a response in an ongoing conversation.

fixture_max_tokens_response

</>

pub fn fixture_max_tokens_response() -> request.CreateMessageResponse

A max tokens response fixture

Returns a CreateMessageResponse that was truncated due to max_tokens limit. Use this when testing handling of truncated responses.

fixture_simple_response

</>

pub fn fixture_simple_response() -> request.CreateMessageResponse

A simple text response fixture

Returns a CreateMessageResponse with a simple greeting text. Use this for basic response handling tests.

Example

let response = fixture_simple_response()
let text = request.response_text(response)
// text == "Hello! How can I help you today?"

For custom text, use mock_response(text) instead.

fixture_stop_sequence_response

</>

pub fn fixture_stop_sequence_response() -> request.CreateMessageResponse

A stop sequence response fixture

Returns a CreateMessageResponse that stopped due to a custom stop sequence. Use this when testing stop sequence handling.

fixture_tool_use_response

</>

pub fn fixture_tool_use_response() -> request.CreateMessageResponse

A tool use response fixture

Returns a CreateMessageResponse with tool use content. Use this when testing tool execution workflows.

Example

let response = fixture_tool_use_response()
assert request.needs_tool_execution(response) == True
let calls = request.get_pending_tool_calls(response)

has_api_key

</>

pub fn has_api_key() -> Bool

Check if an API key is available for integration tests

mock_auth_error

</>

pub fn mock_auth_error() -> response.Response(String)

Create a mock HTTP authentication error response (401)

mock_error_body

</>

pub fn mock_error_body(
  error_type: String,
  message: String,
) -> String

Build a mock error body JSON

mock_error_response

</>

pub fn mock_error_response(
  status_code: Int,
  error_type: String,
  error_message: String,
) -> response.Response(String)

Create a mock HTTP error response

Returns a Response(String) representing an HTTP error response. Use this when testing error handling code.

Example

let http_response = mock_error_response(400, "invalid_request_error", "Bad request")
let assert Error(err) = http.parse_messages_response(http_response)

mock_invalid_request_error

</>

pub fn mock_invalid_request_error(
  error_message: String,
) -> response.Response(String)

Create a mock HTTP invalid request error response (400)

mock_overloaded_error

</>

pub fn mock_overloaded_error() -> response.Response(String)

Create a mock HTTP overloaded error response (529)

mock_rate_limit_error

</>

pub fn mock_rate_limit_error() -> response.Response(String)

Create a mock HTTP rate limit error response (429)

mock_response

</>

pub fn mock_response(
  text: String,
) -> request.CreateMessageResponse

Create a mock CreateMessageResponse with custom text

This is the simplest way to create a test response. Returns a parsed CreateMessageResponse directly, ready to use with functions like request.response_text().

Example

let response = mock_response("Hello from Claude!")
let text = request.response_text(response)
assert text == "Hello from Claude!"

For more control over the response, use mock_response_with() or the fixture_* functions.

mock_response_with

</>

pub fn mock_response_with(
  text: String,
  model model: String,
  stop_reason stop_reason: option.Option(request.StopReason),
  input_tokens input_tokens: Int,
  output_tokens output_tokens: Int,
) -> request.CreateMessageResponse

Create a mock CreateMessageResponse with custom options

Allows customizing the model, stop reason, and token usage.

Example

let response = mock_response_with(
  "Generated text",
  model: "claude-opus-4-20250514",
  stop_reason: Some(request.MaxTokens),
  input_tokens: 100,
  output_tokens: 500,
)

mock_text_response

</>

pub fn mock_text_response(
  text: String,
) -> response.Response(String)

Create a mock HTTP response with text content

Returns a Response(String) representing an HTTP response from the API. Use this when testing HTTP handling code. To get a CreateMessageResponse, parse it with http.parse_messages_response().

Example

let http_response = mock_text_response("Hello!")
// http_response.status == 200
// http_response.body contains JSON

// To parse into CreateMessageResponse:
let assert Ok(parsed) = http.parse_messages_response(http_response)

For a simpler API that returns CreateMessageResponse directly, use mock_response() instead.

mock_text_response_body

</>

pub fn mock_text_response_body(
  id: String,
  text: String,
) -> String

Build a mock text response body JSON

The generated JSON includes all fields that the Anthropic API returns, including stop_sequence (set to null for text responses).

mock_tool_use_response

</>

pub fn mock_tool_use_response(
  tool_id: String,
  tool_name: String,
  tool_input: String,
) -> response.Response(String)

Create a mock HTTP response with tool use content

Returns a Response(String) representing an HTTP response with tool use. Use this when testing HTTP handling code for tool use scenarios.

Example

let http_response = mock_tool_use_response(
  "toolu_123",
  "get_weather",
  "{\"location\": \"Paris\"}",
)
let assert Ok(parsed) = http.parse_messages_response(http_response)

For pre-parsed tool use responses, use fixture_tool_use_response().

mock_tool_use_response_body

</>

pub fn mock_tool_use_response_body(
  id: String,
  tool_id: String,
  tool_name: String,
  tool_input: String,
) -> String

Build a mock tool use response body JSON

The generated JSON includes all fields that the Anthropic API returns, including stop_sequence (set to null for tool use responses).

Two Categories of Test Helpers

1. HTTP Response Mocks (mock_* functions)

2. Fixture Responses (fixture_* functions)

Quick Reference

Example: Testing Business Logic

Example: Testing HTTP Handling

Example

Example

Example

Example

Example

Example

Example

1. HTTP Response Mocks (`mock_*` functions)

2. Fixture Responses (`fixture_*` functions)