k6/websockets

Modern WebSocket API for k6 load testing

k6/websockets

The k6/websockets module provides a modern, standards-compliant WebSocket API for k6. This is the newer WebSocket implementation that follows the browser WebSocket API more closely.

This module is different from k6/ws, which provides the legacy WebSocket API. The k6/websockets module offers a more modern, event-driven approach.

WebSocket Class

The main class for creating WebSocket connections.

Constructor

import { WebSocket } from 'k6/websockets';

const ws = new WebSocket(url);
const wsWithProtocol = new WebSocket(url, protocols);

url · string · required

The WebSocket server URL (must start with ws:// or wss://)

protocols · string | string[]

Optional subprotocol(s) to use

Properties

binaryType · string

Type of binary data being received. Can be "blob" or "arraybuffer" (default: "blob")

bufferedAmount · number

Number of bytes queued to be sent (read-only)

extensions · string

Extensions selected by the server (read-only)

protocol · string

Subprotocol selected by the server (read-only)

readyState · number

Current connection state:

• 0 (CONNECTING): Connection not yet established
• 1 (OPEN): Connection is open and ready to communicate
• 2 (CLOSING): Connection is in the process of closing
• 3 (CLOSED): Connection is closed

url · string

The WebSocket URL (read-only)

Methods

send()

Sends data through the WebSocket connection.

data · string | ArrayBuffer | Blob · required

Data to send to the server

ws.send("Hello, server!");
ws.send(JSON.stringify({ type: "message", content: "Hello" }));

close()

Closes the WebSocket connection.

code · number

Numeric status code (default: 1000)

reason · string

Human-readable closing reason

ws.close();
ws.close(1000, "Normal closure");

Event Handlers

addEventListener()

Registers an event listener for WebSocket events.

event · string · required

Event type: "open", "message", "close", "error", or "ping"/"pong"

handler · function · required

Function to call when the event occurs

ws.addEventListener('open', () => {
  console.log('Connection opened');
});

ws.addEventListener('message', (event) => {
  console.log('Received:', event.data);
});

ws.addEventListener('close', () => {
  console.log('Connection closed');
});

ws.addEventListener('error', (event) => {
  console.error('WebSocket error:', event.error);
});

Complete Example

Based on the k6 source example:

import { randomString, randomIntBetween } from 'https://jslib.k6.io/k6-utils/1.1.0/index.js';
import { WebSocket } from 'k6/websockets';

const sessionDuration = randomIntBetween(1000, 3000); // user session between 1s and 3s

export default function () {
  for (let i = 0; i < 4; i++) {
    startWSWorker(i);
  }
}

function startWSWorker(id) {
  // Create a new websocket connection
  const ws = new WebSocket(`wss://quickpizza.grafana.com/ws`);
  ws.binaryType = 'arraybuffer';
  
  ws.addEventListener('open', () => {
    // Change the user name
    ws.send(JSON.stringify({ event: 'SET_NAME', new_name: `VU ${__VU}:${id}` }));
    
    // Listen for messages/errors and log them into console
    ws.addEventListener('message', (e) => {
      const msg = JSON.parse(e.data);
      if (msg.event === 'CHAT_MSG') {
        console.log(`VU ${__VU}:${id} received: ${msg.user} says: ${msg.message}`);
      } else if (msg.event === 'ERROR') {
        console.error(`VU ${__VU}:${id} received:: ${msg.message}`);
      } else {
        console.log(`VU ${__VU}:${id} received unhandled message: ${msg.message}`);
      }
    });
    
    // Send a message every 2-8 seconds
    const intervalId = setInterval(() => {
      ws.send(JSON.stringify({ event: 'SAY', message: `I'm saying ${randomString(5)}` }));
    }, randomIntBetween(2000, 8000)); // say something every 2-8 seconds
    
    // After a sessionDuration stop sending messages and leave the room
    const timeout1id = setTimeout(function () {
      clearInterval(intervalId);
      console.log(`VU ${__VU}:${id}: ${sessionDuration}ms passed, leaving the chat`);
      ws.send(JSON.stringify({ event: 'LEAVE' }));
    }, sessionDuration);
    
    // After a sessionDuration + 3s close the connection
    const timeout2id = setTimeout(function () {
      console.log(`Closing the socket forcefully 3s after graceful LEAVE`);
      ws.close();
    }, sessionDuration + 3000);
    
    // When connection is closing, clean up the previously created timers
    ws.addEventListener('close', () => {
      clearTimeout(timeout1id);
      clearTimeout(timeout2id);
      console.log(`VU ${__VU}:${id}: disconnected`);
    });
  });
}

Event Objects

MessageEvent

data · string | ArrayBuffer | Blob

The data sent by the server

origin · string

The origin of the WebSocket server

CloseEvent

code · number

The close code sent by the server

reason · string

The reason for closing

wasClean · boolean

Whether the connection closed cleanly

Key Differences from k6/ws

k6/websockets

• Event-driven API
• Multiple event listeners
• Standards-compliant
• Modern browser-like API

k6/ws

• Callback-based API
• Single handler per event
• Legacy implementation
• Simpler for basic use cases

Use Cases

• Real-time chat applications
• Live notifications and updates
• Multiplayer games
• Financial tickers and dashboards
• IoT device communication

Related Resources

• k6/ws (Legacy API)
• WebSocket Protocol Testing
• Timers Module