Skip to main content

Testing

Testing language models can be challenging, because they are non-deterministic and calling them is slow and expensive.

The Go AI SDK is designed with testability in mind. All models are interfaces, which makes it easy to create mock implementations for testing. This allows you to test your code in a repeatable and deterministic way without actually calling a language model provider.

Testing Strategies​

1. Use the SDK mocks​

The pkg/testutil package ships ready-made mocks for every model type: MockLanguageModel, MockEmbeddingModel, MockImageModel, MockSpeechModel, MockTranscriptionModel, MockRerankingModel and MockProvider. Each mock has a Do...Func field you can set to control the response, and records the calls it receives.

package myapp

import (
"context"
"testing"

"github.com/digitallysavvy/go-ai/pkg/ai"
"github.com/digitallysavvy/go-ai/pkg/provider"
"github.com/digitallysavvy/go-ai/pkg/provider/types"
"github.com/digitallysavvy/go-ai/pkg/testutil"
)

func TestMockLanguageModel(t *testing.T) {
inputTokens, outputTokens, totalTokens := int64(10), int64(20), int64(30)

model := &testutil.MockLanguageModel{
DoGenerateFunc: func(ctx context.Context, opts *provider.GenerateOptions) (*types.GenerateResult, error) {
return &types.GenerateResult{
Text: "Mock response",
FinishReason: types.FinishReasonStop,
Usage: types.Usage{
InputTokens: &inputTokens,
OutputTokens: &outputTokens,
TotalTokens: &totalTokens,
},
}, nil
},
}

result, err := ai.GenerateText(context.Background(), ai.GenerateTextOptions{
Model: model,
Prompt: "Hello",
})
if err != nil {
t.Fatal(err)
}
if result.Text != "Mock response" {
t.Errorf("unexpected text: %q", result.Text)
}
if len(model.GenerateCalls) != 1 {
t.Errorf("expected 1 call, got %d", len(model.GenerateCalls))
}
}

With no DoGenerateFunc set, MockLanguageModel returns a default "mock response" result. With no DoStreamFunc, it streams "mock " and "response".

2. Mock text stream​

Use testutil.NewMockTextStream to build a stream from a fixed list of chunks:

package myapp

import (
"context"

"github.com/digitallysavvy/go-ai/pkg/provider"
"github.com/digitallysavvy/go-ai/pkg/provider/types"
"github.com/digitallysavvy/go-ai/pkg/testutil"
)

func newStreamingModel(text string) *testutil.MockLanguageModel {
return &testutil.MockLanguageModel{
DoStreamFunc: func(ctx context.Context, opts *provider.GenerateOptions) (provider.TextStream, error) {
return testutil.NewMockTextStream([]provider.StreamChunk{
{Type: provider.ChunkTypeText, Text: text},
{Type: provider.ChunkTypeFinish, FinishReason: types.FinishReasonStop},
}), nil
},
}
}

Use testutil.NewMockTextStreamWithError to simulate a stream that fails.

Testing Examples​

Testing GenerateText​

package myapp

import (
"context"
"testing"

"github.com/digitallysavvy/go-ai/pkg/ai"
"github.com/digitallysavvy/go-ai/pkg/provider"
"github.com/digitallysavvy/go-ai/pkg/provider/types"
"github.com/digitallysavvy/go-ai/pkg/testutil"
)

func TestGenerateText(t *testing.T) {
ctx := context.Background()

tests := []struct {
name string
prompt string
mockResponse string
expectedResult string
expectError bool
}{
{
name: "successful generation",
prompt: "Hello, test!",
mockResponse: "Hello, world!",
expectedResult: "Hello, world!",
expectError: false,
},
{
name: "empty response",
prompt: "Test",
mockResponse: "",
expectedResult: "",
expectError: false,
},
}

for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
// Create mock model
mockModel := &testutil.MockLanguageModel{
DoGenerateFunc: func(ctx context.Context, opts *provider.GenerateOptions) (*types.GenerateResult, error) {
return &types.GenerateResult{
Text: tt.mockResponse,
FinishReason: types.FinishReasonStop,
}, nil
},
}

// Call function under test
result, err := ai.GenerateText(ctx, ai.GenerateTextOptions{
Model: mockModel,
Prompt: tt.prompt,
})

// Assertions
if tt.expectError {
if err == nil {
t.Errorf("expected error, got nil")
}
return
}

if err != nil {
t.Fatalf("unexpected error: %v", err)
}

if result.Text != tt.expectedResult {
t.Errorf("expected %q, got %q", tt.expectedResult, result.Text)
}
})
}
}

