PlaywrightのrouteFromHARでAPI応答を録画・再生

​​Playwright​E2Eテスト,TypeScript,モック

Playwright の page.routeFromHAR() を使うと、本物の API が返した応答を HAR ファイルに録画しておき、次からのテストではそのファイルから応答を返せます。E2Eテストを、バックエンドの API が止まっていても、データが日々変わっても、毎回同じ応答で動かしたい場面で使えます。page.route でモックの応答を作る方法では JSON を手で書きますが、routeFromHAR なら本物の応答をそのまま使えます。

私は検証環境で、猫の一覧を API から読み込む小さなページを作り、録画、再生、録画したファイルの書き換え、録画のやり直しを順に試しました。サーバー側では API に届いた通信を数え、再生のときに通信がサーバーまで届いていないことも確かめています。

補足

検証環境は Ubuntu 24.04.5 LTS、Node.js 22.23.4、@playwright/test 1.63.0、Playwright 用の Chromium です。ページと API は、Node.js の http モジュールで書いた小さなサーバーから配信しました。browserContext.routeFromHAR()、newContext() の recordHar オプション、npx playwright open --save-har による録画、.zip 形式の HAR、Firefox・WebKit は試していません。

検証に使ったページと API

ページを開くと GET /api/cats?page=1 で猫の一覧を読み込み、「たま(3歳)」「みけ(5歳)」のように表示します。「次のページ」ボタンは GET /api/cats?page=2 を呼び、検索のフォームは POST /api/search に {"q":"たま"} のような JSON を送ります。API が失敗したときは「読み込めませんでした:」に続けてエラーの内容を出します。

サーバーは、環境変数 API_DOWN=1 を付けて起動すると、API がすべて 503 を返すようにしました。本物の API が使えない状態の代わりです。playwright.config.ts では webServer でこのサーバーを起動し、baseURL を http://localhost:4173 にしています。

update: true で、本物の応答を録画する

録画するテストでは、page.goto() より前に routeFromHAR() を呼び、update: true を付けます。公式ドキュメントの HAR ファイルでモックする方法の説明のとおり、update: true のときは HAR から応答を返さず、実際の通信の内容でファイルを作り直します。

ts
import { test, expect } from '@playwright/test';

test('API の応答を HAR に録画する', async ({ page }) => {
  await page.routeFromHAR('hars/cats.har', {
    url: '**/api/**',
    update: true,
  });
  await page.goto('/');
  await expect(page.getByRole('listitem').first()).toHaveText('たま(3歳)');

  await page.getByLabel('名前で検索').fill('たま');
  await page.getByRole('button', { name: '検索' }).click();
  await expect(page.locator('#result')).toHaveText('1件:たま');
});

url: '**/api/**' を付けたので、録画と再生の対象は /api/ の通信だけです。ページの HTML は、これまでどおりサーバーから受け取ります。routeFromHAR の API リファレンスによると、ファイルが書き出されるのは、ブラウザーのコンテキストを閉じたときです。

実行すると、サーバーには一覧の GET と検索の POST が届き、hars フォルダーに4つのファイルができました(左の数字はファイルの大きさで、単位はバイトです)。

text
14 2d5930e690fef715c7224b4d8cd934043bab20d2.json
67 444d3c6e5f9f6800f850623fdb5bceccfb1077f3.json
3690 cats.har
34 f630bc17934271613f6017fa5b6331eb2402a365.json

cats.har には通信が2件記録されていました。応答の本文は HAR の中にはなく、_file に書かれた名前の別のファイルに入っています。必要な部分だけ抜き出すと、次のとおりです。

json
[
  {
    "method": "GET",
    "url": "http://localhost:4173/api/cats?page=1",
    "status": 200,
    "content": {
      "size": -1,
      "mimeType": "application/json",
      "_file": "444d3c6e5f9f6800f850623fdb5bceccfb1077f3.json"
    }
  },
  {
    "method": "POST",
    "url": "http://localhost:4173/api/search",
    "postData": {
      "mimeType": "application/json",
      "text": "",
      "params": [],
      "_file": "2d5930e690fef715c7224b4d8cd934043bab20d2.json"
    },
    "status": 200,
    "content": {
      "size": -1,
      "mimeType": "application/json",
      "_file": "f630bc17934271613f6017fa5b6331eb2402a365.json"
    }
  }
]

3つの .json ファイルの中身は、一覧の応答 [{"id":1,"name":"たま","age":3},{"id":2,"name":"みけ","age":5}]、検索の応答 [{"id":1,"name":"たま","age":3}]、そして POST で送った本文 {"q":"たま"} でした。応答だけでなく、送った本文も別のファイルになります。ファイル名は、中身の SHA-1 と同じ値でした。

