Socket on Grafana Labs

Socket.close([code])

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

Socket.close([code])

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.

Close the WebSocket connection.

Parameter	Type	Description
code (optional)	number	WebSocket status code. (default: 1001)

Example

import ws from 'k6/ws';

export default function () {
  const url = 'wss://echo.websocket.org';
  const response = ws.connect(url, null, function (socket) {
    socket.on('open', function () {
      socket.close();
    });
  });
}

Socket.on(event, callback)

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

Socket.on(event, 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.

Set up callback functions for various events on the WebSocket connection. Multiple handlers can be defined for the same event.

Parameter	Type	Description
event	string	The event name to define a callback for.
callback	function	The function to call when the event happens.

Event name	Description
open	Emitted when the connection is established
message	Emitted when a message is received from the server.
ping	Emitted when a ping is received from the server. The client will automatically send back a `pong`.
pong	Emitted when a pong is received from the server.
close	Emitted when the connection is closed by the client Socket.close() or when the server sends the `close` event with code status 1000 (normal closure).
error	Emitted when an error occurs. Non-normal closure errors will be forwarded.

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

Socket.ping()

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

Socket.ping()

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.

Send a ping. Ping messages can be used to verify that the remote endpoint is responsive.

Example

import ws from 'k6/ws';

export default function () {
  const url = 'wss://echo.websocket.org';
  const response = ws.connect(url, null, function (socket) {
    socket.on('open', function () {
      socket.on('pong', function () {
        // As required by the spec, when the ping is received, the recipient must send back a pong.
        console.log('connection is alive');
      });

      socket.ping();
    });
  });
}

Socket.send(data)

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

Socket.send(data)

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.

Send a data string through the connection. You can use JSON.stringify to convert a JSON or JavaScript values to a JSON string.

Parameter	Type	Description
data	string	The data to send.

Example

import ws from 'k6/ws';

export default function () {
  const url = 'wss://echo.websocket.org';
  const response = ws.connect(url, null, function (socket) {
    socket.on('open', function () {
      socket.send('my-message');
      socket.send(JSON.stringify({ data: 'hola' }));
    });
  });
}

See also Socket.sendBinary(data)

Socket.sendBinary(data)

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

Socket.sendBinary(data)

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.

Send binary data through the connection.

Parameter	Type	Description
data	ArrayBuffer	The data to send.

Example

import ws from 'k6/ws';

const binFile = open('./file.pdf', 'b');

export default function () {
  ws.connect('http://wshost/', function (socket) {
    socket.on('open', function () {
      socket.sendBinary(binFile);
    });

    socket.on('binaryMessage', function (msg) {
      // msg is an ArrayBuffer, so we can wrap it in a typed array directly.
      new Uint8Array(msg);
    });
  });
}

See also Socket.send(data)

Socket.setInterval(callback, interval)

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

Socket.setInterval(callback, interval)

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.

Call a function repeatedly, while the WebSocket connection is open.

Parameter	Type	Description
callback	function	The function to call every `interval` milliseconds.
interval	number	The number of milliseconds between two calls to `callback`.

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 res = ws.connect(url, params, function (socket) {
    socket.on('open', function open() {
      console.log('connected');

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

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

  check(res, { 'status is 101': (r) => r && r.status === 101 });
}

Socket.setTimeout(callback, delay)

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

Socket.setTimeout(callback, delay)

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.

Call a function at a later time, if the WebSocket connection is still open then.

Parameter	Type	Description
callback	function	The function to call when `delay` has expired.
delay	number	The delay time, in milliseconds.

Example

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

export default function () {
  console.log('T0: Script started');
  const url = 'wss://echo.websocket.org';
  const response = ws.connect(url, null, function (socket) {
    console.log('T0: Entered WebSockets run loop');
    socket.setTimeout(function () {
      console.log('T0+1: This is printed');
    }, 1000);
    socket.setTimeout(function () {
      console.log('T0+2: Closing socket');
      socket.close();
    }, 2000);
    socket.setTimeout(function () {
      console.log('T0+3: This is not printed, because socket is closed');
    }, 3000);
  });
  console.log('T0+2: Exited WebSockets run loop');
  sleep(2);
  console.log('T0+4: Script finished');
}