Skip to main content

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us