k6/websockets

WebSocket API with browser-compatible interface and global event loop

The k6/websockets module implements the browser WebSocket API with additional k6-specific functionality like cookies, tags, and custom headers.

The k6/experimental/websockets module has been deprecated. Use k6/websockets instead.

Overview

This module uses a global event loop instead of a local one, which enables a single VU to handle multiple concurrent WebSocket connections. This improves performance compared to the older k6/ws module.

Key Difference from k6/ws

The main difference between k6/websockets and k6/ws is that this module uses a global event loop, allowing a single VU to have multiple concurrent connections, which improves performance.

Importing the Module

import { WebSocket } from 'k6/websockets';

API Reference

Classes and Methods

WebSocket(url, protocols, params) · constructor

Constructs a new WebSocket connection.

Parameters:

url · string · required

WebSocket URL (e.g., wss://echo.websocket.org)

protocols · string | string[]

Optional protocol(s) to use

params · Params

Connection parameters (headers, cookies, compression, tags)

Instance Methods

WebSocket.close() · function

Closes the WebSocket connection.

WebSocket.ping() · function

Sends a ping frame to the server.

WebSocket.send(data) · function

Sends data through the WebSocket connection.

Parameters:

data · string | ArrayBuffer | Blob · required

Data to send to the server

WebSocket.addEventListener(event, handler) · function

Adds an event listener for a specific event.

Parameters:

event · string · required

Event name: 'open', 'message', 'error', 'close', 'ping', 'pong'

handler · function · required

Callback function to handle the event

Instance Properties

WebSocket.readyState · number

The current state of the connection. One of:

• 0 - CONNECTING
• 1 - OPEN
• 2 - CLOSING
• 3 - CLOSED

WebSocket.url · string

The URL of the connection as resolved by the constructor.

WebSocket.bufferedAmount · number

The number of bytes queued using send() but not yet transmitted.

WebSocket.binaryType · string

Controls the type of binary data received. Either "blob" (default) or "arraybuffer".

Event Handlers

WebSocket.onopen · function

Handler called when the connection is established.

WebSocket.onmessage · function

Handler called when a message is received.

WebSocket.onerror · function

Handler called when an error occurs.

WebSocket.onclose · function

Handler called when the connection is closed.

WebSocket.onping · function

Handler called when a ping is received.

WebSocket.onpong · function

Handler called when a pong is received.

Connection Parameters

Params Object

compression · string

Compression algorithm to use. Currently only "deflate" is supported.

jar · http.CookieJar

Cookie jar for the WebSocket connection. Uses the default VU cookie jar if not specified.

headers · object

Custom HTTP headers to include in the WebSocket handshake request.

headers: { 'X-MyHeader': 'k6test' }

tags · object

Custom metric tags for filtering results and setting thresholds.

tags: { k6test: 'yes' }

WebSocket Metrics

k6 automatically collects WebSocket-specific metrics:

Metric	Type	Description
ws_connecting	Trend	Time to establish connection
ws_session_duration	Trend	Total session duration
ws_sessions	Counter	Total number of sessions
ws_msgs_sent	Counter	Messages sent
ws_msgs_received	Counter	Messages received
ws_ping	Trend	Ping round-trip time

Examples

Multiple Concurrent Connections

This example shows how a single VU can run multiple WebSocket connections asynchronously:

Multiple Connections

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);

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

function startWSWorker(id) {
  const ws = new WebSocket(`wss://quickpizza.grafana.com/ws`);
  ws.binaryType = 'arraybuffer';

  ws.addEventListener('open', () => {
    ws.send(JSON.stringify({ event: 'SET_NAME', new_name: `VU ${__VU}:${id}` }));

    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}`);
      }
    });

    const intervalId = setInterval(() => {
      ws.send(JSON.stringify({ event: 'SAY', message: `I'm saying ${randomString(5)}` }));
    }, randomIntBetween(2000, 8000));

    const timeout1id = setTimeout(function () {
      clearInterval(intervalId);
      console.log(`VU ${__VU}:${id}: ${sessionDuration}ms passed, leaving the chat`);
      ws.send(JSON.stringify({ event: 'LEAVE' }));
    }, sessionDuration);

    const timeout2id = setTimeout(function () {
      console.log(`Closing the socket forcefully 3s after graceful LEAVE`);
      ws.close();
    }, sessionDuration + 3000);

    ws.addEventListener('close', () => {
      clearTimeout(timeout1id);
      clearTimeout(timeout2id);
      console.log(`VU ${__VU}:${id}: disconnected`);
    });
  });
}

import { WebSocket } from 'k6/websockets';

export default function () {
  const url = 'ws://localhost:10000';
  const params = {
    headers: { 'X-MyHeader': 'k6test' },
    tags: { k6test: 'yes' },
  };

  const ws = new WebSocket(url, null, params);

  ws.onopen = () => {
    console.log('WebSocket connection established!');
    ws.close();
  };
}

Related Resources

k6/ws

Alternative WebSocket module with local event loop

Blob

Handle binary data in WebSocket messages

WebSocket Testing Guide

Learn WebSocket testing patterns

Metrics Reference

WebSocket metrics documentation