Debugging Script with the Developer Tools

  • Article

This content refers to an older version of F12 developer tools. Please visit our latest F12 tools documentation.

The Developer Tools feature of Windows Internet Explorer 8 offers a built-in, lightweight Microsoft JScript debugger that enables developers to set breakpoints and to step through client-side JScript code without leaving the browser. This document outlines the high-level features of the JScript debugger. To get acquainted with the other features of the Internet Explorer 8 Developer Tools, refer to Discovering Internet Explorer Developer Tools; to get a complete reference of the Developer Tools interface commands, refer to Developer Tools User Interface Reference.

  • Introduction
  • Start Debugging
  • Setting Breakpoints
  • Controlling Execution
  • Inspecting Variables
  • Inspecting Call Stack
  • Using Console to Execute Code Statements
  • Using Console for Logging Alerts and Error Messages
  • Remarks
  • Related topics

Introduction

JScript debugging is a critical part of Web development. With the intuitive, lightweight JScript debugger, the Developer Tools feature brings one-click simplicity to the end-to-end JScript debugging experience. After installing Internet Explorer 8, developers can debug JScript on any site loaded in Windows Internet Explorer.

To open Developer Tools within Internet Explorer 8, press F12; alternatively, on the Tools command bar, click the Developer Tools button.

Note  Although the JScript debugger can be used for debugging any engine implementing IActiveScriptSite interfaces (like Microsoft Visual Basic Scripting Edition (VBScript)), only JScript debugging is supported.

Start Debugging

With the Developer Tools in Script tab, begin the debugging process by clicking the Start Debugging button or pressing F5. Clicking this button will trigger these events:

  • A Debugging Requires Webpage Refresh dialog box will give you an option to refresh the page. If you click OK, the debugging will start and the page will refresh; if you click Cancel, debugging will not start and the page will not refresh.
  • Once debugging starts, if the Developer Tools window is pinned to the Internet Explorer 8 instance, it will Unpin itself. When debugging stops, you can Pin it back to the Internet Explorer 8 instance.

To stop debugging, either click the Stop Debugging button or press SHIFT+F5. The following screen shot shows options on the Script tab.

Options on Script tab

Note  The Debugging Requires Webpage Refresh dialog box only shows up if you have not enabled script debugging for Internet Explorer. Clicking OK in the dialog box will temporarily enable script debugging for this instance of Internet Explorer until you close the window. To enable script debugging for all instances of Internet Explorer, on the Internet Options menu, click the Advanced tab. Then, under the Browsing category, uncheck the Disable script debugging (Internet Explorer) option, and then click OK. For the changes to take effect, close all instances of Internet Explorer then reopen them again.

Note  All scripts on a page, both separate files and inline script blocks, are available in the drop-down Script List box, whether debugging has started or not. You can switch between these files at any time while in Script mode tab. The source of the currently selected file will show up in the Primary Content Pane.

Setting Breakpoints

From the Primary Content Pane where the script code is displayed, you can set breakpoints by:

  • Clicking on the line number to insert or delete a breakpoint
  • Right-clicking on a line of code and choosing Insert Breakpoint
  • Positioning the cursor on a line of code and press F9 to insert or delete a breakpoint

Breakpoints can be set whether the debugger is started or not. Once a breakpoint is set, the breakpoint icon Breakpoint icon will appear next to the line number of the code, and the code of that line will be highlighted.

A breakpoint pauses script execution immediately before the breakpoint line, and the debugger will highlight the next line to be executed. During debugging, any runtime errors will cause the debugger to break at the location of the error. To prevent breaking on an error, unset the Break on Error toggle button or press CTRL+SHIFT+E. While the debugger pauses execution, the browser will not respond to any user input. The following screen shot shows the setting and managing of breakpoints.

Breakpoints on Script tab

