appium-troubleshooting

Appium トラブルシューティングのワークフロー

トラブルシューティングの振り分けと引き継ぎ

各実行を UiAutomator2 または XCUITest に固定します。ドライバーが不明な場合は、先に機能またはドライバーを特定する Appium のログ行を取得してください。別のドライバーの場合は、ここで停止し、このリポジトリにはそのドライバー向けに実装されたトラブルシューティング手順がないことを報告してください。

証拠から前提条件、インストール、または doctor の失敗が特定された場合は、現在のトラブルシューティングの引き継ぎを完了し、該当するセットアップ Skill に進んでください。

• UiAutomator2：skills/setup-uiautomator2/SKILL.md
• XCUITest：skills/setup-xcuitest/SKILL.md

実機の署名、プロビジョニング、または WDA のデプロイについては、XCUITest のセットアップ Skill のみが次の手順を担い、 skills/xcuitest-real-device-config/SKILL.md に進みます。

必要な入力

失敗した正確なコマンドとエラー、ドライバー、対象プラットフォーム、グローバル appium モードまたは明示的に指定されたローカル npx appium モード、ホスト OS、デバイスまたはシミュレーターの状態、関連する機能、最近のサーバーまたはデバイスのログ、最小限の再現手順、およびチェックを再実行する権限を確認します。

判断ロジック

• UiAutomator2 のセッション開始、誤ったアクティビティ、早期切断、socket hang up、ヘルパーサーバー、または adb トランスポートの症状には、指定された UiAutomator2 のセッション開始リファレンスを使用します。
• UiAutomator2 のネイティブまたはハイブリッドのロケーターに関する症状には、指定された UiAutomator2 のロケーターリファレンスを使用します。
• XCUITest の WDA の起動、インストール、到達可能性、アプリの起動、またはデバイス／シミュレーターの状態に関する症状には、指定された XCUITest のトラブルシューティングリファレンスを使用します。
• XCUITest の要素検索またはロケーターに関する症状には、指定された XCUITest の要素検索とロケーターのリファレンスを併用します。
• 機能の値が疑わしい原因の一部である場合に限り、共有の capabilities Context を読み込みます。
• 該当する公式リファレンスで正確な症状を説明できない場合に限り、コミュニティ検索 Context を使用します。

ワークフローの概要

1. コマンドモードを一度だけ決定します。デフォルトではグローバル appium を使用します。ローカルモードを明示的に選択した場合は、プロジェクトのルートから実行し、Appium コマンドを npx --no-install appium に置き換えます。
2. 何かを変更する前に、正確なエラー、プラットフォーム、ドライバー、関連する機能、および最小限の再現手順を取得します。
3. 提供された Appium とドライバーのバージョンを記録します。バージョン、インストール済み一覧、接続、または doctor のチェックは、必要な証拠が不足している場合、または症状から実施が妥当な場合にのみ実行します。
4. 該当するドライバープロファイルと、選択した症状に関するリファレンスのみを読み込みます。再現手順の理解に役立つ場合に限り、該当する例も読み込みます。
5. 前提条件または doctor のチェックに失敗した場合は、詳細なトラブルシューティングに進む前に、該当ドライバー専用のセットアップ Skill に従います。
6. 修正を依頼された場合は、対象を絞った、元に戻せる変更を1つ適用し、失敗した最小限のコマンド、セッション開始、WDA チェック、またはロケーター検索を再実行します。診断のみを依頼された場合は、証拠に基づいて原因を特定した時点で停止し、次の対応として対象を絞った変更を提示します。
7. まず Appium とドライバーの公式ドキュメントを使用し、コミュニティの情報は検証済みの代替手段としてのみ使用します。

トラブルシューティングの安全性と承認に関する制約

• 対象を絞った証拠の収集と、元に戻せる最小限の変更から始めます。
• 広範囲のリセット、再インストール、デバイスの消去、署名の変更、信頼設定の変更、または無関係な機能の変更を行う前に承認を求めます。
• ローカルモードが明示的に要求されていない限り、グローバルのコマンドモードを維持します。
• グローバルとローカルのコマンドモードを分けて扱います。ローカルの Appium が見つからない場合は、npx によるパッケージのダウンロードを許可せず、その障害を報告します。
• インストール、特権、署名、信頼設定、またはプロビジョニングの変更に進む前に、セットアップまたは実機に関する承認要件を適用します。
• 成功とするには、症状が再現されるか、再チェックに合格する必要があります。証拠が不十分なままの場合は、仮説と、原因を判別するための次のチェックを報告します。

完了条件

修正依頼は、確認済みの修正後に失敗していたチェックが通過した場合に passed と報告します。それ以外の場合は、コマンドの証拠と具体的な次のアクションを添えて blocked と報告します。手動でのブロッカーを切り分けただけでは、失敗が修正されたことにはなりません。診断のみの依頼は、一致する証拠によって原因を特定し、状態を変更せずに最小限の修正案または原因を判別する次のチェックを報告した場合に完了とします。

証拠の範囲

選択したドライバーと症状の経路、コマンドと結果、変更内容、最小限の再チェック、およびドライバー固有のセットアップの続きについて報告します。任意の Doctor の警告はブロッカーではないものとして扱い、セットアップまたは実機に関する続きの作業は、引き続きワークフローの選択が必要な引き継ぎとして報告します。

自己改善プロンプト

最終回答の前に、不足している、曖昧な、古くなっている、または再試行の原因となるトラブルシューティング手順があれば、そのアセットのパスと修正案の文面を報告します。無関係なアセットは変更しません。

証拠

入力例：このサーバーログと必要な機能を使って、UiAutomator2 セッションが起動中に失敗する理由を診断してください。 修正を推奨する前に、ログ、機能、デバイスの状態、およびドライバー固有のチェックに照らして、疑われる失敗の種類を検証します。