Introduction

GripMock is a mock server for gRPC services. Point it at your .proto files or a compiled .pb descriptor, describe the responses you want in YAML or JSON, and it serves them — no backend, and no client library beyond the gRPC one your language already has.

Architecture

The engine does not generate gRPC server code at runtime, and does not spawn a generated server through cmd/exec. Stubbing and transport are handled in process, which is where the startup time and the image size come from — see the Performance Comparison.

Key Features

• Quick Start: Use your .proto files to start a mock server instantly
• YAML & JSON: Define test responses in the format you prefer
• Header & Input Matching: equals, contains, matches, anyOf v3.11.0, glob v3.12.0
• Streaming: Server, client, and bidirectional streaming support
• Error Simulation: Test error handling with codes and details
• Dynamic Templates: Build responses from the request v3.4.0, with faker.* v3.10.0
• Effects: Stateful stubs with automatic upsert/delete after match v3.11.0
• Health Checks: Built-in health endpoints + mockable health service v3.9.3
• TLS/mTLS: Native TLS support for secure gRPC v3.8.1
• Plugins: Extend template functions with Go plugins v3.5.0
• Match Limit (options.times): Limit how many times a stub can be matched v3.7.0
• Embedded SDK: Run GripMock inside Go tests v3.7.0
• MCP API: AI/agent tooling integration v3.7.0
• Embedded SDK: Programmatic GripMock usage in Go tests with built-in verification helpers v3.7.0
• Upstream Modes: Reflection-based proxy/replay/capture modes for reverse proxy, local-first fallback, and automatic stub recording v3.9.0
• Upstream Modes: proxy, replay, capture for gradual migration v3.9.0
• OpenTelemetry: Export traces via OTLP v3.10.0
• Prometheus: Metrics at /metrics v3.10.0
• Docker: Lightweight container for CI/CD
• GitHub Actions: Official action for CI workflows

Streaming Support

GripMock supports all gRPC streaming patterns:

• Request-Response — single request, single response
• Server Streaming — single request, multiple responses
• Client Streaming — multiple messages, single response
• Bidirectional — continuous two-way messaging

See Streaming for details.

Web Interface v3.0.0

The dashboard at http://localhost:4771/ lists the loaded stubs, shows which of them have been matched, and lets you edit them without restarting the server.

Runtime descriptor loading v3.7.0

.pb descriptors can be pushed into a running server without a restart — see the Descriptor API.

Getting Started

Install from Docker or a release binary, point GripMock at your .proto files, and write the responses as YAML or JSON. Quick Usage walks through the first run.

Bugs and questions go to GitHub issues.