A list of all breakpoints is available in the Breakpoints tab of the debugger. There, you can find the location of all breakpoints, along with the file name and line number where a break point has been set. To go to the source code location of a breakpoint, double-click the breakpoint in the list. To deactivate the breakpoint without removing it, clear the check box next to the breakpoint. To remove the breakpoint, right-click it and select Delete from the shortcut menu. Internet Explorer maintains the breakpoint information until you close the Developer Tools, even if you navigate away from the current site.

Note  A breakpoint can become invalid in many scenarios. An invalid breakpoint is disabled and a warning icon is displayed on top of the breakpoint icon. A breakpoint will become invalid if you navigate away from the site on which it is set. It can be invalid if you set it at a wrong location in non-debug mode, or if you start debugging where debugger finds no matching code. It can also become invalid if you refresh the page on which it is set and the source code changes.

When a breakpoint is set, execution will pause at the breakpoint whenever it is encountered. If you want execution to pause at that breakpoint only when a certain condition is true, then set a condition for that breakpoint. To set a breakpoint Condition, do the following:

  1. Right-click the breakpoint from the Primary Content Pane or from the Breakpoints pane. A shortcut menu will appear.
  2. Select the Condition... option. A dialog box will appear.
  3. In the Conditional Breakpoint dialog box, enter the condition and click OK.

This will cause the debugger to pause execution at this breakpoint only when the condition is true.

Controlling Execution

Breakpoints are used to pause script execution in order to give you a chance to inspect the state of the codes at that point. When execution stops at a breakpoint, you can control execution by using any of the following command buttons.

Debugger's execution control buttons

  • Continue

    Continue to run the script without pausing, until another breakpoint or script error is encountered. Keyboard shortcut: F5.

  • Break All

    Pause execution immediately before the next script statement executes. Click the button or press CTRL+SHIFT+B to activate this command, then perform the actions you want to debug.

  • Break On Error

    Pause execution at the point where the error has occurred. This command is active by default. If you do not want to pause execution at these error points, click this button to deactivate this command; however, in both cases, an error message will show up in the console for each error encountered. Keyboard shortcut to toggle command on/off: CTRL+SHIFT+E.

  • Step Into

    Executes the next line of script and pauses, even if the next line is inside a new method. Keyboard shortcut: F11.

  • Step Over

    Continues to the next line of script in the current method, and then pauses. Useful for stepping over method calls. Keyboard shortcut: F10.

  • Step Out

    Continues executing the script to the next line in the method that has called the current method. Useful for stepping out of loops and method calls. Keyboard shortcut: SHIFT+F11.

Inspecting Variables

Any variable can be inspected through the Locals pane and the Watch pane. To inspect variables:

  • start the debugger by clicking on Start Debugging
  • set breakpoint(s) along the execution path
  • then, execute scripts

During execution, the debugger will pause at the first breakpoint encountered. Once execution is paused, variables in the Locals pane and Watch pane can then be inspected and edited.

The Locals pane of the debugger displays the Name, Value, and Type of all the variables available in the current execution scope. If a variable is out of scope, it is unavailable and does not show up in the Locals pane. For these 'out of scope' variables and objects, use the Watch pane to keep an eye on them at any time.

You can watch variables from different scopes by adding them to the Watch pane. You can add variables to the Watch pane in several ways:

  1. From the Primary Content Pane, select a script text, then right-click to activate the context menu, and click Add Watch. This will add that text to the watch list.
  2. From the Locals pane, right-click a variable or object, then click Add Watch to add it to the watch list.
  3. From the Watch pane, click Click to add, and then type the name of a variable you want to watch. The Click to add text can be found at the bottom of the watch list as it is the last item in the list of the Watch pane, as shown in the following screen shot.

Variables in the Locals pane

With each execution of a line of code, the debugger will update the variable values in the Locals and Watch panes. The updated values are displayed as red text. To modify the value of a variable in the Locals or Watch pane, double-click the value, type a new value, and press ENTER. Alternatively, you can right-click the object and then click Edit Value to begin editing. After you are finished, press ENTER to commit or ESC to cancel your edit.

