Playwrightの–shardでテストを複数のジョブに分ける方法

​​Playwright​CI,E2Eテスト,TypeScript

Playwright の --shard=1/3 のようなオプションを使うと、テスト全体を決まった数に分け、そのうちの1つだけを実行できます。CI で E2E テストに時間がかかるとき、テストを複数のジョブ(マシン)に分けて同時に流せば、待ち時間を短くできます。検証環境で12件のテストを3つに分けたところ、fullyParallel を有効にしないと分け方がファイル単位になり、3つの件数が6件・2件・4件と偏りました。有効にすると4件ずつにそろいました。

分けて動かした結果は、blob レポーターで保存し、npx playwright merge-reports で1つのレポートにまとめられます。

補足

検証環境は Ubuntu 24.04.5 LTS、Node.js 22.23.4、@playwright/test 1.63.0 です。テストは TypeScript で書き、ブラウザは Chromium(ヘッドレス)だけで動かしました。ページは page.setContent() でその場に作り、サーバーには接続していません。CI のサービス上での実行や、本当に別々のマシンでの実行は試していません。複数のマシンの代わりに、同じ検証環境で3つのプロセスを同時に起動して時間を比べました。

検証に使ったテスト

テストファイルは4つです。cart.spec.ts だけ6件と多く、login.spec.ts・profile.spec.ts・search.spec.ts は2件ずつ、合わせて12件です。

どのテストも、「保存」を押して1秒後に出る「保存しました」の表示を待ちます。

ts
// tests/page.ts
export const savePage = `
<button id="save">保存</button>
<p id="status"></p>
<script>
  document.querySelector('#save').addEventListener('click', () => {
    setTimeout(() => {
      document.querySelector('#status').textContent = '保存しました';
    }, 1000);
  });
</script>
`;
ts
// tests/cart.spec.ts(ほかの3ファイルは、件数を2にして名前を変えただけ)
import { test, expect } from '@playwright/test';
import { savePage } from './page';

for (let n = 1; n <= 6; n++) {
  test(`cart-${n}`, async ({ page }) => {
    await page.setContent(savePage);
    await page.getByRole('button', { name: '保存' }).click();
    await expect(page.locator('#status')).toHaveText('保存しました');
  });
}

設定ファイルでは、1つのジョブの中での並列(workers)の影響を除くため、workers: 1 にしました。レポーターは、環境変数 CI があるときだけ blob にしています(後の節で使います)。

ts
// playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  workers: 1,
  reporter: process.env.CI ? 'blob' : 'list',
  use: { browserName: 'chromium' },
});

–shard の書き方と、分かれ方の確かめ方

--shard には「何番目/全部でいくつ」を渡します。番号は1から始まります。3つに分けるなら、ジョブごとに --shard=1/3、--shard=2/3、--shard=3/3 を付けて実行します(公式ドキュメントにある、シャーディングの説明)。

bash
npx playwright test --shard=1/3

どのテストがどのシャードに入るかは、--list を付けると実行せずに確かめられます。

text
$ npx playwright test --list --shard=1/3
Listing tests:
  cart.spec.ts:5:3 › cart-1
  cart.spec.ts:5:3 › cart-2
  cart.spec.ts:5:3 › cart-3
  cart.spec.ts:5:3 › cart-4
  cart.spec.ts:5:3 › cart-5
  cart.spec.ts:5:3 › cart-6
Total: 6 tests in 1 file

--shard=2/3 は login.spec.ts の2件、--shard=3/3 は profile.spec.ts と search.spec.ts の4件でした。ファイルは分割されず、cart.spec.ts の6件はまるごと1つめのシャードに入っています。

fullyParallel を有効にすると件数がそろう

--fully-parallel を付けて同じ一覧を出すと、3つとも4件ずつになりました。cart.spec.ts のテストが、1つめと2つめのシャードに分かれています。--shard=3/3 は profile.spec.ts と search.spec.ts の4件で、付けないときと同じなので省きます。

text
$ npx playwright test --list --shard=1/3 --fully-parallel
Listing tests:
  cart.spec.ts:5:3 › cart-1
  cart.spec.ts:5:3 › cart-2
  cart.spec.ts:5:3 › cart-3
  cart.spec.ts:5:3 › cart-4
Total: 4 tests in 1 file

$ npx playwright test --list --shard=2/3 --fully-parallel
Listing tests:
  cart.spec.ts:5:3 › cart-5
  cart.spec.ts:5:3 › cart-6
  login.spec.ts:5:3 › login-1
  login.spec.ts:5:3 › login-2
Total: 4 tests in 2 files

公式ドキュメントの、シャードの偏りについての説明にも、fullyParallel: true のときはテスト1件ずつの単位で分けるので偏りが少なく、有効にしないときはファイル単位で分けると書かれています。同じ説明の中で、CI でシャードを均等に分けたいときは fullyParallel: true にすることが勧められています。設定ファイルに書いておけば、コマンドラインで毎回付ける必要はありません。

ts
// playwright.config.ts
export default defineConfig({
  fullyParallel: true,
  // …
});

3つを同時に動かしたときの時間

分け方の違いが、全体の時間にどう出るかを測りました。別々のマシンの代わりに、同じ検証環境で --shard=1/3〜3/3 の3つのプロセスを同時に起動し、3つ全部が終わるまでの時間を測っています。

