The WebSocket class represents WebSocket connections established by pages. WebSocket instances are emitted via the page.on('websocket') event.
Methods
url
Returns the URL of the WebSocket.
const url = webSocket.url();
console.log(url);
string
isClosed
Returns whether the WebSocket has been closed.
if (webSocket.isClosed()) {
console.log('WebSocket is closed');
}
boolean
waitForEvent
Waits for a specific event to be emitted.
const frame = await webSocket.waitForEvent('framesent');
console.log('Frame sent:', frame.payload);
Event name. Can be:
framesent - Emitted when a frame is sentframereceived - Emitted when a frame is receivedclose - Emitted when the WebSocket closessocketerror - Emitted when a socket error occurs
Optional predicate function to filter events.
Maximum time to wait in milliseconds. Defaults to 30000 (30 seconds).
Promise<any>
Events
framesent
Emitted when a WebSocket frame is sent from the page.
webSocket.on('framesent', frame => {
console.log('Sent:', frame.payload);
});
payload: string | Buffer - The frame payload
framereceived
Emitted when a WebSocket frame is received by the page.
webSocket.on('framereceived', frame => {
console.log('Received:', frame.payload);
});
payload: string | Buffer - The frame payload
close
Emitted when the WebSocket is closed.
webSocket.on('close', () => {
console.log('WebSocket closed');
});
socketerror
Emitted when a socket error occurs.
webSocket.on('socketerror', error => {
console.log('Socket error:', error);
});
Example Usage
Monitor WebSocket Messages
page.on('websocket', ws => {
console.log('WebSocket opened:', ws.url());
ws.on('framesent', frame => {
console.log('→', frame.payload);
});
ws.on('framereceived', frame => {
console.log('←', frame.payload);
});
ws.on('close', () => {
console.log('WebSocket closed');
});
});
Filter WebSocket Messages
page.on('websocket', ws => {
if (ws.url().includes('api.example.com')) {
ws.on('framereceived', frame => {
if (typeof frame.payload === 'string') {
const data = JSON.parse(frame.payload);
console.log('Received data:', data);
}
});
}
});
Wait for Specific Message
const ws = await page.waitForEvent('websocket', ws =>
ws.url().includes('chat.example.com')
);
const frame = await ws.waitForEvent('framereceived', {
predicate: frame => {
if (typeof frame.payload === 'string') {
return frame.payload.includes('welcome');
}
return false;
}
});
console.log('Welcome message received:', frame.payload);
Handle WebSocket Errors
page.on('websocket', ws => {
ws.on('socketerror', error => {
console.error('WebSocket error:', error);
});
ws.on('close', () => {
console.log('WebSocket connection closed');
});
});
