1# Debugging Frontend Pages by Using DevTools
2
3
4The **Web** component supports debugging of web frontend pages by using DevTools, a web frontend development and debugging tool that allows you to debug an application's frontend pages on a PC. Before you do this, use [setWebDebuggingAccess()](../reference/apis-arkweb/js-apis-webview.md#setwebdebuggingaccess) to enable frontend page debugging for the **Web** component and make sure the test device connected to the PC runs 4.1.0 or a later version.
5
6
7## Procedure
8
9### Enabling Web Debugging for Application Code
10
11Before debugging a web page, call the [setWebDebuggingAccess()](../reference/apis-arkweb/js-apis-webview.md#setwebdebuggingaccess) API to enable the web debugging function.
12If the web debugging function is not enabled, DevTools cannot detect the web page to be debugged.
13
141. Enable web frontend page debugging in the application code.
15
16   ```ts
17   // xxx.ets
18   import { webview } from '@kit.ArkWeb';
19
20   @Entry
21   @Component
22   struct WebComponent {
23     controller: webview.WebviewController = new webview.WebviewController();
24
25     aboutToAppear() {
26       // Enable web frontend page debugging.
27       webview.WebviewController.setWebDebuggingAccess(true);
28     }
29
30     build() {
31       Column() {
32         Web({ src: 'www.example.com', controller: this.controller })
33       }
34     }
35   }
36   ```
372. Declare the required permission in the **module.json5** file of the HAP module in the application project in DevEco Studio. For details, see [Declaring Permissions in the Configuration File](../security/AccessToken/declare-permissions.md).
38
39   ```
40   "requestPermissions":[
41      {
42        "name" : "ohos.permission.INTERNET"
43      }
44    ]
45   ```
46
47### Connecting the Device to a PC
48
49Connect the device to a PC and enable Developer mode for subsequent port forwarding operations.
50
511. Enable Developer mode and USB debugging on your device.
52
53   (1) Choose **Settings** > **System** and check whether **Developer options** is available. If not, go to **Settings** > **About** and touch the version number for seven consecutive times until the message "Enable developer mode?" is displayed. Touch **OK** and enter the PIN (if set). Then the device will automatically restart.
54
55   (2) Connect the device to the PC using a USB cable. Choose **Settings** > **System** > **Developer options** and enable USB debugging. In the displayed dialog box, touch **Allow**.
56
572. Run the hdc command to connect to the device.
58   Run the following command in the CLI to check whether hdc can discover the device.
59   ```shell
60   hdc list targets
61   ```
62   - If a device ID is returned, the device is connected.
63   ![hdc_list_targets_success](figures/devtools_resources_hdc_list_targets_success.png)
64   - If **[Empty]** is returned, the device is not found.
65   ![hdc_list_targets_empty](figures/devtools_resources_hdc_list_targets_empty.jpg)
66
673. Enter the hdc shell.
68   After hdc is connected to the device, run the following command to enter hdc shell.
69   ```shell
70   hdc shell
71   ```
72
73### Port Forwarding
74After the application code calls the **setWebDebuggingAccess** API to enable web debugging, the ArkWeb kernel starts a domain socket listener to enable DevTools to debug web pages.
75However, Chrome cannot directly access the domain socket on the device. Therefore, the domain socket on the device needs to be forwarded to the PC.
76
771. Run the following command in hdc shell to obtain the domain socket created by ArkWeb on the device.
78   ```shell
79   cat /proc/net/unix | grep devtools
80   ```
81   * If the preceding operations are correct, the domain socket port is displayed.
82   ![hdc_grep_devtools_38532](figures/devtools_resources_hdc_grep_devtools_38532.jpg)
83
84   * If it is not displayed, check the following items again.
85     (1) The web debugging function is enabled for the application.
86     (2) The application uses the **Web** component to load the web page.
87
882. Exit hdc shell, and run the following command to forward the obtained domain socket to TCP port 9222 of the PC.
89
90   ```shell
91   hdc fport tcp:9222 localabstract:webview_devtools_remote_38532
92   ```
93   > **NOTE**
94   >
95   > The number following **webview_devtools_remote_** indicates the process ID of the application where the **Web** component is located. The number is not fixed. Change the number to the obtained value.
96   > If the process ID of the application changes (for example, the application is restarted), forward the port again.
97
98   The following figure shows a successful forwarding.
99   ![hdc_fport_38532_success](figures/devtools_resources_hdc_fport_38532_success.jpg)
100
1013. Run the following command to check whether the port is successfully forwarded.
102   ```shell
103   hdc fport ls
104   ```
105   * If a port forwarding task is returned, the operation is successful.
106   ![hdc_fport_ls_38532](figures/devtools_resources_hdc_fport_ls_38532.png)
107   * If **[Empty]** is returned, the operation fails.
108   ![hdc_fport_ls_empty](figures/devtools_resources_hdc_fport_ls_empty.jpg)
109
110### Opening the Debugging Tool Page in Chrome
111  1. Input **chrome://inspect/\#devices** in the address box of Chrome on the PC and open the page.
112  2. Configure the Chrome debugging tool.
113     The web page to be debugged needs to be discovered from the local TCP port 9222. Therefore, ensure that **Discovery network targets** is selected. Then, configure the network.
114     (1) Click the **Configure** button.
115     (2) Add **localhost:9222** to **Target discovery settings**.
116
117     ![chrome_configure](figures/devtools_resources_chrome_configure.jpg)
118
119  3. To debug multiple applications at the same time, add multiple port numbers in **Configure** of the **Devices** option on the Chrome debugging tool page.
120
121     ![debug-effect](figures/debug-domains.png)
122
123### Waiting for the Page to Be Debugged
124
125  If the preceding steps are successful, the page to be debugged is displayed on the Chrome debugging page.
126  ![chrome_inspect](figures/devtools_resources_chrome_inspect.jpg)
127
128### Starting Web Page Debugging
129
130  ![debug-effect](figures/debug-effect.png)
131
132## Script
133### On Windows
134Copy the following information to create a .bat file, enable application debugging, and run the file.
135   ```
136   @echo off
137   setlocal enabledelayedexpansion
138
139   :: Initialize port number and PID list
140   set PORT=9222
141   set PID_LIST=
142
143   :: Get the list of all forwarded ports and PIDs
144   for /f "tokens=2,5 delims=:_" %%a in ('hdc fport ls') do (
145       if %%a gtr !PORT! (
146           set PORT=%%a
147       )
148       for /f "tokens=1 delims= " %%c in ("%%b") do (
149           set PID_LIST=!PID_LIST! %%c
150       )
151   )
152
153   :: Increment port number for next application
154   set temp_PORT=!PORT!
155   set /a temp_PORT+=1
156   set PORT=!temp_PORT!
157
158   :: Get the domain socket name of devtools
159   for /f "tokens=*" %%a in ('hdc shell "cat /proc/net/unix | grep devtools"') do (
160       set SOCKET_NAME=%%a
161
162       :: Extract process ID
163       for /f "delims=_ tokens=4" %%b in ("!SOCKET_NAME!") do set PID=%%b
164
165       :: Check if PID already has a mapping
166       echo !PID_LIST! | findstr /C:" !PID! " >nul
167       if errorlevel 1 (
168           :: Add mapping
169           hdc fport tcp:!PORT! localabstract:webview_devtools_remote_!PID!
170           if errorlevel 1 (
171               echo Error: Failed to add mapping.
172               pause
173               exit /b
174           )
175
176           :: Add PID to list and increment port number for next application
177           set PID_LIST=!PID_LIST! !PID!
178           set temp_PORT=!PORT!
179           set /a temp_PORT+=1
180           set PORT=!temp_PORT!
181       )
182   )
183
184   :: If no process ID was found, prompt the user to open debugging in their application code and provide the documentation link
185   if "!SOCKET_NAME!"=="" (
186       echo No process ID was found. Please open debugging in your application code using the corresponding interface. You can find the relevant documentation at this link: [https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/web/web-debugging-with-devtools.md]
187       pause
188       exit /b
189   )
190
191   :: Check mapping
192   hdc fport ls
193
194   echo.
195   echo Script executed successfully. Press any key to exit...
196   pause >nul
197
198   :: Try to open the page in Edge
199   start msedge chrome://inspect/#devices.com
200
201   :: If Edge is not available, then open the page in Chrome
202   if errorlevel 1 (
203       start chrome chrome://inspect/#devices.com
204   )
205
206   endlocal
207   ```
208### On Linux or macOS
209Copy the following information to create an .sh file. Note that you need to run the **chmod** command and convert the file format. Enable the application debugging and run the file.
210   ```
211   #!/bin/bash
212
213   # Get current fport rule list
214   CURRENT_FPORT_LIST=$(hdc fport ls)
215
216   # Delete the existing fport rule one by one
217   while IFS= read -r line; do
218       # Extract the taskline
219       IFS=' ' read -ra parts <<< "$line"
220       taskline="${parts[1]} ${parts[2]}"
221
222       # Delete the corresponding fport rule
223       echo "Removing forward rule for $taskline"
224       hdc fport rm $taskline
225       result=$?
226
227       if [ $result -eq 0 ]; then
228           echo "Remove forward rule success, taskline:$taskline"
229       else
230           echo "Failed to remove forward rule, taskline:$taskline"
231       fi
232
233   done <<< "$CURRENT_FPORT_LIST"
234
235   # Initial port number
236   INITIAL_PORT=9222
237
238   # Get the current port number, use initial port number if not set previously
239   CURRENT_PORT=${PORT:-$INITIAL_PORT}
240
241   # Get the list of all PIDs that match the condition
242   PID_LIST=$(hdc shell cat /proc/net/unix | grep webview_devtools_remote_ | awk -F '_' '{print $NF}')
243
244   if [ -z "$PID_LIST" ]; then
245       echo "Failed to retrieve PID from the device"
246       exit 1
247   fi
248
249   # Increment the port number
250   PORT=$CURRENT_PORT
251
252   # Forward ports for each application one by one
253   for PID in $PID_LIST; do
254       # Increment the port number
255       PORT=$((PORT + 1))
256
257       # Execute the hdc fport command
258       hdc fport tcp:$PORT localabstract:webview_devtools_remote_$PID
259
260       # Check if the command executed successfully
261       if [ $? -ne 0 ]; then
262           echo "Failed to execute hdc fport command"
263           exit 1
264       fi
265   done
266
267   # List all forwarded ports
268   hdc fport ls
269   ```
270
271## FAQs
272
273### What should I do if hdc cannot discover devices?
274**Symptom**
275
276   The device ID is not displayed after the following command is executed.
277   ```shell
278   hdc list targets
279   ```
280
281**Solution**
282
283  * Ensure that USB debugging is enabled on the device.
284  * Ensure that the device is connected to the PC.
285
286### What should I do if "unauthorized" is displayed in the hdc command output?
287**Symptom**
288
289   When the hdc command is executed, the system displays a message indicating that the device is "unauthorized".
290
291**Possible Causes**
292
293   The PC is not authorized to debug the device.
294
295**Solution**
296
297  When a device with USB debugging enabled is connected to an unauthorized PC, a dialog box is displayed, asking you whether to allow USB debugging. In this case, select **Allow**.
298
299### What should I do if the domain socket of DevTools cannot be found?
300**Symptom**
301
302   No result is displayed after the following command is executed in hdc shell.
303   ```shell
304   cat /proc/net/unix | grep devtools
305   ```
306
307**Solution**
308
309  * Ensure that the step of [Enabling Web Debugging for Application Code](#enabling-web-debugging-for-application-code) is performed.
310  * Ensure that the application uses the **Web** component to load the web page.
311
312### What should I do if port forwarding fails?
313**Symptom**
314
315   The configured forwarding task is not displayed after the following command is executed.
316   ```shell
317   hdc fport ls
318   ```
319
320**Solution**
321
322  * Ensure that the domain socket exists on the device.
323  * Ensure that **tcp:9222** on the PC is not occupied.
324    If **tcp:9222** is occupied, forward the domain socket to another TCP port that is not occupied, for example, **tcp:9223**.
325    If the domain socket is forwarded to a new TCP port, you need to change the port number in **Target discovery settings** of Chrome on the PC.
326
327### What should I do if the web page to be debugged cannot be found in Chrome on the PC after port forwarding is successful?
328**Symptom**
329
330  The web page to be debugged cannot be found in Chrome on the PC.
331
332**Possible Causes**
333
334The port forwarding may be invalid due to the following reasons:
335  * The device is disconnected from the PC. As a result, all forwarding tasks in hdc are cleared.
336  * The hdc service is restarted. As a result, all forwarding tasks in hdc are cleared.
337  * The process ID of the application on the device is changed (for example, the application is restarted). As a result, the previous forwarding tasks in hdc become invalid.
338  * Exceptions occur when multiple forwarding tasks are forwarded to the same port.
339
340**Solution**
341
342  * Ensure that the local **tcp:9222** (or other configured port) on the PC is not occupied.
343  * Ensure that the domain socket exists on the device.
344  * Ensure that the process ID in the domain socket name is the same as that of the application to be debugged.
345  * Delete unnecessary forwarding tasks from hdc.
346  * After the domain socket is successfully forwarded, open **http://localhost:9222/json** using the Chrome on the PC. Change **9222** in the URL to the actual TCP port number.
347
348    - If the web page is normally displayed, the port forwarding is successful. On the Chrome debugging page, perform the operation of [Waiting for the Page to Be Debugged](#waiting-for-the-page-to-be-debugged).
349    ![chrome_localhost](figures/devtools_resources_chrome_localhost.jpg)
350
351    - If an error page is displayed, port forwarding fails. For details about the solution, see [What should I do if port forwarding fails](#what-should-i-do-if-port-forwarding-fails).
352    ![chrome_localhost_refused](figures/devtools_resources_chrome_localhost_refused.jpg)
353
354  * If the **http://localhost:9222/json** page is normally displayed on Chrome, but the debugging target cannot be found on the Chrome debugging page, perform the following operations:
355    - Ensure that the port number in **Configure** on the Chrome debugging page is the same as the TCP port number specified for port forwarding.
356    - In this topic, the default TCP port number is **9222**.
357      If you use another TCP port number (for example, **9223**), change the TCP port number in [Port Forwarding](#port-forwarding) and [Opening the Debugging Tool Page in Chrome](#opening-the-debugging-tool-page-in-chrome).
358
359<!--no_check-->