Socket.IO Engine
Socket.IO (opens in a new tab) is a popular library for building real-time event-based applications. This page covers Socket.IO testing functionality in Artillery provided by the built-in Socket.IO engine.
Enabling Socket.IO support
To use the Socket.IO engine in an Artillery scenario, set the engine
attribute of a scenario definition to socketio
.
scenarios:
- name: My Socket.IO test
engine: socketio # Enable the Socket.IO engine
flow:
- emit:
channel: "echo"
data: "Hello world!"
Socket.IO-specific configuration
Query
Query parameters (opens in a new tab) can be specified as a string or as a dictionary:
config:
target: "https://myapp.staging:3002"
socketio:
query: "user_id=0xc0ffee&color=blue"
config:
target: "https://myapp.staging:3002"
socketio:
query:
user_id: "0xc0fee"
color: "blue"
Path
A custom path (opens in a new tab) may be set with the path
option.
In the following example, the virtual users will connect to the admin
namespace with the custom path mypath
:
config:
target: "https://myapp.staging:3002/admin"
socketio:
path: "/mypath"
Extra headers
Extra headers (opens in a new tab) may be passed with extraHeaders
option:
config:
target: "https://myapp.staging:3002/admin"
socketio:
extraHeaders:
x-client-id: "abc"
The extraHeaders
option only works if the default polling
transport is used. When using other transports, extra headers won't be taken into account by the server.
WebSocket transports only
You can skip long-polling (opens in a new tab) by using the transports
option to specify WebSocket transport:
config:
target: "https://myapp.staging:3002/admin"
socketio:
transports: ["websocket"]
Scenario actions and configuration
The Socket.IO engine allows for HTTP actions actions to be used in scenarios alongside emit
, which is the main Socket.IO action. Looping with loop
and pausing execution with think
is also supported, see Testing HTTP for details.
emit
Sending Data
The emit
action supports the following attributes:
channel
- The name of the Socket.IO channel to emit an event.data
- The data to emit as a string.namespace
- Optional namespace to use for emitting the event.
Multiple arguments for the emit
actions are not supported yet
Acknowledgements & Response Validation
Additionally, if you need to wait for an Socket.IO acknowledgement response (opens in a new tab) or validate a response, you can also use the following attributes:
response
- Optional object if you want to wait for a response:channel
- The name of the channel where the response is received.data
- The data to verify is in the response.
acknowledge
- Optional object if you want to wait for an acknowledgement.
If you emit to a specific namespace, the response data is expected within the same namespace.
Validating an acknowledgement response may be done by setting one of the following attributes on acknowledge
:
data
- Match the response exactly to the value provided.match
- Match the response with a JSONPath expression. This attribute expects an object with two attributes:json
- The part of the response to compare.value
- The expected value.
Examples
Emit a single event:
config:
target: "https://socketio.test/"
phases:
- duration: 60
arrivalRate: 25
scenarios:
- name: "Emit an event"
engine: socketio
flow:
- emit:
channel: "echo"
data: "Hello from Artillery"
Emit an event and validate a response:
config:
target: "https://socketio.test/"
phases:
- duration: 60
arrivalRate: 25
scenarios:
- name: "Emit an event"
engine: socketio
flow:
- emit:
channel: "echo"
data: "Hello from Artillery"
response:
channel: "echoResponse"
data: "Hello from Artillery"
Emit an event and validate an acknowledgement:
config:
target: "https://socketio.test/"
phases:
- duration: 60
arrivalRate: 25
scenarios:
- name: "Emit and validate acknowledgement"
engine: socketio
flow:
- emit:
channel: "userDetails"
acknowledge:
match:
json: "$.0.name"
value: "Artillery"
Emit data to a namespace:
config:
target: "https://socketio.test/"
phases:
- duration: 60
arrivalRate: 25
scenarios:
- name: "Emit to /namespace1"
engine: socketio
emit:
namespace: "/namespace1"
channel: "echo"
data: "Emitting data to namespace"
Mixing in HTTP Actions
A single scenario can combine both HTTP and Socket.IO actions.
The following example is a common scenario when testing servers based on Express.js (opens in a new tab):
config:
target: "http://lab.artillery.io"
phases:
- duration: 10
arrivalRate: 1
scenarios:
- engine: "socketio"
flow:
- get:
url: "/movies/10"
capture:
- json: "$.title"
as: "title"
- json: "$.genre"
as: "genre"
- log: "Emitting captured values: {{ title }}, {{ genre }}"
- emit:
channel: "echo"
data: "{{ title }}"
# validate the received response
response:
channel: "echoResponse"
data: "{{ title }}"
- emit:
channel: "echo"
data: "{{ genre }}"
response:
channel: "echoResponse"
data: "{{ genre }}"
- think: 1
- emit:
channel: "echo"
data: "do not care about the response"
- emit:
channel: "echo"
data: "still do not care about the response"
- think: 1
Try it live! (opens in a new tab)
Connecting Without Sending Any Data
You can use think
to emulate clients connecting to the app and listening without sending anything themselves.
config:
target: "https://socketio.test/"
phases:
- duration: 3600
arrivalRate: 5
scenarios:
- engine: "socketio"
flow:
- think: 600 # do nothing for 10m and disconnect
Debugging
If you're having issues getting your test scenarios to complete successfully, you can print out helpful debugging messages using the DEBUG
environment variable.
Print errors
Set DEBUG=socketio
when running your tests to view any errors that occurred during the test run.
On macOS and Linux systems, you can temporarily set the DEBUG
environment variable by setting its value when running your Artillery test script:
DEBUG=socketio artillery run my-script.yaml
For the Windows Command Prompt, you first need to set the DEBUG
environment variable using the set
command before running the test script:
set DEBUG=socketio
artillery run my-script.yaml
If you use PowerShell on Windows, you can set the DEBUG
environment variable using $Env:DEBUG
before running the test script:
$Env:DEBUG = 'socketio'
artillery run my-script.yaml