vendor/google.golang.org/grpc/Documentation/gomock-example.md

   1 # Mocking Service for gRPC
   2
   3 [Example code unary RPC](https://github.com/grpc/grpc-go/tree/master/examples/helloworld/mock_helloworld)
   4
   5 [Example code streaming RPC](https://github.com/grpc/grpc-go/tree/master/examples/route_guide/mock_routeguide)
   6
   7 ## Why?
   8
   9 To test client-side logic without the overhead of connecting to a real server. Mocking enables users to write light-weight unit tests to check functionalities on client-side without invoking RPC calls to a server.
  10
  11 ## Idea: Mock the client stub that connects to the server.
  12
  13 We use Gomock to mock the client interface (in the generated code) and programmatically set its methods to expect and return pre-determined values. This enables users to write tests around the client logic and use this mocked stub while making RPC calls.
  14
  15 ## How to use Gomock?
  16
  17 Documentation on Gomock can be found [here](https://github.com/golang/mock).
  18 A quick reading of the documentation should enable users to follow the code below.
  19
  20 Consider a gRPC service based on following proto file:
  21
  22 ```proto
  23 //helloworld.proto
  24
  25 package helloworld;
  26
  27 message HelloRequest {
  28     string name = 1;
  29 }
  30
  31 message HelloReply {
  32     string name = 1;
  33 }
  34
  35 service Greeter {
  36     rpc SayHello (HelloRequest) returns (HelloReply) {}
  37 }
  38 ```
  39
  40 The generated file helloworld.pb.go will have a client interface for each service defined in the proto file. This interface will have methods corresponding to each rpc inside that service.
  41
  42 ```Go
  43 type GreeterClient interface {
  44     SayHello(ctx context.Context, in *HelloRequest, opts ...grpc.CallOption) (*HelloReply, error)
  45 }
  46 ```
  47
  48 The generated code also contains a struct that implements this interface.
  49
  50 ```Go
  51 type greeterClient struct {
  52    cc *grpc.ClientConn
  53 }
  54 func (c *greeterClient) SayHello(ctx context.Context, in *HelloRequest, opts ...grpc.CallOption) (*HelloReply, error){
  55     // ...
  56     // gRPC specific code here
  57     // ...
  58 }
  59 ```
  60
  61 Along with this the generated code has a method to create an instance of this struct.
  62 ```Go
  63 func NewGreeterClient(cc *grpc.ClientConn) GreeterClient
  64 ```
  65
  66 The user code uses this function to create an instance of the struct greeterClient which then can be used to make rpc calls to the server.
  67 We will mock this interface GreeterClient and use an instance of that mock to make rpc calls. These calls instead of going to server will return pre-determined values.
  68
  69 To create a mock we’ll use [mockgen](https://github.com/golang/mock#running-mockgen).
  70 From the directory ``` examples/helloworld/ ``` run ``` mockgen google.golang.org/grpc/examples/helloworld/helloworld GreeterClient > mock_helloworld/hw_mock.go ```
  71
  72 Notice that in the above command we specify GreeterClient as the interface to be mocked.
  73
  74 The user test code can import the package generated by mockgen along with library package gomock to write unit tests around client-side logic.
  75 ```Go
  76 import "github.com/golang/mock/gomock"
  77 import hwmock "google.golang.org/grpc/examples/helloworld/mock_helloworld"
  78 ```
  79
  80 An instance of the mocked interface can be created as:
  81 ```Go
  82 mockGreeterClient := hwmock.NewMockGreeterClient(ctrl)
  83 ```
  84 This mocked object can be programmed to expect calls to its methods and return pre-determined values. For instance, we can program mockGreeterClient to expect a call to its method SayHello and return a HelloReply with message “Mocked RPC”.
  85
  86 ```Go
  87 mockGreeterClient.EXPECT().SayHello(
  88     gomock.Any(), // expect any value for first parameter
  89     gomock.Any(), // expect any value for second parameter
  90 ).Return(&helloworld.HelloReply{Message: “Mocked RPC”}, nil)
  91 ```
  92
  93 gomock.Any() indicates that the parameter can have any value or type. We can indicate specific values for built-in types with gomock.Eq().
  94 However, if the test code needs to specify the parameter to have a proto message type, we can replace gomock.Any() with an instance of a struct that implements gomock.Matcher interface.
  95
  96 ```Go
  97 type rpcMsg struct {
  98     msg proto.Message
  99 }
 100
 101 func (r *rpcMsg) Matches(msg interface{}) bool {
 102     m, ok := msg.(proto.Message)
 103     if !ok {
 104         return false
 105     }
 106     return proto.Equal(m, r.msg)
 107 }
 108
 109 func (r *rpcMsg) String() string {
 110     return fmt.Sprintf("is %s", r.msg)
 111 }
 112
 113 ...
 114
 115 req := &helloworld.HelloRequest{Name: "unit_test"}
 116 mockGreeterClient.EXPECT().SayHello(
 117     gomock.Any(),
 118     &rpcMsg{msg: req},
 119 ).Return(&helloworld.HelloReply{Message: "Mocked Interface"}, nil)
 120 ```
 121
 122 ## Mock streaming RPCs:
 123
 124 For our example we consider the case of bi-directional streaming RPCs. Concretely, we'll write a test for RouteChat function from the route guide example to demonstrate how to write mocks for streams.
 125
 126 RouteChat is a bi-directional streaming RPC, which means calling RouteChat returns a stream that can __Send__ and __Recv__ messages to  and from the server, respectively. We'll start by creating a mock of this stream interface returned by RouteChat and then we'll mock the client interface and set expectation on the method RouteChat to return our mocked stream.
 127
 128 ### Generating mocking code:
 129 Like before we'll use [mockgen](https://github.com/golang/mock#running-mockgen). From the `examples/route_guide` directory run:  `mockgen google.golang.org/grpc/examples/route_guide/routeguide RouteGuideClient,RouteGuide_RouteChatClient > mock_route_guide/rg_mock.go`
 130
 131 Notice that we are mocking both client(`RouteGuideClient`) and stream(`RouteGuide_RouteChatClient`) interfaces here.
 132
 133 This will create a file `rg_mock.go` under directory `mock_route_guide`. This file contins all the mocking code we need to write our test.
 134
 135 In our test code, like before, we import the this mocking code along with the generated code
 136
 137 ```go
 138 import (
 139     rgmock "google.golang.org/grpc/examples/route_guide/mock_routeguide"
 140     rgpb "google.golang.org/grpc/examples/route_guide/routeguide"
 141 )
 142 ```
 143
 144 Now conside a test that takes the RouteGuide client object as a parameter, makes a RouteChat rpc call and sends a message on the resulting stream. Furthermore, this test expects to see the same message to be received on the stream.
 145
 146 ```go
 147 var msg = ...
 148
 149 // Creates a RouteChat call and sends msg on it.
 150 // Checks if the received message was equal to msg.
 151 func testRouteChat(client rgb.RouteChatClient) error{
 152     ...
 153 }
 154 ```
 155
 156 We can inject our mock in here by simply passing it as an argument to the method.
 157
 158 Creating mock for stream interface:
 159
 160 ```go
 161     stream := rgmock.NewMockRouteGuide_RouteChatClient(ctrl)
 162 }
 163 ```
 164
 165 Setting Expectations:
 166
 167 ```go
 168     stream.EXPECT().Send(gomock.Any()).Return(nil)
 169     stream.EXPECT().Recv().Return(msg, nil)
 170 ```
 171
 172 Creating mock for client interface:
 173
 174 ```go
 175     rgclient := rgmock.NewMockRouteGuideClient(ctrl)
 176 ```
 177
 178 Setting Expectations:
 179
 180 ```go
 181     rgclient.EXPECT().RouteChat(gomock.Any()).Return(stream, nil)
 182 ```