Playwrightのtest.stepでレポートを読みやすくする方法

​​Playwright​E2Eテスト,TypeScript

Playwright の test.step() を使うと、1つのテストの中の操作を「ログインする」「カートに入れる」のような段階(ステップ)に分け、その名前をレポートに出せます。E2Eテストが CI で落ちたとき、ログや HTML レポートを開いて、どの段階で失敗したのかをすぐ見つけたい場面で役に立ちます。

私は検証環境で、ログインしてから商品をカートに入れ、注文するまでを確かめる同じ内容のテストを、ステップなしとステップありの2通りで書きました。わざと合計金額を間違える不具合を入れたページで落とし、list レポーターと HTML レポーターの表示を比べています。

補足

検証環境は Ubuntu 24.04、Node.js 22.23.4、@playwright/test 1.63.0 です。ブラウザは Playwright 用の Chromium だけで、ページは Node.js の http モジュールで書いた小さなサーバーから配信しました。line・dot・JSON などほかのレポーター、トレースビューアーでの表示、Firefox・WebKit は試していません。

検証に使った注文画面とテスト

ページには、ログインのフォーム、ノート(300円)とペン(150円)の「カートに入れる」ボタン、合計の欄(#total)、「注文する」ボタンがあります。環境変数 BUG=1 を付けてサーバーを起動したときだけ、2つ目以降の商品を合計に足し忘れる不具合のあるページを返すようにしました。テストのコードはどちらの場合も同じで、ノートとペンを入れたあとの合計が 450 円になることを確かめます。

ステップなしのテストは、操作と確認を上から順に並べただけです。

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

test('ステップなしで注文する', async ({ page }) => {
  await page.goto('/');
  await page.getByLabel('メールアドレス').fill('user@example.com');
  await page.getByLabel('パスワード').fill('secret');
  await page.getByRole('button', { name: 'ログイン' }).click();
  await expect(page.getByText('user@example.com でログイン中')).toBeVisible();
  await page.getByRole('button', { name: 'ノートをカートに入れる' }).click();
  await page.getByRole('button', { name: 'ペンをカートに入れる' }).click();
  await expect(page.locator('#total')).toHaveText('450');
  await page.getByRole('button', { name: '注文する' }).click();
  await expect(page.locator('#summary')).toHaveText('2点、450円');
});

ステップありのテストでは、同じ操作を3つの test.step() に分けました。API リファレンスの test.step の説明のとおり、1つ目の引数がステップの名前、2つ目が中で実行する関数です。

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

test('ステップに分けて注文する', async ({ page }) => {
  await test.step('ログインする', async () => {
    await page.goto('/');
    await page.getByLabel('メールアドレス').fill('user@example.com');
    await page.getByLabel('パスワード').fill('secret');
    await page.getByRole('button', { name: 'ログイン' }).click();
    await expect(page.getByText('user@example.com でログイン中')).toBeVisible();
  });

  await test.step('カートに2つ入れる', async () => {
    await page.getByRole('button', { name: 'ノートをカートに入れる' }).click();
    await page.getByRole('button', { name: 'ペンをカートに入れる' }).click();
    await expect(page.locator('#total')).toHaveText('450');
  });

  await test.step('注文する', async () => {
    await page.getByRole('button', { name: '注文する' }).click();
    await expect(page.locator('#summary')).toHaveText('2点、450円');
  });
});

失敗したときの見出しに、ステップの名前が付く

不具合のあるページで、2つのテストを list レポーターで実行しました。どちらも合計の確認で落ちます。失敗の詳細の見出しを並べると、次のとおりです(長い罫線は省きました)。

text
  1) tests/flat.spec.ts:3:5 › ステップなしで注文する
  2) tests/steps.spec.ts:3:5 › ステップに分けて注文する › カートに2つ入れる

ステップありのテストでは、テストの名前のあとに、失敗したステップの名前「カートに2つ入れる」が付きました。エラーの本文(期待した値 "450" と実際の値 "300")は、どちらも同じです。

エラーの場所を示す行も変わります。ステップなしのテストは at の行が1つだけですが、ステップありのテストでは、失敗した行(15行目)に加えて、そのステップを呼んだ行(12行目)も出ました。パスは /path/to/app に置き換えています。

