arkweb-app-debug

ArkWeb アプリのデバッグ

このスキルを使用する場面

ユーザーが HarmonyOS の ArkWeb（WebView）アプリケーションをデバッグする必要がある場合に、このスキルを使用します。

• デバッグ：「WebView をデバッグして」「DevTools をアプリに接続して」「WebView を検証して」
• テスト：「Web ページをテストして」「WebView のテストを自動化して」「WebView の要素を確認して」
• トラブルシューティング：「WebView が動作しない」「DevTools に接続できない」「ソケットが見つからない」
• 検証：「WebView のコンソールを表示して」「ネットワークリクエストを検証して」「Web 要素を確認して」

クイックスタート

ArkWeb のデバッグセッションを開始します。

# Using the debug script (auto-configures environment)
$SKILL_DIR/scripts/start-debug.sh

# Or with explicit package name
$SKILL_DIR/scripts/start-debug.sh --package com.example.app

同梱リソース

このスキルには、scripts/ 内にデバッグスクリプトが含まれています。

スクリプト	目的
start-debug.sh	デバッグセッションを開始します（macOS/Linux、環境を自動設定）
start-debug.py	デバッグセッションを開始します（クロスプラットフォームの Python）
start-debug.bat	デバッグセッションを開始します（Windows、環境を自動設定）

すべてのスクリプトは、以下を自動的に行います。

• DevEco Studio のインストールを検出します（ohos-app-build-debug スキルを使用）
• hdc およびその他のツールの環境を設定します
• HarmonyOS プロジェクトの設定を検索します
• デバイスに接続し、ポートフォワーディングを作成します
• http://127.0.0.1:9222 で Chrome DevTools を開きます

詳しいドキュメントについては、references/ を参照してください。

よくあるワークフロー

デバッグセッションを開始する

# Run the debug script from your HarmonyOS project directory
cd /path/to/harmonyos/project
$SKILL_DIR/scripts/start-debug.sh

# The script automatically:
# - Detects project configuration (package name, HAP path)
# - Connects to device
# - Creates port forwarding to webview_devtools socket
# - Opens Chrome DevTools

ohos-app-build-debug との連携

開発ワークフロー全体は次のとおりです。

# 1. Build and install app (using ohos-app-build-debug skill)
$OHOS_SKILL_DIR/scripts/build.py
$OHOS_SKILL_DIR/scripts/install.py -f entry/build/default/outputs/default/entry-default-signed.hap
$OHOS_SKILL_DIR/scripts/launch.py

# 2. Start debugging (this skill)
$SKILL_DIR/scripts/start-debug.sh

AI による自動テスト（MCP を使用）

Chrome DevTools MCP が設定されている場合、Claude は WebView の機能を自動的にテストできます。

User: Please test the login functionality in my webview
Claude: (Automatically uses Chrome DevTools MCP)
  - Opens DevTools connection
  - Navigates to login page
  - Fills out form
  - Submits and verifies results

MCP の設定と利用可能なツールについては、references/mcp-guide.md を参照してください。

仕組み

自動検出

デバッグスクリプトは、以下を自動的に行います。

1. DevEco Studio の検出：ohos-app-build-debug スキルを使用して DevEco Studio を検索し、hdc を設定します
2. プロジェクトの検索：HarmonyOS プロジェクトのルートを上方向に検索します（最大 5 階層）
3. 設定の読み取り：AppScope/app.json5 からパッケージ名を抽出します
4. デバイスへの接続：hdc を使用して HarmonyOS デバイスに接続します
5. ソケットの検索：webview_devtools ソケットを動的に特定します（PID の変更に対応）
6. ポートフォワーディングの作成：デバイスから localhost:9222 へのポートフォワーディングを設定します
7. DevTools を開く：DevTools を備えた Chrome/Chromium を起動します

重要なタイミング

実際のデバッグ経験に基づく目安です。

• アプリの起動後：Web コンポーネントがデバッグソケットを作成するまで 10 秒待ちます
• ポートフォワーディング後：ソケットの初期化に 2 秒待ちます
• ソケットの検索：最大 15 秒間、2 秒ごとに再試行します

スクリプトはこれらの待機時間を自動的に処理します。

応答ガイドライン

ArkWeb のデバッグについてユーザーを支援する際は、以下に従ってください。

1. まず環境を確認する

   • hdc が利用可能であることを確認します（スクリプトが自動的に検出するはずです）
   • デバイスの接続を確認します：hdc list targets
   • aboutToAppear() に setWebDebuggingAccess(true) が設定されていることを確認します

2. スクリプトを使用する

   • scripts/ ディレクトリ内のスクリプトを呼び出します
   • $SKILL_DIR を実際のスキルのインストールパスに置き換えます
   • $OHOS_SKILL_DIR を ohos-app-build-debug スキルのパスに置き換えます

3. よくある問題に対処する

   • ソケットが見つからない：アプリの初期化に 10～15 秒待ち、Web コンポーネントがレンダリングされていることを確認します
   • ポートが使用中：前のセッションが実行中の可能性があります。hdc fport list で確認します
   • デバイスが見つからない：USB 接続と認証を確認します
   • hdc が見つからない：スクリプトは ohos-app-build-debug 経由で自動的に検出するはずです

4. ohos-app-build-debug と連携する

   • ビルド／インストールの問題には、ohos-app-build-debug スキルを使用します
   • このスキルはデバッグのみに特化しています

5. 実際のコマンドを表示する

   • 透明性を確保するため、実行中の hdc コマンドを表示します
   • ポートフォワーディングの設定を表示します
   • DevTools の URL を示します

アプリケーションの要件

ArkWeb アプリケーションでは、aboutToAppear() 内でデバッグを有効にする必要があります。

import { webview } from '@kit.ArkWeb';

@Entry
@Component
struct Index {
  controller: webview.WebviewController = new webview.WebviewController();

  aboutToAppear() {
    // CRITICAL: Enable debugging BEFORE Web component renders
    webview.WebviewController.setWebDebuggingAccess(true);
  }

  build() {
    Web({ src: this.currentUrl, controller: this.controller })
  }
}

エラー処理

DevEco Studio／hdc が検出されない場合：

• DevEco Studio がインストールされていることを確認してください
• ohos-app-build-debug スキルが利用可能であることを確認してください
• スクリプトは環境の自動設定を試みます

デバイスが接続されていない場合：

• USB ケーブルの接続を確認してください
• デバイスで USB デバッグが有効になっていることを確認してください
• プロンプトが表示されたら、デバイスで USB デバッグを許可してください

ソケットが見つからない場合：

• コードに setWebDebuggingAccess(true) が含まれていることを確認してください
• アプリが完全に初期化されるまで 10～15 秒待ってください
• Web コンポーネントがレンダリングされていることを確認してください（URL に移動します）
• アプリがクラッシュしていないか確認してください：hdc shell ps -A | grep <package>

詳細なトラブルシューティングについては、references/troubleshooting.md を参照してください。

前提条件

• DevEco Studio 3.1 以降（4.0 以降を推奨）、または PATH に hdc が設定されていること
• USB デバッグが有効な HarmonyOS デバイス
• setWebDebuggingAccess(true) が有効になっている ArkWeb アプリ
• Python 3.8 以降（start-debug.py スクリプト用）
• Chrome／Chromium ブラウザー（DevTools 用）

オプション：AI 自動テスト用の Chrome DevTools MCP

DevEco Studio のダウンロード：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-download