PlaywrightでTabキーのフォーカス順をテストする方法
Playwright でフォーカスの順番をテストするには、page.keyboard.press('Tab') で Tab キーを押し、expect(locator).toBeFocused() で、フォーカスが来てほしい要素を1つずつ確かめます。マウスを使わずキーボードだけでフォームを入力できるか、モーダルを開いている間に後ろの画面へフォーカスが抜けないか、といったアクセシビリティの確認を E2E テストに入れるときに使う書き方です。
私は検証環境で会員登録のフォームを作り、Tab キーを押したときにフォーカスがどこへ移るかを記録しました。そのうえで、順番どおりに移ることを確かめるテストと、順番が崩れたときに落ちるテストを動かしました。
検証環境は Ubuntu 24.04、Node.js 22.23.4、@playwright/test 1.63.0 です。ブラウザは Playwright 用の Chromium だけで、ページは Node.js の http モジュールで書いた小さなサーバーから配信しました。Firefox と WebKit、React などのフレームワークで作った画面、スクリーンリーダーでの読み上げは試していません。
試した会員登録のフォーム
フォームの部分は次の HTML です。ページの先頭には、ふだんは画面の外に隠れていてフォーカスが来たときだけ出る「本文へ移動」のリンク(スキップリンク)と、「ホーム」「ヘルプ」のリンクを置きました。
<main id="main" tabindex="-1">
<h1>会員登録</h1>
<form onsubmit="event.preventDefault()">
<label>お名前 <input name="name"></label>
<label>メールアドレス <input name="email" type="email"></label>
<label class="hidden">招待コード <input name="code"></label>
<label>プラン
<select name="plan"><option>無料</option><option>有料</option></select>
</label>
<label><input type="checkbox" name="agree"> 利用規約に同意する</label>
<button type="button" disabled>下書き保存</button>
<div role="button" tabindex="0" id="terms">規約を読む</div>
<button type="submit">登録する</button>
</form>
<button type="button" id="open">ヘルプを開く</button>
</main>
「招待コード」は display: none で隠し、「下書き保存」は disabled にしています。「規約を読む」は、div に tabindex="0" を付けてボタンの代わりにしたものです。フォームの送信は event.preventDefault() で止め、「登録する」を押してもページが読み込み直されないようにしました。
Tab キーを押すたびに、フォーカスのある要素の名前を記録しました。ページを開いた直後のフォーカスは body で、そこから12回押した結果です。
最初 body
[
'a「本文へ移動」',
'a「ホーム」',
'a「ヘルプ」',
'input「お名前」',
'input「メールアドレス」',
'select「プラン」',
'input「利用規約に同意する」',
'div「規約を読む」',
'button「登録する」',
'button「ヘルプを開く」',
'body',
'a「本文へ移動」'
]
隠した「招待コード」、disabled の「下書き保存」、tabindex="-1" の main には、フォーカスが来ませんでした。tabindex="0" の div には来ました。最後の「ヘルプを開く」の次は body に戻り、もう1回押すと先頭の「本文へ移動」に戻りました。

