WebStorm 2017.2 Help

Trace Run Tab

The tab consists of a toolbar and three panes: Events Pane, Event Stack Pane, and Quick Evaluation Pane.

On this page:

Events Toolbar

Use the buttons on the toolbar to control the range of events to capture, configure their presentation, and navigate through the list of captured events.

ItemTooltip and shortcutDescription
expandAll Expand all Ctrl+NumPad Plus Click this button to have all the nodes in the list expanded.
collapseAll Collapse all Ctrl+NumPad - Click this button to have all the nodes in the list collapsed.
arrowUp Up the Stack Trace
Click this button to navigate to the previous traced page in the stack trace.
arrowDown Down the Stack Trace Click this button to navigate to the next traced page in the stack trace.
autoScrollToSource Autoscroll to source Press this toggle button to have the list in the Events pane automatically synchronized with the Editor.
  • When the button is pressed: as soon as you click an event in the Events pane, the details of the event are displayed in the Event Stack pane and the script that is invoked by the event is opened in the editor automatically.

    When you navigate through the Event Stack with the Autoscroll to Trace mode turned on, the corresponding files are also automatically opened in the editor with the calling functions highlighted.

  • When the button is released: the script that is invoked by the event is opened in the editor only upon double-clicking the event in the Event Stack pane.
iconFilter Capture Events Click this button to configure the range of events to be captured and shown in the Events list.

By default, the Spy-js tool captures all events on all opened Web pages, excluding https secure web sites, unless you have specified a URL address explicitly in the run configuration. The Events pane of the Spy-js tool window shows all captured events. If for some reasons you do not want to have all events captured, you can suppress capturing some of them by applying user-defined event filters. When you click iconFilter, the pop-up list shows all the available filters, the currently applied filter is marked with a tick. By default the Capture All predefined filter is applied.

To stop capturing events without stopping the application, choose Mute All. The application is still running but the Events pane shows the last captured event. This is helpful if you want to analyze a script and therefore need it to be displayed in the Events pane instead of being removed as new events are captured.

To define a custom event filter:

  1. Click iconFilter, and then choose Edit Capture Exclusions from the list.
  2. In the Spy-js Capture Exclusions Dialog that opens, click Add new on the left-hand pane.
  3. In the right-hand pane, specify the filter name in the Exclusion name field and configure a list of exclusion rules.

    To add a rule, click new, the Add Condition to Exclusion dialog box opens. Type a pattern in the Value/pattern text box, in theCondition type drop-down list specify whether the pattern should be applied to event types or script names. Note that glob pattern matching is used. When you click OK, WebStorm brings you to the Spy-js Capture Exclusions Dialog.

    To edit a rule, select it in the list, click edit1, and update the rule in the dialog box that opens. To remove a rule, select it in the list and click delete.

To activate a filter, set a tick next to the required filter in the list.

