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
- Choose Parasoft > Preferences.
- In the System Properties preferences page, click Add JARs.
- In the file chooser that opens, select websockettransport.jar.
- Click Apply and restart SOAtest.
Command Line Installation
Add the websockettransport.jar file to the system.properties.classpath property in your localsettings 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 ( 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: |
| Mode | Specify the message mode for the transport. The following modes are valid:
Default: |
| 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 Default: |
| Connection Timeout | Specify how long (in milliseconds) to wait for a connection to be established before timing out. Default: |
| Log Level | Specify how much information you want logged to the console and the Event Monitoring view. The following levels are available:
Default: |
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., You can also use the XPath and operator to match multiple nodes in the message, e.g., If the XPath evaluates to the Boolean Default: |
|---|---|
| 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: |
| Timeout | Specify how long (in milliseconds) to wait for an incoming message before timing out. Default: |
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 Testing Considerations
You should enable the Tests run as a group option in the parent Test Suite under Execution Options when load testing clients that open a shared WebSocket connection. This option is required so that each virtual user (VU) can run the entire scenario, which enables each VU to create and reuse its own WebSocket connections. If the Tests are individually runnable option 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.
