Introduction

GripMock is your go-to tool for testing gRPC services. It creates a mock server that responds exactly how you want it to, making testing faster and more reliable.

What is GripMock?

GripMock is a mock server for gRPC services. Give it your .proto files, and it instantly creates a working server that responds with your predefined test data. Perfect for testing your applications without needing a real backend server.

Why Use GripMock?

• Fast Setup: Get a working server in seconds
• Easy Testing: Define responses in simple YAML or JSON files
• Real Scenarios: Test file uploads, chat applications, and data streaming
• No Dependencies: Works with any programming language that supports gRPC
• Production Ready: Built-in health checks and Docker support

Architecture Story

GripMock was initially inspired by tokopedia/gripmock, but the current project is fully rewritten.

The modern GripMock engine is fundamentally different:

• It does not generate gRPC server code at runtime
• It does not spawn generated servers via cmd/exec
• It uses a native in-process runtime for stubbing and transport handling

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: Fine-grained request matching with equals, contains, matches, anyOf v3.11.0
• Streaming: Server, client, and bidirectional streaming support
• Error Simulation: Test error handling with codes and details
• Dynamic Templates: Generate realistic data with faker.*, , etc. 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
• 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 provides a user-friendly way to:

• Create and edit test responses
• Monitor which responses are being used
• Manage your test scenarios visually

Access it at http://localhost:4771/ when you start GripMock.

Experimental Features

• Embedded SDK v3.7.0: Programmatic GripMock usage in Go tests with built-in verification helpers
• Upstream Modes v3.9.0: Reflection-based proxy/replay/capture modes for reverse proxy, local-first fallback, and automatic stub recording

Runtime descriptor loading v3.7.0

Need to load .pb descriptors into a running server without restart? See Descriptor API (/api/descriptors).

Getting Started

1. Install: Download or use Docker
2. Configure: Point to your .proto files
3. Define Responses: Create YAML/JSON files with your test data
4. Test: Your mock server is ready!

Need Help?

Stuck with something? Check out our GitHub issues page or join our community discussions.