cogwheel blue with arrow Click this button to remove all or some events from tracing and have the corresponding trace files closed in the editor. Choose one of the following options on the drop-down list that is displayed:
  • Remove all: choose this option to cancel tracing of all captured events without closing the trace files in the editor.
  • Close all trace files: choose this option to have all trace files in the editor closed but keep tracing the corresponding event. To remove an event or script from tracing and close the corresponding trace files in the editor, choose Remove on the context menu of the event or script.
  • Remove all inactive: choose this option to remove all nodes for pages that are not active anymore (for example, because the pages have been closed in browser).
  • Save trace: choose this option to save an image of the current session. The .json files that store the calls and properties of the session are compressed into a zip archive. Upon request, when you choose Load trace, the .json files are extracted from the archive and loaded into Spy-js.
  • Load trace: choose this option to have a previously saved image of a tracing session loaded into Spy-js. The .json files that store the calls and properties of that session are extracted and imported.

    Note that a loaded image does not restore the session because no scripts are actually executed. All you can do is analyze the flow and properties of previously executed code.

  • Close all trace files on session stop: choose this option to have all trace files in the editor closed when you click the Stop button stop to stop the tracing session externally by means of the standard shutdown script.

    Clicking the button once invokes soft kill allowing the application to catch the SIGINT event and perform graceful termination (on Windows, the Ctrl+C event is emulated). After the button is clicked once, it is replaced with icon run tool window kill indicating that subsequent click will lead to force termination of the application, e.g. on Unix SIGKILL is sent.

  • Enable Spy-js autocomplete and magnifier: choose this option to have the basic completion list expanded with runtime data (Spy-js autocompletion) and to get the possibility to evaluate expressions without actually running a debugging session (Spy-js magnification). By default, the functionality is turned off.

    The term Spy-js autocompletion denotes expanding the basic completion list with suggestions retrieved from the runtime data. The Spy-js autocompletion functionality is available from source files for the code that has already been executed (highlighted green in the corresponding trace file).

    When you position the caret at a symbol in the source file and press Ctrl+Space, Spy-js retrieves data from the browser or from the running Node.js application and merges it with the basic completion list according to the following rules:

    1. If an object both is present on the basic completion list and is retrieved from the runtime, the variant that provides more information about parameters, attributes, their type, etc. remains on the list.
    2. Objects retrieved by Spy.js are shown on top of the list and marked with the icon_spy_js.png icon. If a retrieved object is specific for a browser, the object is marked with the icon_spy_js.png icon and with the icon of this browser.

    The term Spy-js magnification denotes evaluating expressions without actually running a debugging session. When you click the expression in question or position the caret at it and press Ctrl+Alt+F8, a tooltip is displayed below the expression showing the expression value. If Spy-js retrieves several values, click add icon in the tooltip to expand the list of values.

    The magnification functionality is available from source files for both executed and not yet executed code.

  • Spy-js supports source maps, which means that you can now jump from the Event Stack pane right to the original source code in ECMAScript 6, TypeScript or CoffeeScript and observe what code fragments were executed. Use the following options to configure the way source maps are treated:
    • Enable source map look-up: choose this option to enable navigation to the ECMAScript 6, TypeScript or CoffeeScript source code using the source maps generated during compilation.
    • Enable source map generation: choose this option to generate source maps for everything to map the instrumented code. Choose this option if you are going to debug the original code in Chrome Dev Tools or FireFox FireBug development tools.
    • Always open source mapped trace if available: choose this option to have Spy-js try to open the mapped trace file when you invoke navigation from an event to its caller.

Events Pane

The pane shows a tree of captured events. The top-level nodes represent documents that are Web pages involved in tracing. When you hover the mouse over a document, WebStorm displays a tooltip with the URL address of the document, the browser in which it is opened, and the operating system the browser is running on. The document node is also supplied with an icon that indicates the browser in which it is opened.

Under each document node, events detected on the page and scripts started from it are listed. Events of the same type are grouped into visual containers. The header of a container displays the name of the events grouped in it, the average execution time across all the events within the container, and the number of events inside the container. You can expand each node and inspect the individual events in it.

Script file names have different colour indicators to help distinguishing between them when working with the Event Stack pane. By hovering your mouse over a script file name, you can see the full script URL.

Once an event is clicked, its call stack is displayed in the Event Stack pane. The stack is represented by a tree of function calls.

Context Menu of a Document Node

Menu item Description
Remove Choose this option to cancel tracing all the scripts on the selected page and remove the selected node with all the items under it from the Events pane. All the currently opened trace files remain opened in the editor.
Remove all children Choose this option to delete the items under the selected page but keep tracing it so that new events from the page are still received. The document node itself remains in the Event pane, and all the currently opened trace files remain opened in the editor.
Remove and close trace file(s) Choose this option to cancel tracing all the scripts on the selected page, remove the selected node and all the items under it from the Events pane, and close the corresponding trace files in the editor.
Close trace file(s) Choose this option to close all the currently opened trace files that correspond to the selected document node and items under it. The document node and the items under it remain in the Events pane.
Refresh the page in browser Choose this option to reload the page that corresponds to the selected document node. Tracing of the selected node is abandoned, a new document node for tracing the same page is created, and the old node becomes inactive.
Try closing the page in browser Choose this option to close the page that corresponds to the selected node. Tracing of the selected node is abandoned, and the node becomes inactive.
Show application dependency diagram Choose this option to build a diagram with the dependencies within the entire application.
  • The diagram is opened in a separate editor tab. The nodes in the diagram represent your project files, while the edges represent the fact that there’s one or more functions in the source file that invoke functions in the target file.
  • To examine the details of a node or an edge, select the node or the edge in question and view its Details tree in a dedicated pane in the upper right-hand corner of the editor. The pane displays the connecting function combinations, along with event(s) the calls are made within and the number of calls made.

Context Menu of an Event or Script

