The fastest and most reliable gRPC mock server for testing and development.

GripMock creates a mock server from your .proto files or compiled .pb descriptors, making gRPC testing simple and efficient. Perfect for end-to-end testing, development environments, and CI/CD pipelines.

• 🚀 Instant Setup - Create a working gRPC server in seconds
• 📝 YAML & JSON Support - Define stubs in your preferred format
• 🔄 All Streaming Types - Unary, server, client, and bidirectional streaming
• ⚡ 20-35% Faster - Enhanced performance for quicker tests
• 🔒 100% Backward Compatible - All existing tests continue to work
• 🐳 Docker Ready - Lightweight container for CI/CD
• 🖥️ Web Interface - Manage stubs through a friendly dashboard
• 📋 JSON Schema - Full IDE support with validation
• ❤️ Health Checks - Production-ready monitoring endpoints

📖 Full Documentation - Complete guide with examples

This service is a fork of tokopedia/gripmock, but you should choose our fork. Here's why:

• ✅ YAML support as JSON alternative for static stubs
• ✅ Health check endpoints (/api/health/liveness, /api/health/readiness)
• ✅ Header matching support for authentication testing
• ✅ gRPC error codes for realistic error simulation
• ✅ Priority system for controlling stub matching order
• ✅ Binary descriptor support (.pb files) for faster startup
• ✅ Array streaming for server streaming methods
• ✅ JSON Schema validation with IDE support
• ✅ Enhanced performance with 20-35% speed improvements

• ✅ Updated dependencies - All deprecated packages fixed
• ✅ Reduced image size - Optimized Docker containers
• ✅ Better error handling - 404 errors for missing stubs
• ✅ Active maintenance - Regular updates and bug fixes
• ✅ Comprehensive documentation - Complete guides and examples

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

Choose your preferred installation method:

brew tap gripmock/tap
brew install gripmock

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

docker pull bavix/gripmock

go install github.com/bavix/gripmock/v3@latest

Start with a .proto file:

gripmock service.proto

Add static stubs:

gripmock --stub stubs/ service.proto

Using Docker:

docker run -p 4770:4770 -p 4771:4771 \
  -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

Check out our comprehensive examples in the examples folder:

• 🔄 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

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!"
}

service: Greeter
method: SayHello
input:
  equals:
    name: "gripmock"
output:
  data:
    message: "Hello GripMock!"

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"

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

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"

GripMock supports three powerful matching strategies:

input:
  equals:
    name: "gripmock"
    age: 25
    active: true

input:
  contains:
    name: "grip"  # Matches "gripmock", "gripster", etc.

input:
  matches:
    email: "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"
    phone: "^\\+?[1-9]\\d{1,14}$"

• GET /api/stubs - List all stubs
• POST /api/stubs - Add new stub
• POST /api/stubs/search - Find matching stub
• DELETE /api/stubs - Clear all stubs
• GET /api/health/liveness - Health check
• GET /api/health/readiness - Readiness check

# 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"}
  }'

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

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

We welcome contributions! Please see our Contributing Guide for details.

This project is licensed under the MIT License - see the LICENSE file for details.

Made with ❤️ by the GripMock community