Playwrightのfixturesで、テストの準備を使い回す方法

​​Playwright​E2Eテスト,TypeScript

Playwright の E2E テストで、ページを開いてテスト用のデータを入れる、API サーバーを立てる、といった準備を毎回のテストに書いているなら、fixtures(フィクスチャ)にまとめると使い回せます。フィクスチャは、準備と後片付けを1か所に書いておき、テストの引数に名前を書くだけで受け取れる仕組みです。

準備に時間がかかるものは、{ scope: 'worker' } を付けると worker プロセスごとに1回だけ作られます。検証環境で、準備に1秒かかるサーバーを4件のテストで使ったところ、テストごとに作ると全体で4.6〜4.7秒、worker ごとに作ると1.6〜1.7秒でした。

補足

検証環境は Ubuntu 24.04、Node.js 22.23.4、@playwright/test 1.63.0 です。テストは TypeScript で書き、ブラウザは Chromium(ヘッドレス)だけで動かしました。ページは page.setContent() でその場に作り、API サーバーはテストの中で Node.js の http モジュールを使って 127.0.0.1 に立てています。準備に時間がかかる処理の代わりに、サーバーを立てる前にわざと1秒待たせました。自動で動くフィクスチャ(auto)、設定から値を渡すフィクスチャ(option)、mergeTests で複数のファイルのフィクスチャを合わせる方法、globalSetup は試していません。

test.extend でフィクスチャを作る

例として、「やること」の一覧ページを使います。どのテストも「2件入った状態のページ」から始めたいとします。この準備を todoPage というフィクスチャにまとめました。

フィクスチャは、test.extend() で新しい test を作って定義します。関数の中で await use(値) を呼ぶと、その値がテストに渡ります。use より前が準備、後ろが後片付けです。

ts
// tests/fixtures.ts(todoPage の部分だけにして簡単にしたもの)
import { test as base, expect, type Page } from '@playwright/test';

type TestFixtures = {
  todoPage: Page;
};

export const test = base.extend<TestFixtures>({
  todoPage: async ({ page }, use) => {
    console.log('[todoPage] 準備');
    await page.setContent(todoHtml);
    for (const item of ['牛乳を買う', '本を返す']) {
      await page.getByLabel('新しいやること').fill(item);
      await page.getByRole('button', { name: '追加' }).click();
    }
    await use(page);
    console.log('[todoPage] 後片付け');
  },
});

export { expect };

todoHtml は、入力欄と「追加」ボタンと一覧だけのページの HTML です。todoPage の関数は、引数で組み込みのフィクスチャ page を受け取っています。このように、フィクスチャは別のフィクスチャを使って作れます。

テストの側は、@playwright/test の代わりにこのファイルから test を読み込み、引数に todoPage と書きます。準備のコードはテストに出てきません。

ts
// tests/todo.spec.ts
import { test, expect } from './fixtures';

test('最初から2件ある', async ({ todoPage }) => {
  console.log('  テスト本体: 最初から2件ある');
  await expect(todoPage.getByRole('listitem')).toHaveCount(2);
});

test('3件目を追加できる', async ({ todoPage }) => {
  console.log('  テスト本体: 3件目を追加できる');
  await todoPage.getByLabel('新しいやること').fill('部屋を片付ける');
  await todoPage.getByRole('button', { name: '追加' }).click();
  await expect(todoPage.getByRole('listitem')).toHaveCount(3);
});

test('フィクスチャを使わないテスト', async ({ page }) => {
  console.log('  テスト本体: フィクスチャを使わないテスト');
  await page.setContent('<p>こんにちは</p>');
  await expect(page.getByText('こんにちは')).toBeVisible();
});

準備と後片付けが動く順番

worker を1つにして実行し、console.log の出力で順番を確かめました。

text
$ npx playwright test tests/todo.spec.ts --workers=1

Running 3 tests using 1 worker

[todoPage] 準備
  テスト本体: 最初から2件ある
[todoPage] 後片付け
  ✓  1 tests/todo.spec.ts:3:1 › 最初から2件ある (222ms)
[todoPage] 準備
  テスト本体: 3件目を追加できる
[todoPage] 後片付け
  ✓  2 tests/todo.spec.ts:8:1 › 3件目を追加できる (221ms)
  テスト本体: フィクスチャを使わないテスト
  ✓  3 tests/todo.spec.ts:15:1 › フィクスチャを使わないテスト (75ms)

  3 passed (1.2s)

分かることは3つです。

  • 準備はテストのたびに動きます。[todoPage] 準備 が、テストごとに出ています。
  • 後片付けは、テスト本体が終わってから動きます。
  • todoPage を引数に書いていない3件目のテストでは、準備も後片付けも動きませんでした。

3つめの動きは、公式ドキュメントの実行の順番の説明にも書かれています。自動で動くもの以外のフィクスチャは、テストが必要としたときだけ動きます。フィクスチャにした準備は、それを使うテストでだけ動きます。

時間がかかる準備は worker ごとに1回にする

テスト用の API サーバーのように、立てるのに時間がかかり、テストのたびに作り直さなくてよいものは、worker ごとのフィクスチャにします。配列で [関数, { scope: 'worker' }] と書きます。型は、test.extend の2つめの型引数に書きます。

ts
// tests/fixtures.ts(抜き出し)
type WorkerFixtures = {
  apiURL: string;
};