Menu item Description
Mute event Choose this option to add an event to an exclusion filter on the fly.
Mute script Choose this option to add a script to an exclusion filter on the fly.
Remove Choose this option to cancel tracing the selected event or script, remove the selected item from the Events pane, but leave the corresponding trace files opened in the editor.
Add label Choose this option to set a timestamp label. Timestamp labels help you to analyze your code execution within a specific period of time. For example, you can set two timestamp labels and view which events were captured between them. Or on the contrary, you can locate the events that were not captured within a certain period of time although you expected them to be and thus detect performance problems.
Show event dependency diagram Choose this option to build a diagram with the dependencies in which the event selected event is involed.
  • The diagram is opened in a separate editor tab. The nodes in the diagram represent your project files, while the edges represent the fact that there’s one or more functions in the source file that invoke functions in the target file.
  • To examine the details of a node or an edge, select the node or the edge in question and view its Details tree in a dedicated pane in the upper right-hand corner of the editor. The pane displays the connecting function combinations, along with event(s) the calls are made within and the number of calls made.

Configuring the Range of Events to Capture

By default, the Spy-js tool captures all events on all opened Web pages, excluding https secure web sites, unless you have specified a URL address explicitly in the run configuration. The Events pane of the Spy-js tool window shows all captured events. If for some reasons you do not want to have all events captured, you can suppress capturing some of them by applying user-defined event filters. All the available filters are listed upon clicking the Capture Events button iconFilter on the toolbar, the currently applied filter is marked with a tick. By default the Capture All predefined filter is applied.

To stop capturing events without stopping the application, choose Mute All. The application is still running but the Events pane shows the last captured event. This is helpful if you want to analyze a script and therefore need it to be displayed in the Events pane instead of being removed as new events are captured.

You can define new custom filters or add event patterns to existing filters on the fly.

Defining a new event filter

  1. Click the Capture Events button iconFilter on the toolbar, and then choose Edit Capture Exclusions from the list.
  2. In the Spy-js Capture Exclusions Dialog that opens, click Add new on the left-hand pane.
  3. In the right-hand pane, specify the filter name in the Exclusion name field and configure a list of exclusion rules.

    To add a rule, click new, the Add Condition to Exclusion dialog box opens. Type a pattern in the Value/pattern text box, in theCondition type drop-down list specify whether the pattern should be applied to event types or script names. Note that glob pattern matching is used. When you click OK, WebStorm brings you to the Spy-js Capture Exclusions Dialog.

    To edit a rule, select it in the list, click edit1, and update the rule in the dialog box that opens. To remove a rule, select it in the list and click delete.

Activating a filter

  • Click iconFilter and set a tick next to the required filter in the list. If no filters are configured or none of the available filters fits the task, create a new filter as described above.

Adding an event to an exclusion filter on the fly

While navigating through the tree of already captured events in the Events pane, you may come across some events or scripts that you definitely do not want to trace. You can create a filter as described above but in this case you will have to leave the pane. With WebStorm, you can create an exclusion rule based on any event or script, as soon as you have detected such event or script, right from the Events pane. The rule will be either added to the currently applied filter or a new filter will be created if the current setting is Capture All.

  • To add an event to an exclusion filter on the fly, select the event to exclude and choose Mute <event name> event or Mute <script name> file.

    If a user-defined filter is currently applied, the new rule is added to it silently. If Capture All is currently active, the Spy-js Capture Exclusions Dialog opens, where you can create a new filter based on the selected event or script or choose an existing filter and add the new rule to it.

Event Stack Pane

Once an event in the Events pane is clicked, its call stack is displayed in the Event Stack pane. The stack is represented by a tree of function calls. Each tree node represents the invoked function. Node text contains the total execution time, the script file name and the function name. When you click a node, the Quick Evaluation pane shows additional function call details, parameter values and return value, occurred exception details if there was one during the function execution.

The pane is synchronized with the editor, so you can navigate from an item in the stack tree to the corresponding trace file or source file.

  • A trace file is a write-protected prettified version of the script selected in the Events pane or the script whose function is double clicked in the Event Stack pane. A trace file is named <file name>.js.trace. When you double click an item in the stack tree or select it and choose Jump to Trace on the context menu of the selection, the corresponding trace file opens in the editor with the cursor positioned at the clicked function. Another approach is to press the Autoscroll to Trace toggle button and select various stack nodes. In this case, the trace file opens when you click an event or script in the Events pane.

    You can not only jump to a function but also to the place in the code where it was called from. To do that, select the required item and choose Jump to Caller on the context menu.

    The contents of the file are highlighted to display the code execution path of the selected stack node.

  • When you are tracing an application with ECMASript6, CoffeeScript, and TypeScript code, Spy-js also generates mapped trace files. These are EcmaScript 6, TypeScript, or CoffeeScript trace files with the extensions .ts.trace, .coffee.trace, or .js.trace. The fragments of code in these files are highlighted as if they were really executed.
  • You can also navigate to the source file displayed as is, without prettifying, by selecting an item in the Event Stack pane and choosing Jump to Source on the context menu of the selection. If the traced site is mapped with a WebStorm project, WebStorm detects the corresponding local file according to the mapping and opens this file in the editor. If you are tracing a site that is not mapped to a WebStorm project, WebStorm opens the read-only page source, just as if you chose View Page Source in the browser.

    When the traced site is mapped with a WebStorm project, WebStorm opens the source file on any attempt to edit the opened trace file.

