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"