mockllm

package
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 8, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package mockllm provides a mock LLM server for E2E testing.

It implements an OpenAI-compatible chat completions API that can be configured to return specific responses based on message patterns or sequences.

Basic usage: 

server := mockllm.NewServer()
server.OnMessage("hello", mockllm.TextResponse("Hello! How can I help?"))
server.Start(t)
defer server.Close()

// Configure crush to use server.URL() as the provider base URL

Tool call example: 

server := mockllm.NewServer()
server.OnAny(mockllm.ToolCall("ping", `{}`))
server.OnToolResult("ping", mockllm.TextResponse("Pong received!"))
server.Start(t)

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AssertLastMessageContains 

func AssertLastMessageContains(t *testing.T, server *Server, text string)

AssertLastMessageContains checks if the last user message contains the text.

func AssertRequestCount 

func AssertRequestCount(t *testing.T, server *Server, expected int)

AssertRequestCount checks the number of requests made to the server.

func AssertToolWasCalled 

func AssertToolWasCalled(t *testing.T, server *Server, toolName string)

AssertToolWasCalled checks if a specific tool was called.

func AssertToolWasNotCalled 

func AssertToolWasNotCalled(t *testing.T, server *Server, toolName string)

AssertToolWasNotCalled checks that a specific tool was not called.

func EchoResponse 

func EchoResponse(prefix string) func(req *ChatRequest) *ChatResponse

EchoResponse creates a response that echoes the last user message.

func EmptyResponse 

func EmptyResponse() func(req *ChatRequest) *ChatResponse

EmptyResponse creates a response with no content (edge case testing).

func ErrorResponse 

func ErrorResponse(errorMessage string) func(req *ChatRequest) *ChatResponse

ErrorResponse creates a response with an error message.

func MultiToolCallResponse 

func MultiToolCallResponse(calls ...ToolCallSpec) func(req *ChatRequest) *ChatResponse

MultiToolCallResponse creates a response that invokes multiple tools.

func SetupTestEnv 

func SetupTestEnv(t *testing.T, serverURL string) string

SetupTestEnv creates an isolated test environment with the mock LLM server. Returns the tmpDir for use with NewIsolatedTerminalWithConfigAndEnv.

func SetupTestEnvWithConfig 

func SetupTestEnvWithConfig(t *testing.T, serverURL string, additionalConfig map[string]any) string

SetupTestEnvWithConfig creates an isolated test environment with custom config. Merges the provided config with mock LLM settings.

func TestConfig 

func TestConfig(serverURL string) string

TestConfig creates config JSON that points to the mock server.

func TextAndToolResponse 

func TextAndToolResponse(content, toolName string, arguments any) func(req *ChatRequest) *ChatResponse

TextAndToolResponse creates a response with both text and a tool call.

func TextResponse 

func TextResponse(content string) func(req *ChatRequest) *ChatResponse

TextResponse creates a simple text response.

func ToolCallResponse 

func ToolCallResponse(toolName string, arguments any) func(req *ChatRequest) *ChatResponse

ToolCallResponse creates a response that invokes a tool.

Types

type ChatRequest 

type ChatRequest struct {
	Model       string    `json:"model"`
	Messages    []Message `json:"messages"`
	Tools       []Tool    `json:"tools,omitempty"`
	ToolChoice  any       `json:"tool_choice,omitempty"`
	Stream      bool      `json:"stream,omitempty"`
	MaxTokens   int       `json:"max_tokens,omitempty"`
	Temperature *float64  `json:"temperature,omitempty"`
	TopP        *float64  `json:"top_p,omitempty"`
}

ChatRequest represents an OpenAI chat completion request.

type ChatResponse 

type ChatResponse struct {
	ID      string   `json:"id"`
	Object  string   `json:"object"`
	Created int64    `json:"created"`
	Model   string   `json:"model"`
	Choices []Choice `json:"choices"`
	Usage   *Usage   `json:"usage,omitempty"`
}

ChatResponse represents an OpenAI chat completion response.

func NewResponse 

func NewResponse(model string) *ChatResponse

NewResponse creates a new chat response with defaults.

type Choice 

type Choice struct {
	Index        int     `json:"index"`
	Message      Message `json:"message"`
	FinishReason string  `json:"finish_reason,omitempty"`
}

Choice represents a completion choice.

type Conversation 

type Conversation struct {
	// contains filtered or unexported fields
}

Conversation is a helper for building multi-turn conversations in tests.

func NewConversation 

func NewConversation(server *Server) *Conversation

NewConversation creates a new conversation builder.

func (*Conversation) Apply 

func (c *Conversation) Apply()

Apply sets up the conversation on the server.

func (*Conversation) Then 

func (c *Conversation) Then(respond ResponseFunc) *Conversation

Then adds the next response in the conversation.

func (*Conversation) ThenError 

func (c *Conversation) ThenError(message string) *Conversation

ThenError adds an error response.

func (*Conversation) ThenText 

func (c *Conversation) ThenText(content string) *Conversation

ThenText adds a text response.

func (*Conversation) ThenTool 

func (c *Conversation) ThenTool(name string, args any) *Conversation

ThenTool adds a tool call response.

type Delta 

type Delta struct {
	Role      string          `json:"role,omitempty"`
	Content   string          `json:"content,omitempty"`
	ToolCalls []ToolCallDelta `json:"tool_calls,omitempty"`
}

Delta represents incremental content in a stream.

type Function 

type Function struct {
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	Parameters  any    `json:"parameters,omitempty"`
}

Function represents a function definition.

type FunctionCall 

type FunctionCall struct {
	Name      string `json:"name"`
	Arguments string `json:"arguments"`
}

FunctionCall represents a function call.

type FunctionDelta 