export const test = base.extend<TestFixtures, WorkerFixtures>({
  // (todoPage は省略)

  // テストごとにサーバーを立てる版(比べるため)
  apiURLEachTest: async ({}, use) => {
    console.log('[apiURLEachTest] 準備');
    const server = await startServer();
    await use(server.url);
    await server.close();
    console.log('[apiURLEachTest] 後片付け');
  },

  // worker ごとに1回だけ作るフィクスチャ
  apiURL: [async ({}, use, workerInfo) => {
    console.log(`[apiURL] 準備 worker=${workerInfo.workerIndex}`);
    const server = await startServer();
    await use(server.url);
    await server.close();
    console.log(`[apiURL] 後片付け worker=${workerInfo.workerIndex}`);
  }, { scope: 'worker' }],
});

startServer() は、1秒待ってから http.createServer() で一覧の JSON を返すサーバーを立て、その URL と止めるための関数を返します(apiURLEachTest の型 string は TestFixtures に足しています)。テストは、受け取った URL に組み込みの request で GET を送るだけにしました。

ts
// tests/api.spec.ts(api-each.spec.ts は、apiURLEachTest を使うこととテスト名だけが違う)
import { test, expect } from './fixtures';

for (const n of [1, 2, 3, 4]) {
  test(`APIから一覧を取れる ${n}`, async ({ apiURL, request }) => {
    console.log(`  テスト本体: APIから一覧を取れる ${n}`);
    const res = await request.get(`${apiURL}/items`);
    expect((await res.json()).items).toHaveLength(2);
  });
}

worker を1つにして実行すると、worker ごとのフィクスチャでは、準備は最初に1回、後片付けは最後に1回だけでした。

text
$ npx playwright test tests/api.spec.ts --workers=1

Running 4 tests using 1 worker

[apiURL] 準備 worker=0
  テスト本体: APIから一覧を取れる 1
  ✓  1 tests/api.spec.ts:4:3 › APIから一覧を取れる 1 (35ms)
  テスト本体: APIから一覧を取れる 2
  ✓  2 tests/api.spec.ts:4:3 › APIから一覧を取れる 2 (20ms)
  テスト本体: APIから一覧を取れる 3
  ✓  3 tests/api.spec.ts:4:3 › APIから一覧を取れる 3 (14ms)
  テスト本体: APIから一覧を取れる 4
  ✓  4 tests/api.spec.ts:4:3 › APIから一覧を取れる 4 (18ms)
[apiURL] 後片付け worker=0

  4 passed (1.7s)

テストごとのフィクスチャにした apiURLEachTest では、準備と後片付けが4回ずつ動き、1件ごとに1.0〜1.1秒かかりました。

text
$ npx playwright test tests/api-each.spec.ts --workers=1

Running 4 tests using 1 worker

[apiURLEachTest] 準備
  テスト本体: テストごとのサーバー 1
[apiURLEachTest] 後片付け
  ✓  1 tests/api-each.spec.ts:4:3 › テストごとのサーバー 1 (1.0s)
(2〜4件目も同じ順で、どれも 1.0s)

  4 passed (4.6s)

それぞれ3回ずつ実行した全体の時間は、次のとおりです。

フィクスチャ 準備の回数 全体の時間(3回)
テストごと(apiURLEachTest) 4回 4.6秒、4.7秒、4.6秒
worker ごと(apiURL) 1回 1.7秒、1.7秒、1.6秒
上の段はテストごとに1秒の準備が4回並び、下の段は1秒の準備が1回だけで、そのあとに短いテスト本体が4本続く図
4件のテストで、サーバーを準備した回数と全体の時間

worker ごとのフィクスチャでは、1件目のテストの時間(35ms)に、1秒の準備は入っていませんでした。テストごとのフィクスチャは、1件ごとの時間に準備の1秒が入っています。公式ドキュメントのフィクスチャのタイムアウトの説明にも、テストごとのフィクスチャの準備と後片付けの時間はテストのタイムアウトに含まれ、worker ごとのフィクスチャには別のタイムアウトがあると書かれています。

worker が増えると、準備もその数だけ動く

「worker ごとに1回」なので、worker が2つなら準備は2回です。2つのファイルを --workers=2 --fully-parallel でまとめて実行したところ、[apiURL] 準備 は worker=0 と worker=1 で1回ずつ、[apiURLEachTest] 準備 は4回出ました。全体では8件が3.7秒で通りました。テストの実行全体で1回だけ準備する方法としては、公式ドキュメントに globalSetup とプロジェクトの依存関係の2つが載っています。

worker ごとのフィクスチャからは page を使えない

worker ごとのフィクスチャの中で、組み込みの page を使おうとすると、テストが1件も動かずにエラーで止まりました。page はテストごとのフィクスチャだからです。

ts
// tests/bad/bad.spec.ts(抜き出し)
const test = base.extend<{}, { sharedPage: Page }>({
  sharedPage: [async ({ page }, use) => {
    await use(page);
  }, { scope: 'worker' }],
});
text
$ npx playwright test tests/bad --workers=1
worker fixture "sharedPage" cannot depend on a test fixture "page" defined in <builtin>.

   at bad/bad.spec.ts:3
(コードの該当箇所の表示は省略)

エラーの文面のとおり、page はテストごとのフィクスチャです。worker ごとのフィクスチャは複数のテストにまたがって残るので、テストが終わるたびに後片付けされる page には頼れません。ページを開く準備は、todoPage のようにテストごとのフィクスチャに書きます。

​Posted by 86