Testing StreamText​

package myapp

import (
"context"
"strings"
"testing"

"github.com/digitallysavvy/go-ai/pkg/ai"
"github.com/digitallysavvy/go-ai/pkg/provider"
"github.com/digitallysavvy/go-ai/pkg/provider/types"
"github.com/digitallysavvy/go-ai/pkg/testutil"
)

func TestStreamText(t *testing.T) {
ctx := context.Background()

tests := []struct {
name string
prompt string
mockChunks []string
expectedResult string
}{
{
name: "streaming response",
prompt: "Hello, test!",
mockChunks: []string{"Hello", ", ", "world", "!"},
expectedResult: "Hello, world!",
},
}

for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
// Create mock model
mockModel := &testutil.MockLanguageModel{
DoStreamFunc: func(ctx context.Context, opts *provider.GenerateOptions) (provider.TextStream, error) {
return newMockStreamWithChunks(tt.mockChunks), nil
},
}

// Call function under test
stream, err := ai.StreamText(ctx, ai.StreamTextOptions{
Model: mockModel,
Prompt: tt.prompt,
})
if err != nil {
t.Fatalf("unexpected error: %v", err)
}

// Collect streamed text
var builder strings.Builder
for chunk := range stream.Chunks() {
builder.WriteString(chunk.Text)
}

if err := stream.Err(); err != nil {
t.Fatalf("stream error: %v", err)
}

result := builder.String()
if result != tt.expectedResult {
t.Errorf("expected %q, got %q", tt.expectedResult, result)
}
})
}
}

// newMockStreamWithChunks creates a mock stream with multiple chunks
func newMockStreamWithChunks(chunks []string) provider.TextStream {
streamChunks := make([]provider.StreamChunk, 0, len(chunks)+1)
for _, chunk := range chunks {
streamChunks = append(streamChunks, provider.StreamChunk{
Type: provider.ChunkTypeText,
Text: chunk,
})
}
streamChunks = append(streamChunks, provider.StreamChunk{
Type: provider.ChunkTypeFinish,
FinishReason: types.FinishReasonStop,
})
return testutil.NewMockTextStream(streamChunks)
}

Testing GenerateObject​

package myapp

import (
"context"
"encoding/json"
"testing"

"github.com/digitallysavvy/go-ai/pkg/ai"
"github.com/digitallysavvy/go-ai/pkg/provider"
"github.com/digitallysavvy/go-ai/pkg/provider/types"
"github.com/digitallysavvy/go-ai/pkg/schema"
"github.com/digitallysavvy/go-ai/pkg/testutil"
)

func TestGenerateObject(t *testing.T) {
ctx := context.Background()

objSchema := map[string]interface{}{
"type": "object",
"properties": map[string]interface{}{
"name": map[string]interface{}{"type": "string"},
"age": map[string]interface{}{"type": "number"},
},
"required": []string{"name", "age"},
}

tests := []struct {
name string
mockResponse string
expectedName string
expectedAge float64
expectError bool
}{
{
name: "valid object",
mockResponse: `{"name":"John","age":30}`,
expectedName: "John",
expectedAge: 30,
expectError: false,
},
}

for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
mockModel := &testutil.MockLanguageModel{
DoGenerateFunc: func(ctx context.Context, opts *provider.GenerateOptions) (*types.GenerateResult, error) {
return &types.GenerateResult{
Text: tt.mockResponse,
FinishReason: types.FinishReasonStop,
}, nil
},
}

result, err := ai.GenerateObject(ctx, ai.GenerateObjectOptions{
Model: mockModel,
Schema: schema.NewSimpleJSONSchema(objSchema),
Prompt: "Generate a person",
})

if tt.expectError {
if err == nil {
t.Errorf("expected error, got nil")
}
return
}

if err != nil {
t.Fatalf("unexpected error: %v", err)
}

// Parse the object (result.Object is already unmarshaled into a
// generic interface{}; re-marshal it to decode into a typed struct)
var person struct {
Name string `json:"name"`
Age float64 `json:"age"`
}
objBytes, err := json.Marshal(result.Object)
if err != nil {
t.Fatalf("failed to marshal object: %v", err)
}
if err := json.Unmarshal(objBytes, &person); err != nil {
t.Fatalf("failed to unmarshal object: %v", err)
}

if person.Name != tt.expectedName {
t.Errorf("expected name %q, got %q", tt.expectedName, person.Name)
}

if person.Age != tt.expectedAge {
t.Errorf("expected age %f, got %f", tt.expectedAge, person.Age)
}
})
}
}

