playwright

playwright skill の概要

この skill でできること

playwright skill は、playwright-cli を使ってターミナルから実ブラウザを操作するための skill です。特に、ナビゲーション、フォーム入力、スクリーンショット、スナップショット、抽出、UI フローのデバッグが必要な場面で力を発揮します。これはテストスイート作成向けではなく、ブラウザ自動化向けに設計されており、Playwright がグローバルに入っていない環境でも動かせるラッパースクリプトを備えた CLI ファーストのワークフローを採用しています。

どんな人に向いているか

手作業で本格的な自動化スタックを組まずに、信頼できるブラウザ操作をしたいなら playwright skill を入れる価値があります。ライブページの確認、ユーザーフローの再現、ページ内容の収集、UI の挙動を再現性のある形でデバッグしたいエージェントに適しています。

何が最も重要か

この skill の最大の差別化ポイントは、ラッパーベースのワークフローです。npx を確認し、skill のパスを一度設定すれば、PWCLI 経由で playwright-cli コマンドを使えます。セットアップの手間が減るため、特にブラウザ作業が複雑だったり、UI が頻繁に変わったりする場面で、アドホックな自動化に実用的です。

playwright skill の使い方

インストールして skill のパスを設定する

まずは skill のインストール手順を実行します。

npx skills add openai/skills --skill playwright

そのあと、シェルセッションまたはプロファイルで一度だけパスを設定します。

export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
export PWCLI="$CODEX_HOME/skills/playwright/scripts/playwright_cli.sh"

それ以外の作業を始める前に、npx が使えるか確認してください。使えない場合は、先に Node.js/npm をインストールします。ラッパーはそれに依存しています。

漠然とした目的を、よいプロンプトに変える

skill には、曖昧な依頼ではなく具体的なブラウザ作業を渡してください。よい入力には、対象サイト、実行したい操作、欲しい成果物が含まれます。

よいプロンプトの形:

• “Use playwright skill to log into the staging app, navigate to the invoices page, and capture a screenshot of the filtered table.”
• “Use playwright for Browser Automation to open this URL, extract the visible product names, and report any console warnings.”
• “Use playwright skill to reproduce this signup error and capture a trace plus the final page state.”

こうすることで、skill が適切なコマンド、スナップショット、デバッグ手順を選びやすくなります。

まず読むべきファイル

実運用では、まず以下から確認するのが実用的です。

• SKILL.md — 基本ワークフローと制約
• references/cli.md — コマンドの対応範囲
• references/workflows.md — 操作パターンとセッションの使い方
• scripts/playwright_cli.sh — ラッパーが npx をどう解決するかの確認

skill が自分の環境に合うか判断したい場合は、既定の意図を示す agents/openai.yaml と、来歴を確認できる NOTICE.txt も軽く目を通しておくとよいです。

実践的なワークフローのコツ

基本の流れは、ページを開く → snapshot を取る → 要素 ID を使って操作する → もう一度 snapshot して状態変化を確認する、です。フォーム操作では、入力欄が分かっているなら複数回のキー入力より fill を優先してください。デバッグでは、失敗の前後を console、network、tracing-start/tracing-stop で囲んで、推測ではなく証拠を取るのが有効です。

playwright skill FAQ

playwright は単なるプロンプトですか、それとも実際にインストールできるワークフローですか？

これは単なるプロンプト文ではなく、ラッパースクリプトと参照コマンドを備えた、実際にインストールできる playwright skill です。インストールすることで、再現可能なコマンド構成、セッション処理、予測しやすい入口が手に入る点が重要です。

どんなときに playwright を使わないほうがいいですか？

静的なコード生成、単純な HTTP リクエスト、テストランナーだけが必要なら使わないでください。さらに、環境で npx を提供できない場合も相性がよくありません。Node.js/npm が使えるようになるまでラッパーは停止します。

初心者でも使いやすいですか？

はい、ブラウザ作業で、ページとゴールを明確に説明できるなら使いやすいです。主な学習ポイントは Playwright の文法ではなく、具体的なブラウザの到達点を依頼し、その前にスナップショットを見て状況を確認することです。

@playwright/test とは何が違いますか？

CLI 主導のブラウザ自動化をしたいならこの skill を使います。テストファイル、アサーション、テストハーネスが明示的に必要なら @playwright/test を使ってください。この skill は、完全なテストプロジェクトではなく、対話的な利用とライブワークフローに最適化されています。

playwright skill を改善するには

初期状態をもっと具体的に伝える

より良い結果は、URL、ログイン状態、デバイスやビューポートの制約、返してほしい成果物を明示した入力から生まれます。認証が関わるなら、資格情報が既にあるのか、MFA が想定されるのか、ナビゲーション後で止めるのか送信まで進めるのかも伝えてください。

成功条件を正確に共有する

終了条件は具体的に書いてください。「モーダルが閉じたあとにスクリーンショットを保存」「表示されている最初の 20 行を抽出」「Checkout をクリックしたあとにコンソールエラーを報告」などです。これで不要な探索が減り、playwright の使い方がより決定的になります。

必要なデバッグ成果物を明示する

ワークフローが失敗しているなら、欲しい証拠を指定してください。構造確認には snapshot、見た目の状態にはスクリーンショット、操作タイミングには trace、実行時エラーには console/network 出力が役立ちます。漠然と「問題を直して」と頼むより、はるかに有用です。

よくある失敗を避ける

最も多いミスは、UI の経路を十分に指定せず、実装方法だけを細かく縛ることです。ページが変わりやすいなら、正確なクリック回数を要求しないでください。目的を伝え、現在のページ状態に応じたナビゲーションは skill に任せるほうがよいです。また、本当に @playwright/test が必要な場合を除き、ブラウザ自動化とテストスイート要件を混ぜないようにしてください。