playwright-best-practices

Playwright のテストを書く、落ちるテストを直す、CI に載せる、といった作業を、決まった作法に沿ってやらせたいときです。

公開元は Playwright のテスト結果のダッシュボードを出している currents.dev で、README は TypeScript で書くテストを対象にしていると明記しています。

SKILL.md の大きさ

26,306 バイト

同梱の手引き

58 本

手引きのフォルダ

8 つ

作業別の索引の組

11 組

数字はどれも 2026-10-23 時点の実測です。

SKILL.md は索引、中身は同梱の手引き

SKILL.md の 26KB は、ほとんどが「この作業ならこの手引きを読め」という表です。コードの書き方そのものは、同梱の 58 本に分かれています（2026-10-23 時点で合わせて約 72 万バイト）。

README の言い方では、作業に合わせて該当する手引きだけを読ませる作りで、全部を一度に読み込まない、とされています。

作業の種類から引く

索引は作業の種類で 11 組に分かれています。主なものを並べます。

• 新しいテストを書くE2E・コンポーネント・API・GraphQL・見た目の比較・アクセシビリティ・Electron・拡張機能など
• スマホと画面幅端末のエミュレーション、スワイプやタップ、ブレークポイント
• ブラウザの APIWebSocket、位置情報、権限、クリップボード、カメラ、複数タブ
• 落ちる原因を探すトレースビューア、要素が見つからない、タイムアウト、競合状態
• 設計の判断ページオブジェクトかフィクスチャか、何をモックするか
• CI と設定GitHub Actions・GitLab・Docker・並列と分割・カバレッジ・レポート

ほかに、異常系とオフライン、複数ユーザーの同時操作、フレームワーク別（React・Angular・Vue/Nuxt・Next.js）、既存のテストの整理、高度な使い方（HAR の記録と再生、決済やメールのモックなど）の組があります。索引の後ろに、同じ中身を木の形に並べた「早見の分かれ道」も付いています。

テストを書いたら通るまで回す

本文の最後に、テストを書いた・直したあとの手順が決まっています。

1. 流すnpx playwright test --reporter=list で実行する
2. 落ちたら出力とトレース（npx playwright show-trace）を見て、セレクタ・待ち方・アサーションを直し、流し直す
3. 全部通るまで全件が通るまで次へ進まない
4. 大事なものは繰り返す--repeat-each=5 で 5 回流して、たまに落ちないか確かめる

1 回通っただけで終わらせず、繰り返して不安定さを炙り出すところまでが手順に入っています。

手引きの中身の例

手引きはどれも、良い例のコードと避ける書き方の表で組まれています。要の考え方をいくつか挙げます。

• セレクタは役割（getByRole）→ ラベル → 文字 → テスト用 ID → CSS や XPath の順で選ぶ（core/locators.md）
• waitForTimeout(5000) のような固定の待ちはしない。自動待機か、応答を待つ書き方にする（core/assertions-waiting.md）
• モックするのは自分で持っていない外部サービスだけ。自分の API とデータベースはモックしない（architecture/when-to-mock.md）
• 不安定なテストは、画面・環境・データと並列・テストの順序の 4 種類に分けて原因を探す（debugging/flaky-tests.md）

モックの判断表では、決済（Stripe）、メール送信（SendGrid）、OAuth の提供元、アクセス解析、地図は「常にモック」とされています。自分のログインの仕組みは「ほぼモックしない」で、保存したログイン状態（storageState）で毎回のログインを省け、と書かれています。

ブラウザをその場で操作させたいだけのとき

このスキルはテストのコードを書くための作法です。画面を開いて押して確かめるだけなら、ブラウザを CLI で操作させる playwright-cli のほうが向いています。

Python で手早く確かめたいとき

手引きのコードはすべて TypeScript の @playwright/test です。Python のスクリプトでローカルの画面を確かめたいなら、webapp-testing が合います。

• テストの一式を書いて保守するこのスキル。設計・CI・不安定なテストまで面倒を見る
• 画面をその場で操作して確かめるplaywright-cli。要素の一覧を読んで押す
• Python で手早く確かめるwebapp-testing。スクリプトを書いて流す

Playwright 以外のテスト基盤

Cypress や Selenium、Vitest だけの単体テストには対応していません。コンポーネントのテストも、Playwright のコンポーネントテストの仕組みを前提にしています。

解析で見つかったもの

SKILL.md が求める実行は、テストを流す npx playwright test と、トレースを開く npx playwright show-trace です。外部への通信や、テスト以外のファイルを書き換える指示はありません。テストのファイルを書く・直すのは、このスキルを使う目的そのものです。

安全性のテストは自分のアプリだけに向ける

testing-patterns/security-testing.md には、XSS の入力例や CSRF、権限の確かめ方のテストが入っています。自分が管理しているアプリと検証環境に向けて使うものです。

同梱の数は README と 1 本ずれる

README は「57 本の手引き」と書いていますが、実際に同梱されているのは 58 本です（2026-10-23 時点）。README の表に core/test-tags.md が載っていないためで、SKILL.md の索引には載っています。

費用と前提

外部の有料サービスは使いません。ただし、--repeat-each=5 は同じテストを 5 回流すので、重いテストでは時間がかかります。

公開元の currents.dev はテスト結果のダッシュボードの会社ですが、SKILL.md の手順は自社のサービスを使うことを求めていません。ライセンスは MIT です（リポジトリの LICENSE.md。2026-10-23 確認）。

既存のテストが壊れやすいとき、どこから読ませればいいですか

「ログインのテストがときどき落ちる」のように症状を言えば、索引から不安定なテストの手引きとデバッグの手引きが選ばれます。落ち方を 4 種類に分け、繰り返し流して再現させ、トレースで原因を探す流れです。直したあとは --repeat-each=5 で繰り返して確かめる手順まで入っています。

playwright-cli とどう違いますか

playwright-cli はブラウザをその場で操作させる道具で、このスキルはテストのコードを書いて保守するための作法です。画面を触って確かめるのが目的なら playwright-cli、CI で毎回流すテストを書くならこちらです。両方を入れて、触って確かめたことをこのスキルでテストに起こす使い方もできます。

全部の手引きを読み込むので重くなりませんか

SKILL.md 自体は 26KB あり、呼ばれるとこれが読み込まれます。同梱の 58 本は、作業に合わせて該当するものだけを開く作りです。1 本はおおむね 6〜31KB なので、1 回の作業で読むのは数本分になります。

React や Next.js に合わせた書き方もありますか

あります。React・Angular・Vue（Nuxt を含む）・Next.js の 4 つに、それぞれ専用の手引きがあります。React なら Strict Mode の二重実行や Suspense、Next.js なら App Router のストリーミングや SSR のように、フレームワークごとのつまずきどころを扱っています。

対応しているエージェントはどれですか

公開元は特定のエージェントを名指ししていません。README は「AI に Playwright の専門的な手引きを与えるスキル」とだけ書き、npx skills add での導入を案内しています（2026-10-23 確認）。当サイトは公開元が明記しているものだけを対応として表示するので、このページには対応のエージェントが出ません。