Document last modified: 12/11/97.
This document gives a brief introduction to Netscape JavaScript Debugger 1.1. JavaScript is a cross-platform, object-based scripting language. This 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.
Netscape JavaScript Debugger requires Netscape Communicator 4.02 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 primary configuration of the JavaScript debugger windows is shown in Figure 1.
Figure 1 JavaScript debugger configuration
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.
While stopped in the debugger, you can use commands from the Windows menu open the Object Inspector, Breakpoint, and Watches windows.
Where To Find Commands
There are three common places to access the debugger's commands: the menu bar, the toolbar, and the right-click menu in a Source View window.
Most of the items that occur on menus also occur on the toolbar. In addition, if you right-click in a Source View window over selected text, a menu of common commands appears. These commands are also available on the menus and some are 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 (either from the menu bar or from the right-click menu) for these tasks. When there is no button for a task, the menu item on the menu bar is described.
Source View Windows
The JavaScript debugger creates a separate Source View window, as shown in Figure 2, for each HTML page you open in the debugger. (See "Opening a page to debug" for information on how you can open a page.)
Figure 2 Source View window
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:
When execution is stopped, you can perform these actions in Source View windows:
Call Stack
The Call Stack, shown in Figure 3, displays the current execution location.
Figure 3 Call Stack window
If this window is not empty, you are currently stopped in the debugger.
Console
The console, shown in Figure 4, is active only while JavaScript execution is stopped.
Figure 4 Console window
The console is divided into two parts:
When execution is stopped, you can have the debugger evaluate the current selection in a Source View window. To do so, on Windows and Unix you right-click on the selection. On Macintosh PowerPC, you command-click on it. On any system, a menu appears from which you can choose Evaluate. The result is displayed in the Console window. You can also click the Eval button on the toolbar to evaluate the current selection.
Page List
The Page List, shown in Figure 5, 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.
Figure 5 Page List
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.
Object Inspector
The Object Inspector, shown in Figure 6, lets you inspect and work with the property values of an object. If a property value is itself an object, the inspector lets you see that object's property values and so on.
Figure 6 Object Inspector
The Object Inspector is divided into three sections:
The Object Inspector is a powerful tool for examining the current state of your JavaScript objects.
Breakpoint Window
The Breakpoint window, shown in Figure 7, allows you to manipulate breakpoints. For information on breakpoints, see "Working with Breakpoints".
Figure 7 Breakpoint window
Watches Window
The Watches window, shown in Figure 8, lets you manipulate watches. For information on watches, see "Working with Watches".
Figure 8 The Watches window.
Opening a page to debug
There are two ways to open a page you want to debug. The simplest method is as follows:
- In the debugger, click the Intrpt button.
This sets an interrupt. (See "Working with Interrupts" for information about interrupts.)
- 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:
- In Navigator, open the page you want to debug.
- 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.
- Select the page you want to open in the debugger and click Open to display the page in a Source View window.
- 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.)
- 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 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.
You can manipulate breakpoints in the Breakpoint window, shown in Figure 7.
The breakpoints you set in one debugger session are saved with the debugger. The next time you start the debugger, the same breakpoints are automatically in effect.
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 clicking the Run button in the debugger.
To manually add a breakpoint
You may wish to add a breakpoint to a line of code without first opening the file in a Source View window. In general, because you do not have to manually type the URL and the line number, it is much easier to add breakpoints through a Source View window. However, if you know precisely where the breakpoint should occur, follow these steps:
- From the Windows menu, choose Breakpoints.
The Breakpoint window appears.
- Choose New to create a new breakpoint.
The Edit Breakpoint dialog, shown in Figure 9, appears.
- In the line text box, enter the line number of the breakpoint.
- In the url text box, enter the complete URL of the file.
You need to enter the URL exactly.
- If the breakpoint is to be conditional, add the condition in the condition text box.
Conditional breakpoints are discussed in "To edit a breakpoint's condition".
Figure 9 New Breakpoint dialog box
To edit a breakpoint's condition
Any breakpoint can be made into a conditional breakpoint by editing its condition as follows:
- Select the line in the Source View window which holds the breakpoint.
- From the Control menu, choose Edit Breakpoint.
A dialog box appears in which you can edit the condition expression. When this dialog first appears, the condition is true
. This means "always stop". You can enter any JavaScript expression as the condition.
Instead of using a Source View window to select the breakpoint to edit, you can select the breakpoint in the Breakpoint window and choose Edit.
Whichever method you choose, the same dialog box, shown in Figure 10, appears.
Figure 10 Editing a breakpoint
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.lengt
h 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 8, 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.
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.
The watches you set in one debugger session are saved with the debugger. The next time you start the debugger, the same watches are automatically in effect.
To add a new watch
You can add a new watch to the list in three ways.
To add text from a Source View window:
- In a Source View window, select the text you want to add.
- From the Edit menu, choose Copy to Watch.
This adds the selected text as the last item in the Watches window. It also causes the interpreter to evaluate all items in the Watches window. Choosing Copy to Watch does not, however, bring the Watches window to the surface.
- From the Windows menu, choose Watches.
The Watches window appears. From there you can perform other operations on the watch expressions.
To add text from the Object Inspector:
- Choose Add Watch.
This adds the text currently in the top line of the inspector as the last item in the Watches widow. It also causes the interpreter to evaluate all items in the Watches window. Choosing Copy to Watch does not, however, bring the Watches window to the surface.
- From the Windows menu, choose Watches.
The Watches window appears. From there you can perform other operations on the watch expressions.
If you want to create a watch expression from scratch, do the following:
- From the Windows menu, choose Watches.
The Watches window appears.
- Click the New button.
The New Watch dialog appears.
- Enter an expression in the New Watch dialog and click OK.
Clicking OK confirms the change; if you want to discard the new watch, choose Cancel. If you clicked OK, the new watch expression is added as the last expression in the Watches window.
- Click the Done button to indicate that you are finished making changes to the watches.
The Watch window disappears.
To edit a watch expression
- From the Windows menu, choose Watches.
The Watches window appears.
- In the Watches window, select the watch expression you want to edit.
- Click the Edit button.
The Edit Watch dialog appears.
- Make the necessary changes and click OK to confirm the changes or Cancel to discard them.
- Click the Done button to indicate that you are finished making changes to the watches.
The Watch window disappears.
To delete a watch
- From the Windows menu, choose Watches.
The Watches window appears.
- In the Watches window, select the watch expression you want to delete.
- Click the Delete button.
The selected expression disappears from the Watch window. There is no undelete.
- Click the Done button to indicate that you are finished making changes to the watches.
The Watch window disappears.
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:
- From the Windows menu, choose Watches.
The Watches window appears.
- In the Watches window, select the watch expression you want to move.
- Click the Move Up button to move the expression earlier in the order. Click the Move Down button to move the expression later in the order.
- Click the Done button to indicate that you are finished making changes to the watches.
The Watch window disappears.
To evaluate all watches
To immediately evaluate all watches:
- From the Windows menu, choose Watches.
The Watches window appears.
- Click the Evaluate button.
The interpreter evaluates all watch expressions, displaying the expression and its result in the Console.
- Click the Done button to indicate that you are finished working with the watches.
The Watch window disappears.
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:
- From the Edit menu, choose Preferences.
- From that submenu, choose Show Line Numbers or Hide Line Numbers.
Clearing the Console Window
If you work with the console window for an extended period, it can contain a lot of information, making it difficult to find lines you're interested in. You may want to clear that window to make it easier to see what is later added.
To clear the console window:
This does not change the state of the debugger, it simply erases the content of the console.
Manually adjusting source lines
There might be cases where the marks in the left column are not correctly aligned with the actual source. To manually adjust these marks:
- Right-click (on Windows or Unix) or command-click (on Macintosh) in the left column at the point you want to start the adjustment.
- 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 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: 12/12/97 09:21:29
Copyright © 1997
Netscape Communications Corporation