You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 2 Current »

Overview

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.

Requirements

Build the protobuf-extension.jar

You will need to build a Protobuf extension jar to use the Protobuf extension. To do so:

  1. Download the Protocol Buffer Compiler (protoc) mentioned in Requirements.
  2. Run the following command with the appropriate arguments:
    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

Installation

This artifact can be installed from the UI or the command line.

UI Installation

  1. Go to Parasoft > Preferences and click System Properties.
  2. Click Add JARs and choose the protobuf-extension.jar.
  3. Click Apply.
  4. Restart SOAtest/Virtualize.

Command Line Installation

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

Usage

Adding the Protobuf Clients

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.

Configuration and Usage

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

  • Send XML instead of Protobuf when in Form Input or Form XML mode: Enable this option to skip serializing the request as binary Protobuf, such as when using the Protobuf client as a consumer only to avoid conversion errors in a request that will not be used.

Schema for Modeling Request Payload Using Form Input

  • Message type: Choose from the type definitions available in the schemas built into your protobuf-extension.jar.

Adding Protobuf Message Responders

You can add Protobuf message responders to your suite using the Add Responder wizard. See Creating Message Responders Manually for details. 

Configuration and Usage

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

  • Respond with XML instead of Protobuf when in Form Input or Form XML mode: Enable this option when chaining other tools to process the Protobuf message in XML format. 

Schema for Modeling Request Payload Using Form Input

  • Message type: Choose from the type definitions available in the schemas built into your protobuf-extension.jar.

You can also configure the responder to use a different Protobuf message type for incoming requests. To do so:

  1. In the message responder, click the Options tab and choose Request Handling.
  2. Enable Convert incoming request to XML using different message format than response.
  3. Choose Protobuf from the Format menu.
  4. Choose the message type that is expected to come into the virtual asset from the Message type menu that appears.

Specifying Conversion Options

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:

  • Package: An optional package name to use for parsing native Protobuf messages.
  • Message: An optional message type name to use for parsing native Protobuf messages.
  • Format: Controls whether to expect Protobuf messages in the standard binary format or in ProtoJSON format. By default, messages are generated in binary format. The message format for parsing native messages is detected automatically unless specified.
  • Log Level: Specify how much information you want logged to the console. The default is 2 (warn).

Package and Message Usage

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.

Working with ProtoJSON

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:

  1. Set Input mode to Literal and provide the JSON version of the Protobuf message in the text area.
  2. Switch to the Form Input view. The Message type field and Form Input fields will be automatically populated from the JSON message. At runtime, the Protobuf message generated from the Form Input view will be in binary format by default.

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, set Conversion direction to From XML to native and set Format to JSON. The Message type can be left blank because it will be inferred from the XML. A JSON Assertor can then be chained to the XML Converter tool, for example.

Using Protobuf with gRPC

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.

  • No labels

Need assistance? Visit our support page