Protobuf is a language-agnostic, schema-based data serialization system created by Google. The Protobuf message format is binary and is considered more efficient than other formats like JSON & XML. The Protobuf extension enables SOAtest and Virtualize to support the Protobuf message format.
Installing the extension adds the Protobuf Client for SOAtest and the Protobuf Message Responder for Virtualize.
You will need to build a Protobuf extension jar to use the Protobuf extension. To do so:
java -jar com.parasoft.soavirt.messages.protobuf.jar <ARGUMENTS> |
The example below (for Windows) shows the command with all arguments. This will generate the jar (protobuf-extension.jar) which can then be added to SOAtest:
java -jar com.parasoft.soavirt.messages.protobuf-<VERSION>.jar -protoc C:\protoc-<VERSION>-win64\bin\protoc.exe -includes -protoDir C:\<PATH_TO_PROTO_FILES> -logLevel 4 |
For more information about the Protobuf jar, run:
java -jar com.parasoft.soavirt.messages.protobuf-<VERSION>.jar -help |
This artifact can be installed from the UI or the command line.
Add protobuf-extension.jar to the system.properties.classpath property in your settings properties file. For example:
system.properties.classpath=<path to jar>/protobuf-extension.jar
You can add standalone Protobuf clients to your suite using the Add Test wizard or chain Protobuf tools as a payload output of an existing tool using the Add Output wizard. See Adding Projects, .tst files, and Test Suites for details.
Protobuf clients function in a manner similar to other messaging clients but are configured to use the Protobuf format by default. In addition, there are a few configuration options that are unique to Protobuf clients:
XML Conversion Options
Schema for Modeling Request Payload Using Form Input
You can add Protobuf message responders to your suite using the Add Responder wizard. See Creating Message Responders Manually for details.
Protobuf message responders function in a manner similar to other responders. Refer to Message Responder Overview for information on configuring and using responders. There are a few configuration options that are unique to Protobuf message responders:
XML Conversion Options
Schema for Modeling Request Payload Using Form Input
You can also configure the responder to use a different Protobuf message type for incoming requests. To do so:
In the Protobuf message format, when an option is blank, the conversion will use the default option for that option. Otherwise, if a value is selected or entered, the conversion will attempt to use that value. Note that if an invalid value is entered manually, you may get an error when trying to switch between Form Input/Form XML and Literal views, or when running the test.
The following conversion options are available on the Conversion Options tab:
In the Protobuf Client, the outgoing request is configured by specifying a type in the Message type field. By default, the incoming response is parsed using this message type, but you can use the Package and Message conversion options to specify a different message type for parsing the incoming response.
In the Protobuf Responder, the outgoing response is configured by specifying a type in the Message type field. By default, the incoming request is parsed using this message type, but you can use the Request Handling options to select a different message type for parsing the incoming request. See Request Handling for more information. The Package and Message conversion options should be left blank.
In traffic wizards, the message type of each request and response is detected automatically. The Package and Message conversion options should be left blank. However, in some situations there may be more than one message type that can correctly identify a binary Protobuf message. The Package and Message conversion options can be used to force the expected message type if there is any such ambiguity.
In XML Converter tools, use the Message type field to select the expected message type. If a message type is not selected, a compatible type will be automatically chosen at execution. The Package and Message conversion options should be left blank.
In Traffic Viewers, Protobuf messages are automatically parsed and displayed on the Tree and Element tabs. The labels shown for each field are contrived because Protobuf messages are binary and do not actually contain named fields. The field names are based on the definition of a compatible message type that is automatically selected to parse the message.
The Protobuf extension can generate and consume messages in ProtoJSON format or the standard binary format. Specify the format in the Format field on the XML Conversion Options tab. By default, messages are generated in binary format. The message format for parsing native messages is detected automatically unless specified.
In the Protobuf Client and the Protobuf Responder tool, the outgoing message can be initialized from ProtoJSON:
Literal and provide the JSON version of the Protobuf message in the text area.The Protobuf Client and the Protobuf Responder tools have a Payload Converted to XML output that allows the incoming message to be validated in XML format, typically with an XML Assertor tool or a Diff tool in XML mode. If you instead want to validate messages as ProtoJSON, first chain an XML Converter tool. In the XML Converter tool under Tool Options, set Format to Protobuf and Conversion direction to From XML to native. The Message type can be left blank because it will be inferred from the XML. Under Options, set Format to JSON. A JSON Assertor can then be chained to the XML Converter tool, for example.
One of the benefits of using the Protobuf extension is the ability to use it in conjunction with the gRPC Transport in order to send messages in one format and receive messages in another format.