gripmock

command module
v3.23.8 Latest Latest
Warning

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

Go to latest
Published: Nov 1, 2026 License: MIT Imports: 2 Imported by: 0

README ยถ

GripMock

CI Coverage Release Docker Pulls

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).

greeter

โœจ 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

gripmock-ui

Access the web dashboard at http://localhost:4771/ to manage your stubs visually.

๐Ÿš€ Quick Start

Installation

Choose your preferred installation method:

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"

๐Ÿ” 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:

๐Ÿ“Š 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

Image size benchmark Startup readiness benchmark Memory benchmark Latency percentiles benchmark Throughput benchmark

๐Ÿ”— Useful Resources

๐Ÿค Contributing

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

๐Ÿ“„ License

MIT โ€” see LICENSE.

Documentation ยถ

The Go Gopher

There is no documentation for this package.

Directories ยถ

Path Synopsis
examples
plugins/delay command
plugins/hash command
plugins/math command
internal
app
domain/rest
Package rest provides primitives to interact with the openapi HTTP API.
Package rest provides primitives to interact with the openapi HTTP API.
infra/types
Package types provides custom JSON types for Gripmock.
Package types provides custom JSON types for Gripmock.
pbs
pkg
plugins/cshared
Package cshared is the plugin side of the c-shared transport: on Windows a plugin is a DLL and answers over two C entry points instead of Go symbols.
Package cshared is the plugin side of the c-shared transport: on Windows a plugin is a DLL and answers over two C entry points instead of Go symbols.
plugins/cshared/export
Package export carries the C entry points a plugin DLL must expose.
Package export carries the C entry points a plugin DLL must expose.
sdk
Package sdk provides an embedded gRPC mock server for tests.
Package sdk provides an embedded gRPC mock server for tests.
sdk/internal/httpmock
Package httpmock provides a httptest server using the real gripmock REST handlers.
Package httpmock provides a httptest server using the real gripmock REST handlers.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ ๆข็ฝ‘ๅ€