公式ドキュメントの、HAR ファイルを書き換える方法の説明では、本文のファイルを「hars フォルダーの中のハッシュの名前の .txt ファイル」としています。検証環境では、JSON の応答は .json の拡張子で保存されました。

update を外すと、HAR から応答が返る

再生するテストでは、update を外すだけです。最後に、サーバーに届いた API の通信の数を /__hits から受け取って出しています。

ts
import { test, expect } from '@playwright/test';

test('HAR から API の応答を再生する', async ({ page }) => {
  await page.routeFromHAR('hars/cats.har', { url: '**/api/**' });
  await page.goto('/');
  await expect(page.getByRole('listitem')).toHaveText(['たま(3歳)', 'みけ(5歳)']);

  await page.getByLabel('名前で検索').fill('たま');
  await page.getByRole('button', { name: '検索' }).click();
  await expect(page.locator('#result')).toHaveText('1件:たま');

  const res = await page.request.get('/__hits');
  console.log('サーバーに届いた API の通信:', (await res.json()).hits);
});

まず HAR を使わずに、API_DOWN=1 で起動したサーバーのページを開くと、画面には「読み込めませんでした:HTTP 503」と出ました。同じく API_DOWN=1 を付けて、上の再生するテストを実行した結果です。

text
$ API_DOWN=1 npx playwright test tests/replay.spec.ts --reporter=list
Running 1 test using 1 worker
サーバーに届いた API の通信: 0
  ✓  1 tests/replay.spec.ts:3:5 › HAR から API の応答を再生する (220ms)
  1 passed (874ms)

API が 503 を返すサーバーでも、一覧と検索の結果は録画したとおりに表示され、テストは通りました。サーバーに届いた API の通信は 0 回です。一覧の GET も検索の POST も、HAR から応答が返っています。

HAR にない通信は、初期設定では中断される

録画していない通信がページから出たときの動きは、notFound オプションで決まります。API リファレンスによると、初期値の 'abort' では中断し、'fallback' ではそのまま本物のサーバーへ送ります。

録画していない「次のページ」(page=2)のボタンを押すテストと、録画したときと違う言葉(「みけ」)で検索するテストを書きました。どちらも url に合う通信なので、Playwright は HAR の中から応答を探します。

ts
test('HAR にない通信は、初期設定では中断される', async ({ page }) => {
  await page.routeFromHAR('hars/cats.har', { url: '**/api/**' });
  await page.goto('/');
  await expect(page.getByRole('listitem')).toHaveCount(2);

  await page.getByRole('button', { name: '次のページ' }).click();
  await expect(page.locator('#error')).toHaveText(/読み込めませんでした/);
  console.log('abort のとき:', await page.locator('#error').textContent());
  console.log('サーバーに届いた API の通信:', (await (await page.request.get('/__hits')).json()).hits);
});

test('notFound: fallback なら、HAR にない通信はサーバーに届く', async ({ page }) => {
  await page.routeFromHAR('hars/cats.har', { url: '**/api/**', notFound: 'fallback' });
  await page.goto('/');
  await expect(page.getByRole('listitem')).toHaveCount(2);

  await page.getByRole('button', { name: '次のページ' }).click();
  await expect(page.getByRole('listitem')).toHaveText(['たま(3歳)', 'みけ(5歳)', 'くろ(1歳)']);
  console.log('サーバーに届いた API の通信:', (await (await page.request.get('/__hits')).json()).hits);
});

検索のテストは、「みけ」で検索して結果の欄を出すだけなので、コードは省きます。結果は次のとおりです(最初と最後の行は省きました)。

text
abort のとき: 読み込めませんでした:Failed to fetch
サーバーに届いた API の通信: 0
  ✓  1 tests/notfound.spec.ts:3:5 › HAR にない通信は、初期設定では中断される (195ms)
[WebServer] [server] GET /api/cats?page=2 (API 1回目)
サーバーに届いた API の通信: 1
  ✓  2 tests/notfound.spec.ts:14:5 › notFound: fallback なら、HAR にない通信はサーバーに届く (181ms)
本文が違う POST: 検索できませんでした:Failed to fetch
  ✓  3 tests/notfound.spec.ts:24:5 › POST は本文まで一致しないと HAR から返らない (185ms)

初期設定のままでは、page=2 の通信は中断され、ページの fetch() は Failed to fetch で失敗しました。notFound: 'fallback' にすると、同じ通信がサーバーに届き、3匹目の「くろ」が表示されました。

POST は、URL が同じでも本文が {"q":"みけ"} だと HAR の記録に合わず、中断されました。公式ドキュメントの、HAR から再生する方法の説明にも、HAR の再生では URL と HTTP メソッドを厳密に照合し、POST は送った本文まで厳密に照合すると書かれています。検索のように送る値が変わる API は、テストで使う値で録画しておく必要があります。

