PlaywrightのLocator優先順位を3分で理解する

「テストがすぐ壊れる…」その原因、セレクタ（要素の探し方）にあるかもしれません。 Playwright公式が推奨する、メンテナンス不要の「最強Locator優先順位」をサクッと解説します。

結論：この順番で検討せよ！

Playwrightでは「ユーザーが見ている情報」で探すのが鉄則です。

優先度	Locator (メソッド)	探す対象
Lv 1 (最強)	getByRole	ボタン、見出しなどの「役割」
Lv 2 (推奨)	getByLabel / getByPlaceholder	フォームの項目名やヒント
Lv 3 (普通)	getByText	画面上のテキストそのもの
Lv 4 (最終手段)	getByTestId	テスト専用の目印

なぜ「役割（Role）」で探すのがいいの？

開発者がデザイン（CSS）やHTMLの構造を変えても、「そこがログインボタンである」という役割（Role）は変わらないからです。

壊れやすい例（CSS依存）

await page.locator('.btn-primary >> nth=2').click();
// クラス名が変わったり、ボタンが増えただけで即死

壊れにくい例（Role指定）

await page.getByRole('button', { name: 'ログイン' }).click();
// HTMLがからに変わっても、見た目が変わっても動き続ける

ケース別・ベストな選び方

「どう書くんだっけ？」と迷ったらこれを見てください。

• ボタンを押したいとき 👉 getByRole('button', { name: '送信' })
• 入力欄に文字を入れたいとき 👉 getByLabel('メールアドレス') または getByPlaceholder('example@com')
• 特定のメッセージを確認したいとき 👉 getByText('完了しました')
• 画像が表示されているか見たいとき 👉 getByAltText('プロフィール写真')

これは使わないで！

• page.locator('.my-class')（CSSセレクタ）
• page.locator('//div/span[1]')（XPath）

これらは「中身」ではなく「ガワ」を見ているため、リニューアルや微修正で全滅します。

まとめ：30秒で復習

1. ユーザーが見ているもの（役割・名前・テキスト）で探す。
2. 一番のオススメは getByRole。
3. どうしても指定できない時だけ data-testid を付与する。

---

「自分のコード、CSSセレクタだらけかも…」と思った方は、まずは1箇所 getByRole に書き換えるところから始めてみましょう！