

GripMock ๐
Languages: English | ็ฎไฝไธญๆ | ๆฅๆฌ่ช | Deutsch | Espaรฑol
A gRPC mock server for testing and development.
GripMock builds a mock server from your .proto files or a compiled .pb descriptor: 29 804 req/s and a 0.4 s cold start from a 19 MB image (benchmark).

โจ Features
- Native Runtime - Single in-process engine without runtime gRPC code generation
- Descriptor Sources - Load API from
.proto, compiled .pb, BSR modules, or gRPC reflection
- Dynamic
.pb Service Loading - Load compiled protobuf descriptors at runtime via API without restarts
- Hot Stub Management - Create, update, and remove stubs via API/UI without server restarts
- Flexible Matching -
equals, contains, matches, glob, headers, priority, and match limits
- Array-Aware Matching - Optional array-order flexibility to reduce brittle test assertions
- Dynamic Templates - Build responses from request payload, headers, and stream context
- Complete gRPC Coverage - Unary, server streaming, client streaming, and bidirectional streaming
- Error, Details, and Delay Simulation - Return realistic gRPC status codes, details (
Any), and response timing
- TLS and mTLS Support - Run secure gRPC/HTTP test environments with native TLS options
- Advanced Protobuf Type Support - Handle well-known and extended protobuf types (
google.protobuf.*, google.type.*)
- YAML/JSON + Schema - Author stubs in either format with JSON Schema IDE validation
- Plugin Ecosystem - Extend functions with Go plugins on Linux, macOS and Windows, with matching builder image tags
- Built-in Faker Templates - Generate realistic fake person/contact/geo/network data directly in templates (
faker.*)
- OpenTelemetry Tracing - OTLP tracing for gRPC and HTTP paths (
otelgrpc + otelhttp)
- Prometheus Metrics (
/metrics) - Runtime/process metrics (go_*, process_*) plus GripMock metrics
- Operational APIs - Health endpoints, descriptors API, stubs API, and web dashboard
- Embedded SDK - Run GripMock inside Go tests with verification helpers
- MCP API - Streamable MCP endpoint for agent and tool integrations
- Upstream Modes -
proxy, replay, capture modes for gradual migration from live upstream services to local mocks
๐ Documentation
Full Documentation - Complete guide with examples
Deep dives on the newer surfaces:
Descriptor API ยท
Upstream Modes ยท
Embedded SDK ยท
Faker Reference ยท
OpenTelemetry + Metrics ยท
GitHub Actions ยท
Performance Comparison
๐ฅ๏ธ Web Interface