Inspecting Call Stack

The Callstack pane provides a list of execution contexts whenever the debugger pauses execution at a breakpoint. To jump to any stack item, double-click the item. The debugger will bring that method into view in the Primary Content Pane. From there you can inspect the variables at that execution context in the Locals and Watch panes.

Using Console to Execute Code Statements

The Console pane of the debugger provides a console for executing script statements on-the-fly. Type any valid statement or variable name, and press ENTER (or click Run Script) to execute that statement in the context of the current page and right where execution is paused.

To set the values of variables, use the standard assignment syntax:

var s = 'my query string';

Clicking the Multi Line Mode button expands the input window to allow entry of multiple lines. It also changes the behavior of the ENTER key, such that the key creates a new line instead of executing the script. Here, you can type multiple lines of code and then execute them by clicking Run Script. The input window, which is resizable, offers additional controls through the shortcut menu.

You can use the Console pane at any time, even if debugger is not started. When execution stops at a breakpoint, the commands entered in this pane will run in the execution scope of the breakpoint; when execution is not paused, the commands will run in the global scope.

Using Console for Logging Alerts and Error Messages

All the script errors in a particular instance of Windows Internet Explorer are logged to the Console pane once the Developer Tools is open. To navigate to the error location, click the source information provided in the error.

You can also log messages to the Console by using console.log APIs. Instead of using window.alert() and generating countless dialogs, call console.log to output strings to the Console pane. To differentiate between messages, use different console.log APIs; for example:

  • console.log
  • console.info
  • console.warn
  • console.error
  • console.assert

These console commands can be called with a list of arguments that will be concatenated to generate the output string. The arguments can also be formatted by using substitution patterns in the style of printf. For example, you can call console.log in one of the following ways:

  • console.log("Variable x = " + x + " and variable y = " + y)
  • console.log("Variable x = ", x, " and variable y = ", y)
  • console.log("Variable x = %d and variable y = %d", x, y)

The console.assert command, however, requires an expression in its first argument to evaluate to either true or false. If the expression evaluates to true, then the assertion message will not be output to the console; otherwise, the message will be output to the console. For example:

var x = 1;
var y = 1;

//This expression evaluates to TRUE, so the message will not show up in the console
console.assert(x==y, "ASSERT: x == " + x + "; y == " + y);

//This expression will evaluates to FALSE so the message will show up in the console
y = 2;
console.assert(x==y, "ASSERT: x == " + x + "; y == " + y);

These console messages can be filtered from the console pane to show or hide. To select the messages you want to show or hide from the Console pane, set the Filter as follows: right-click the Console pane and move the cursor over Filter. A list of available filters appears where the filter with a check mark is active.

In addition, the console object can be extended to add new functionalities to your development needs. For example, you might want a customized method to output your debugging messages to the console. To add a console.debug command, you might add the following code snippets to your JScript code:

console.debug = function(name, value){
    console.warn("DEBUG: " + name + "==" + value);
}

The preceding example takes in two arguments and simply outputs them to the Console pane with minimal formating. Since you get to define console.debug, you can customize function arguments and behavior however you wish to suite your needs. In this way, the console object can be use to add any number of new commands you may need.

Note  Because you are using existing console commands within your new command, Filter will still be applied. For example, the console.debug command in the previous example uses console.warn to output messages to the Console pane. If you uncheck Console Warnings from the Filter list, then none of the output from console.warn will show up in the Console pane.

Remarks

  • To clear all console.log messages, use console.clear() in your code or from the Console command line. The console.clear() will not clear script error messages or codes you entered into the Console command line.
  • To completely clear the Console pane, right-click in the Console pane and choose the Clear Console options. This will clear all messages in the Console pane.

Discovering Internet Explorer Developer Tools

Debugging HTML and CSS with the Developer Tools

Profiling Script with the Developer Tools

Developer Tools User Interface Reference

Developer Tools Keyboard Shortcuts Reference