type FunctionDelta struct {
	Name      string `json:"name,omitempty"`
	Arguments string `json:"arguments,omitempty"`
}

FunctionDelta represents incremental function call data.

type MatchFunc 

type MatchFunc func(req ChatRequest) bool

MatchFunc determines if a handler should respond to a request.

func Always 

func Always() MatchFunc

Always returns true for any request.

func And 

func And(matchers ...MatchFunc) MatchFunc

And combines matchers with AND logic.

func HasSystemPrompt 

func HasSystemPrompt() MatchFunc

HasSystemPrompt returns true if the request has a system message.

func HasToolCall 

func HasToolCall(toolName string) MatchFunc

HasToolCall returns true if any assistant message contains a tool call with the given name.

func HasToolResult 

func HasToolResult(toolName string) MatchFunc

HasToolResult returns true if there's a tool result message with the given name.

func MessageContains 

func MessageContains(text string) MatchFunc

MessageContains returns true if the last user message contains the text.

func MessageCount 

func MessageCount(n int) MatchFunc

MessageCount returns true if the request has exactly n messages.

func MessageEquals 

func MessageEquals(text string) MatchFunc

MessageEquals returns true if the last user message equals the text exactly.

func Never 

func Never() MatchFunc

Never returns false for any request.

func Not 

func Not(m MatchFunc) MatchFunc

Not negates a matcher.

func Or 

func Or(matchers ...MatchFunc) MatchFunc

Or combines matchers with OR logic.

func SystemPromptContains 

func SystemPromptContains(text string) MatchFunc

SystemPromptContains returns true if the system prompt contains the text.

type Message 

type Message struct {
	Role       string     `json:"role"` // system, user, assistant, tool
	Content    string     `json:"content,omitempty"`
	Name       string     `json:"name,omitempty"`
	ToolCalls  []ToolCall `json:"tool_calls,omitempty"`
	ToolCallID string     `json:"tool_call_id,omitempty"`
}

Message represents a chat message.

type Request 

type Request struct {
	Method    string
	Path      string
	Body      ChatRequest
	Timestamp time.Time
}

Request represents a captured request to the mock server.

type ResponseFunc 

type ResponseFunc func(req *ChatRequest) *ChatResponse

ResponseFunc generates a response for a request.

type Server 

type Server struct {
	// contains filtered or unexported fields
}

Server is a mock OpenAI-compatible LLM server.

func NewServer 

func NewServer() *Server

NewServer creates a new mock LLM server.

func (*Server) Close 

func (s *Server) Close()

Close shuts down the server.

func (*Server) Default 

func (s *Server) Default(respond ResponseFunc) *Server

Default sets the default response when no handlers match.

func (*Server) LastRequest 

func (s *Server) LastRequest() *Request

LastRequest returns the most recent request.

func (*Server) On 

func (s *Server) On(match MatchFunc, respond ResponseFunc) *Server

On adds a custom handler with a matcher.

func (*Server) OnAny 

func (s *Server) OnAny(respond ResponseFunc) *Server

OnAny adds a handler that matches any request.

func (*Server) OnMessage 

func (s *Server) OnMessage(contains string, respond ResponseFunc) *Server

OnMessage adds a handler that matches when the last user message contains the text.

func (*Server) OnToolResult 

func (s *Server) OnToolResult(toolName string, respond ResponseFunc) *Server

OnToolResult adds a handler that matches when there's a tool result with the given name.

func (*Server) Requests 

func (s *Server) Requests() []Request

Requests returns all captured requests.

func (*Server) Reset 

func (s *Server) Reset()

Reset clears all handlers and request history.

func (*Server) Sequence 

func (s *Server) Sequence(responses ...ResponseFunc) *Server

Sequence configures the server to return responses in order. Each call to the server returns the next response in the sequence.

func (*Server) Start 

func (s *Server) Start(t *testing.T) string

Start starts the HTTP server and returns its URL.

func (*Server) URL 

func (s *Server) URL() string

URL returns the server's base URL.

type StreamChoice 

type StreamChoice struct {
	Index        int    `json:"index"`
	Delta        Delta  `json:"delta"`
	FinishReason string `json:"finish_reason,omitempty"`
}

StreamChoice represents a streaming choice.

type StreamChunk 

type StreamChunk struct {
	ID      string         `json:"id"`
	Object  string         `json:"object"`
	Created int64          `json:"created"`
	Model   string         `json:"model"`
	Choices []StreamChoice `json:"choices"`
	Usage   *Usage         `json:"usage,omitempty"`
}

StreamChunk represents a streaming response chunk.

func ParseSSEStream 

func ParseSSEStream(r io.Reader) ([]StreamChunk, error)

ParseSSEStream parses an SSE stream and returns chunks. Useful for testing streaming responses.

type Tool 

type Tool struct {
	Type     string   `json:"type"` // "function"
	Function Function `json:"function"`
}

Tool represents a tool definition.

type ToolCall 

type ToolCall struct {
	ID       string       `json:"id"`
	Type     string       `json:"type"` // "function"
	Function FunctionCall `json:"function"`
}

ToolCall represents a tool invocation.

type ToolCallDelta 

type ToolCallDelta struct {
	Index    int           `json:"index"`
	ID       string        `json:"id,omitempty"`
	Type     string        `json:"type,omitempty"`
	Function FunctionDelta `json:"function,omitempty"`
}

ToolCallDelta represents incremental tool call data.

type ToolCallSpec 

type ToolCallSpec struct {
	Name      string
	Arguments any
}

ToolCallSpec defines a tool call for MultiToolCallResponse.

type Usage 

type Usage struct {
	PromptTokens     int `json:"prompt_tokens"`
	CompletionTokens int `json:"completion_tokens"`
	TotalTokens      int `json:"total_tokens"`
}

Usage represents token usage information.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.