Playwrightのtest.stepでレポートを読みやすくする方法
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 円になることを確かめます。
ステップなしのテストは、操作と確認を上から順に並べただけです。
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つ目が中で実行する関数です。
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 レポーターで実行しました。どちらも合計の確認で落ちます。失敗の詳細の見出しを並べると、次のとおりです(長い罫線は省きました)。
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 に置き換えています。
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行ずつ出せます。
import { defineConfig } from '@playwright/test';
export default defineConfig({
reporter: [['list', { printSteps: true }]],
});
私は環境変数で指定し、不具合のないページで2つのテストを実行しました。
$ 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行目はテスト全体の結果の行です。失敗の詳細は省きました)。
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」の欄を撮りました。上がステップなし、下がステップありのテストです。


ステップなしのテストでは、page.goto() から失敗した toHaveText() まで、8つの操作が、どれも同じ階層に並びます。ステップありのテストでは、テストのコードから出る行は「ログインする」と「カートに2つ入れる」の2つだけで、失敗したステップに赤い×が付きます。開くと、ステップを呼んだコードの抜粋が出て、その下に click() 2回と toHaveText() がまとまって表示されます。どの操作で落ちたかも分かります。各行の右には、かかった時間が出ます。
共通の操作をまとめた関数では、box でエラーの指す行を変えられる
ログインやカートの操作を関数にまとめ、その中で test.step() を呼ぶこともできます。ただし、このままでは、失敗したときのエラーは関数の中の行を指します。API リファレンスによると、box: true を付けたステップでは、中で起きたエラーが、ステップを呼んだ場所を指すようになります。
次の関数の box を、テストから切り替えられるようにして試しました。
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つでした。
> 8 | await expect(page.locator('#total')).toHaveText(total);
| ^
box: true のときは、テストの中で関数を呼んだ行を指し、at の行もテストのファイルの1つだけになりました。
> 16 | await addToCart(page, ['ノート', 'ペン'], '450', true);
| ^
どちらの場合も、失敗の見出しには › カートに2つ入れる が付きました。何度も使う関数の中身より、テストのどの呼び出しで落ちたかを先に見たいときは、box: true が向いています。
入れ子、戻り値、subtitle、スキップ
ステップの中にステップを入れたり、ステップから値を返したりもできます。Playwright 1.63 で追加された subtitle オプションと、test.step.skip() も合わせて試しました。
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 を付けたときの、ステップの行は次のとおりです。
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つ入れる」のように、画面の上で何をしている段階なのかが分かる名前を付けると、レポートだけを見て失敗した場所の見当がつきます。