text
        at /path/to/app/tests/steps.spec.ts:15:42
        at /path/to/app/tests/steps.spec.ts:12:3

list レポーターで、ステップを1行ずつ出す

list レポーターは、初期設定ではステップを表示しません。公式ドキュメントの list レポーターの説明によると、設定ファイルで printSteps: true を渡すか、環境変数 PLAYWRIGHT_LIST_PRINT_STEPS を使うと、ステップを1行ずつ出せます。

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

export default defineConfig({
  reporter: [['list', { printSteps: true }]],
});

私は環境変数で指定し、不具合のないページで2つのテストを実行しました。

text
$ PLAYWRIGHT_LIST_PRINT_STEPS=1 npx playwright test tests/flat.spec.ts tests/steps.spec.ts --reporter=list --workers=1
Running 2 tests using 1 worker
  ✓  1 tests/flat.spec.ts:3:5 › ステップなしで注文する (277ms)
     2.1 tests/steps.spec.ts:3:5 › ステップに分けて注文する › ログインする (86ms)
     2.2 tests/steps.spec.ts:3:5 › ステップに分けて注文する › カートに2つ入れる (78ms)
     2.3 tests/steps.spec.ts:3:5 › ステップに分けて注文する › 注文する (34ms)
  ✓  2 tests/steps.spec.ts:3:5 › ステップに分けて注文する (235ms)
  2 passed (1.1s)

ステップありのテストでは、ステップごとに 2.1〜2.3 の番号と、かかった時間が出ました。ステップなしのテストは、click() や fill() が1行ずつ出ることはなく、テストの1行だけでした。

不具合のあるページで同じように実行すると、ステップの行は次の2行だけでした(3行目はテスト全体の結果の行です。失敗の詳細は省きました)。

text
     1.1 tests/steps.spec.ts:3:5 › ステップに分けて注文する › ログインする (109ms)
     1.2 tests/steps.spec.ts:3:5 › ステップに分けて注文する › カートに2つ入れる (5.1s)
  ✘  1 tests/steps.spec.ts:3:5 › ステップに分けて注文する (5.2s)

「カートに2つ入れる」は、toHaveText() が5秒待ってから落ちたため 5.1s かかり、そのあとの「注文する」は実行されないので出ていません。ステップの行には成功・失敗の記号が付かないため、どこで止まったかは、最後に出たステップと失敗の見出しで判断します。

HTML レポートでは、操作がステップの下にまとまる

同じ2つのテストを、不具合のあるページで HTML レポーターを使って実行し、レポートの「Test Steps」の欄を撮りました。上がステップなし、下がステップありのテストです。

HTML レポートの Test Steps の欄。Navigate、Fill、Click、Expect の操作が、テストのコードの順に1行ずつ並び、最後の Expect "toHaveText" の行だけ、緑のチェックの代わりに赤い×が付いている
ステップなしのテスト。操作が1行ずつ並ぶ
HTML レポートの Test Steps の欄。「ログインする」「カートに2つ入れる」の2つのステップが並び、失敗した「カートに2つ入れる」を開くと、2回の Click と Expect "toHaveText" がその下にまとまっている
ステップありのテスト。失敗したステップを開いたところ

ステップなしのテストでは、page.goto() から失敗した toHaveText() まで、8つの操作が、どれも同じ階層に並びます。ステップありのテストでは、テストのコードから出る行は「ログインする」と「カートに2つ入れる」の2つだけで、失敗したステップに赤い×が付きます。開くと、ステップを呼んだコードの抜粋が出て、その下に click() 2回と toHaveText() がまとまって表示されます。どの操作で落ちたかも分かります。各行の右には、かかった時間が出ます。

共通の操作をまとめた関数では、box でエラーの指す行を変えられる

ログインやカートの操作を関数にまとめ、その中で test.step() を呼ぶこともできます。ただし、このままでは、失敗したときのエラーは関数の中の行を指します。API リファレンスによると、box: true を付けたステップでは、中で起きたエラーが、ステップを呼んだ場所を指すようになります。

次の関数の box を、テストから切り替えられるようにして試しました。

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

