PlaywrightでWebSocketのやり取りをテストする方法
Playwright では、ページが WebSocket で送ったメッセージと受け取ったメッセージを、テストの中で確かめられます。page.routeWebSocket() を使えば、サーバーの代わりにテストから返事をしたり、サーバーからのメッセージを書き換えたりもできます。チャット、通知、株価や在庫の表示のように、リアルタイム通信で画面が変わる部分の E2E テストで使う書き方です。
私は検証環境で、WebSocket でつながる小さなサポートチャットの画面を作りました。そのうえで、やり取りの中身を見るテスト、サーバーなしで返事をするテスト、本物のサーバーとのあいだで書き換えるテストを動かしました。
検証環境は Ubuntu 24.04、Node.js 22.23.4、@playwright/test 1.63.0、TypeScript 7.0.2 です。ブラウザは Playwright 用の Chromium だけで、サーバーは Node.js の http モジュールと ws 8.23.0 で書き、同じマシンの中で ws://(暗号化なし)でつないでいます。Firefox・WebKit、wss://、バイナリのメッセージ、context.routeWebSocket() は試していません。
試したチャット画面
http://localhost:4173/ を開くと、ページが ws://localhost:4173/ws に WebSocket でつなぎます。つながると「接続しました」と出て、サーバーからの最初のメッセージで「担当者が 3 人待機しています」と出ます。メッセージを入力して「送信」を押すと、サーバーが「「…」を受け付けました」と返します。
メッセージはどれも JSON の文字列です。
サーバー → ページ {"type":"welcome","staff":3}
ページ → サーバー {"type":"chat","text":"…"}
サーバー → ページ {"type":"reply","text":"「…」を受け付けました"}
ページ側は type が notice のメッセージを受け取ると「お知らせ: …」を出し、接続が切れると「切断されました(コード …)」を出します。サーバーは、受けた接続の数を /stats で返すようにして、本物のサーバーにつながったかどうかを、テストから接続の数で確かめられるようにしました。サーバーは playwright.config.ts の webServer で、テストの前に立ち上げています。
送ったメッセージと受けたメッセージを確かめる
ページが WebSocket の接続を始めると、ページで websocket イベントが出ます。そこで受け取る WebSocket の waitForEvent() で、送ったメッセージ(framesent)と受け取ったメッセージ(framereceived)を待てます。
import { test, expect } from '@playwright/test';
test('送ったフレームと受けたフレームを確かめる', async ({ page }) => {
const wsPromise = page.waitForEvent('websocket');
await page.goto('/');
const ws = await wsPromise;
console.log('url', ws.url());
await ws.waitForEvent('framereceived', {
predicate: (f) => JSON.parse(String(f.payload)).type === 'welcome',
});
const sent = ws.waitForEvent('framesent');
const received = ws.waitForEvent('framereceived', {
predicate: (f) => JSON.parse(String(f.payload)).type === 'reply',
});
await page.getByLabel('メッセージ').fill('配送状況を知りたい');
await page.getByRole('button', { name: '送信' }).click();
console.log('sent', (await sent).payload);
console.log('received', (await received).payload);
await expect(page.getByRole('listitem').last()).toHaveText('担当: 「配送状況を知りたい」を受け付けました');
});
url ws://localhost:4173/ws
sent {"type":"chat","text":"配送状況を知りたい"}
received {"type":"reply","text":"「配送状況を知りたい」を受け付けました"}
このテストは通りました。テキストのメッセージでは payload は文字列なので、JSON のメッセージは JSON.parse() してから中を見ます。predicate を渡すと、predicate が真を返すメッセージが届くまで待ちます。ここでは type を見て、目当てのメッセージを選んでいます。
このテストでは、送信ボタンを押す前に waitForEvent() を呼んで Promise を受け取っておき、押したあとで await しています。
やり取りをすべて記録する
順番も含めて全部見たいときは、page.on('websocket') の中で framesent と framereceived に関数を登録し、配列にためます。
test('すべてのフレームを記録する', async ({ page }) => {
const frames: string[] = [];
page.on('websocket', (ws) => {
ws.on('framesent', (f) => frames.push('→ ' + f.payload));
ws.on('framereceived', (f) => frames.push('← ' + f.payload));
});
await page.goto('/');
await expect(page.locator('#status')).toHaveText('接続しました');
await page.getByLabel('メッセージ').fill('こんにちは');
await page.getByRole('button', { name: '送信' }).click();
await expect(page.getByRole('listitem')).toHaveCount(3);
console.log(frames.join('\n'));
});
← {"type":"welcome","staff":3}
→ {"type":"chat","text":"こんにちは"}
← {"type":"reply","text":"「こんにちは」を受け付けました"}
goto() のあとで待ち始めると間に合わない
websocket イベントは、ページが WebSocket の接続を始めたときに出ます。goto() のあとで page.waitForEvent('websocket') を呼ぶと、接続はできているのに待ちが終わらず、タイムアウトしました(上限を3秒にして実行しました)。
TimeoutError: page.waitForEvent: Timeout 3000ms exceeded while waiting for event "websocket"
最初の例のように、goto() の前に waitForEvent() を呼んで Promise を受け取っておき、goto() のあとで await します。
サーバーにつながずに、テストから返事をする
Playwright 1.48 で入った page.routeWebSocket() を使うと、ページの WebSocket を横取りできます。WebSocketRoute の API リファレンスによると、ハンドラーの中で connectToServer() を呼ばなければ、本物のサーバーにはつながず、Playwright がページの中で接続を開いた状態にします。テストの側は、onMessage() でページから送られたメッセージを受け、send() でページに返します。
test('サーバーにつながずに、テストから返事をする', async ({ page, request }) => {
const before = await connections(request);
const received: string[] = [];
await page.routeWebSocket('/ws', (ws) => {
ws.send(JSON.stringify({ type: 'welcome', staff: 0 }));
ws.onMessage((message) => {
received.push(String(message));
const msg = JSON.parse(String(message));
ws.send(JSON.stringify({ type: 'reply', text: 'テストからの返事: ' + msg.text }));
});
});
await page.goto('/');
await expect(page.locator('#status')).toHaveText('接続しました');
await expect(page.getByRole('listitem').first()).toHaveText('担当者が 0 人待機しています');
await page.getByLabel('メッセージ').fill('返品したい');
await page.getByRole('button', { name: '送信' }).click();
await expect(page.getByRole('listitem').last()).toHaveText('担当: テストからの返事: 返品したい');
console.log('テストが受けたメッセージ', received);
console.log('サーバーが受けた接続の増え方', (await connections(request)) - before);
});
connections() は、/stats から受けた接続の数を取ってくる、テストの中の小さな関数です。
テストが受けたメッセージ [ '{"type":"chat","text":"返品したい"}' ]
サーバーが受けた接続の増え方 0
ページには「接続しました」「担当者が 0 人待機しています」と、テストから返した内容が出ました。サーバーが受けた接続は増えていません。URL の '/ws' は、playwright.config.ts の baseURL(http://localhost:4173)からの相対で書いています。page.routeWebSocket() の説明にあるとおり、文字列の URL は baseURL からの相対で指定できます。
担当者が0人のときの表示のように、本物のサーバーでは作りにくい状態も、テストから返すメッセージを変えるだけで作れます。
お知らせや切断を、好きなときに起こす
ハンドラーで受け取った WebSocketRoute を変数に取っておくと、テストの好きなタイミングでページにメッセージを送ったり、接続を切ったりできます。サーバーから全員に送るお知らせや、サーバー側の異常で切れたときの表示を確かめるのに使えます。
import { test, expect, type WebSocketRoute } from '@playwright/test';
test('サーバーからのお知らせと切断を、好きなときに起こす', async ({ page }) => {
let route!: WebSocketRoute;
await page.routeWebSocket('/ws', (ws) => { route = ws; });
await page.goto('/');
await expect(page.locator('#status')).toHaveText('接続しました');
route.send(JSON.stringify({ type: 'notice', text: '本日は18時で受付を終了します' }));
await expect(page.getByRole('listitem')).toHaveText(['お知らせ: 本日は18時で受付を終了します']);
await route.close({ code: 1011, reason: 'server error' });
await expect(page.locator('#status')).toHaveText('切断されました(コード 1011)');
});
このテストは通りました。close() に渡した code は、ページの close イベントの code にそのまま届きました。

routeWebSocket() は goto() の前に呼ぶ
goto() でページを開いて接続ができたあとに routeWebSocket() を呼んでも、今ある接続は横取りされませんでした。ハンドラーではどのメッセージにも「モック」と返すようにしましたが、ページに出たのは本物のサーバーの返事で、サーバーが受けた接続も1つ増えていました。
最後のメッセージ 担当: 「テスト」を受け付けました
サーバーが受けた接続の増え方 1
page.routeWebSocket() の説明にも、横取りされるのは呼んだあとに作られた WebSocket だけで、ページを開く前に呼ぶのがよいと書かれています。
横取りした接続では websocket イベントが出なかった
routeWebSocket() で横取りした接続にも、page.on('websocket') を登録して、やり取りを記録してみました。「やり取りをすべて記録する」と同じ記録に、websocket イベントが出たことも加えました。ページには返事が出てテストは通りましたが、記録できたイベントとメッセージは0件でした。
記録できたイベントとフレームの数 0
Chromium で試した結果です。サーバーなしで返事をするテストでは、ページから届いたメッセージは、onMessage() の中で配列にためて確かめます。
本物のサーバーにつなぎ、途中で書き換える
ハンドラーの中で connectToServer() を呼ぶと、本物のサーバーにつながり、サーバー側を表す WebSocketRoute が返ります。API リファレンスによると、何もしなければ、メッセージはページとサーバーのあいだでそのまま受け渡されます。サーバー側の onMessage() を登録すると、サーバーからページへの受け渡しが止まり、テストが send() で渡す形になります。
サーバーからの最初のメッセージの staff だけを0に書き換えて、ページに渡してみました。
test('本物のサーバーにつなぎ、サーバーからの返事だけ書き換える', async ({ page }) => {
const fromServer: string[] = [];
await page.routeWebSocket('/ws', (ws) => {
const server = ws.connectToServer();
server.onMessage((message) => {
fromServer.push(String(message));
const msg = JSON.parse(String(message));
if (msg.type === 'welcome') msg.staff = 0;
ws.send(JSON.stringify(msg));
});
});
await page.goto('/');
await expect(page.getByRole('listitem').first()).toHaveText('担当者が 0 人待機しています');
await page.getByLabel('メッセージ').fill('在庫はありますか');
await page.getByRole('button', { name: '送信' }).click();
await expect(page.getByRole('listitem').last()).toHaveText('担当: 「在庫はありますか」を受け付けました');
console.log(fromServer.join('\n'));
});
{"type":"welcome","staff":3}
{"type":"reply","text":"「在庫はありますか」を受け付けました"}
サーバーは staff を3で送っていますが、ページには「担当者が 0 人待機しています」と出ました。返事のほうは書き換えずに渡したので、本物のサーバーの返事がそのまま出ています。ページから送ったメッセージは、ページ側の onMessage() を登録していないので、そのままサーバーに届いています。
逆向きも同じです。ページ側の ws.onMessage() で受けたメッセージの text を大文字にして server.send() で渡すと、hello と送ったのに、サーバーからは「「HELLO」を受け付けました」と返ってきました。
サーバー側の onMessage() で何も送らないと、ページには届かない
server.onMessage(() => {}) のように、登録だけして ws.send() を呼ばないと、サーバーからのメッセージはページに1つも届きませんでした。送信したあとの画面には自分のメッセージしかなく、返事を待つ確認はタイムアウトしました。
表示されたメッセージ [ '届きますか' ]
Error: expect(locator).toHaveText(expected) failed
Locator: getByRole('listitem').last()
Expected pattern: /担当:/
Received string: "届きますか"
Timeout: 3000ms
最初の「担当者が 3 人待機しています」も出ていません。一部のメッセージだけを書き換えたいときも、onMessage() を登録したら、書き換えないメッセージもハンドラーの中で send() して渡します。
20回くり返しても同じ結果だった
失敗を確かめるための2件を除いた8件のテストを、--repeat-each 20 で20回ずつ、合わせて160回動かしたところ、すべて通りました。
160 passed (31.0s)
固定の時間を待つ waitForTimeout() は使っていません。メッセージは waitForEvent() の predicate で、画面は expect() で、それぞれ目当ての状態になるまで待っています。





