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 and 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

Shell Script

curl -s https://raw.githubusercontent.com/bavix/gripmock/refs/heads/master/setup.sh | sh -s

PowerShell (Windows)

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

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"

🔍 Input Matching

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:

• Upstream Modes Overview
• Proxy Mode
• Replay Mode
• Capture Mode

📊 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

• Documentation - Complete guides and examples
• Testing gRPC with Testcontainers - Article by @AndrewIISM
• JSON Schema - Stub validation schema
• OpenAPI - REST API documentation

🤝 Contributing

See the Contributing Guide. Changes to gRPC behaviour need integration tests in .gctf format.

📄 License

MIT — see LICENSE.