gRPC Mock APIs - Overview

The gRPC feature is currently in closed beta. Reach out to the WireMock team for access.

WireMock Cloud enables you to mock your gRPC APIs in a similar fashion to a general HTTP/HTTPS mock API. Incoming gRPC messages are converted to JSON for the purpose of request matching and templating. JSON responses are also converted to gRPC messages before being sent to the client.

Usage

Creating a gRPC mock API

To create a gRPC mock API, select the gRPC API template on the mock API creation page and give it a name (and optional custom hostname) of your choosing.

Uploading a descriptor set file

Once your API is created, the first step to take before you can configure your stubs is to upload a gRPC descriptor set file that describes your gRPC services, methods and messages. Navigate to your mock API’s gRPC page and select a file from your file system to upload.

See generating a descriptor set file for details of how to obtain a descriptor set.

Configuring gRPC stubs.

Once you’ve successfully uploaded your descriptor set file you can create stubs for your gRPC API. The stub form for a gRPC mock API is similar to a general HTTP/HTTPS mock API with a few key differences. Firstly, each gRPC stub must be associated with a particular service and method defined in the uploaded descriptor set file.

Request matching for gRPC stubs is limited to body matchers. Additionally, body matchers are constrained to only JSON related matchers (e.g. “equals JSON”, “matches JSONPath”).

Response statuses can be configured to any valid gRPC status.

Response bodies must return valid JSON that confirms to the gRPC method’s response message. For example, given a descriptor set file that was generated from the following proto file:

syntax = "proto3";

service BookingService {
  rpc booking(BookingRequest) returns (BookingResponse);
}

message BookingRequest {
  string id = 1;
}

message BookingResponse {
  string id = 1;
  string created = 2;
  repeated Participant participants = 3;
}

message Participant {
  string name = 1;
}

The stub response body for the booking method would look something like the following:

{
  "id": "123",
  "created": "2024-08-13T10:12:00",
  "participants": [
    {
      "name": "Bob"
    },
    {
      "name": "Alice"
    }
  ]
}

When the response status of your stub is set to a non OK status, the response body is not used and a Status Reason must be provided.

Generating a descriptor set file

To generate a descriptor set file from your proto file, simply add the --descriptor_set_out option to your protoc command. For example,

protoc --descriptor_set_out my-api.dsc MyApi.proto