PlaywrightでWebSocketのやり取りをテストする方法

​​Playwright​E2Eテスト,TypeScript,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 の文字列です。

text
サーバー → ページ  {"type":"welcome","staff":3}
ページ → サーバー  {"type":"chat","text":"…"}
サーバー → ページ  {"type":"reply","text":"「…」を受け付けました"}

ページ側は type が notice のメッセージを受け取ると「お知らせ: …」を出し、接続が切れると「切断されました(コード …)」を出します。サーバーは、受けた接続の数を /stats で返すようにして、本物のサーバーにつながったかどうかを、テストから接続の数で確かめられるようにしました。サーバーは playwright.config.ts の webServer で、テストの前に立ち上げています。

送ったメッセージと受けたメッセージを確かめる

ページが WebSocket の接続を始めると、ページで websocket イベントが出ます。そこで受け取る WebSocket の waitForEvent() で、送ったメッセージ(framesent)と受け取ったメッセージ(framereceived)を待てます。

ts
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('担当: 「配送状況を知りたい」を受け付けました');
});
text
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 に関数を登録し、配列にためます。

ts
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'));
});
text
← {"type":"welcome","staff":3}
→ {"type":"chat","text":"こんにちは"}
← {"type":"reply","text":"「こんにちは」を受け付けました"}

goto() のあとで待ち始めると間に合わない

websocket イベントは、ページが WebSocket の接続を始めたときに出ます。goto() のあとで page.waitForEvent('websocket') を呼ぶと、接続はできているのに待ちが終わらず、タイムアウトしました(上限を3秒にして実行しました)。

text
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() でページに返します。

ts
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 から受けた接続の数を取ってくる、テストの中の小さな関数です。

text
テストが受けたメッセージ [ '{"type":"chat","text":"返品したい"}' ]
サーバーが受けた接続の増え方 0

ページには「接続しました」「担当者が 0 人待機しています」と、テストから返した内容が出ました。サーバーが受けた接続は増えていません。URL の '/ws' は、playwright.config.ts の baseURL(http://localhost:4173)からの相対で書いています。page.routeWebSocket() の説明にあるとおり、文字列の URL は baseURL からの相対で指定できます。

担当者が0人のときの表示のように、本物のサーバーでは作りにくい状態も、テストから返すメッセージを変えるだけで作れます。

お知らせや切断を、好きなときに起こす

ハンドラーで受け取った WebSocketRoute を変数に取っておくと、テストの好きなタイミングでページにメッセージを送ったり、接続を切ったりできます。サーバーから全員に送るお知らせや、サーバー側の異常で切れたときの表示を確かめるのに使えます。

ts
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 にそのまま届きました。

「切断されました(コード 1011)」と出たサポートチャットの画面。その下に「お知らせ: 本日は18時で受付を終了します」とメッセージの入力欄がある
テストからお知らせを送り、コード 1011 で切ったあとの画面

routeWebSocket() は goto() の前に呼ぶ

goto() でページを開いて接続ができたあとに routeWebSocket() を呼んでも、今ある接続は横取りされませんでした。ハンドラーではどのメッセージにも「モック」と返すようにしましたが、ページに出たのは本物のサーバーの返事で、サーバーが受けた接続も1つ増えていました。

text
最後のメッセージ 担当: 「テスト」を受け付けました
サーバーが受けた接続の増え方 1

page.routeWebSocket() の説明にも、横取りされるのは呼んだあとに作られた WebSocket だけで、ページを開く前に呼ぶのがよいと書かれています。

横取りした接続では websocket イベントが出なかった

routeWebSocket() で横取りした接続にも、page.on('websocket') を登録して、やり取りを記録してみました。「やり取りをすべて記録する」と同じ記録に、websocket イベントが出たことも加えました。ページには返事が出てテストは通りましたが、記録できたイベントとメッセージは0件でした。

text
記録できたイベントとフレームの数 0

Chromium で試した結果です。サーバーなしで返事をするテストでは、ページから届いたメッセージは、onMessage() の中で配列にためて確かめます。

本物のサーバーにつなぎ、途中で書き換える

ハンドラーの中で connectToServer() を呼ぶと、本物のサーバーにつながり、サーバー側を表す WebSocketRoute が返ります。API リファレンスによると、何もしなければ、メッセージはページとサーバーのあいだでそのまま受け渡されます。サーバー側の onMessage() を登録すると、サーバーからページへの受け渡しが止まり、テストが send() で渡す形になります。

サーバーからの最初のメッセージの staff だけを0に書き換えて、ページに渡してみました。

ts
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'));
});
text
{"type":"welcome","staff":3}
{"type":"reply","text":"「在庫はありますか」を受け付けました"}

サーバーは staff を3で送っていますが、ページには「担当者が 0 人待機しています」と出ました。返事のほうは書き換えずに渡したので、本物のサーバーの返事がそのまま出ています。ページから送ったメッセージは、ページ側の onMessage() を登録していないので、そのままサーバーに届いています。

逆向きも同じです。ページ側の ws.onMessage() で受けたメッセージの text を大文字にして server.send() で渡すと、hello と送ったのに、サーバーからは「「HELLO」を受け付けました」と返ってきました。

サーバー側の onMessage() で何も送らないと、ページには届かない

server.onMessage(() => {}) のように、登録だけして ws.send() を呼ばないと、サーバーからのメッセージはページに1つも届きませんでした。送信したあとの画面には自分のメッセージしかなく、返事を待つ確認はタイムアウトしました。

text
表示されたメッセージ [ '届きますか' ]
text
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回動かしたところ、すべて通りました。

text
  160 passed (31.0s)

固定の時間を待つ waitForTimeout() は使っていません。メッセージは waitForEvent() の predicate で、画面は expect() で、それぞれ目当ての状態になるまで待っています。

​Posted by 86