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
- Go to Parasoft > Preferences and click System Properties.
- Click Add JARs and choose the websockettransport.jar file.
- Click Apply.
- 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 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 ( 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 ( 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. The default is |
| Mode | Specify the message mode for the transport. The following modes are valid:
The default is |
| Frame Type | Specify the frame type for the messages, either 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 The default is |
| Connection Timeout | Specify how long (in milliseconds) to wait for a connection to be established before timing out. The default is |
| Log Level | Specify how much information you want logged to the console and the Event Monitoring view. The following levels are available:
The default is |
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 ten HTTP headers. Headers are configured using a name:value format, for example, 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, 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: You can also use the XPath and operator to match multiple nodes in the message, for example, If the XPath evaluates to the Boolean The default is |
|---|---|
| Message Format | Specify the format (for example, XML, JSON, and so on) 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. The default is |
| Timeout | Specify how long (in milliseconds) to wait for an incoming message before timing out. The default is |
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 Keep connection alive or Close connection after test execution. The WebSocket transport allows multiple active connections to be used.
If the connection ID matches the ID for a connection that is already open, 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, a new connection will be created.
If Keep connection alive is enabled, SOAtest will not call close() on the connection at the end of that test's execution. If Close connection after test execution 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.
- Saxon HE (Mozilla Public License 2.0)
- JCS Core (Apache License 2.0)
- SLF4J (MIT License)
- Tyrus (CDDL1.1 and GPL 2.0 with Classpath Exception)
Additional license details are available in this plugin's licenses folder.