Testing Tool Calling​

package myapp

import (
"context"
"testing"

"github.com/digitallysavvy/go-ai/pkg/ai"
"github.com/digitallysavvy/go-ai/pkg/provider"
"github.com/digitallysavvy/go-ai/pkg/provider/types"
"github.com/digitallysavvy/go-ai/pkg/testutil"
)

func TestToolCalling(t *testing.T) {
ctx := context.Background()

weatherTool := types.Tool{
Name: "weather",
Description: "Get the weather",
Parameters: map[string]interface{}{
"type": "object",
"properties": map[string]interface{}{
"location": map[string]interface{}{"type": "string"},
},
"required": []string{"location"},
},
Execute: func(ctx context.Context, input map[string]interface{}, opts types.ToolExecutionOptions) (interface{}, error) {
return map[string]interface{}{
"temperature": 72,
"condition": "sunny",
}, nil
},
}

mockModel := &testutil.MockLanguageModel{
DoGenerateFunc: func(ctx context.Context, opts *provider.GenerateOptions) (*types.GenerateResult, error) {
// Simulate tool call
return &types.GenerateResult{
ToolCalls: []types.ToolCall{
{
ID: "call-1",
ToolName: "weather",
Arguments: map[string]interface{}{
"location": "San Francisco",
},
},
},
FinishReason: types.FinishReasonToolCalls,
}, nil
},
}

result, err := ai.GenerateText(ctx, ai.GenerateTextOptions{
Model: mockModel,
Prompt: "What's the weather?",
Tools: []types.Tool{weatherTool},
})
if err != nil {
t.Fatalf("unexpected error: %v", err)
}

if len(result.ToolResults) == 0 {
t.Errorf("expected tool results, got none")
}
}

Testing with Embedding Models​

package myapp

import (
"context"
"testing"

"github.com/digitallysavvy/go-ai/pkg/ai"
"github.com/digitallysavvy/go-ai/pkg/testutil"
)

func TestEmbed(t *testing.T) {
ctx := context.Background()

mockModel := &testutil.MockEmbeddingModel{}

result, err := ai.Embed(ctx, ai.EmbedOptions{
Model: mockModel,
Input: "test text",
})
if err != nil {
t.Fatalf("unexpected error: %v", err)
}

if len(result.Embedding) != 5 {
t.Errorf("expected 5-dimensional embedding, got %d", len(result.Embedding))
}
}

Testing Best Practices​

1. Use Table-Driven Tests​

Go's table-driven tests are ideal for testing multiple scenarios:

func TestMultipleScenarios(t *testing.T) {
tests := []struct {
name string
input string
expected string
}{
{"scenario 1", "input1", "output1"},
{"scenario 2", "input2", "output2"},
{"scenario 3", "input3", "output3"},
}

for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
// Test logic here
})
}
}

2. Test Error Conditions​

Always test error paths:

func TestErrorHandling(t *testing.T) {
ctx := context.Background()
mockModel := &testutil.MockLanguageModel{
DoGenerateFunc: func(ctx context.Context, opts *provider.GenerateOptions) (*types.GenerateResult, error) {
return nil, errors.New("mock error")
},
}

_, err := ai.GenerateText(ctx, ai.GenerateTextOptions{
Model: mockModel,
Prompt: "test",
})

if err == nil {
t.Error("expected error, got nil")
}
}

3. Test Context Cancellation​

Test that your code respects context cancellation:

func TestContextCancellation(t *testing.T) {
ctx, cancel := context.WithCancel(context.Background())
cancel() // Cancel immediately

mockModel := &testutil.MockLanguageModel{
DoGenerateFunc: func(ctx context.Context, opts *provider.GenerateOptions) (*types.GenerateResult, error) {
// A real model call would fail on a canceled context; the mock
// must check it explicitly since it never makes an HTTP request.
if err := ctx.Err(); err != nil {
return nil, err
}
return &types.GenerateResult{Text: "unreachable"}, nil
},
}

_, err := ai.GenerateText(ctx, ai.GenerateTextOptions{
Model: mockModel,
Prompt: "test",
})

if err == nil {
t.Error("expected context cancellation error")
}
}

4. Use Test Helpers​

Create reusable test helpers:

func newTestModel(response string) *testutil.MockLanguageModel {
return &testutil.MockLanguageModel{
DoGenerateFunc: func(ctx context.Context, opts *provider.GenerateOptions) (*types.GenerateResult, error) {
return &types.GenerateResult{
Text: response,
FinishReason: types.FinishReasonStop,
}, nil
},
}
}

func TestWithHelper(t *testing.T) {
model := newTestModel("test response")
// Use model in test...
}

5. Test Callbacks​

Test that callbacks are called correctly:

func TestOnFinishCallback(t *testing.T) {
ctx := context.Background()
callbackCalled := false

mockModel := &testutil.MockLanguageModel{}

_, err := ai.GenerateText(ctx, ai.GenerateTextOptions{
Model: mockModel,
Prompt: "test",
OnFinish: func(ctx context.Context, result *ai.GenerateTextResult, userContext interface{}) {
callbackCalled = true
},
})

if err != nil {
t.Fatalf("unexpected error: %v", err)
}

if !callbackCalled {
t.Error("OnFinish callback was not called")
}
}

6. Use Subtests for Complex Scenarios​

Break down complex tests into subtests:

func TestComplexScenario(t *testing.T) {
t.Run("setup", func(t *testing.T) {
// Setup test
})

t.Run("execution", func(t *testing.T) {
// Execute test
})

t.Run("validation", func(t *testing.T) {
// Validate results
})
}

7. Mock External Dependencies​

When testing code that uses AI SDK, mock the model interface:

type MyService struct {
model provider.LanguageModel
}

func (s *MyService) ProcessText(ctx context.Context, text string) (string, error) {
result, err := ai.GenerateText(ctx, ai.GenerateTextOptions{
Model: s.model,
Prompt: text,
})
if err != nil {
return "", err
}
return result.Text, nil
}

func TestMyService(t *testing.T) {
mockModel := &testutil.MockLanguageModel{
DoGenerateFunc: func(ctx context.Context, opts *provider.GenerateOptions) (*types.GenerateResult, error) {
return &types.GenerateResult{
Text: "processed: " + opts.Prompt.Messages[0].Content[0].(types.TextContent).Text,
}, nil
},
}

service := &MyService{model: mockModel}
result, err := service.ProcessText(context.Background(), "test")

if err != nil {
t.Fatalf("unexpected error: %v", err)
}

if result != "processed: test" {
t.Errorf("unexpected result: %s", result)
}
}

Integration Testing​

For integration tests with real providers, use build tags to separate them from unit tests:

//go:build integration
// +build integration

package myapp

import (
"context"
"os"
"testing"

"github.com/digitallysavvy/go-ai/pkg/ai"
"github.com/digitallysavvy/go-ai/pkg/providers/openai"
)

func TestRealProvider(t *testing.T) {
if os.Getenv("OPENAI_API_KEY") == "" {
t.Skip("OPENAI_API_KEY not set")
}

ctx := context.Background()
provider := openai.New(openai.Config{APIKey: os.Getenv("OPENAI_API_KEY")})
model, _ := provider.LanguageModel("gpt-6-astra")

result, err := ai.GenerateText(ctx, ai.GenerateTextOptions{
Model: model,
Prompt: "Say hello",
})

if err != nil {
t.Fatalf("unexpected error: %v", err)
}

if result.Text == "" {
t.Error("expected non-empty response")
}
}

Run integration tests with:

go test -tags=integration ./...

See Also​