In this section:

Introduction

The Parasoft WebSocket Transport Extension adds support for the WebSocket transport to applicable messaging client tools in SOAtest. This enables you to take full advantage of SOAtest's rich interface when configuring, sending, and validating messages sent over WebSockets. The WebSocket Transport Extension supports messages sent over the WS or WSS protocols per the RFC 6455 standard.

Prerequisites

  • SOAtest 9.10.0 or later
  • Oracle Java 8

Installation

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

UI Installation

  1. Choose Parasoft > Preferences.
  2. In the System Properties preferences page, click Add JARs.
  3. In the file chooser that opens, select websockettransport.jar.
  4. Click Apply and restart SOAtest.

Command Line Installation

Add the websockettransport.jar file to the system.properties.classpath property in your settings properties file. For example:

system.properties.classpath=<path to jar>/websockettransport.jar

Usage

The WebSocket Transport is used in the following tools:

The transport is configured in the transport tab. To use the WebSocket Transport, select WebSocket in the Transport drop-down menu, then configure the available options (see Configuration Options).

Configuration Options

The following configuration options are available.

Connection Settings

URI

Specify the URI you want to invoke, including the protocol (ws:// or wss://).

This is required to create a new connection. After the initial connection is created, you can use the connection ID to control which connection you want to work with.

Connection ID

Specify a connection ID if you are testing multiple connections. Any string can be used for connection IDs.

If you specify a connection ID that references an already-open connection, as well as a URI, the URI will be ignored because the connection will already be open.

You do not need to set the connection ID if you are working with a single connection within a test suite; SOAtest will use the default value (<default>) for the connection ID.

However, if you want to open and send/receive messages on multiple connections within the same scenario, you need to specify unique connection IDs for each of them.

Default: <default>.

Mode

Specify the message mode for the transport. The following modes are valid:

send: The transport will send a message but will not wait to process incoming messages from the server.

receive: The transport will wait for an incoming message that matches the criteria specified in the Incoming Message Handling options.

sendAndReceive: The transport first sends the message configured within SOAtest, then it waits for an incoming message that matches the criteria specified in the Incoming Message Handling options.

Default: <sendAndReceive>.

Frame Type

Specify the frame type for the messages, either text or binary.

The WebSocket protocol transmits payloads using data frames, which much be configured with a text or a binary type. You should use the default value (text) in all cases except when sending a binary message, in which case you should use binary.  See https://tools.ietf.org/html/rfc6455#section-5.6

Default: text.

Connection Timeout

Specify how long (in milliseconds) to wait for a connection to be established before timing out.

Default: 5000.

Log Level

Specify how much information you want logged to the console and the Event Monitoring view. The following levels are available:

1: error

2: warn

3: info

4: debug

Default: 2.

HTTP Headers Settings

When WebSocket connections are opened, there is an opening handshake that is an HTTP Upgrade request. This section configures HTTP headers that should be sent as part of this upgrade request (see https://tools.ietf.org/html/rfc6455#section-1.3).

You can configure up to 10 HTTP headers. Headers are configured using a name:value format, e.g., User-Agent:Mozilla/5.0.

Incoming Message Handling

Once SOAtest opens a connection, the transport listens for all incoming messages from the server and adds them to an internal queue. When in receive or sendAndReceive mode, the transport attempts to find a message that matches the settings specified the Message Selector setting. The queue is checked first. If a matching message is found, then that message is sent to the Traffic Viewer as the response message. The message is also sent to tools that are chained to the response outputs of the client tool. If a matching message is not found in the queue, then the transport waits for a message to come from the server that matches the Message Selector settings. If no message is received within the specified timeout then an error message is reported.

Messages remain on the internal queue until the connection is closed by SOAtest. If the connection is closed by the server, then the messages will remain in the queue so that you can validate messages that the server may send to the client immediately before closing the connection.

Message Selector

Specify an XPath that selects which incoming message should be processed by the transport. The XPath should select a node in the message and a value for the node using the following format: xpath=value (e.g., /root/name=”Bob”).

You can also use the XPath and operator to match multiple nodes in the message, e.g., /root/name=”Bob” and /root/age=”40”.

If the XPath evaluates to the Boolean true, a non-zero number, a node or a set of nodes, the XPath is considered a match. If the XPath evaluates to false, the number 0, or an empty set of nodes, then the XPath is not considered a match. The matching rules for Booleans are based on W3C’s recommendations (see https://www.w3.org/TR/xpath-functions/#func-boolean).

Default: select next message. The default setting is used if this field is left blank. In this case, the transport will process the next message. This can be the next message in the queue or the next message that comes from the server if there are no queued messages.

Message Format

Specify the format (e.g., XML, JSON, etc.) of the incoming message being matched in the Message Selector. This field is only required if the expected message is not in XML or JSON format and a value is specified for Message Selector.

By default, the transport can automatically detect XML or JSON formats. If the message is in another format, you must specify it in this field.

The format should match the name of the format as it appears within an XML Converter tool or as it is defined within a custom message format. When a Message Format is specified, SOAtest will convert the message into XML based on the default conversion options for the specified message format.

Default: auto-detect.

Timeout

Specify how long (in milliseconds) to wait for an incoming message before timing out.

Default: 30000.

Example Use Case

The internal queue and message selector eliminate the dependency on ensuring that messages are received from the server in a specific order. Ensuring that a client is listening for a message at the exact moment the message is received from the server is also unnecessary.

If two different messages from the server are expected, for example, you can validate that they were received and that their contents are correct regardless of the order in which they are received. In this case, you would configure two different client tools with XPaths that match each message.

If the message the second tool is configured to match arrives before the first expected message, it will be added to the queue. The message that the first tool is configured to match will be processed when it arrives. The second tool will then be able to process its message already in the queue.

Connection Management Settings

You can enable either the Keep connection alive or Close connection after test execution option. The WebSocket transport allows multiple active connections to be used.

If the connection ID matches the ID for a connection that is already open, then that connection will be reused. If the connection ID matches an ID for a connection that has been closed or has never been used to open a connection previously, then a new connection will be created.

If the Keep connection alive option is enabled, SOAtest will not call close() on the connection at the end of that test's execution. If the Close connection after test execution option is enabled, SOAtest will close the connection at the end of that test’s execution. Unlike built-in transports, there is no final cleanup of open connections for custom transports when execution is finished, so you should enable Close connection after text execution for the last test of a given connection. If this is not done, the connection will stay open.

Example Scenario

In the following scenario, both connections will be kept open after the test run is over:

  • Connection A (keep alive)
  • Connection B (keep alive)
  • Connection A (keep alive)
  • Connection B (keep alive)

To fix this, you would enable Close connection after test execution for the last test that uses a particular connection:

  • Connection A (keep alive)
  • Connection B (keep alive)
  • Connection A (close connection)
  • Connection B (close connection)

Load Test Considerations

If you intend to load test clients that open a shared WebSocket connection, you should enable "Tests run as a group" in the parent Test Suite (which can be found on the Execution Options > Test Execution tab). This option allows each virtual user (VU) to run the entire scenario, so each VU is able to create and reuse its own WebSocket connections. If "Tests are individually runnable" is enabled instead, each VU will run one of the tests from the suite in isolation with no connection sharing available.

Third-party Content

This extension includes items that have been sourced from third parties as outlined below.

Additional license details are available in this plugin's licenses folder.

  • No labels