k6/ws on Grafana Labs

connect( url, params, callback )

Mon, 21 Sep 2026 15:16:28 +0000

connect( url, params, callback )

Note
A module with a better and standard API exists.

The new k6/websockets API partially implements the WebSockets API living standard.

When possible, we recommend using the new API. It uses a global event loop for consistency with other k6 APIs and better performance.

Initiate a WebSocket connection to a remote host.

Calling connect will block the VU finalization until the WebSocket connection is closed. Instead of continuously looping the main function (export default function () { ... }) over an over, each VU will be halted listening to async events and executing their event handlers until the connection is closed.

The following events can close the connection:

remote host close event.
Socket.close().
k6 VU interruption based on test configuration or CLI commands.

Parameter	Type	Description
url	string	Request URL (e.g. “wss://echo.websocket.org”).
params	object	Params object containing additional request parameters.
callback	function	The callback function that will be called when the WebSocket connection is initiated. A Socket object will be passed to the function, and this object can be used to set up callbacks etc when things happen on the WebSocket connection

Returns

Type	Description
Response	HTTP Response object.

Example

import ws from 'k6/ws';

export default function () {
  const url = 'wss://echo.websocket.org';
  const resp = ws.connect(url, null, function (socket) {
    socket.on('open', function () {
      console.log('WebSocket connection established!');
      socket.close();
    });
  });
}

Params

Mon, 21 Sep 2026 15:16:28 +0000

Params

Note
A module with a better and standard API exists.

The new k6/websockets API partially implements the WebSockets API living standard.

When possible, we recommend using the new API. It uses a global event loop for consistency with other k6 APIs and better performance.

Params is an object used by the WebSocket methods that generate WebSocket requests. Params contains request-specific options like headers that should be inserted into the request.

Name	Type	Description
`Params.compression`	string	Compression algorithm to be used by the WebSocket connection. The only supported algorithm currently is `deflate`. If the option is left unset or empty, it defaults to no compression.
`Params.jar`	http.CookieJar	The cookie jar that will be used when making the initial HTTP request to establish the WebSocket connection. If empty, the default VU cookie jar will be used.
`Params.headers`	object	Custom HTTP headers in key-value pairs that will be added to the initial HTTP request to establish the WebSocket connection. Keys are header names and values are header values.
`Params.tags`	object	Custom metric tags in key-value pairs where the keys are names of tags and the values are tag values. The WebSocket connection will generate metrics samples with these tags attached, allowing users to filter the results data or set thresholds on sub-metrics.

Example of custom metadata headers and tags

A k6 script that will make a WebSocket request with a custom header and tag results data with a specific tag

import ws from 'k6/ws';

export default function () {
  const url = 'wss://echo.websocket.org';
  const params = {
    headers: { 'X-MyHeader': 'k6test' },
    tags: { k6test: 'yes' },
  };
  const res = ws.connect(url, params, function (socket) {
    socket.on('open', function () {
      console.log('WebSocket connection established!');
      socket.close();
    });
  });
}

Socket

Mon, 21 Sep 2026 15:16:28 +0000

Socket

Note
A module with a better and standard API exists.

The new k6/websockets API partially implements the WebSockets API living standard.

When possible, we recommend using the new API. It uses a global event loop for consistency with other k6 APIs and better performance.

Socket is a WebSocket client to interact with a WebSocket connection. You can use it to listen various events happening on the WebSocket connection and send messages to the server. Additionally, you can use socket.setTimeout() and socket.setInterval() to execute code in the background, or repeatedly, while the WebSocket connection is open.

Method	Description
Socket.close()	Close the WebSocket connection.
Socket.on(event, callback)	Set up an event listener on the connection for any of the following events: - open - binaryMessage - message - ping - pong - close - error.
Socket.ping()	Send a ping.
Socket.send(data)	Send string data.
Socket.sendBinary(data)	Send binary data.
Socket.setInterval(callback, interval)	Call a function repeatedly at certain intervals, while the connection is open.
Socket.setTimeout(callback, period)	Call a function with a delay, if the connection is open.

WebSocket built-in metrics

k6 automatically collects metrics when interacting with a WebSocket service through the k6/ws API. Review the list in the metrics reference.

Check out the Results output article for more information about how to process the metric information.

Example

import ws from 'k6/ws';
import { check } from 'k6';

export default function () {
  const url = 'wss://echo.websocket.org';
  const params = { tags: { my_tag: 'hello' } };

  const response = ws.connect(url, params, function (socket) {
    socket.on('open', function open() {
      console.log('connected');
      socket.send(Date.now());

      socket.setInterval(function timeout() {
        socket.ping();
        console.log('Pinging every 1sec (setInterval test)');
      }, 1000);
    });

    socket.on('ping', function () {
      console.log('PING!');
    });

    socket.on('pong', function () {
      console.log('PONG!');
    });

    socket.on('pong', function () {
      // Multiple event handlers on the same event
      console.log('OTHER PONG!');
    });

    socket.on('message', function (message) {
      console.log(`Received message: ${message}`);
    });

    socket.on('close', function () {
      console.log('disconnected');
    });

    socket.on('error', function (e) {
      if (e.error() != 'websocket: close sent') {
        console.log('An unexpected error occured: ', e.error());
      }
    });

    socket.setTimeout(function () {
      console.log('2 seconds passed, closing the socket');
      socket.close();
    }, 2000);
  });

  check(response, { 'status is 101': (r) => r && r.status === 101 });
}
//VU execution won't be completely finished until the connection is closed.