fix は、失敗するテストや flaky なテスト向けの Playwright デバッグ skill です。agent が再現、burn-in runs、trace capture、そして timing、isolation、environment、infrastructure の問題を taxonomy に基づいて診断する流れを進められるよう支援します。
この skill の評価は 80/100 で、失敗する、または flaky な Playwright tests を汎用プロンプトより少ない当て推量で agent にデバッグさせたい directory users にとって、有力な掲載候補です。trigger が明確で、実用的な troubleshooting taxonomy もありますが、install/readme materials がないことと、ユーザーの Playwright setup に関する前提があるため、導入の分かりやすさには制限があります。
- frontmatter は "fix test"、"flaky test"、"debug test"、"intermittent failure" など具体的なユーザーフレーズを挙げており、発動条件が明確です。
- 再現、repeat runs による burn-in、parallel workers での実行、trace capture、failure の分類まで、実用的な診断ワークフローを提供します。
- flaky-test taxonomy が別途用意されており、decision tree と、timing、isolation、environment、infrastructure の問題に対する具体的な Playwright fix patterns が含まれています。
- skill directory には install command、README、metadata が用意されていないため、ユーザーは広い repository context からインストール方法を推測する必要があります。
- Workflow は npx を使う Node/Playwright project を前提としており、custom runners、configs、標準的でない CI setups を持つ projects へのガイダンスは限定的です。
fix skill の概要
fix skill でできること
fix skill は、失敗する、または不安定な Playwright テストを調査するための、デバッグに特化したワークフローです。アサーションエラーだけを見て推測するのではなく、失敗を再現し、trace などの証拠を集め、flaky-test taxonomy に沿って問題を分類することで、「このテストが壊れている」という状態から、原因として可能性の高い箇所まで AI エージェントを導きます。
Playwright テストのデバッグに向いているケース
end-to-end テストを保守していて、「test failing」「flaky test」「ローカルでは通るが CI で落ちる」「たまにだけ失敗する」といった状況によく遭遇するなら、この skill はインストールする価値があります。特に Playwright を CI で使っているチームでは、タイミング、テスト分離、環境差、インフラ負荷などが失敗原因になりやすく、fix skill が役立ちます。
汎用プロンプトより役立つ理由
一般的なデバッグ用プロンプトは、すぐにコード修正へ飛びがちです。fix skill は、まず再現し、失敗が消えるなら burn-in を行い、trace を取得し、そのうえで症状をカテゴリに対応づける、という順序を強制します。付属の flaky-taxonomy.md には、診断の分岐と修正パターンが具体的にまとめられています。たとえば、await の不足、共有状態、CI のみで発生する viewport/font/timezone 差、ブラウザクラッシュ、worker 起因の不安定さなどを扱います。
インストール前に知っておきたい制約
これは万能のバグ修正ツールではありません。対象は Playwright テストに限定されており、エージェントがテストファイルを確認し、Playwright コマンドを実行し、trace、スクリーンショット、ログ、CI の失敗メッセージなどの出力を読めることを前提にしています。補助スクリプトは含まれていないため、価値の中心は自動化ではなく、ワークフローと taxonomy にあります。
fix skill の使い方
fix のインストールと最初に確認するファイル
互換性のある skills 環境で、次のコマンドを使ってインストールします。
npx skills add alirezarezvani/claude-skills --skill fix
インストール後は、まず SKILL.md を読んで実行ワークフローを確認し、次に flaky-taxonomy.md を開いて判断ツリーとよくある修正方法を確認してください。リポジトリ内のパスは engineering-team/playwright-pro/skills/fix です。有用なソースファイルは意図的に小さくまとめられており、設定すべき隠しスクリプト、ルール、メタデータファイルはありません。
fix skill に渡すとよい入力
良い結果を得るには、少なくとも次のいずれかを提供してください。
e2e/login.spec.tsのようなテストファイルパス- 正確なテスト名、または
--grepに渡す文字列 - 失敗メッセージ、スタックトレース、アサーションエラー
- 失敗がローカルで起きるのか、CI で起きるのか、または両方か
- 単体では通るが、フルスイートでは失敗するか
- 利用可能であれば trace、スクリーンショット、動画、CI artifact のパス
- 関連する Playwright 設定。特に workers、retries、projects、viewport、timezone、base URL
弱いプロンプト: “Fix my flaky checkout test.”
より良いプロンプト: “Use the fix skill for Debugging e2e/checkout.spec.ts, test should submit paid order. It passes locally alone, fails in CI about 30% of runs, and the failure is Timeout 5000ms exceeded waiting for getByRole('button', { name: 'Pay' }). CI uses 4 workers and retries=2. Suggest the reproduction commands, likely category, and minimal code/config changes.”
実践的な fix の利用ワークフロー
まず、失敗している正確なファイルから始めます。
npx playwright test <file> --reporter=list
通る場合は、不安定なテストの可能性があるため burn-in を実行します。
npx playwright test <file> --repeat-each=10 --reporter=list
並列実行時だけ問題が出る場合は、parallelism を有効にして実行します。
npx playwright test --fully-parallel --workers=4 --repeat-each=5
次に、trace の証拠を取得します。
npx playwright test <file> --trace=on --retries=0
コードを編集する前に、エージェントへ失敗の分類を依頼してください。想定されるカテゴリは、timing/async、test isolation、environment、infrastructure です。これにより、安易に waitForTimeout を追加する、グローバル timeout を引き上げる、実際の race condition を retries で隠す、といったよくない修正を避けられます。
良い結果を得るためのプロンプト例
証拠と依頼内容を分けたプロンプトにします。
“Use the fix skill. Diagnose before changing code. Test: <file> / <test name>. Reproduction result: <passes/fails command>. CI/local behavior: <details>. Trace or screenshot: <path or summary>. Current suspicion: <optional>. Please categorize using flaky-taxonomy.md, explain the evidence, propose the smallest safe fix, and list the command to verify it.”
この構成にすると、推測ベースのパッチではなく、検証可能なデバッグ計画を出しやすくなります。
fix skill FAQ
fix は flaky test 専用ですか？
いいえ。fix skill は、常に失敗する Playwright テストと、断続的に失敗するテストの両方を扱えます。決定的に失敗するケースでも、再現と trace 取得から始めます。断続的な失敗では、timing、isolation、infrastructure のパターンを明らかにするために、burn-in や parallel-worker の確認を追加します。
この skill を使わないほうがよい場面は？
unit test、backend integration test、Playwright のカバレッジがない本番バグ、広範なアプリケーション設計のデバッグを主目的にする場合は、この skill をメインの道具として使うべきではありません。一般的なヒントが得られることはありますが、コマンド、taxonomy、例は Playwright の end-to-end テスト向けに書かれています。
Playwright trace viewer だけを使う場合と何が違いますか？
trace viewer は「何が起きたか」を見せてくれます。fix skill は、その trace が何を意味するのかを判断する助けになります。たとえば、要素が見つからない原因は、async race、前のテストから漏れた状態、CI の viewport 差、ネットワーク依存など、複数考えられます。taxonomy は artifact を診断の道筋と修正タイプへつなげます。
fix は初心者にも使いやすいですか？
はい。Playwright コマンドを実行し、エラーを共有できるユーザーであれば使いやすい構成です。初心者にとっては、明確なコマンド順序とカテゴリ表が特に役立ちます。ただし、基本的なプロジェクト設定の知識を置き換えるものではありません。Playwright はすでにインストール済みで、テストスイートが実行可能であり、artifact にアクセスできる必要があります。
fix skill を改善する方法
fix により強い失敗証拠を渡す
最も重要な改善は、入力の質を上げることです。すでに試した正確なコマンドと、その結果を含めてください。“Fails in CI” よりも、“fails in CI with 4 workers, passes locally with one worker, fails locally with --fully-parallel --workers=4 --repeat-each=5” のほうがはるかに有用です。この一点だけで、一般的な timing 問題ではなく、isolation や parallelism の可能性に絞り込めます。
よくあるデバッグの失敗パターンを避ける
診断の前にパッチを求めないでください。よくない結果として、固定 sleep の追加、グローバル timeout の引き上げ、retries の増加、原因を確認しない selector の書き換えなどがあります。コード編集の前に、カテゴリ、証拠、最小限の修正、検証コマンドを skill に明示させてください。
最初の修正後に反復する
提案された変更を適用したら、意味のある最小の検証コマンドを再実行します。timing を対象にした修正なら burn-in を使います。isolation を対象にした修正なら、単体テスト実行とスイート実行の挙動を比較します。CI environment を対象にした修正なら、Docker、workers、timezone、viewport、mocked network services など、CI に近い設定で再現してください。
自分のプロジェクト向けに fix ガイドを拡張する
チームは、skill のワークフロー付近にプロジェクト固有のメモを追加することで、ローカルでの結果を改善できます。たとえば、一般的な CI 設定、既知の flaky services、必要な test data resets、標準 fixtures、mock strategy、推奨 locator conventions などです。fix skill は、taxonomy とリポジトリ固有の実際の失敗パターンを組み合わせたときに最も効果を発揮します。