playwright-frontend

Playwright フロントエンド（ロケーター可能なマークアップの作成）

対象読者：アプリを開発するフロントエンドエンジニア — core/ のテスト作成者向けガイドに対応するものです。ここでの目的は、テストと AI エージェントが不安定さを避けて要素を確実に特定できるよう、DOM 上に小規模で安定した機械可読の契約を用意することです。

data-testid は UI の自動化レイヤーにおける公開 API です。テストやエージェントがこれに依存した後で名前を変更すると、互換性を損なう変更になります。まずアクセシブルなマークアップを作成し、自動化で長期的に使える識別子が必要な箇所に、意図的で適切な名前を付けた、一意かつ安定したテスト ID を追加してください。

ガイド一覧

トピック	ガイド
data-testid の規約（使用場面、命名、一意性、安定性）	data-testid-conventions.md
フレームワークのパターン（React、Vue、Angular、Svelte）＋ ID の一元管理＋本番環境での削除	examples.md

基本ルール

1. まずセマンティックな HTML を使う — getByRole／getByLabel が機能するよう、要素に適切なロール、ラベル、アクセシブルな名前を設定してから、テスト ID を追加します。
2. ロール、ラベル、テキストでは不十分な場合に限り data-testid を追加する — ロールのないカスタムウィジェット、スコープ用コンテナー、リストの行、動的またはローカライズされた領域などが該当します。getByRole で一意に特定できるコントロールには必要ありません。
3. 全体で一意になる名前を付ける — feature-component-element[-variant]、kebab-case。
4. リストでは配列のインデックスではなく、安定したドメインキーを末尾に付ける — user-row-${user.id} ✅ / user-row-${index} ❌。
5. 値をテキスト、ロケール、スタイル、DOM 上の位置から切り離す — これらは変わりますが、テスト ID は変わらないようにします。
6. 属性を一つに統一する — Playwright のデフォルトの testIdAttribute は data-testid です。data-test／data-qa と混在させないでください。

関連項目

• core/locators.md／core/locator-strategy.md — 利用する側のガイド。テストを書く際のロケーターの選び方を説明します。
• Playwright 公式ドキュメント：ロケーター、ベストプラクティス。