ポイント

url に合う通信は、録画し忘れていても本物のサーバーへは出ず、ページの中で失敗します。url に合わない通信は、これまでどおりサーバーに届きます。

録画した応答を書き換えて、画面を確かめる

応答の本文は別の .json ファイルなので、テキストエディターで書き換えられます。一覧の応答のファイルに、名前の長い3匹目を足しました。

json
[
  { "id": 1, "name": "たま", "age": 3 },
  { "id": 2, "name": "みけ", "age": 5 },
  { "id": 99, "name": "とても長い名前の猫のテストデータ", "age": 12 }
]

この HAR を使い、3匹が表示されることを確かめるテストは、API_DOWN=1 のサーバーで通りました。本物の API にはないデータでも、画面の表示を確かめられます。

update: true で録画し直すときは、書き換えたファイルに気をつける

書き換えたあとで、録画するテストをもう一度実行しました。サーバーの応答は、1回目と同じです。

text
14 2d5930e690fef715c7224b4d8cd934043bab20d2.json
176 444d3c6e5f9f6800f850623fdb5bceccfb1077f3.json
3690 cats.har
34 f630bc17934271613f6017fa5b6331eb2402a365.json

cats.har は録画し直されましたが、一覧の応答のファイル 444d3c… は 176 バイトのままで、書き換えた3匹の内容が残りました。続けて再生すると、3匹が表示されるテストも通りました。ファイル名は応答の中身の SHA-1 で決まるので、同じ応答を録画し直すと同じ名前になります。検証環境では、その名前のファイルは上書きされず、書き換えた3匹の内容のまま残りました。

次に、サーバーを NEW_CAT=1 で起動して、一覧に「しろ」が増えた状態で録画し直しました。

text
100 0d6f559ebfee10fd5f6de86816c594403435eb30.json
14 2d5930e690fef715c7224b4d8cd934043bab20d2.json
176 444d3c6e5f9f6800f850623fdb5bceccfb1077f3.json
3690 cats.har
34 f630bc17934271613f6017fa5b6331eb2402a365.json

新しい応答は 0d6f55… という別のファイルに保存され、cats.har もそちらを指すようになりました。書き換えた 444d3c… はフォルダーに残っていますが、cats.har からはもう使われません。再生すると、3匹目は「しろ(2歳)」になり、書き換えた内容を前提にしたテストは失敗しました。

text
    - Expected  - 1
    + Received  + 1
      Array [
        "たま(3歳)",
        "みけ(5歳)",
    -   "とても長い名前の猫のテストデータ(12歳)",
    +   "しろ(2歳)",
      ]
注意

録画した応答を手で書き換えたあとに update: true で録画し直すと、本物の応答が変わっていた場合、書き換えた内容は使われなくなります。応答が同じなら書き換えたファイルがそのまま残るので、どちらになったかは見た目では分かりにくくなります。書き換えたファイルは Git で差分を見ながら管理し、録画し直したあとは cats.har の _file がどのファイルを指しているかを確かめます。

録画の設定を変えたときのファイルの違い

routeFromHAR() には、録画の仕方を変えるオプションが2つあります。API リファレンスによると、updateContent は本文をどこに保存するかを決めるオプションで、'attach' なら別のファイル、'embed' なら HAR の中に入れます。updateMode はどこまで詳しく記録するかを決めるオプションで、初期値の 'minimal' は再生に要る情報だけを記録し、'full' は時間やサイズなども記録します。url を省くと、すべての通信が対象になります。

一覧を読み込むだけのテストで、設定を変えて録画しました。

設定 できたファイル 記録された通信
updateContent: 'embed' embed.har(1,839バイト)だけ /api/cats?page=1 の1件。本文は "text" に入った
updateMode: 'full' full.har(2,165バイト)と本文の .json 同じ1件。timings に wait: 2.689 などが記録され、pages も1件記録された
url なし all.har、本文の .json、ページの .html ページの GET / と /api/cats?page=1 の2件

'embed' は、ファイルが1つで済む代わりに、応答の本文が JSON の文字列としてエスケープされて入ります。書き換えるなら、何も指定しないで録画したときの別ファイルのほうが扱いやすいです。url を省くとページの HTML まで録画され、再生のときもページ自体が HAR から返ります。API だけを差し替えたいなら、url で対象を絞ります。

updateMode: 'full' の記録には、接続先の serverIPAddress も入りました(検証環境では 127.0.0.1)。初期設定の 'minimal' で録画した HAR には、この項目はありませんでした。HAR をリポジトリに入れるなら、接続先の情報が残らない 'minimal' のままにしておくのが安心です。

​Posted by 86