A Guide to JMeter WebSocket Samplers

WebSocket is a protocol that provides a two-way communication channel between a web browser and a server over a single TCP connection. This protocol is becoming more and more popular each year and is supported by most of modern browsers. In this blog, we'll cover various JMeter WebSocket Samplers including when to use them.

How Does JMeter Handle WebSockets?

Apache JMeter™ doesn’t support the WebSocket protocol out of the box. However, there are a couple of plugins we can use to help with that. One of them is the JMeter WebSocket Sampler by Maciej Zaleski, you can learn how to use it in this blog post. Another great plugin is JMeter WebSocket Samplers by Peter Doornbosch.

Installing the Plugin

Follow the next steps to install this plugin:

• Download the most recent plugin JAR file from this link
• Copy the file to the lib/ext directory of your JMeter
• Restart JMeter

After these manipulations you will find some new elements and features in JMeter:

• Config elements: WebSocket Binary Frame Filter, WebSocket Text Frame Filter, WebSocket Ping/Pong Frame Filter;
• Samplers: WebSocket Open Connection, WebSocket Ping/Pong, WebSocket request-response Sampler, WebSocket Single Write Sampler, WebSocket Single Read Sampler, WebSocket Close;
• Assertions: Binary Response Assertion;
• Binary display option for View Results Tree listener.

Let’s take a look at some more details and features of these new Samplers. We will cover the new Config Elements and Assertions in the next blog post.

A short description about each of the samplers:

• WebSocket Open Connection - Opens a WebSocket connection
• WebSocket Ping/Pong - Sends a ping and receives a pong
• WebSocket request-response Sampler - Sends and receives text or binary WebSocket frames
• WebSocket Single Write Sampler - Sends text or binary WebSocket frames
• WebSocket Single Read Sampler - Receives text or binary WebSocket frames
• WebSocket Close - Closes a websocket connection

In my opinion, the best way to learn about all of these samplers is to create some real scripts and try them in action. So let’s do that. We will show how to use all of the new samplers in a test scenario, even though in most cases you will use only some of these samplers in your scripts.

We will use a free public Gateway Echo service to create our script. The endpoint of it is ws://echo.websocket.org. Since this is an Echo service, all messages sent to this service will be echoed back to the client.

So, let’s begin!

1. Add a Thread Group to the Test plan.

Test plan -> Add -> Thread (Users) -> Thread Group

WebSocket Open Connection

2. Add a WebSocket Open Connection sampler to the Thread Group. The current sampler will explicitly set up a WebSocket connection.

Thread Group -> Add -> Sampler -> WebSocket Open Connection

Review all the fields of this sampler and fill in the following values:

• Protocol: ws
• Server name or IP: echo.websocket.org
• Port: 80
• Path: (empty)
• Connection timeout (ms): 20000
• Read timeout (ms): 6000

The protocol can be WS or WSS (Secure WebSocket). Use WSS for encrypted connections.

The connection timeout parameter specifies how long JMeter will wait for a connection before failing by timeout.

The read timeout parameter specifies how long JMeter will wait for a response from the server before failing by timeout.

Ramp up your JMeter testing with BlazeMeter — the industry's most-trusted performance testing platform. Get started for FREE today!

Start Testing Now

WebSocket Ping/Pong

3. Add a WebSocket Ping/Pong sampler to the Thread Group. We need this sampler to test the Ping/Pong functionality.

Thread Group -> Add -> Sampler -> WebSocket Ping/Pong

This sampler specifies the following parameter:

• Pong (read) timeout (ms): 6000

Pong timeout means that the sampler will fail if JMeter doesn’t get a pong message within 6 seconds. This sampler will use the existing connection.

WebSocket request-response Sampler

4. Add a WebSocket request-response Sampler to the Thread Group. This sampler will be used for sending a text frame and receiving an answer from the server.

Thread Group -> Add -> Sampler -> WebSocket request-response Sampler

Fill in the following values:

• Connection: use existing connection
• Data type: Text
• Request data: blazemeter
• Response (read) timeout (ms): 6000

The connection option can be used to set up a new WebSocket connection or use the existing one. The data area specifies the data type, the data itself and the response timeout value.

5. Add a WebSocket request-response Sampler to the Thread Group. The next sampler will send binary data to the Echo service.

Thread Group -> Add -> Sampler -> WebSocket request-response Sampler

Set the following fields:

• Connection: use existing connection
• Data type: Binary
• Request data: 0x62 0x6c 0x61 0x7a 0x65 0x6d 0x65 0x74 0x65 0x72
• Response (read) timeout (ms): 6000

Request data accepts binary frames in hexadecimal format, for example 0x6d or 6d. The value of our current request means blazemeter in hexadecimal format. We can also use JMeter variables in this field.

WebSocket Single Write Sampler

6. Add a WebSocket Single Write Sampler to the Thread Group. This request will send data to the server without waiting for response.

Thread Group -> Add -> Sampler -> WebSocket Single Write Sampler

