openharmonyinsight/arkweb-app-debug

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