florkbr / deal-go

Protoc plugin to generate contract tests for gRPC in Go

Deal - Go

Introduction

This plugin allows us to write Consumer-Driver Contracts tests!

Deal will generate some code for us:

• A Client to be used in the client side to mock the responses based on the contract
• A Stub Server to be used in the client side as the Client above, but you should run it as another application
• Server Test Function, you should pass your server implementation to the function and all the contracts will be validated against it

You can check out an example project here.

Usage example

Proto service

First you need a proto service:

syntax = "proto3";

import "google/protobuf/struct.proto";
import "deal/v1/contract/annotations.proto";

option go_package = "YOUR_PACKAGE_HERE/example";

message RequestMessage {
  string requestField = 1;
}

message ResponseMessage {
  int64 responseField = 1;
}

service MyService {
  rpc MyMethod(RequestMessage) returns (ResponseMessage);
}

Contract file

After that you need to write the contract that should be respected, the contract is written as a JSON file. You can set both, Success and Failures cases:

{
  "name": "Some Name Here",
  "services": {
    "MyService": {
      "MyMethod": {
        "successCases": [
          {
            "description": "Should do something",
            "request": {
              "requestField": "VALUE"
            },
            "response": {
              "responseField": 42
            }
          }
        ],
        "failureCases": [
          {
            "description": "Some description here",
            "request": {
              "requestField": "ANOTHER_VALUE"
            },
            "error": {
              "errorCode": "NotFound",
              "message": "ANOTHER_VALUE NotFound"
            }
          }
        ]
      }
    }
  }
}

Generating code

If you're using buf just add the following entry and execute buf generate passing your contract file path:

version: v1beta1
plugins:
  - name: go-deal
    out: protogen
    opt: paths=source_relative,contract-file=contract.json

Disclaimer: You must be using go-grpc in order to make the things work

To use the generated client you can just import it from the generated module:

import "YOUR_PACKAGE_HERE/example"

func main() {
	  contractClient := example.MyServiceContractClient{}

	  // TODO: Add the rest of the example here
}