Overview

This page covers WebSocket testing functionality in Artillery provided by the built-in WebSocket engine.

Enabling WebSocket support

To use the WebSocket engine in an Artillery scenario, set the engine attribute of a scenario definition to ws.

scenarios:
    - name: My WebSocket test
      engine: ws # Enable the Socket.io engine
      flow:
          - send: "Hello world!"

WebSocket-specific configuration

Setting Subprotocols

WebSocket subprotocols may be configured with config.ws.subprotocols option:

config:
  target: "wss://my.websocket.service"
  phases:
    - duration: 20
      arrivalRate: 10
  ws:
    # Set a custom subprotocol:
    subprotocols:
      - json
      - soap
scenarios:
  - engine: "ws"
    flow:
      - send: "hello"
      - think: 1
      - send: "world"

Specifying Headers

Connection headers may be specified via config.ws object. For example, to set a custom subprotocol via the Sec-WebSocket-Protocol header:

config:
  target: "wss://echo.websocket.org"
  phases:
    - duration: 20
      arrivalRate: 10
  ws:
    # Set a custom subprotocol:
    headers:
      Sec-WebSocket-Protocol: my-protocol
scenarios:
  - engine: "ws"
    flow:
      - send: "hello"
      - think: 1
      - send: "world"

Other configuration options

The underlying WebSocket client can be configured with a "ws" section in the "config" section of your test script. For a list of available options, please see WS library docs.

Scenario actions and configuration

Four types of actions are supported: send, think, loop, and function.

Sending data with `send`

Use send to send data to the server:

If the argument is an object, it will be converted to a string with JSON.stringify before being sent.

- send: "a string"
# the following will be stringified and sent as '{"x":5,"y":6}'
- send:
    x: 5
    y: 6

Pausing execution with `think`

To pause the virtual user for N seconds, use a think action:

- send: "hello"
- think: 5 # pause for 5 seconds
- send: "world"

Repeating actions with `loop`

See Testing HTTP for a detailed description of the loop action.

Running custom code with `function`

Custom JS code may be run with the function action:

config:
  target: "wss:/my.server"
  processor: "./my-functions.js"
scenarios:
  - engine: ws
    flow:
      - function: "createTimestampedObject"
      - send: "{{ data }}"

// my-functions.js

module.exports = { createTimestampedObject };

function createTimestampedObject(userContext, events, done) {
  const data = { timestamp: Date.now(), hello: "world" };
  // set the "data" variable for the virtual user to use in the subsequent action
  userContext.vars.data = data;
  return done();
}

Example

config:
  target: "wss://echo.websocket.org"
  phases:
    - duration: 20
      arrivalRate: 10
  ws:
    # Ignore SSL certificate errors
    # - useful in *development* with self-signed certs
    rejectUnauthorized: false
scenarios:
  - engine: "ws"
    flow:
      - send: "hello"
      - think: 1
      - send: "world"