> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/grafana/k6/llms.txt
> Use this file to discover all available pages before exploring further.

# k6/ws

> WebSocket client for real-time bidirectional communication.

The `k6/ws` module provides WebSocket client functionality for testing real-time applications.

## Functions

### connect(url, \[params], callback)

Establishes a WebSocket connection.

<ParamField path="url" type="string">
  WebSocket URL (ws\:// or wss\://)
</ParamField>

<ParamField path="params" type="object" optional>
  Connection parameters
</ParamField>

<ParamField path="callback" type="function">
  Function to execute after connection is established. Receives Socket object.
</ParamField>

<ResponseField name="response" type="HTTPResponse">
  HTTP response object from the connection handshake
</ResponseField>

```javascript theme={null}
import ws from 'k6/ws';
import { check } from 'k6';

export default function () {
  const url = 'ws://echo.websocket.org';
  const response = ws.connect(url, function (socket) {
    socket.on('open', () => console.log('connected'));
    socket.on('message', (data) => console.log('Message:', data));
    socket.on('close', () => console.log('disconnected'));
  });

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

## Connection Parameters

<ParamField path="headers" type="object" optional>
  Custom headers for the WebSocket handshake
</ParamField>

<ParamField path="tags" type="object" optional>
  Custom tags for metrics
</ParamField>

<ParamField path="jar" type="CookieJar" optional>
  Cookie jar to use for the connection
</ParamField>

<ParamField path="compression" type="string" optional>
  Compression algorithm (`deflate` is supported, experimental)
</ParamField>

```javascript theme={null}
const params = {
  headers: { 'Authorization': 'Bearer token' },
  tags: { name: 'websocket-test' },
};

ws.connect(url, params, function (socket) {
  // ...
});
```

## Socket Object

The Socket object is passed to the connect callback and provides methods to interact with the WebSocket.

### Event Handlers

#### on(event, handler)

Registers an event handler.

<ParamField path="event" type="string">
  Event name: `open`, `message`, `binaryMessage`, `ping`, `pong`, `close`, or `error`
</ParamField>

<ParamField path="handler" type="function">
  Function to call when event occurs
</ParamField>

```javascript theme={null}
socket.on('open', function () {
  console.log('WebSocket connection established');
});

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

socket.on('binaryMessage', function (data) {
  console.log('Binary data received:', new Uint8Array(data));
});

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

socket.on('error', function (e) {
  console.log('Error:', e.error());
});
```

### Sending Messages

#### send(data)

Sends a text message.

<ParamField path="data" type="string">
  Message to send
</ParamField>

```javascript theme={null}
socket.send('Hello, server!');
socket.send(JSON.stringify({ type: 'message', data: 'test' }));
```

#### sendBinary(data)

Sends a binary message.

<ParamField path="data" type="ArrayBuffer">
  Binary data to send
</ParamField>

```javascript theme={null}
const data = new Uint8Array([1, 2, 3, 4]);
socket.sendBinary(data.buffer);
```

#### ping()

Sends a ping frame.

```javascript theme={null}
socket.ping();
```

### Timing Functions

#### setTimeout(callback, delay)

Executes a function after a delay.

<ParamField path="callback" type="function">
  Function to execute
</ParamField>

<ParamField path="delay" type="number">
  Delay in milliseconds
</ParamField>

```javascript theme={null}
socket.setTimeout(function () {
  socket.send('Delayed message');
}, 1000);
```

#### setInterval(callback, interval)

Executes a function repeatedly at intervals.

<ParamField path="callback" type="function">
  Function to execute
</ParamField>

<ParamField path="interval" type="number">
  Interval in milliseconds
</ParamField>

```javascript theme={null}
socket.setInterval(function () {
  socket.ping();
}, 5000);
```

### Connection Control

#### close(\[code])

Closes the WebSocket connection.

<ParamField path="code" type="number" optional>
  WebSocket close code (default: 1001)
</ParamField>

```javascript theme={null}
socket.close();
// or with custom code
socket.close(1000);
```

## Examples

### Basic WebSocket Test

```javascript theme={null}
import ws from 'k6/ws';
import { check } from 'k6';

export default function () {
  const url = 'ws://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('message', function (data) {
      console.log(`Roundtrip time: ${Date.now() - data} ms`);
      socket.setTimeout(function timeout() {
        socket.send(Date.now());
      }, 500);
    });

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

    socket.on('error', function (e) {
      console.log('An unexpected error occurred: ', 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 });
}
```

### Chat Application Test

```javascript theme={null}
import ws from 'k6/ws';
import { check } from 'k6';

export default function () {
  const url = 'wss://chat.example.com/ws';

  const response = ws.connect(url, function (socket) {
    socket.on('open', function () {
      // Join chat room
      socket.send(JSON.stringify({
        type: 'join',
        room: 'general',
        username: `user-${__VU}`,
      }));
    });

    socket.on('message', function (data) {
      const msg = JSON.parse(data);
      console.log(`Received: ${msg.type}`);

      if (msg.type === 'welcome') {
        // Send a message
        socket.send(JSON.stringify({
          type: 'message',
          text: 'Hello from k6!',
        }));
      }
    });

    socket.setTimeout(function () {
      socket.close();
    }, 10000);
  });

  check(response, { 'connected': (r) => r && r.status === 101 });
}
```

### Binary Data Transfer

```javascript theme={null}
import ws from 'k6/ws';

export default function () {
  ws.connect('ws://echo.websocket.org', function (socket) {
    socket.on('open', function () {
      // Send binary data
      const data = new Uint8Array([1, 2, 3, 4, 5]);
      socket.sendBinary(data.buffer);
    });

    socket.on('binaryMessage', function (data) {
      const arr = new Uint8Array(data);
      console.log('Received binary:', arr);
      socket.close();
    });
  });
}
```

<Warning>
  WebSocket connections cannot be used in the init context. They must be created in the VU context (default function).
</Warning>