WebStorm 2016.2 Help

Debugging JavaScript

On this page:

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.

  1. 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.
  2. 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)

  1. Set the breakpoints in the JavaScript code, as required.
  2. Open the HTML file with the JavaScript injection to debug or select the HTML file in the Project view.
  3. 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.

  4. 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.
  5. 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)

  1. Set the breakpoints in the JavaScript code, as required.
  2. Create a permanent debug configuration.
    1. On the main menu, choose Run | Edit Configurations.
    2. Click the Add New Configuration toolbar button add.png, and choose JavaScript Debug on the context menu.
    3. 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. Use the following format: http://localhost:<built-in server port>/<project root>/<path to the HTML file relative to the project root>
      • Choose the browser to debug the application in (Firefox or Chrome).
    4. Click OK to save the configuration settings.
  3. Choose the newly created configuration in the Select run/debug configuration drop-down list on the tool bar and click the Debug toolbar button debug.

    The HTML file specified in the run configuration opens in the chosen browser and the Debug tool window appears.

  4. 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.
  5. 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.

  1. Enable debugging in Firefox:
    1. Open your Firefox browser, then open Tools | Web Developer | Toggle Tools.
    2. In the Development Tools pane that opens, click Toolbox Options button cogwheel on the toolbar and select the Enable remote debugging check box under Advanced Settings.
      js_debugging_enable_debugging_in_ff_advanced_settings.png
    3. In the console at the bottom of the browser (the console appeared opened when you opened the Developer toolbar), type listen <port number>.
      js_debugging_enable_debugging_in_ff_console_listen.png
      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.
    If you completed the above mentioned steps successfully, a pop-up window with the following message is shown: Listening on port 6000.
  2. Create a run/debug configuration:
    1. Choose Run | Edit Configuration on the main menu. Alternatively, click Shift+Alt+F10 and select Edit Configuration from the pop-up menu.
    2. In the Edit Configuration dialog box that opens, click the Add New Configuration toolbar button add.png, 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.
    3. 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.
    4. Click OK to save the configuration settings.
  3. Set the breakpoints where necessary.
  4. 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.
  5. Choose the newly created configuration in the Select run/debug configuration drop-down list on the toolbar and click the Debug toolbar button debug. 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.
  6. Refresh the page with your application in Firefox: the page shows the results of code execution up to the first breakpoint.
  7. 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

  1. Set the breakpoints in the JavaScript code, as required.
  2. Create a permanent debug configuration.
    1. Choose Run | Edit Configuration on the main menu. Alternatively, click Shift+Alt+F10 and select Edit Configuration from the pop-up menu.
    2. In the Edit Configuration dialog box that opens, click the Add New Configuration toolbar button add.png, and choose JavaScript Debug on the context menu.
    3. 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.
      Click OK to save the configuration settings.
  3. Choose the newly created configuration in the Select run/debug configuration drop-down list on the tool bar and click the Debug toolbar button debug.

    The HTML file specified in the run configuration opens in the chosen browser and the Debug tool window appears.

  4. 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.
  5. 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:

  1. Choose Run | Edit Configuration on the main menu. Alternatively, click Shift+Alt+F10 and select Edit Configuration from the pop-up menu.
  2. In the Edit Configuration dialog box that opens, click the Add New Configuration toolbar button add.png, and choose JavaScript Debug on the context menu.
  3. 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.
The image below shows an example of a JavaScript debugging session.
ws_debug_tool_window_async.png
  • 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.

  1. Set the breakpoints in the Workers to debug.
  2. 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:
    ws_debug_service_workers.png
  3. Create a JavaScript Debug run/debug configuration:
    1. Choose Run | Edit Configuration on the main menu. Alternatively, click Shift+Alt+F10 and select Edit Configuration from the pop-up menu.
    2. In the Edit Configuration dialog box that opens, click the Add New Configuration toolbar button add.png, and choose JavaScript Debug on the context menu.
    3. 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.
      Click OK to save the configuration settings.
  4. Choose the newly created configuration in the Select run/debug configuration drop-down list on the tool bar and click the Debug toolbar button debug.

    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:

    ws_js_debug_workers_frames.png

    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.

See Also

Last modified: 15 November 2016