Testing Utilities & VCR

Relevant source files

The following files were used as context for generating this wiki page:

• internal/testutil/vcr.go
• toolrunner/runner_test.go
• betamessage_test.go
• CONTRIBUTING.md
• aws/aws_test.go

The Anthropic Go SDK employs a robust testing infrastructure designed to handle complex API interactions, tool executions, and streaming responses. This system relies on a combination of a Mock Server, VCR (Video Cassette Recorder) snapshots for HTTP traffic, and Golden files for verifying complex outputs.

The primary goal of these utilities is to ensure deterministic testing of non-deterministic AI responses and to provide a mechanism for running tests without requiring active network connections to the Anthropic API.

Sources: CONTRIBUTING.md:46-52, internal/testutil/vcr.go:1-35

VCR (Video Cassette Recorder) System

The VCR system captures real HTTP interactions and saves them to "cassette" files (YAML format). Subsequent test runs replay these cassettes instead of making live network calls.

VCR Architecture and Flow

The system utilizes the go-vcr library to intercept HTTP traffic via a custom http.Client transport.

The diagram shows the decision logic for the VCR recorder based on environment variables and the data flow between tests and the API.
Sources: internal/testutil/vcr.go:15-32

Key VCR Components

Component	Description	Location
NewVCRHTTPClient	Primary helper to initialize a client wired to a recorder.	internal/testutil/vcr.go
ANTHROPIC_LIVE	Environment variable. If set to 1, the recorder captures new traffic.	internal/testutil/vcr.go
testdata/cassettes	Storage directory for captured YAML interaction files.	internal/testutil/vcr.go

Sources: internal/testutil/vcr.go:15-28

Golden File Testing

Golden files are used to verify the consistency of large or complex assistant responses, such as those produced by the ToolRunner. Instead of asserting against hardcoded strings, the test compares the actual output against a "golden" snapshot file.

Implementation in ToolRunner

Tests utilize testutil.CompareGolden to validate assistant text content.

func TestToolRunner_All_Basic(t *testing.T) {
    // ... setup runner ...
    got := []byte(assistantText(last) + "\n")
    testutil.CompareGolden(t, "testdata/snapshots/tool_runner_basic.golden", got)
}

Sources: toolrunner/runner_test.go:88-108

Mock Server Integration

For general unit testing and CI environments, the SDK documentation recommends using a mock server. This server is typically generated or run against the OpenAPI specification.

• Setup: Users are encouraged to run ./scripts/mock before running tests.
• Base URL Handling: Tests check for TEST_API_BASE_URL to point the client toward the local mock server instead of the live API.

Sources: CONTRIBUTING.md:46-50, betamessage_test.go:21-25

Testing Service Integrations

Testing for specific providers like AWS Bedrock involves verifying header injection and authentication logic (SigV4) without necessarily calling the cloud provider.

AWS Signature Verification Flow

The testing suite for AWS Bedrock captures requests to verify that the middleware correctly signs requests and injects required headers like Anthropic-Workspace-Id.

This diagram illustrates how the aws_test.go suite intercepts requests to validate signature fragments and workspace metadata.
Sources: aws/aws_test.go:42-53, aws/aws_test.go:134-155

Summary of Test Utilities

Utility	Primary Use Case	File Reference
NewVCRHTTPClient	Integration tests requiring realistic API response replays.	internal/testutil/vcr.go
CompareGolden	Asserting against long-form text or complex JSON structures.	toolrunner/runner_test.go
CheckTestServer	Ensuring the mock environment is active before proceeding.	betamessage_test.go
capturedRequest	Verifying headers (Auth, Workspace ID) in cloud-specific clients.	aws/aws_test.go

Sources: internal/testutil/vcr.go, toolrunner/runner_test.go, aws/aws_test.go

The testing utilities in this repository provide a layered approach to verification. By combining VCR-backed integration tests with golden snapshotting, the SDK maintains high reliability across complex stateful operations like multi-turn tool use and streaming.