toBeFocused() で1つずつ確かめる
順番どおりに移るかどうかは、来てほしい要素のロケーターを順に並べ、Tab キーを押すたびに toBeFocused() で確かめます。
import { test, expect } from '@playwright/test';
test('Tab キーで、上から順にフォーカスが移る', async ({ page }) => {
await page.goto('/');
const expected = [
page.getByRole('link', { name: '本文へ移動' }),
page.getByRole('link', { name: 'ホーム' }),
page.getByRole('link', { name: 'ヘルプ' }),
page.getByLabel('お名前'),
page.getByLabel('メールアドレス'),
page.getByLabel('プラン'),
page.getByLabel('利用規約に同意する'),
page.getByRole('button', { name: '規約を読む' }),
page.getByRole('button', { name: '登録する' }),
page.getByRole('button', { name: 'ヘルプを開く' }),
];
for (const target of expected) {
await page.keyboard.press('Tab');
await expect(target).toBeFocused();
}
});
このテストは通りました。--repeat-each 20 で、テストファイルにある6本(この記事に載せたテストと、disabled の「下書き保存」が飛ばされることを確かめるテスト)を20回ずつくり返しても、120回すべて通りました。
Keyboard の API リファレンスでは、多くの場合は page.keyboard.press() より locator.press() を使うように勧めています。ただし locator.press() は、先にその要素にフォーカスを当ててからキーを押します(locator.press() の説明)。ページの頭から順にたどるテストでは、どこにもフォーカスを当てずに押したいので、page.keyboard.press() を使います。
途中から始めるときと、Shift+Tab で戻るとき
フォームの途中から確かめたいときは、locator.press('Tab') が便利です。その要素にフォーカスを当ててから Tab キーを押すので、次の要素に移ります。
await page.getByLabel('メールアドレス').press('Tab');
await expect(page.getByLabel('プラン')).toBeFocused();
逆の順番は、Shift+Tab で確かめます。
await page.getByRole('button', { name: '登録する' }).focus();
await page.keyboard.press('Shift+Tab');
await expect(page.getByRole('button', { name: '規約を読む' })).toBeFocused();
await page.keyboard.press('Shift+Tab');
await expect(page.getByLabel('利用規約に同意する')).toBeFocused();
どちらも通りました。「登録する」から Shift+Tab を4回押すと、「規約を読む」「利用規約に同意する」「プラン」「メールアドレス」の順で戻りました。disabled の「下書き保存」は、戻るときも飛ばされました。
順番が崩れたときは、フォーカスのある要素の名前を確かめると原因が分かる
「お名前」「メールアドレス」「登録する」の3つが並ぶページで、「メールアドレス」にだけ tabindex="1" を付けました。すると Tab キーを押した順番は「メールアドレス」「お名前」「登録する」になりました。MDN の tabindex の説明にあるとおり、正の値の tabindex を持つ要素が先に来ます。
このページで、最初の Tab キーで「お名前」に来ることを toBeFocused() で確かめると、待ったあとで落ちました(上限を2秒にしました)。
Error: expect(locator).toBeFocused() failed
Locator: getByLabel('お名前')
Expected: focused
Received: inactive
Timeout: 2000ms
Received: inactive からは「お名前」にフォーカスがないことしか分かりません。代わりに、フォーカスのある要素を page.locator(':focus') で指し、toHaveAccessibleName() で名前を確かめる書き方を試しました。
await page.goto('/positive');
await page.keyboard.press('Tab');
await expect(page.locator(':focus')).toHaveAccessibleName('お名前', { timeout: 2000 });
Error: expect(locator).toHaveAccessibleName(expected) failed
Locator: locator(':focus')
Expected: "お名前"
Received: "メールアドレス"
Timeout: 2000ms
Call log:
- Expect "toHaveAccessibleName" locator(':focus') with timeout 2000ms
- waiting for locator(':focus')
21 × locator resolved to <input name="email" tabindex="1"/>
- unexpected value "メールアドレス"
こちらは、実際にフォーカスが来たのが「メールアドレス」で、その要素に tabindex="1" が付いていることまで、エラーの文面に出ました。順番のテストが落ちて原因を探すときは、この書き方に変えると早く見つかります。
モーダルの外にフォーカスが抜けないことを確かめる
「ヘルプを開く」を押すと、<dialog aria-label="ヘルプ"> を showModal() で開くようにしました。中には「よくある質問」のリンクと「閉じる」ボタンがあります。開いた直後のフォーカスは「よくある質問」でした。そこから Tab キーを6回押して、フォーカスの場所を記録しながら、後ろの「ヘルプを開く」にフォーカスが来ないことを not.toBeFocused() で確かめました。
await page.getByRole('button', { name: 'ヘルプを開く' }).click();
const dialog = page.getByRole('dialog', { name: 'ヘルプ' });
await expect(dialog.getByRole('link', { name: 'よくある質問' })).toBeFocused();
for (let i = 1; i <= 6; i++) {
await page.keyboard.press('Tab');
console.log(`Tab ${i}回目`, await page.evaluate(() =>
document.activeElement === document.body ? 'body' : document.activeElement?.textContent?.trim()));
await expect(page.getByRole('button', { name: 'ヘルプを開く' })).not.toBeFocused();
}
Tab 1回目 閉じる
Tab 2回目 body
Tab 3回目 よくある質問
Tab 4回目 閉じる
Tab 5回目 body
Tab 6回目 よくある質問
テストは通りました。フォーカスは dialog の中の2つと body を回り、後ろのフォームには一度も移りませんでした。ページの最後で Tab キーを押したときと同じく、最後の「閉じる」の次は body で、先頭の「よくある質問」に戻るのはその次の Tab キーでした。dialog の中を1周したことを確かめるときは、この body の1回を数に入れます。
比べるために、<dialog> を使わず、div の hidden を外して表示するだけのパネルも作りました。開いたときに中の「よくある質問」へフォーカスを当てますが、Tab キーを外へ出さない処理は入れていません。同じように Tab キーを2回押してから、後ろの「後ろのボタン」にフォーカスがないことを確かめると、テストは落ちました。
Error: expect(locator).not.toBeFocused() failed
Locator: getByRole('button', { name: '後ろのボタン' })
Expected: not focused
Received: focused
1回目で「閉じる」、2回目でパネルの外の「後ろのボタン」に移っていました。閉じ込める処理がないと、このテストが落ちて、フォーカスが外に抜けたことが分かります。
キーボードで来たときだけフォーカスの枠が出ることを確かめる
このページでは、:focus-visible のときだけピンクの枠(outline)を出すようにしています。MDN の :focus-visible の説明にあるとおり、ブラウザはキーボードで移ったときには枠を出し、ボタンをマウスでクリックしたときにはふつう出しません。この違いは toHaveCSS() で確かめられます。
await page.getByLabel('お名前').press('Tab');
await expect(page.getByLabel('メールアドレス')).toBeFocused();
await expect(page.getByLabel('メールアドレス')).toHaveCSS('outline-style', 'solid');
const submit = page.getByRole('button', { name: '登録する' });
await submit.click();
await expect(submit).toBeFocused();
await expect(submit).toHaveCSS('outline-style', 'none');
このテストは通りました。クリックした「登録する」にもフォーカスはありますが、枠は出ていません。toBeFocused() だけでは、キーボードで操作する人に今どこにいるかが見えているかまでは分かりません。枠の CSS も合わせて確かめておくと、Tab キーで来た要素に枠が出ているかまでテストできます。





