testplane-skill

Testplane スキル

Testplane は Mocha と WebdriverIO を基盤とするブラウザー自動化・テストランナーです。このスキルを使って、実際のブラウザー状態を調査し、失敗したレポートをデバッグし、プロジェクトの規約に沿って Testplane テストを作成または修正します。

初期化

このスキルのコマンドを実行する前に、この SKILL.md があるディレクトリを特定し、$SKILL_DIR として使用してください。

初回のみのセットアップ：

cd $SKILL_DIR && npm run setup

簡易チェック：

node $SKILL_DIR/scripts/index.js

インストール済みパッケージを再利用できるよう、可能な場合は $SKILL_DIR から @testplane/cli を実行してください。

cd $SKILL_DIR && npx @testplane/cli --help

基本ルール

• プロジェクトに既存のスクリプト、設定、ヘルパー、ページオブジェクト、フィクスチャ、カスタムコマンドがある場合は、そちらを優先してください。
• 推測したセレクターより、アプリやレポートから見つけた実際のセレクターを優先してください。
• 安定したセレクターを優先してください。テスト ID／データ属性、セマンティックセレクター、安定した ID／名前の順に使用し、その後に CSS を代替として使ってください。
• スクリーンショットより @testplane/cli snapshot を優先してください。スクリーンショットは視覚的な証拠が必要な場合にのみ使用してください。
• テスト修正に browser.pause() を使用しないでください。具体的なページ状態、テキスト、URL、要素の表示／存在、またはアプリ固有の結果を待機してください。
• ユーザーから明示的に提供されない限り、シークレット、認証情報、.env ファイル、生の Cookie、トークン、非公開の認証情報を読み取らないでください。既存の認証ヘルパーまたはブラウザー状態ファイルを使用してください。
• ユーザーが Testplane HTML レポートのパスまたは URL を提示した場合は、テストを変更する前にレポートを調査してください。
• コマンドの構文が不明な場合は、npx @testplane/cli --help または npx @testplane/cli <command> --help を実行してください。

@testplane/cli を使ったブラウザーの調査

アプリのレンダリング内容の確認、セレクターの特定、認証状態の検証、またはテストの作成／修正前の動作把握が必要な場合に使用してください。

cd $SKILL_DIR
npx @testplane/cli navigate http://localhost:3000
npx @testplane/cli click --role button --name "Save"
npx @testplane/cli snapshot

便利なコマンド：

• navigate <url> --timeout 60000：必要に応じてブラウザーを自動起動し、ページを開きます。
• snapshot：簡潔な DOM スナップショットを取得します。大きなスナップショットは一時ファイルに保存されます。
• click、hover、type、select、wait：実際の要素を操作します。
• console：Chromium ベースのセッションで、未確認のブラウザーコンソールメッセージを読み取ります。
• run-code：組み込みコマンドでは対応できない場合に Testplane／WebdriverIO コードを実行します。
• list-tabs、new-tab、switch-tab、close-tab：タブを操作します。
• attach --session <json>：--keep-browser を指定して Testplane を実行した後に出力されるブラウザー JSON に接続します。
• --session-name <name>：フローごとに別々のブラウザーセッションを保持します。

調査の手順：

1. 関連するブラウザー状態に移動するか、接続します。
2. 対象を絞った操作を 1 つ実行します。
3. 意味のある状態変化の後にスナップショットを取得します。
4. テストでは、見つかったセレクターと画面上の動作を使用します。

カスタムのブラウザー設定が必要な場合を除き、launch は避けてください。navigate などの通常のコマンドはブラウザーを自動起動します。

Testplane レポートからのデバッグ

ユーザーからローカルまたはリモートの Testplane HTML レポートが提示された場合は、まずこのワークフローを使用してください。リモートレポートの URL は CLI によって自動的にダウンロードされ、キャッシュされます。

cd $SKILL_DIR
npx @testplane/cli test-results <report> --status failed --fields name,status,browser,attempt,duration,file,error
npx @testplane/cli inspect-result <report> --name "full test name" --browser chrome --attempt 0

レポートのワークフロー：

1. test-results で失敗を一覧表示します。必要に応じて --grep、--browser、--duration、--grep-error、--meta key=value、または --file を追加します。
2. 正確な name、browser、必要に応じて attempt を指定して inspect-result を使い、具体的な結果を調査します。
3. コードを編集する前に、ステータス、エラー、ステップ、メタデータ、画像、添付ファイルを確認します。
4. 結果に Time Travel スナップショットの添付ファイルがある場合は、time-travel-snapshot で調査します。
5. その後で、問題がテストコード、アプリの動作、認証／環境、タイミング、または視覚的なベースラインデータのいずれにあるかを判断します。

結果が大量にある場合は、構造化された JSON を保存します。

npx @testplane/cli test-results <report> --status failed --save-json