export async function addToCart(page: Page, items: string[], total: string, box: boolean) {
  await test.step(`カートに${items.length}つ入れる`, async () => {
    for (const item of items) {
      await page.getByRole('button', { name: `${item}をカートに入れる` }).click();
    }
    await expect(page.locator('#total')).toHaveText(total);
  }, { box });
}

テストのファイルでは、ログインを beforeEach で済ませておき、addToCart(page, ['ノート', 'ペン'], '450', false) と true の2通りで呼んで、不具合のあるページで落としました。エラーの出力から、該当する行だけを抜き出して載せます。

box なしのときは、関数の中の toHaveText() の行を指しました。at の行は、関数の中の2行(cart.ts の8行目と4行目)と、テストの行(box.spec.ts の12行目)の3つでした。

text
    >  8 |     await expect(page.locator('#total')).toHaveText(total);
         |                                          ^

box: true のときは、テストの中で関数を呼んだ行を指し、at の行もテストのファイルの1つだけになりました。

text
    > 16 |   await addToCart(page, ['ノート', 'ペン'], '450', true);
         |   ^

どちらの場合も、失敗の見出しには › カートに2つ入れる が付きました。何度も使う関数の中身より、テストのどの呼び出しで落ちたかを先に見たいときは、box: true が向いています。

入れ子、戻り値、subtitle、スキップ

ステップの中にステップを入れたり、ステップから値を返したりもできます。Playwright 1.63 で追加された subtitle オプションと、test.step.skip() も合わせて試しました。

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

test('入れ子のステップと戻り値', async ({ page }) => {
  await test.step('ログインする', async () => {
    await page.goto('/');
    await test.step('入力する', async () => {
      await page.getByLabel('メールアドレス').fill('user@example.com');
      await page.getByLabel('パスワード').fill('secret');
    });
    await page.getByRole('button', { name: 'ログイン' }).click();
  });

  const total = await test.step('カートに入れる', async () => {
    await page.getByRole('button', { name: 'ノートをカートに入れる' }).click();
    return page.locator('#total').textContent();
  }, { subtitle: 'ノート' });
  expect(total).toBe('300');

  await test.step.skip('クーポンを使う', async () => {
    // クーポンの画面はまだない
  });
});

テストは通りました。test.step() は中の関数が返した値をそのまま返すので、合計の '300' をステップの外で受け取れています。list レポーターで printSteps を付けたときの、ステップの行は次のとおりです。

text
     1.1 tests/nested.spec.ts:3:5 › 入れ子のステップと戻り値 › ログインする › 入力する (34ms)
     1.2 tests/nested.spec.ts:3:5 › 入れ子のステップと戻り値 › ログインする (87ms)
     1.3 tests/nested.spec.ts:3:5 › 入れ子のステップと戻り値 › カートに入れる ノート (30ms)
     1.4 tests/nested.spec.ts:3:5 › 入れ子のステップと戻り値 › クーポンを使う (0ms)

list レポーターでは、入れ子のステップは「ログインする › 入力する」のように親の名前とつないで出ます。行はステップが終わった順に出るので、内側の「入力する」が外側の「ログインする」より先です。番号は入れ子でも 1.1〜1.4 の通し番号でした。subtitle の「ノート」は、名前のあとに空白を挟んで付きました。スキップしたステップは、list レポーターでは (0ms) と出るだけで、スキップしたことは分かりません。

HTML レポートでは、「入力する」は「ログインする」を開いた下に出ました。スキップしたステップは「クーポンを使う (skipped)」と表示され、subtitle は「カートに入れる ノート」のように名前の横に出ています。

API リファレンスの test.step.skip の説明では、test.step.skip() より、ステップの中で step.skip() を呼ぶ書き方が勧められています。step は、ステップの関数が引数で受け取る TestStepInfo です(async (step) => { … })。TestStepInfo の API リファレンスによると、step.skip(条件, 説明) の形で、条件が成り立つときだけステップを飛ばすこともできます。

ステップの名前の付け方

ここまでの出力で分かるとおり、ステップの名前は、失敗の見出し、list レポーターの行、HTML レポートの一覧にそのまま出ます。click や fill のような操作の名前は、Playwright が自動で出します。そのため、ステップには「ログインする」「カートに2つ入れる」のように、画面の上で何をしている段階なのかが分かる名前を付けると、レポートだけを見て失敗した場所の見当がつきます。

​Posted by 86