GripMock is a mock server for gRPC services. It's using a .proto file or compiled .pb descriptor to generate implementation of gRPC service for you.
You can use gripmock for setting up end-to-end testing or as a dummy server in a software development phase.
The server implementation is in GoLang but the client can be any programming language that support gRPC.
This service is a fork of the service tokopedia/gripmock, but you should choose our fork. And here are the reasons:
- Updated all deprecated dependencies tokopedia#64;
- Add yaml as json alternative for static stab's;
- Add endpoint for healthcheck (/api/health/liveness, /api/health/readiness);
- Add feature ignoreArrayOrder bavix#108;
- Add support headers tokopedia#144;
- Add grpc error code tokopedia#125;
- Added gzip encoding support for grpc server tokopedia#134;
- Fixed issues with int64/uint64 tokopedia#67;
- Add 404 error for stubs not found tokopedia#142;
- Support for deleting specific stub tokopedia#123;
- Reduced image size tokopedia#91 bavix#512;
- Active support tokopedia#82;
- Added documentation;
- Binary descriptor support (
.pbfiles) for faster startup
If you have a simple service, you likely only need a single .proto file to start the GripMock server. However, for more complex projects, you can use the --imports flag to include additional proto files. This approach can become cumbersome, so the recommended solution is to compile a .pb (Protocol Buffers descriptor) file.
GripMock can be installed using one of the following methods:
Homebrew provides an easy way to install GripMock on macOS and Linux.
Tap the official Homebrew tap for GripMock:
brew tap gripmock/tapInstall GripMock with the following command:
brew install gripmockVerify that GripMock is installed correctly by checking its version:
gripmock --versionYou should see output similar to:
gripmock version v3.2.4
For Unix-based systems (Linux/macOS) on arm64/amd64 architectures:
curl -s https://raw.githubusercontent.com/bavix/gripmock/refs/heads/master/setup.sh | sh -sExample installation output:
ℹ Starting GripMock installation... 🚀
ℹ Checking dependencies...
✔ Dependencies are ready.
ℹ Detecting system information...
✔ Detected OS: linux 🌍
✔ Detected architecture: amd64 💻
ℹ Fetching the latest version of GripMock from GitHub...
✔ Latest version: 3.2.8 🎉
ℹ Downloading checksums file...
✔ Checksums file downloaded.
ℹ Downloading GripMock for linux/amd64...
✔ Downloaded GripMock (9.59 MB)
✔ Checksum verified successfully.
ℹ Installing GripMock...
✔ GripMock has been successfully installed.
ℹ You can now run 'gripmock --help' to get started.
✔ Installation complete! You're all set to use GripMock 🎉This script automatically:
- Detects your OS (Linux/macOS) and architecture (arm64/amd64)
- Verifies system dependencies
- Downloads the latest release securely
- Validates checksums
- Installs to your system PATH
Pre-built binaries for various platforms are available on the Releases page. Download the appropriate binary for your system and add it to your PATH.
GripMock is also available as a Docker image. Pull the latest image with:
docker pull bavix/gripmockIf you have Go installed, you can install GripMock directly:
go install github.com/bavix/gripmock/v3@latestExample using protoc:
protoc --proto_path=. --descriptor_set_out=service.pb --include_imports hello.protoExample using buf:
buf build -o service.pbStart with a .pb or .proto file:
gripmock service.pb
# or
gripmock service.protoUse a folder containing multiple .proto files:
gripmock protofolder/Static Stubs (provide mock responses):
# For a folder of proto files
gripmock --stub stubfolder/ protofolder/
# For a single proto file
gripmock --stub stubfolder/ service.proto
# For a pre-compiled .pb file
gripmock --stub stubfolder/ service.pbFolder of proto files:
docker run -p 4770:4770 -p 4771:4771 \
-v stubfolder:/stubs \
-v /protofolder:/proto \
bavix/gripmock /proto/Single proto file:
docker run -p 4770:4770 -p 4771:4771 \
-v stubfolder:/stubs \
-v /protofolder:/proto \
bavix/gripmock /proto/service.protoPre-compiled .pb file:
docker run -p 4770:4770 -p 4771:4771 \
-v stubfolder:/stubs \
-v /protofolder:/proto \
bavix/gripmock /proto/service.pb- 4770: gRPC port for mock server
- 4771: HTTP port for web UI and REST API
Check examples folder for various usecase of GripMock.
From client perspective, GripMock has 2 main components:
- gRPC server that serves on
tcp://localhost:4770. Its main job is to serve incoming rpc call from client and then parse the input so that it can be posted to Stub service to find the perfect stub match. - Stub server that serves on
http://localhost:4771. Its main job is to store all the stub mapping. We can add a new stub or list existing stub using http request.
Matched stub will be returned to gRPC service then further parse it to response the rpc call.
Stubbing is the essential mocking of GripMock. It will match and return the expected result into gRPC service. This is where you put all your request expectation and response
Both .proto and .pb definitions work identically with all stubbing features
You could add stubbing on the fly with a simple REST API. HTTP stub server is running on port :4771
GET /api/stubsWill list all stubs mapping.POST /api/stubsWill add stub with provided stub dataPOST /api/stubs/searchFind matching stub with provided input. see Input Matching below.DELETE /api/stubsClear stub mappings.
Stub Format is JSON text format. It has a skeleton as follows:
{
"service":"<servicename>", // name of service defined in proto
"method":"<methodname>", // name of method that we want to mock
"headers":{ // Optional. headers matching rule. see Headers Matching Rule section below
// put rule here
},
"input":{ // input matching rule. see Input Matching Rule section below
// put rule here
},
"output":{ // output json if input were matched
"data":{
// put result fields here
},
"headers":{ // Optional
// put result headers here
},
"error":"<error message>", // Optional. if you want to return error instead.
"code":"<response code>" // Optional. Grpc response code. if code !=0 return error instead.
}
}For our hello service example we put a stub with the text below:
{
"service":"Greeter",
"method":"SayHello",
"input":{
"equals":{
"name":"gripmock"
}
},
"output":{
"data":{
"message":"Hello GripMock"
}
}
}You could initialize gripmock with stub json files and provide the path using --stub argument. For example you may
mount your stub file in /mystubs folder then mount it to docker like
Using .proto:
docker run -p 4770:4770 -p 4771:4771 -v /mypath:/proto -v /mystubs:/stub bavix/gripmock --stub=/stub /proto/hello.protoUsing .pb:
docker run -p 4770:4770 -p 4771:4771 -v /mypath:/proto -v /mystubs:/stub bavix/gripmock --stub=/stub /proto/service.pbPlease note that Gripmock still serves http stubbing to modify stored stubs on the fly.
Stub will respond with the expected response only if the request matches any rule. Stub service will serve /api/stubs/search endpoint with format:
{
"service":"<service name>",
"method":"<method name>",
"data":{
// input that suppose to match with stored stubs
}
}So if you do a curl -X POST -d '{"service":"Greeter","method":"SayHello","data":{"name":"gripmock"}}' localhost:4771/api/stubs/search stub service will find a match from listed stubs stored there.
Input matching has 3 rules to match an input: equals,contains and matches
Nested fields are allowed for input matching too for all JSON data types. (string, bool, array, etc.)
Gripmock recursively goes over the fields and tries to match with given input.
ignoreArrayOrder Disables sorting check inside arrays.
- service: MicroService
method: SayHello
input:
ignoreArrayOrder: true # disable sort checking
equals:
v1:
- {{ uuid2base64 "77465064-a0ce-48a3-b7e4-d50f88e55093" }}
- {{ uuid2base64 "99aebcf2-b56d-4923-9266-ab72bf5b9d0b" }}
- {{ uuid2base64 "5659bec5-dda5-4e87-bef4-e9e37c60eb1c" }}
- {{ uuid2base64 "ab0ed195-6ac5-4006-a98b-6978c6ed1c6b" }}
output:
data:
code: 1000Without this flag, the order of the transmitted values is important to us.
equals will match the exact field name and value of input into expected stub. example stub JSON:
{
.
.
"input":{
"equals":{
"name":"gripmock",
"greetings": {
"english": "Hello World!",
"indonesian": "Halo Dunia!",
"turkish": "Merhaba Dünya!"
},
"ok": true,
"numbers": [4, 8, 15, 16, 23, 42]
"null": null
}
}
.
.
}contains will match input that has the value declared expected fields. example stub JSON:
{
.
.
"input":{
"contains":{
"field2":"hello",
"field4":{
"field5": "value5"
}
}
}
.
.
}matches using regex for matching fields expectation. example:
{
.
.
"input":{
"matches":{
"name":"^grip.*$",
"cities": ["Jakarta", "Istanbul", ".*grad$"]
}
}
.
.
}Stub will respond with the expected response only if the request matches any rule. Stub service will serve /api/stubs/search endpoint with format:
{
"service":"<service name>",
"method":"<method name>",
"data":{
// input that suppose to match with stored stubs
}
}So if you do a curl -X POST -d '{"service":"Greeter","method":"SayHello","data":{"name":"gripmock"}}' localhost:4771/api/stubs/search stub service will find a match from listed stubs stored there.
Headers matching has 3 rules to match an input: equals,contains and matches
Headers can consist of a key and a value. If there are several values, then you need to list them separated by ";". Data type string.
Gripmock recursively goes over the fields and tries to match with given input.
equals will match the exact field name and value of input into expected stub. example stub JSON:
{
.
.
"headers":{
"equals":{
"authorization": "mytoken",
"system": "ec071904-93bf-4ded-b49c-d06097ddc6d5"
}
}
.
.
}contains will match input that has the value declared expected fields. example stub JSON:
{
.
.
"headers":{
"contains":{
"field2":"hello"
}
}
.
.
}matches using regex for matching fields expectation. example:
{
.
.
"headers":{
"matches":{
"name":"^grip.*$"
}
}
.
.
}This project is licensed under the MIT License.
See LICENSE for details.