Debugging JavaScript
On this page:
- Basic terms
- Starting a debugging session by opening an HTML file from WebStorm (local debugging)
- Starting a debugging session through a user-defined configuration (local debugging)
- Local debugging in Firefox
- Remote debugging
- Mapping
- Debugging asynchronous code
- Debugging workers
Basic terms
When an HTML file with injected JavaScript code is opened in the browser, the script execution starts and suspends on reaching the first breakpoint, whereupon you can analyze the suspended program, step through it, resume execution when ready, etc. This HTML file does not necessarily have to be the one that implements the starting page of the application.
Depending on the location of the application files, WebStorm distinguishes between local and remote debugging modes.
-
Local debugging. In this mode, the application files remain where they are in the WebStorm project on you machine.
WebStorm runs them on the built-in Web server with the root URL
http://localhost:<built-in server port>/<project root>
. The built-in server port (1024 or higher) is specified on the Data Views page of the Settings dialog box. A debugging session in this mode can be initiated in two ways:- Open the HTML file with the JavaScript injection to be tested and launch the temporary run/debug configuration that WebStorm has generated automatically. This approach it helpful when you do not need to debug the entire application but just one script.
- Create and launch a permanent debug configuration.
-
Remote debugging. In this mode, the application files are on an external web server
and you have their copies in a WebStorm project on your computer.
No matter, whether the web server itself is running on a physically remote host or on your machine,
application files deployed on it are treated as remote.
For details, see Working with Web Servers: Copying Files.
You can deploy the application files to a web server and launch the application yourself or debug an already running application.
When a remote HTML file with a JavaScript injection is opened, the debugger tells WebStorm the name of the currently processed file and the number of the line to be processed. WebStorm opens the local copy of this file and indicates the line with the provided number. This behaviour is enabled by specifying correspondence between files and folders on the server and their local copies. This correspondence is called mapping, it is set in the debug configuration.
A Remote debugging session can be initiated only through a permanent debug configuration that you have to define yourself manually.
WebStorm supports local and remote JavaScript debugging only in Google Chrome and other browsers of the Chrome family. In Firefox, remote debugging is not supported at all. Local debugging is supported for Firefox, version 36 an higher, through the Firefox Remote debug configuration.
Starting a debugging session by opening an HTML file from WebStorm (local debugging)
- Set the breakpoints in the JavaScript code, as required.
- Open the HTML file with the JavaScript injection to debug or select the HTML file in the Project view.
- On the context menu of the editor or the selection, choose Debug <file name>.
The automatically generated debug configuration starts a debugging session.
This configuration is temporary but you can save it later.
The file opens in the default browser and the Debug tool window appears.
- If you are using Chrome or Dartium, you need a Chrome extension. If the extension is not installed and activated in your browser, the Debug tool window shows a message with a link to the web store where the extension is available. Click the link and install the extension. For details, see Using JetBrains Chrome Extension.
- In the Debug tool window, proceed as usual: step through the program, stop and resume program execution, examine it when suspended, view actual HTML DOM, edit the code, etc.
Starting a debugging session through a user-defined configuration (local debugging)
- Set the breakpoints in the JavaScript code, as required.
-
Create a permanent debug configuration.
- On the main menu, choose .
- Click the Add New Configuration toolbar button , and choose JavaScript Debug on the context menu.
- In the Run/Debug Configuration: JavaScript Debug dialog box that opens, specify the following:
- Click OK to save the configuration settings.
-
Choose the newly created configuration in the Select run/debug configuration drop-down list on the tool bar
and click the Debug toolbar button .
The HTML file specified in the run configuration opens in the chosen browser and the Debug tool window appears.
- If you are using Chrome or Dartium, you need a Chrome extension. If the extension is not installed and activated in your browser, the Debug tool window shows a message with a link to the web store where the extension is available. Click the link and install the extension. For details, see Using JetBrains Chrome Extension.
- In the Debug tool window, proceed as usual: step through the program, stop and resume program execution, examine it when suspended, view actual HTML DOM, edit the code, etc.
Local debugging in Firefox
In Firefox, remote debugging is not supported at all. Local debugging is supported for Firefox, version 36 an higher, through the Firefox Remote debug configuration.
-
Enable debugging in Firefox:
- Open your Firefox browser, then open .
- In the Development Tools pane that opens, click Toolbox Options button on the toolbar and select the Enable remote debugging check box under Advanced Settings.
-
In the console at the bottom of the browser (the console appeared opened when you opened the Developer toolbar),
type
listen <port number>
. You can specify any port number, however it is recommended that you use 6000 and higher. Later you will specify this port number in the run configuration.
-
Create a run/debug configuration:
- Choose on the main menu. Alternatively, click Shift+Alt+F10 and select Edit Configuration from the pop-up menu.
- In the Edit Configuration dialog box that opens, click the Add New Configuration toolbar button , and choose Firefox Remote on the context menu. Do not feel mislead by the term Remote. In this context it reflects the technical details of the implementation.
-
In the Run/Debug Configuration: Firefox Remote dialog box that opens, specify the host where the application is running
(currently it is always
localhost
) and the port the debugger will listen to. It must be the port that you specified when enabling debugging in Firefox. The default value is 6000. - Click OK to save the configuration settings.
- Set the breakpoints where necessary.
- Open the HTML file with the related JavaScript code the editor or select it in the Project tool window, choose Open in Browser on the context menu of the selection, then choose Firefox. The browser opens showing the application after the code execution, that is, the breakpoints you set have no effect yet.
- Choose the newly created configuration in the Select run/debug configuration drop-down list on the toolbar and click the Debug toolbar button . In the dialog bo that opens, click OK to allow incoming connections. From the Choose Page to Debug pop-up list, choose the page with your application.
- Refresh the page with your application in Firefox: the page shows the results of code execution up to the first breakpoint.
- In the Debug tool window, proceed as usual: step through the program, stop and resume program execution, examine it when suspended, view actual HTML DOM, edit the code, etc.
Remote debugging
- Set the breakpoints in the JavaScript code, as required.
-
Create a permanent debug configuration.
- Choose on the main menu. Alternatively, click Shift+Alt+F10 and select Edit Configuration from the pop-up menu.
- In the Edit Configuration dialog box that opens, click the Add New Configuration toolbar button , and choose JavaScript Debug on the context menu.
-
In the Run/Debug Configuration: JavaScript Debug dialog box that opens, specify the following:
- The URL address of the HTML file that implements the page to start debugging from. This URL address should correspond with the server access configuration.
- Choose the browser to debug the application in (Chrome or another browser of the Chrome family).
- Optionally define mappings between local files and URL addresses of their copies on the server. These mappings are required only if the local folder structure under the project root differs from the folder structure on the server. If the structures are identical, WebStorm itself "retrieves" the paths to local files by parsing the URL addresses of their copies on the server.
-
Choose the newly created configuration in the Select run/debug configuration drop-down list on the tool bar
and click the Debug toolbar button .
The HTML file specified in the run configuration opens in the chosen browser and the Debug tool window appears.
- If you are using Chrome or Dartium, you need a Chrome extension. If the extension is not installed and activated in your browser, the Debug tool window shows a message with a link to the web store where the extension is available. Click the link and install the extension. For details, see Using JetBrains Chrome Extension.
- In the Debug tool window, proceed as usual: step through the program, stop and resume program execution, examine it when suspended, view actual HTML DOM, edit the code, etc.
Mapping
If you are using a third-party Web server (not the built-in WebStorm server) for debugging or you have defined several resource root folders in addition to the project root, you need to map files, folders, or the entire project folder to the files or folders on the server. When a remote HTML file with a JavaScript injection is opened, the debugger tells WebStorm the name of the currently processed file and the number of the line to be processed. WebStorm opens the local copy of this file and indicates the line with the provided number. This behaviour is enabled by specifying correspondence between files and folders on the server and their local copies. This correspondence is called mapping, it is set in the debug configuration.
To configure mappings:
- Choose on the main menu. Alternatively, click Shift+Alt+F10 and select Edit Configuration from the pop-up menu.
- In the Edit Configuration dialog box that opens, click the Add New Configuration toolbar button , and choose JavaScript Debug on the context menu.
- In the Run/Debug Configuration: JavaScript Debug dialog box that opens, map the files or folders or the entire project folder to URL addresses of files and folders on the server.
Debugging asynchronous code
WebStorm supports debugging asynchronous client-side JavaScript code, currently this functionality is available only in Chrome.
The asynchronous debugging mode is toggled through the Async check box on the tool bar of the Debugger tab in the Debug
tool window.
The check box is displayed only during a JavaScript debugging session.
-
When this check box is selected, WebStorm recognizes breakpoints inside asynchronous code and stops at them and lets you step into asynchronous code.
As soon as a breakpoint inside an asynchronous function is hit or you step into asynchronous code, a new element
Async call from <caller>
is added in the Frames pane of the Debugger tab. WebStorm displays a full call stack, including the caller and the entire way to the beginning of the asynchronous actions. - When the check box is cleared, WebStorm does not recognize and therefore skips breakpoints in the asynchronous code and does not allow you to step into it.
-
With the Async check box selected, the debugger will stop at line3(breakpont), then at line5(breakpoint). On clicking Step into,
the debugger will stop at line5 (on
function
), then will move to line6. - With the Async check box cleared, the debugger will stop at line3(breakpont), then at line5(breakpoint). On clicking Step into, the debugger will move to line9.
Debugging workers
WebStorm supports debugging Service Workers and Web Workers. WebStorm recognizes breakpoints in each worker and shows the debug data for it as a separate thread in the Frame pane on the Debugger tab of the Debug Tool Window.
Note that WebStorm can debug only dedicated workers, debugging for shared workers is currently no supported.
- Set the breakpoints in the Workers to debug.
- If you are using Service Workers, make sure the Allow unsigned requests check box on the Debugger page is selected. Otherwise your service workers may be unavailable during a debug session:
-
Create a JavaScript Debug run/debug configuration:
- Choose on the main menu. Alternatively, click Shift+Alt+F10 and select Edit Configuration from the pop-up menu.
- In the Edit Configuration dialog box that opens, click the Add New Configuration toolbar button , and choose JavaScript Debug on the context menu.
-
In the Run/Debug Configuration: JavaScript Debug dialog box that opens, specify the following:
- The URL address of the HTML file that implements the page to start debugging from. This URL address should correspond with the server access configuration.
- Choose the browser to debug the application in (Chrome or another browser of the Chrome family).
- Optionally define mappings between local files and URL addresses of their copies on the server. These mappings are required only if the local folder structure under the project root differs from the folder structure on the server. If the structures are identical, WebStorm itself "retrieves" the paths to local files by parsing the URL addresses of their copies on the server.
-
Choose the newly created configuration in the Select run/debug configuration drop-down list on the tool bar
and click the Debug toolbar button .
The HTML file specified in the run configuration opens in the chosen browser and the Debug tool window opens with the Frames drop-down list showing all the Workers:
To examine the data (variables, watches, etc.) for a Worker, select its thread in the list and view its data in the Variables and Debug Tool Window. Watches panes. When you select another Worker, the contents of the panes are updated accordingly.