Home

#protoc-gen-mock A plugin to generate gRPC mock services based on protobuf specifications. The generated mocks can be used for:

• Mocking a dependent service for testing purposes
• Stub a dependent service during development (while the real service is not implemented yet)

Installation

It is required to have protoc-gen-go installed. Run the following to install it:

go install github.com/golang/protobuf/protoc-gen-go

Then install protoc-gen-mock by running:

go install github.com/carvalhorr/protoc-gen-mock

Creating mock services

Suppose you have a proto definition called greeter.proto with the content:

syntax = "proto3";

package carvalhorr.greeter;

option go_package = ".;greeter_service";


service Greeter {
	rpc Hello(Request) returns (Response) {}
}

message Request {
	string name = 1;
}

message Response {
	string greeting = 1;
}

Run the command below to generate the mock.

protoc --plugin ./protoc-gen-mock --go_out=plugins=grpc:greeter-service --mock_out=greeter-service greeter.proto

The command above will generate the files:

greeter-service
   greeter.mock.pb.go
   greeter.pb.go

Starting the mock server

Create a file called greeter.go with the content:

package main

import (
	"github.com/carvalhorr/protoc-gen-mock/bootstrap"
	"github.com/carvalhorr/protoc-gen-mock/grpchandler"
	"github.com/carvalhorr/protoc-gen-mock/stub"
	greetermock "greeter-service" // Import the generated mock service
)

func main() {
	bootstrap.BootstrapServers("./tmp/", 1068, 10010, MockServicesRegistersCallback)
}

var MockServicesRegistersCallback = func(stubsMatcher stub.StubsMatcher) []grpchandler.MockService {
	return []grpchandler.MockService{
		greetermock.NewGreeterService(stubsMatcher), // register the mock service
	}
}

Run the mock service:

go run example.go

You will see the message in the console:

INFO[2020-04-26T18:13:35+01:00] Supported methods: /carvalhorr.greeter.Greeter/Hello
INFO[2020-04-26T18:13:35+01:00] REST Server listening on port: 1068          
INFO[2020-04-26T18:13:35+01:00] gRPC Server listening on port: 10010    

The mock service is listening in two different ports:

• 1068 - A rest service to add/delete/update/get stubs
• 10010 - The gRPC mocked service

Stubs

Use Postman or curl to create stubs. Example:

POST 127.0.0.1:1068/stubs

{
    "fullMethod": "/carvalhorr.greeter.Greeter/Hello",
    "request": {
        "match": "exact",
        "content": {
            "name": "John"
        },
        "metadata": {}
    },
    "response": {
        "type": "success",
        "content": {
            "greeting": "Hello, John"
        },
        "error": null
    }
}

You can verify the stubs that were created with:

GET 127.0.0.1:1068/stubs

Using the mock server

Use your gRPC client to connect to the mock server. By default, it runs on port 10010 and will respond as if it was the real service using the stubs you previously created.

If you created the stub above, now you can make a request to the gRPC method /carvalhorr.greeter.Greeter/Hello with the payload {"name": "John"} and get the response {"greeting": "Hello, John"}.