Access the web dashboard at http://localhost:4771/ to manage your stubs visually.
๐ Quick Start
Installation
Choose your preferred installation method:
Homebrew (Recommended)
brew tap gripmock/tap
brew install --cask gripmock
The cask is built with cgo, so --plugins works. brew install --cask gripmock-slim installs the same server without plugin support.
Shell Script
curl -s https://raw.githubusercontent.com/bavix/gripmock/refs/heads/master/setup.sh | sh -s
Add -- --slim to install the build without plugin support. On musl (Alpine) the
slim build is selected automatically. On FreeBSD, the installer selects the
slim build automatically; FreeBSD binaries are currently available for amd64
and arm64 and do not support Go plugins.
PowerShell (Windows)
irm https://raw.githubusercontent.com/bavix/gripmock/refs/heads/master/setup.ps1 | iex
For the build without plugin support, set GRIPMOCK_SLIM first:
$env:GRIPMOCK_SLIM=1
irm https://raw.githubusercontent.com/bavix/gripmock/refs/heads/master/setup.ps1 | iex
Docker
docker pull bavix/gripmock
For plugin builds, use the paired builder image:
docker pull bavix/gripmock:3.18.4-builder
If you never pass --plugins, use the slim image (built without cgo, so
plugin.Open is unavailable):
docker pull bavix/gripmock:3.18.4-slim
Go Install
go install github.com/bavix/gripmock/v3@latest
Basic Usage
Start with a .proto file:
gripmock service.proto
Add static stubs:
gripmock --stub stubs/ service.proto
Load API directly from Buf Schema Registry (BSR):
gripmock --stub third_party/bsr/eliza buf.build/connectrpc/eliza
Load API from live gRPC server reflection:
gripmock grpc://localhost:50051
gripmock grpcs://api.company.local:443
With options:
gripmock grpc://localhost:50051?timeout=10s
gripmock grpcs://10.0.0.5:8443?serverName=api.company.local
gripmock grpc://localhost:50051?bearer=<token>
Use upstream modes over reflection:
# Pure reverse proxy through GripMock
gripmock grpc+proxy://localhost:50051
# Local stubs first, then upstream fallback on matcher miss
gripmock grpc+replay://localhost:50051
# Replay + record upstream misses into GripMock stubs
gripmock grpc+capture://localhost:50051
For private BSR modules:
BSR_BUF_TOKEN=<token> gripmock --stub stubs/ buf.build/acme/private-api
For self-hosted BSR:
BSR_SELF_BASE_URL=https://bsr.company.local \
BSR_SELF_TOKEN=<token> \
gripmock --stub stubs/ bsr.company.local/team/payments
Using Docker:
docker run -p 4770:4770 -p 4771:4771 -p 4769:4769 \
-v $(pwd)/stubs:/stubs \
-v $(pwd)/proto:/proto \
bavix/gripmock --stub=/stubs /proto/service.proto
- Port 4770: gRPC server
- Port 4771: Web UI and REST API
- Port 4769: Gateway (gRPC-web / ConnectRPC)
Observability (v3.10.0)
OTEL_ENABLED=true \
OTEL_EXPORTER_OTLP_ENDPOINT=localhost:4317 \
OTEL_EXPORTER_OTLP_INSECURE=true \
gripmock --stub stubs/ service.proto
GET /metrics is always available
- Tracing export is enabled only when
OTEL_ENABLED=true
๐ค GitHub Actions (CI/CD)
Use the official action bavix/gripmock-action to run GripMock in CI pipelines.
name: test
on: [push, pull_request]
jobs:
e2e:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
- name: Start GripMock
uses: bavix/gripmock-action@v1
with:
source: proto/service.proto
stub: stubs
- name: Run tests
run: go test ./...
What the action does:
- Downloads GripMock from GitHub Releases (
latest or pinned version)
- Starts GripMock in background and waits for readiness (
/api/health/readiness)
- Exposes addresses via outputs (
grpc-addr, http-addr) for test steps
- Stops GripMock automatically in the post step
More examples and full inputs/outputs: GitHub Actions guide.
๐ Examples
The examples folder covers:
- Streaming - Server, client, and bidirectional streaming
- File Uploads - Test chunked file uploads
- Real-time Chat - Bidirectional communication
- Data Feeds - Continuous data streaming
- Authentication - Header-based auth testing
- Performance - High-throughput scenarios
Greeter: dynamic stub demo
Stub (universal):
# yaml-language-server: $schema=https://bavix.github.io/gripmock/schema/stub.json
# examples/projects/greeter/stub_say_hello.yaml
- service: helloworld.Greeter
method: SayHello
input:
matches:
name: ".+"
output:
data:
message: "Hello, {{.Request.name}}!" # dynamic template lives in output
Notes:
- Put dynamic templates only in
output (e.g., data, headers, stream).
- Keep
input matching static (no {{ ... }} in equals/contains/matches).
# Start server
go run main.go examples/projects/greeter/service.proto --stub examples/projects/greeter
# Call via grpcurl
grpcurl -plaintext -d '{"name":"Alex"}' localhost:4770 helloworld.Greeter/SayHello
Expected response:
{
"message": "Hello, Alex!"
}
๐ง Stubbing
Basic Stub Example
service: Greeter
method: SayHello
input:
equals:
name: "gripmock"
output:
data:
message: "Hello GripMock!"
Advanced Features
Priority System:
- service: UserService
method: GetUser
priority: 100 # Higher priority
input:
equals:
id: "admin"
output:
data:
role: "administrator"
- service: UserService
method: GetUser
priority: 1 # Lower priority (fallback)
input:
contains:
id: "user"
output:
data:
role: "user"
Streaming Support:
service: TrackService
method: StreamData
input:
equals:
sensor_id: "GPS001"
output:
stream:
- position: {"lat": 40.7128, "lng": -74.0060}
timestamp: "2024-01-01T12:00:00Z"
- position: {"lat": 40.7130, "lng": -74.0062}
timestamp: "2024-01-01T12:00:05Z"
Dynamic Templates
GripMock supports dynamic templates in the output section using Go's text/template syntax.
- Access request fields:
{{.Request.field}}
- Access headers:
{{.Headers.header_name}}
- Client streaming context:
{{.Requests}} (slice of received messages), {{len .Requests}}, {{(index .Requests 0).field}}
- Bidirectional streaming:
{{.MessageIndex}} gives the current message index (0-based)
- Math helpers:
sum, avg, mul, min, max, add, sub, div
- Utility:
json, split, join, upper, lower, title, sprintf, int, int64, float, round, floor, ceil
- Built-in faker:
faker.Person.*, faker.Contact.*, faker.Geo.*, faker.Network.*, faker.Identity.*
Important rules:
- Do not use dynamic templates inside
input.equals, input.contains, or input.matches (matching must be static)
- For server streaming, if both
output.stream and output.error/output.code are set, messages are sent first and then the error is returned. If output.stream is empty, the error is returned immediately
Header Matching:
service: AuthService
method: ValidateToken
headers:
equals:
authorization: "Bearer valid-token"
input:
equals:
token: "abc123"
output:
data:
valid: true
user_id: "user123"
Four matching strategies, combinable in one stub โ see Matching Logic for how they compose:
1. Exact Match (equals)
input:
equals:
name: "gripmock"
age: 25
active: true
2. Partial Match (contains)
input:
contains:
name: "grip" # Matches "gripmock", "gripster", etc.
3. Regex Match (matches)
input:
matches:
email: "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"
phone: "^\\+?[1-9]\\d{1,14}$"
4. Glob Match (glob)
input:
glob:
filename: "*.txt"
path: "/usr/local/*"
๐ ๏ธ API
REST API Endpoints
GET /api/stubs - List all stubs
POST /api/stubs - Add or update stubs
DELETE /api/stubs - Clear all stubs
DELETE /api/stubs/{uuid} - Delete one stub
POST /api/stubs/batchDelete - Delete several stubs by ID
POST /api/stubs/search - Find the stub a request would hit
POST /api/stubs/validate - Validate stubs without storing them
POST /api/stubs/inspect - Explain why a request matches or misses
GET /api/stubs/used / GET /api/stubs/unused - Matched and never-matched stubs
POST /api/descriptors - Load a FileDescriptorSet at runtime
GET /api/history - Recorded calls
POST /api/verify - Assert call counts
GET /api/health/liveness - Health check
GET /api/health/readiness - Readiness check
Full reference: OpenAPI.
Example API Usage
# Add a stub
curl -X POST http://localhost:4771/api/stubs \
-H "Content-Type: application/json" \
-d '{
"service": "Greeter",
"method": "SayHello",
"input": {"equals": {"name": "world"}},
"output": {"data": {"message": "Hello World!"}}
}'
# Search for matching stub
curl -X POST http://localhost:4771/api/stubs/search \
-H "Content-Type: application/json" \
-d '{
"service": "Greeter",
"method": "SayHello",
"data": {"name": "world"}
}'
๐ JSON Schema Support
Add schema validation to your stub files for IDE support:
JSON files:
{
"$schema": "https://bavix.github.io/gripmock/schema/stub.json",
"service": "MyService",
"method": "MyMethod"
}
YAML files:
# yaml-language-server: $schema=https://bavix.github.io/gripmock/schema/stub.json
service: MyService
method: MyMethod
๐ BSR Integration
A BSR module reference can be passed straight to GripMock in place of a .proto path:
Configuration
# Public BSR (default)
BSR_BUF_BASE_URL=https://buf.build
BSR_BUF_TOKEN=<token>
# Self-hosted BSR
BSR_SELF_BASE_URL=https://bsr.company.local
BSR_SELF_TOKEN=<token>
Usage
# Public module
gripmock buf.build/connectrpc/eliza
# Self-hosted module
gripmock bsr.company.local/team/payments:main
# With stubs
gripmock --stub stubs/ bsr.company.local/team/payments
Routing
GripMock automatically routes modules:
buf.build/owner/repo โ uses Buf profile
bsr.company.local/owner/repo โ uses Self profile
For details see BSR Documentation.
๐ gRPC Reflection Source
GripMock supports descriptor loading from gRPC reflection using endpoint schemes:
grpc://host:port (insecure)
grpcs://host:port (TLS)
Supported query parameters:
timeout (default 5s)
bearer (Authorization token)
serverName (TLS SNI override)
Examples:
gripmock grpc://localhost:50051
gripmock grpcs://api.company.local:443
gripmock grpcs://10.0.0.5:8443?serverName=api.company.local
Full guide: gRPC Reflection Source.
๐ Upstream Modes
Upstream modes work on top of reflection sources and define runtime behavior:
proxy - pure reverse proxy
replay - local-first + upstream fallback
capture - replay + automatic stub recording from upstream
Mode guides:
๐ Benchmark Charts
At 500 stubs, 4 CPUs per container. Full method and numbers: Performance Comparison
|
bavix |
tokopedia |
| Throughput |
29 804 req/s |
6 221 req/s |
| p99 latency |
9.44 ms |
24.08 ms |
| Startup, avg |
0.399 s |
2.205 s |
| Image size, amd64 |
19.17 MB |
226.29 MB |
| Image size, arm64 |
18.49 MB |
219.90 MB |

๐ Useful Resources
๐ค Contributing
See the Contributing Guide. Changes to gRPC behaviour need integration tests in .gctf format.
๐ License
MIT โ see LICENSE.