分け方 シャード1 シャード2 シャード3 3つ全部が終わるまで
fullyParallel なし 6件 9.3秒 2件 3.8秒 4件 6.6秒 10.1秒
fullyParallel あり 4件 6.4秒 4件 6.6秒 4件 6.5秒 7.3秒

分けずに1つのプロセスで12件を動かしたときは17.4秒でした。

text
$ npx playwright test --reporter=dot

Running 12 tests using 1 worker
············
  12 passed (17.4s)

CI では、いちばん遅いシャードが終わるまで結果がそろいません。fullyParallel なしでは、6件を受け持った1つめのシャードの9.3秒に引っぱられ、全体が10.1秒になりました。2つめのシャードは3.8秒で終わっています。件数をそろえた場合は、3つとも6.4〜6.6秒で、全体は7.3秒でした。

なお、実行中の出力の1行目には、どのシャードを動かしているかが出ます。

text
Running 4 tests using 1 worker, shard 1 of 3

シャードの数がファイルの数より多いとき

fullyParallel を有効にしないまま、4ファイルを5つに分けてみました。--list で見ると、--shard=1/5 が cart.spec.ts の6件、3/5〜5/5 が2件ずつで、空になったのは最後ではなく --shard=2/5 でした。この節の出力は、--list の最後の行だけを抜き出し、3/5〜5/5 は省いています。

text
$ npx playwright test --list --shard=1/5 | tail -1
Total: 6 tests in 1 file

$ npx playwright test --list --shard=2/5 | tail -1
Total: 0 tests in 0 files

--shard=2/5 を実行すると、空行が出るだけで、終了コードは0でした。テストが1件もないシャードも、失敗にはなりません。公式ドキュメントの、シャードの偏りについての説明でも、ファイルごとの件数に差があると、テストを1件も動かさないシャードができることがあると書かれています。

各シャードの結果を1つのレポートにまとめる

シャードごとにレポーターを html にすると、HTML レポートもシャードごとに別々にできます。1つにまとめるには、各シャードを blob レポーターで動かし、できたファイルを集めて merge-reports を実行します(公式ドキュメントの、複数のシャードのレポートをまとめる手順)。

この検証では、環境変数 CI=1 を付けて blob レポーターにし、3つのシャードを1つずつ動かしました。各シャードの結果は blob-report フォルダーに、シャードの番号が入った名前の zip ファイルで保存されました。

text
$ CI=1 npx playwright test --shard=1/3 --fully-parallel

Running 4 tests using 1 worker, shard 1 of 3
····
  4 passed (6.2s)

$ ls blob-report
report-1.zip

--shard=2/3 では report-2.zip、--shard=3/3 では report-3.zip ができました。名前が重ならないので、3つを1つのフォルダー(ここでは all-blob-reports)に集めても上書きされません。この検証では、シャードを1つ動かすたびに zip ファイルを移しました。

bash
mkdir -p all-blob-reports && mv blob-report/*.zip all-blob-reports/

3つのシャードを動かしたあと、集めたフォルダーの中身は次のとおりです。

text
$ ls all-blob-reports
report-1.zip
report-2.zip
report-3.zip

集めたフォルダーを指定して merge-reports を実行すると、12件の結果が1つにまとまりました。

text
$ npx playwright merge-reports --reporter=list ./all-blob-reports

Running 12 tests using 3 workers

  ✓   1 tests/cart.spec.ts:5:3 › cart-1 (1.5s)
  ✓   2 tests/cart.spec.ts:5:3 › cart-2 (1.4s)
  …(中略)
  ✓  12 tests/search.spec.ts:5:3 › search-2 (1.4s)

  12 passed (19.9s)

最後の行の19.9秒は、シャードを1つずつ順に動かして作った blob をまとめたときのものです。3つを同時に動かした前の節の時間とは条件が違うので、比べられません。

--reporter=html にすると、playwright-report/index.html に HTML レポートができます。開くと、3つのシャードで動いた12件が、ファイルごとに1つの画面に並んでいました。

まとめた HTML レポートの画面。上に All 12、Passed 12、Failed 0 と出ており、cart.spec.ts の6件、login.spec.ts の2件、profile.spec.ts の1件目までが、緑のチェックマーク付きで並んでいる
3つのシャードの blob レポートからまとめた HTML レポート

GitHub Actions で分けるときの形

公式ドキュメントにある GitHub Actions の例の要点は、次の3つです。

  • strategy.matrix に、シャードの番号(shardIndex: [1, 2, 3, 4])と総数(shardTotal: [4])を書き、シャードごとにジョブを立てる
  • 各ジョブで npx playwright test --shard=${{ matrix.shardIndex }}/${{ matrix.shardTotal }} を実行し、blob-report フォルダーをアーティファクトとしてアップロードする
  • 別のジョブ(needs で全シャードを待つ)で、アーティファクトを1つのフォルダーにダウンロードし、npx playwright merge-reports --reporter html ./all-blob-reports を実行する

例では、テストが失敗したシャードがあってもレポートをまとめられるように、アップロードとまとめるジョブに if: ${{ !cancelled() }} が付いています。

​Posted by 86