arkweb-app-debug

name	arkweb-app-debug
description	Debug HarmonyOS ArkWeb applications using Chrome DevTools Protocol. Use when Claude needs to: (1) Start ArkWeb debugging sessions, (2) Connect Chrome DevTools to HarmonyOS apps via hdc, (3) Inspect webview elements, console, and network, (4) Test ArkWeb applications with Chrome DevTools MCP, (5) Troubleshoot webview debugging issues, or (6) Manage port forwarding and debugging sessions. Automatically detects project configuration, device connection, and debugging sockets. Works with ohos-app-build-debug skill for complete workflow.
allowed-tools	["Bash","Read","Glob","Grep"]

ArkWeb App Debug

When to Use This Skill

Use this skill when the user needs to debug HarmonyOS ArkWeb (webview) applications:

• Debugging: "Debug my webview", "Connect DevTools to app", "Inspect webview"
• Testing: "Test the web page", "Automate webview testing", "Check webview elements"
• Troubleshooting: "Webview not working", "Can't connect DevTools", "Socket not found"
• Inspection: "Show me webview console", "Inspect network requests", "Check web elements"

Quick Start

Start an ArkWeb debugging session:

# 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

Bundled Resources

This skill includes debugging scripts in scripts/:

Script	Purpose
start-debug.sh	Start debugging session (macOS/Linux, auto-configures environment)
start-debug.py	Start debugging session (cross-platform Python)
start-debug.bat	Start debugging session (Windows, auto-configures environment)

All scripts automatically:

• Detect DevEco Studio installation (via ohos-app-build-debug skill)
• Configure environment for hdc and other tools
• Find HarmonyOS project configuration
• Connect to device and create port forwarding
• Open Chrome DevTools on http://127.0.0.1:9222

For detailed documentation, see references/.

Common Workflows

Start Debugging Session

# 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

Integration with ohos-app-build-debug

For complete development workflow:

# 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 Automated Testing (with MCP)

When Chrome DevTools MCP is configured, Claude can automatically test webview functionality:

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

See references/mcp-guide.md for MCP setup and available tools.

How It Works

Automatic Detection

The debug scripts automatically:

1. Detect DevEco Studio: Uses ohos-app-build-debug skill to find DevEco Studio and configure hdc
2. Find Project: Searches upward for HarmonyOS project root (max 5 levels)
3. Read Configuration: Extracts package name from AppScope/app.json5
4. Connect Device: Uses hdc to connect to HarmonyOS device
5. Find Socket: Dynamically locates webview_devtools socket (handles PID changes)
6. Create Port Forward: Sets up port forwarding from device to localhost:9222
7. Open DevTools: Launches Chrome/Chromium with DevTools

Critical Timing

Based on real debugging experience:

• After app start: Wait 10 seconds for Web component to create debugging socket
• After port forward: Wait 2 seconds for socket initialization
• Socket finding: Retry every 2 seconds for up to 15 seconds

The scripts handle these timings automatically.

Response Guidelines

When helping users with ArkWeb debugging:

1. Check Environment First

   • Verify hdc is available (should be auto-detected by scripts)
   • Check device connection: hdc list targets
   • Ensure app has setWebDebuggingAccess(true) in aboutToAppear()

2. Use Scripts

   • Call scripts in scripts/ directory
   • Replace $SKILL_DIR with actual skill installation path
   • Replace $OHOS_SKILL_DIR with ohos-app-build-debug skill path

3. Handle Common Issues

   • Socket not found: Wait 10-15s for app initialization, ensure Web component rendered
   • Port in use: Previous session may be running, check with hdc fport list
   • Device not found: Check USB connection and authorization
   • hdc not found: Scripts should auto-detect via ohos-app-build-debug

4. Coordinate with ohos-app-build-debug

   • For build/install issues, use ohos-app-build-debug skill
   • This skill focuses on debugging only

5. Show Actual Commands

   • Display the hdc commands being executed for transparency
   • Show port forwarding setup
   • Indicate DevTools URL

Application Requirements

ArkWeb applications must enable debugging in 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 })
  }
}

Error Handling

If DevEco Studio/hdc is not detected:

• Verify DevEco Studio is installed
• Ensure ohos-app-build-debug skill is available
• Scripts will attempt to auto-configure environment

If device is not connected:

• Check USB cable connection
• Verify USB debugging is enabled on device
• Authorize USB debugging on device when prompted

If socket is not found:

• Ensure app has setWebDebuggingAccess(true) in code
• Wait 10-15 seconds for app to fully initialize
• Verify Web component has rendered (navigate to a URL)
• Check if app crashed: hdc shell ps -A | grep <package>

For detailed troubleshooting, see references/troubleshooting.md.

Prerequisites

• DevEco Studio 3.1+ (4.0+ recommended) OR hdc in PATH
• HarmonyOS device with USB debugging enabled
• ArkWeb app with setWebDebuggingAccess(true) enabled
• Python 3.8+ (for start-debug.py script)
• Chrome/Chromium browser (for DevTools)

Optional: Chrome DevTools MCP for AI automated testing

Download DevEco Studio: https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-download