> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/grafana/k6-docs/llms.txt
> Use this file to discover all available pages before exploring further.
# k6/websockets
> WebSocket API with browser-compatible interface and global event loop
The `k6/websockets` module implements the browser [WebSocket API](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket) 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
```javascript theme={null}
import { WebSocket } from 'k6/websockets';
```
## API Reference
### Classes and Methods
Constructs a new WebSocket connection.
**Parameters:**
WebSocket URL (e.g., `wss://echo.websocket.org`)
Optional protocol(s) to use
Connection parameters (headers, cookies, compression, tags)
### Instance Methods
Closes the WebSocket connection.
Sends a ping frame to the server.
Sends data through the WebSocket connection.
**Parameters:**
Data to send to the server
Adds an event listener for a specific event.
**Parameters:**
Event name: `'open'`, `'message'`, `'error'`, `'close'`, `'ping'`, `'pong'`
Callback function to handle the event
### Instance Properties
The current state of the connection. One of:
* `0` - CONNECTING
* `1` - OPEN
* `2` - CLOSING
* `3` - CLOSED
The URL of the connection as resolved by the constructor.
The number of bytes queued using `send()` but not yet transmitted.
Controls the type of binary data received. Either `"blob"` (default) or `"arraybuffer"`.
### Event Handlers
Handler called when the connection is established.
Handler called when a message is received.
Handler called when an error occurs.
Handler called when the connection is closed.
Handler called when a ping is received.
Handler called when a pong is received.
## Connection Parameters
### Params Object
Compression algorithm to use. Currently only `"deflate"` is supported.
Cookie jar for the WebSocket connection. Uses the default VU cookie jar if not specified.
Custom HTTP headers to include in the WebSocket handshake request.
```javascript theme={null}
headers: { 'X-MyHeader': 'k6test' }
```
Custom metric tags for filtering results and setting thresholds.
```javascript theme={null}
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:
```javascript Multiple Connections theme={null}
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`);
});
});
}
```
```javascript Custom Headers and Tags theme={null}
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
Alternative WebSocket module with local event loop
Handle binary data in WebSocket messages
Learn WebSocket testing patterns
WebSocket metrics documentation