Context Menu of a Script or Function

Item Description
Jump to Caller Choose this option to navigate to the fragment in the trace file from where the currently selected item was called. When you are tracing an application with ECMASript6, CoffeeScript, and TypeScript code, WebStorm opens either the trace JavaScript file or the mapped trace file (TypeScript, CoffeeScript, or ECMAScript6):
  • If the Always open source mapped trace if available option is selected, the corresponding mapped trace file opens.
  • If the Always open source mapped trace if available option is not selected, the JavaScript trace file opens.
Jump to Trace Choose this option to navigate to the definition of the currently selected item in the trace file.
Jump to Source Choose this option to navigate to the definition of the currently selected item in the source file.
Mute this File Choose this option to add the selected script to an exclusion filter on the fly, see Configuring the Range of Events to Capture.
Capture only this file
Search this function calls across all events Choose this option to navigate between the calls of a function within the whole trace (across all the traced events). This means that if you are tracing 5 pages in the browser and the Events pane, accordingly, shows 5 document nodes, WebStorm searches for the calls of the selected function under all these nodes and displays the number of found calls of the function in the Status bar. The number of found calls is displayed in the Status bar, and the toolbar shows four previously hidden navigation chevron buttons.
spy_js_advanced_search_1.png
Use the chevron buttons to navigate within the found calls:
  • To jump to the first detected call, click spy js advanced search first occurence.
  • To jump to the last detected call, click spy js advanced search last occurence
  • To jump to the next detected call, click spy js advanced search next occurence The Status bar shows a message: Occurrence <number> of <total number of detected calls>
  • To jump to the previous detected call, click spy js advanced search previous occurence.

The search results are reset and the search toolbar is hidden when you invoke another advanced search or navigation.

Also keep in mind that the number of call occurrences is calculated when you choose the Search this function calls across all events option. As you analyze the detected calls, the time passes, new events are captured, and the first detected call can happen to be already removed from the stack which means that it is no longer available for navigation.

Navigate to Use the options under this item to move through the whole stack based on calls and locate the functions that have not been called, that is, locate the fragments of code that have not been executed and analyze the reason for them to be skipped.

The following six actions are available: move to the next/previous call of the next/current/previous function in a trace file. The full list of actions is available from the context menu in the Event Stack pane. Moving to the next and previous calls of the selected function, to the previous call of the previous function, and to the next call of the next function are also available from the navigation toolbar of the Event Stack pane.

spy_js_advanced_navigation_1.png
When you choose one of these actions, the cursor jumps to the call in the stack. If the Autoscroll to Trace toggle button is pressed, the corresponding trace file opens automatically with the cursor positioned at the call.

Synchronization between the Panes and the Editor

The Events and Event Stack panes are synchronized: when you click an event or script in the Events pane, its call stack is displayed in the Event Stack pane. To have also the corresponding trace file opened in the editor, press the Autoscroll to Trace toggle button on the toolbar.

The Event Stack pane is synchronized with the editor: when you click an item in the stack tree twice, the corresponding trace file opens in the editor with the cursor positioned at the clicked function.

To synchronize the Events pane directly with the editor, press the Autoscroll to Trace toggle button on the toolbar. In this case, as soon as you click a node in the Events pane, its call stack is displayed in the Event Stack pane and the corresponding trace file is opened in the editor. With the Autoscroll to Trace mode turned on, when you navigate through the Event Stack the corresponding files are also automatically opened in the editor with the corresponding functions highlighted.

Quick Evaluation Pane

When you click a node in the Event Stack pane, the Quick Evaluation pane shows additional function call details, parameter values and return value, occurred exception details if there was one during the function execution.

Context Menu of Function Call Details

The context menu is available from all items displayed in the pane.

ItemDescription
Inspect Choose this option to open the Inspect dialog box.
Copy Value Choose this option to copy the value of the selected node to the clipboard.
Compare Value with Clipboard Choose this option to open the Differences Viewer which displays the value of the selected node and the value in the clipboard so you can compare them.
Copy Name Choose this option to copy the name of the selected node to the clipboard.
Last modified: 29 November 2017

See Also

Language and Framework-Specific Guidelines: