Support capture, replaying and manipulation of protoc request to simplify plugin development and make them more testable.

It can act as a protoc plugin. That’s why name has to start with protoc-gen- – to make it discoverable by protoc. It will by default wrap an incoming CodeGenerationRequest in a CodeGenerationResponse and store it as out.proto.msg.

It can also convert CodeGenerationRequest and CodeGenerationResponse into json (and convert from json to proto).

With the stored request, you can do additional things:

  • pipe it into you plugin: <out.proto.msg PLUGIN | protoc-gen-capture -wrap=false > response.proto.msg
  • inspect the request: <out.proto.msg protoc-gen-capture -wrap=false -json-out > request.proto.json
  • inspect the response (requires piping into plugin above): <response.proto.msg protoc-gen-capture -wrap=false -req-in=false -json-out > response.proto.json
  • … and of course, store various versions of the above and use them for plugin regression testing.

Here’s the output of protoc-gen-capture --help:

Support capture, replaying and manipulation of protoc request.

Call it as a protoc-plugin to capture code generation requests:
  protoc --capture_out=. ...
  will create a file out.proto.msg in the current directory.
  For sensible values of ..., that is.

To support usage as a plugin, --wrap is true by default.
Unset it if you do not want to convert input requests to responses.
Like when you intend to pipe it to test your plugin:

Use it to test a plugin independent of protoc (result as json):
  < cgreq.proto.msg \
  | protoc_gen_capture -wrap=false -json-out \
  > generation-response.json

You can also convert the code generation request to json:
  < cgreq.proto.msg \
  protoc_gen_capture -req-in=false -wrap=false -json-out \
  > generation-request.json

This enables you to diff results of various program versions.

This program might not be lossless.
It will always decode and reencode.
Unknown message parts will not be visible and might get dropped.

Decoding for responses is shallow. Included files - if proto -
will not be decoded.

  -file string
        only if wrap is true: file name inside code generator response (default "out.proto.msg")
        show this help text
        input is json, else binary proto
        output as json, else deterministic binary proto
        input is request, not response (default true)
        wrap input in response with filename out.proto.msg (default true)


View Github