Getting Started with Netscape JavaScript Debugger

Preview Release 2. This release expires October 31, 1997.

Document last modified: 7/31/97.

This document gives a brief introduction to the preview release version of Netscape JavaScript Debugger. JavaScript is Netscape's cross-platform, object-based scripting language. This preview release version of Netscape JavaScript Debugger allows you to debug client-side JavaScript code. The debugger cannot be used to debug server-side JavaScript, Java, or HTML.

This preview release version of Netscape JavaScript Debugger works with the following versions of Netscape Communicator:

For this operating system You need this version of Communicator
Windows 95/NT

4.0 or later

Macintosh PowerPC

4.0.1 or later

Solaris 2.4, 2.5,
SunOS 4.1.3,
Irix 5.3, 6.2, 6.3

4.0 Preview Release 6 or later

The debugger cannot be used with other browsers.

NOTE: When you're stopped in Netscape JavaScript Debugger, you cannot use many features of Communicator. In particular, you cannot use Navigator to browse web pages. For this reason, it is recommended that you download the PDF version of this document before starting the debugger. You can then either print that document or view it online with Acrobat Reader.
What's in this document:

Starting the Debugger

The end of the installation process automatically runs the debugger. After that first time, you run the debugger by opening the appropriate page in Navigator. On Windows 95/NT, that page is:

[your Communicator install directory]\Program\JSDebug\JSDebugger.html
Here, [your Communicator install directory] is the directory in which Communicator is installed. For example, if you installed it in c:\Program Files\Netscape\Communicator\, then the start page for Netscape JavaScript Debugger would be:

c:\Program Files\Netscape\Communicator\Program\JSDebug\JSDebugger.html
On other platforms, that page is:

[your Communicator install directory]\JSDebug\JSDebugger.html
For future convenience, the first time you use the debugger, you should add the JSDebugger.html page to your bookmarks or to your personal toolbar in Navigator.

NOTE: Several security dialog boxes are displayed the first time you run the debugger. You must grant the security privileges the debugger requests in order for it to function correctly.

Understanding the Windows

The main debugger window is shown in Figure 1.

Figure 1    JavaScript debugger window.