Fill in the following values:

• Connection: use existing connection
• Data type: Text
• Request data: blazemeter-text

Same as for the WebSocket request-response Sampler, we can use the existing connection or create a new one. Data should be in text format.

7. Add a WebSocket Single Write Sampler to the Thread Group. This sampler will be used to send a binary message.

Thread Group -> Add -> Sampler -> WebSocket Single Write Sampler

Fill in the following values:

• Connection: use existing connection
• Data type: Binary
• Request data: 0x62 0x6c 0x61 0x7a 0x65 0x6d 0x65 0x74 0x65 0x72 0x2d 0x74 0x65 0x78 0x74

The request data is added in hexadecimal format and means blazemeter-text.

WebSocket Single Read Sampler

8. Add a WebSocket Single Read Sampler to the Thread Group. This sampler is needed for receiving text messages.

Thread Group -> Add -> Sampler -> WebSocket Single Read Sampler

Set the following fields:

• Connection: use existing connection
• Data type: Text
• Response (read) timeout: 6000

Since this sampler is using the existing connection, we expect to receive a text message from our Echo service.

9. Add a WebSocket Single Read Sampler to the Thread Group. This sampler should catch a binary message.

Thread Group -> Add -> Sampler -> WebSocket Single Read Sampler

Fill in the following values:

• Connection: use existing connection
• Data type: Binary
• Response (read) timeout: 6000

The sampler will fail if a binary message is not received within 6 seconds..

WebSocket Close

10. Add a WebSocket Close sampler to the Thread Group. Of course, we need to close our connection properly. 

Thread Group -> Add -> Sampler -> WebSocket Close

Fill in the following values:

• Close status: 1000
• Response (read) timeout: 6000

This sampler will close the existing WebSocket connection with the reason ‘1000: sampler requested close‘.

11. Add a View Results Tree listener to the Thread Group.

Thread Group -> Add -> Listener -> View Results Tree

12. Run the script!

Check the View Results Tree listener. All samplers should have a green check indicating that all samplers passed successfully. Let‘s review the request and response data for each request, to better understand how they work.

13. WebSocket Open Connection sampler

Request:

• Connect URL: ws://echo.websocket.org:80/

Response:

• Empty

A WebSocket connection was opened with this sampler. Nothing was sent in response.

14. WebSocket Ping/Pong sampler

Request:

• Connect URL: ws://echo.websocket.org:80/

Response:

• Empty

JMeter sent a Ping frame and received a Pong frame.

15. WebSocket request [Text] sampler

Request:

• Connect URL: ws://echo.websocket.org:80/
• Request data: blazemeter

Response:

• See attachment below

As we can see in the screenshot above, the Echo service responded with the same message that was sent.

16. WebSocket request [Binary] sampler

Request:

• Connect URL: ws://echo.websocket.org:80/
• Request data: 0x62 0x6c 0x61 0x7a 0x65 0x6d 0x65 0x74 0x65 0x72

Response:

• See attachment below

Binary data is presented in the response data tab of this request.

NOTE! To see binary data we need to change the display option in the View Results Tree listener from Text to Binary.

17. WebSocket Single Write Sampler [Text]

Request:

• Connect URL: ws://echo.websocket.org:80/
• Request data: blazemeter-text

Response:

• Empty

This sampler sent a text message to the server and didn’t get anything in response.

18. WebSocket Single Write Sampler [Binary]

Request:

• Connect URL: ws://echo.websocket.org:80/
• Request data: 0x62 0x6c 0x61 0x7a 0x65 0x6d 0x65 0x74 0x65 0x72 0x2d 0x74 0x65 0x78 0x74

Response:

• Empty

The Write sampler sent binary data to the server and didn’t get anything in response.

19. WebSocket Single Read Sampler [Text]

Request:

• Connect URL: ws://echo.websocket.org:80/

Response:

• See attachment below

The Read sampler received a text message as expected.

20. WebSocket Single Read Sampler [Binary]

Request:

• Connect URL: ws://echo.websocket.org:80/

Response:

• See attachment below

This sampler received a binary frame, as we can see in the screenshot above.

21. WebSocket Close sampler

Request:

• Requested connection closed with status 1000 and the reason 'sampler requested close'.

Response:

• 1000: sampler requested close

The close sampler successfully closed the WebSocket connection.

This script detailed some basic uses of all the WebSocket samplers available in the JMeter WebSocket Samplers by Peter Doornbosch plugin. Now you know how to use them and you can create awesome scripts for your needs!

I hope this was useful for you! Let us know if you have any questions in the comments section below.

Now that you know how to use the JMeter Websocket Plugin, you are ready to take our advanced JMeter course, free from BlazeMeter University.

Try out BlazeMeter for free to enhance your JMeter abilities!

START TESTING NOW

Related Resources: 

• JMeter’s Dummy Sampler - The Ultimate Guide
• WebSocket Testing With Apache JMeter