タイムトラベルのスナップショットを調べる

レポートに Testplane Time Travel のデータが含まれている場合、またはユーザーからスナップショットの zip が提供された場合は、time-travel-snapshot を使用します。rrweb の記録を再生し、指定した時刻の DOM スナップショットを返します。

npx @testplane/cli time-travel-snapshot <report> \
  --name "full test name" \
  --browser chrome \
  --attempt 0 \
  --time 1400

ヒント：

• 出力にはオフセット付きのテスト手順が一覧表示されます。これらのオフセットを --time の値として使用します。
• --diff-from <time> を使用すると、2 つの時点を比較し、変更された DOM ノードに絞り込めます。
• デフォルトのスナップショットでは有用な詳細が省略されている場合は、--include-attrs data-qa href class または --max-text-length 200 を使用します。
• スナップショットを直接調べる場合は、--snapshot-file /path/to/snapshot.zip --time 100 を使用します。

テスト中にブラウザーが壊れた状態に達し、ライブセッションが終了した場合に特に役立ちます。

Testplane REPL でデバッグする

実行中のテストによってブラウザーがすでに調査したい状態になっている場合は、REPL モードが便利です。プロジェクトのランタイム内で操作できるため、エージェントは生のセレクターから動作を組み立て直すのではなく、既存のページオブジェクト、カスタムコマンド、フィクスチャ、ヘルパーを利用できます。

既存の Testplane REPL セッションに接続します。

cd $SKILL_DIR
npx @testplane/cli attach-repl --port 4444

現在、REPL セッションでサポートされている CLI 操作は 2 つだけです。

npx @testplane/cli snapshot
npx @testplane/cli run-code "await browser.getUrl()"

テストプロセスですでに読み込まれているヘルパーを呼び出すなど、プロジェクト固有のスニペットには run-code を使用します。click、type、wait などのその他の操作コマンドは、まだ REPL モードではサポートされていません。

認証を安全に扱う

既存のログインヘルパーまたはフィクスチャを優先して使用します。再利用可能なブラウザー状態が必要な場合は、シークレットを読み取るのではなく、save-state と restore-state を使用します。

cd $SKILL_DIR
npx @testplane/cli save-state ./tmp/auth-state.json
npx @testplane/cli restore-state ./tmp/auth-state.json

注意：

• 状態には Cookie、localStorage、sessionStorage が含まれる場合があります。
• コマンドの出力には件数が表示され、Cookie の値は表示されません。
• 保存されたファイルには実際の認証情報が含まれる可能性があります。ユーザーから明示的に求められない限り、内容を出力、コミット、確認しないでください。
• 必要なものだけを保存するには、--cookies false、--local-storage false、--session-storage false などのオプションを使用します。
• restore-state はデフォルトでページを更新するため、アプリのコードから復元された状態を認識できます。

既存のテストを実行して修正する

再現可能な範囲が最小となるコマンドを使用します。

npx testplane --grep "Check search field presence"
npx testplane tests/login.testplane.ts

package.json にスクリプトがある場合は、そちらを優先します。

npm run test:e2e -- --grep "Check search field presence"

チェックリスト：

1. 問題を再現する最小のコマンドを見つけます。
2. テストと、近くにあるヘルパー、ページオブジェクト、フィクスチャを読みます。
3. レポートがある場合は、まずそれを調べます。
4. ブラウザーの動作が不明な場合は、CLI のスナップショットまたは REPL を使用します。
5. スリープや推測したセレクターを、明示的な待機と特定済みのセレクターに置き換えます。
6. テストのバグ、アプリのバグ、ビジュアルベースラインの問題、認証状態、環境の問題を切り分けます。

テスト中にしかアプリが目的のページに到達しない場合は、利用可能であれば --keep-browser を付けて実行し、出力されたブラウザーセッション JSON に接続します。

npx @testplane/cli attach --session '{"sessionId":"...","capabilities":{...}}'
npx @testplane/cli snapshot

新しいテストを書く

最初から書き始める前に、可能な限り実際のアプリを調べます。

1. プロジェクトのスクリプト、設定、ブラウザーのセットアップ、ローカルアプリの起動方法を確認します。
2. @testplane/cli で対象のルートを開きます。
3. スナップショットを取得し、セレクターを慎重に選びます。
4. 既存のヘルパー、ページオブジェクト、認証、クリーンアップ、アサーションのパターンを再利用します。
5. 実装の詳細ではなく、ユーザーから確認できる結果を検証します。
6. 明示的な待機を使って、テストを決定的にします。

ビジュアルテスト：

• 動作がビジュアルに関する場合にのみ assertView を使用します。
• キャプチャの前に、アニメーション、読み込み状態、動的コンテンツを安定させます。
• ビジュアルのカバレッジが不要な場合は、DOM アサーションを優先します。