The debugger window has a menu bar, a toolbar and (once you've opened an HTML page) three panes. A Source View window is at the top; the Call Stack is below the Source View and on the left; and the Console is below the Source View and on the right. In this preview release, the windows always appear in this same configuration in the same location.

Menu Bar and Toolbar

The menu bar and the toolbar give you two ways to access the debugger's commands. Most of the items that occur on menus also occur on the toolbar. Where applicable, the instructions in this document tell you how to use the toolbar and the individual panes to access the debugger's functionality. You can also choose menu items for these tasks. When there is no button for a task, the menu item is described.

Source View Windows

The JavaScript debugger creates a separate Source View window for each HTML page you open in the debugger. (See "Opening a page to debug" for information on how you can open a page.)

Each Source View window contains the source of an HTML page. When execution stops in the debugger, the Source View window containing the currently executing HTML page is brought to the surface.

Source View windows use colors and icons in the left margin to indicate the following information:

You can perform these actions in Source View windows:

Call Stack

The Call Stack displays the current execution location. If this window is not empty, you are currently stopped in the debugger.

Console

The console is active only while JavaScript execution is stopped. The console is divided into two parts:

Page List

The Page List appears when you click the Open button. It contains a list of all pages you have opened in Navigator since starting the debugger. The pages are sorted with the most recently opened listed first.

If you open the Page List while execution is stopped in the debugger, the page being debugged is highlighted in the list. If execution is not stopped, the highlighted page is not significant.

To refresh the Page List, from the File menu, choose Refresh All. This also refreshes Source View windows.

Opening a page to debug

There are two ways to open a page you want to debug. The simplest method is as follows:

  1. In the debugger, click the Intrpt button.

    This sets an interrupt. (See "Working with Interrupts" for information about interrupts.)

  2. In Navigator, load the page you want to debug.

    Navigator starts loading the page. As soon as it encounters JavaScript code on the page, it stops execution and opens a Source View window containing the HTML source for that page.

Alternatively, you can do the following:

  1. In Navigator, open the page you want to debug.

  2. Click the Open button on the debugger toolbar.

    The Page List window appears containing a list of the pages you have opened in Navigator since starting the debugger. The pages are sorted with the most recently opened listed first.

  3. Select the page you want to open in the debugger and click Open to display the page in a Source View window.

  4. Set a breakpoint in the code where you want the interpreter to stop and activate the debugger. (See "Working with Breakpoints" for information on setting breakpoints.)

  5. In Navigator, reload the page to start debugging.

Working with Interrupts

Setting an interrupt tells the JavaScript interpreter to halt execution as soon as it can. If JavaScript code is running when you set the interrupt, the interpreter immediately halts execution and activates the debugger. If JavaScript code is not running when you set the interrupt, the interpreter waits until some JavaScript code executes. At that time, the interpreter halts and activates the debugger.

You can set an interrupt for two major purposes:

To toggle an interrupt

Working with Breakpoints

A breakpoint is a specific location at which program execution is halted so that you can review the program's status up to that point. You set a breakpoint on a particular line of code. When execution reaches that line of code, the JavaScript interpreter stops and activates the debugger.

Breakpoints can either be unconditional or conditional. With an unconditional breakpoint, when the interpreter reaches the line of code, it always stops and activates the debugger. With a conditional breakpoint, when the interpreter reaches the line of code, it evaluates the condition (a JavaScript expression). If that expression returns true, then the interpreter activates the debugger. If the expression returns any value other than true, the interpreter does not activate the debugger.

As you select items in the Source View, the state of the BrkPt button changes.

To toggle a breakpoint

Do one of the following:

When you set a breakpoint, a red dot appears by the line in the margin of the Source View window, indicating an unconditional breakpoint. When you remove a breakpoint, the dot disappears.

You can set a breakpoint either when execution is stopped or while JavaScript code is running. If execution is stopped when you set a breakpoint, you can restart execution by reloading the page in Navigator or by clicking the Run button in the debugger.

To edit a breakpoint's condition

Any breakpoint can be made into a conditional breakpoint by editing its condition as follows:

When you make a breakpoint conditional, the red dot by the line in the margin of the Source View window becomes orange. When you remove the breakpoint, the dot disappears.

When the interpreter evaluates the condition expression, it provides no automatic feedback. Any errors in the condition expression are ignored and discarded by the interpreter.

The interpreter stops execution and activates the debugger only when the expression evaluates to true.

NOTE: The condition expression must literally evaluate to true. If it evaluates to anything else (such as 0, false, 1, or "Success"), the interpreter does not activate the debugger.

Conditional Breakpoint Examples

The following are simple examples of condition expressions.

You can use conditional breakpoints in other situations. For example, you may want to log information to the Java console each time a line of code is executed, but not stop on that line. To do so, use an expression similar to the following:

(java.lang.System.out.println("myFunction called with x = " + x)) && false
With this condition, the debugger always prints to the console, but does not stop since the entire expression returns false.

A similar situation would be to log information every time the code is executed but activate the debugger only if the value of prop.length is 5. To do so, use this expression:

(java.lang.System.out.println("myFunction called with x = " + x)), prop.length == 5
You can also use a conditional breakpoint to change values at runtime. Consider the following expression:

(x == -1) && (x = 0) && false
When the interpreter executes the line of code that contains that condition, it first checks to see if the value of x is -1. If so, it sets the value of x to 0. The interpreter does not stop for this condition, since it always returns false.

Working with Watches

A watch is an expression you enter that the interpreter automatically evaluates each time the interpreter stops and activates the debugger. The evaluation occurs for breakpoints, interrupts, or steps. You use the Watches window, shown in Figure 2, to manipulate watches. The Watches window displays the current list of watch expressions and allows you to manipulate the list and edit the items in the list.

Figure 2    The Watches window.

You can set as many watch expressions as you like. The interpreter evaluates them in the order in which they occur in the Watches window. The interpreter displays each watch expression and its output in the Console.

Watch expressions are not specific to a particular page. They are evaluated every time the debugger is activated for any page, regardless of the page from which you set the watch.

To add a new watch

You can add a new watch to the list in two ways, depending on whether or not you want to copy text from a Source View window as part of the new watch expression.

To add text from a Source View window:

If you want to create a watch expression from scratch, do the following:

To edit a watch expression

To delete a watch

To change the evaluation order

The expressions in the Watch window are evaluated from top to bottom. To move a watch expression, do the following:

To evaluate all watches

To immediately evaluate all watches:

Executing Code

The debugger provides several commands for executing sections of code. When stopped in the debugger, you have several options for how you execute code:.

The following sections tell you how to perform these actions.

To continue execution

When stopped in the debugger, you may want to continue execution from the current statement and stop only when a breakpoint is reached. To do so:

To "step into" function calls

When stopped in the debugger, if the line you're stopped at is itself a function call, you may want to execute the individual statements in the function call. To execute the first statement inside the function call and then stop, do the following:

To "step over" function calls

When stopped in the debugger, if the line you're stopped at is itself a function call, you may want to execute the entire function and stop execution after the function returns. In this case, you do not step through the individual statements in that function call. To do so:

To "step out" of a function call

When stopped in the debugger, if the line you're stopped at is inside a function call, you may want to execute the rest of the statements in that function call and stop after the function returns. In this case, you do not step through the rest of the statements in that function call. To do so:

To execute a single statement

When stopped in the debugger, if the line you're stopped at is not a function call, you can execute that single statement. You can do either of the following:

To terminate a function call

When stopped in the debugger, you may want to terminate the current function and continue execution after it. To do so:

Displaying line numbers

To toggle between displaying and hiding line numbers:

Manually adjusting source lines

There might be cases in this preview release version where the marks in the left column are not correctly aligned with the actual source. To manually adjust these marks:

  1. Right-click (on Windows or Unix) or command-click (on Macintosh) in the left-hand column at the point you want to start the adjustment.

  2. Move the mouse (while continuing to hold down the mouse button) up or down.

    A + or - sign appears to indicate where the adjustments have been made, and in which direction.

You can reset the manual adjustments by Alt-clicking in the left-hand column.

Error Reporter Dialog

The Error Reporter dialog displays information about syntax errors and runtime errors in your JavaScript code.

The Error Reporter dialog contains OK, Debug, and Pass On buttons.

Last Updated: 07/31/97 09:05:13


Copyright © 1997 Netscape Communications Corporation