Learning the JavaScript debugger Venkman

The Basics

You should now know how to start Venkman, and it should look like it does in the screenshot provided, and how to customize it to your needs. Now, close down Venkman. Navigate Mozilla to venkman_example_1.html. This is a series of HTML files, containing scripts, I've made, so as to demonstrate each aspect of Venkman. When I tell you to, just move to the next file (by conveniently clicking the link I've provided in the file.)

Checking the source out

One of the basic things you can do in Venkman, is to inspect the source code currently loaded into Venkman. It's important to note, that Venkman only lets you view the source code, and not edit it, it's not an editor.

Currently, the paned called "Source code" is blank, as you haven't told Venkman what you want to see in it (if you don't tell it at all, once you start debugging, it'll display the relevant code by itself.) Let's try and view some HTML code. There's two ways, to get to the code. First, you can view the code for an entire webpage (the venkman_example_1.html file I told you to load earlier, in this case), or you can jump straight to a function definition.

Viewing source code is easy. Make sure that the Loaded Scripts panel is active. It should look something like figure 9 (ignore the "XStringBundle", or any other extra stuff that might appear in the dialog. It's merely Mozilla's dirty underwear showing.)

Figure 9. Loaded Scripts, where all source code can be easily accesses in Venkman.

Now, just double click on the venkman HTML file, and it will appear in the Source Code panel (if it appears garbled, or wrong, try maximizing and then restoring the window size). It should look something like in figure 10.

Figure 10. Venkman is capable of showing, and displaying any code currently loaded into it (click for unscaled version).

As you double clicked the file name, you also expanded the little plus (if this didn't happen, just click the plus now). What you see there (seen as "test" in figure 10), is a full list of all JavaScript functions that exists in that file (my tiny HTML file has only one function though!)

Double click the function name, and it should highlight the function's source code in the HTML display, like in figure 11.

Figure 11. Select any function, and jump straight to the functions definition in Venkman, handily highlighted (click for unscaled version).

One thing you can't see right now, but will be apparent soon enough, is that on the Loaded Scripts tab, not only HTML files are listed, potentially linked JavaScript files will also be listed. And they work in exactly the same way. Double click the filename, to view the file, expand, to view any functions that may be present in that file.

Loaded Scripts

You've just used the "Loaded Scripts" panel, to check out the source code for a HTML document. You'll notice, that each type of file, has it's own icon, and if you expand the file icon, you'll notice further sub icons, representing functions. Here is now a full listing, of what the icons means.

Icon	Type
	JavaScript (.js)
	Hypertext Markup Language (.html, .htm)
	eXtensible Userinterface Language (.xul)
	eXtensible Markup Language (.xml)
	All other files
	JavaScript function

Basically, these are all files, that in Mozilla can contain executable JavaScript. Under each loaded file, you'll see the functions defined in that file. Also, if you're wondering why brackets appear around your function names, it's because Venkman is guessing their names.

The Interactive Session

Now, you've learned how to view the files, it's time to learn the Interactive Session. A very basic, but useful part of Venkman.

Notice the Panel labeled "Interactive Session". If you read the notice (that it spat at you as Venkman started up), it says that any text entered with a proceeding / will be read as a Venkman command, and anything else, will be executed as JavaScript. So let's try this. Write in "1+1" (add ; to the end, if you feel like it), in the field, and press enter:

Figure 12. The Interactive session console, after entering "1+1".

Go a little further, and declare something, say b (set it to 65):

Figure 13. You can write any kind of code in the Interactive session, including declaring variables.

Since this is JavaScript, you not only declare variables, and do basic Math, you can use objects from JavaScript, such as the String class, as illustrated in Figure 14, where I've entered String.fromCharCode(b) + "B".

Figure 14. Normal JavaScript classes and objects can be used, just as usual. Note that, Venkman strips the final apostrophe, from it's console output. You need to write it as "B", of course (this is a bug that was fixed in the latest Venkman, 0.9.79.)

Getting help

No, we don't call the Ghostbuster, because Venkman (oh, the irony) has a perfectly solid help system built in. Anytime you type a command into the Interactive Session, you can get help on the command, by typing in "/help commandname", or to access the general help, just type in "/help".

Setting the context

Now this is all fine, but totally dull (and useless.) Instead of just typing in JavaScript into a void, let's type it in somewhere, where we can mess around some. When Venkman starts up, the so called "evaluation context" is it's own program code. That means that JavaScript code is evaluated relative to Venkman itself. Instead, we want to change that context, to whatever document we have loaded in Mozilla. First, change to the "Open Windows" tab, see figure 15.

Figure 15. Changing to the Open Windows panel, and viewing all current documents in Mozilla.

Click on the little plus next to "Navigator Window", and it should show the file name of the file you loaded into Mozilla, venkman_example_1.html. If you're reading this page in Mozilla, it will show this page as well. Right click on the file, and select "Set as evaluation object", as in Figure 16.

Figure 16. Setting "venkman_example_1.html" as the evaluation object.

Now you've set the HTML file as the current evaluation object. JavaScript you enter now, can manipulate the loaded document, and it can extract information from the same document. Try entering "document.title" into the Interactive session (which you will notice also says it's now using the document, as the evaluation context).

Figure 17. Inspecting the DOM of the current document, using document.title

You'll see it answer back the title of the current document. Now, you can see in my document (try scrolling some in the source code, if you can't see it), that I've declared a variable, a. Try entering simply a, into the Interactive session.

Figure 18. Retrieving variables declared in the loaded document.

If you want to, you can also try to execute the function test included in the file. The prompt should answer back 2.

You can not only inspect the document, using the Interactive session, you can also fully manipulate it. Try setting the document's title, to document.title = "muahah" + a, as in Figure 12.

Figure 19. Manipulating the document through the Interactive session console.

Note, that the Interactive Session supports command history. Pressing up or down, will give you earlier commands you have entered.

Basic debugging

The previous section was basically about inspecting a still document. Unless you load in a document, where things are happening, using setTimeout's, or something similar, you were merely inspecting a still box. Now we get to how to run through a live and executing script. There are many ways to do this, but we'll start with the simplest and easiest. First, close down Venkman, and then in the loaded Mozilla file, venkman_example_1.html, press the "move to next" link, and load venkman_example_2.html.

Start up Venkman as usual again. Be sure to set the evaluation context to the new document.

You've probably been looking at the row of toolbar buttons, and wondered what they did. You'll be using them now. Start by pressing "Stop". You'll notice that the stop button changed into a stop button, with three dots (as in figure 20 below). But none of the others changed.

Figure 20. Venkman's toolbar, with the Stop button activated.

The stop button instructs Venkman, to simply stop (or rather, pause) whatever script is executing at that moment. In this case, no script was executing, so there's nothing to stop. Instead, Venkman goes into "waiting-for-something-to-happen" mode. As soon as a script starts to execute (you click something, to trigger an event, or the page reloads, causing the whole thing to run again), Venkman will step in, and pause everything.

Now, give focus back to Mozilla, and press the "Reload" button, or press Ctrl+R. As soon as you do, Venkman will pop back up, because, as soon as you pressed reload, it reloaded the page, and started to execute the script that I put in the page.

Venkman, having just paused the page's script, should look something like in figure 21, notice how the current line is highlighted in yellow, and that the other buttons are now activated.

Figure 21. Venkman has stopped just at the start of the script block. Waiting for your commands, notice that the other buttons are now activated and that the current line of code is highlighted (click for unscaled version).

Stepping

We now get to play with the fundamental parts of a debugger, having actually paused script execution, you can view each line of code, as Mozilla executes it. The various buttons are, "Step over", "Step into" and "Step out". If you mouse over these buttons, a tooltip will tell you that they are "step over function call", "step into function call", and "step out of the current function" respectively (for now, ignore the "Continue" button, and the clock and the pretty flower also.)

So, at any given line of JavaScript, you can control, if the debugger should step into, over, or out, of that line. But note, that it's merely a "don't bother me with this" feature. Just because you step over a function call, doesn't mean it's not executed!. You'll see this in a short while.

Right now, the debugger is halted on the first "line" of JavaScript (which is kinda empty). Press the "Step into" button (or F11), to advance to the next line. The debugger is now halted at line 4, the variable declaration. Try entering "a" in the Interactive Session now, you'll see that the value is void. Press Step into one more time, and try entering "a" again, and you'll note that it now has a value (of 1).

Next line, is a function declaration, just press step into again. You'll note that it skips all the way down to line 9, and that's of course because the function declaration is a single whole (when it comes to executing it, you'll get to step through the contents of the function line by line).

You're now at the line:

var b = test(a);

You can enter "a" in the Interactive Session, and note it's value is (of course) 1. Entering "test(a)" you'll see the output :

Figure 22. Executing functions "ahead of time", to see what the result will be be.

Nothing especially surprising. But now, it begins to matter, what button you press. If you press "Step into", Venkman will jump up to line 6, and start running the function line by line. If you press "Step over" however, the function is still executed, you just don't get to see it. Try pressing "Step over", and then enter "b" into the Interactive Console, and verify, that indeed, it holds the value "passed : 1".

Keep pressing "Step into/over", to the end of the script. You'll note that the buttons become inactive again, and that the stop button again says "waiting". I recommend you reload the page again, and try the path you didn't take before, just to get a feel for how the buttons work.

Figure 23. Venkman always shows the "scope" of the running code. In figure 21, the whole script block is drawn gray, to indicate that the top level is the scope. In this figure, the function test is the scope, and thus, it's drawn gray.

The debugger keyword

Using stepping, to wade through a large script is not always desirable. For this, you can use the debugger keyword. Whenever a script is executed, and the keyword debugger is encountered, and Venkman is running, Venkman halts execution. In Mozilla, move to the next file, venkman_example_3.html. In the following, you can see how the word debugger appears inside the function. This acts as a command to Venkman, halting execution.

t = 1 + 3;
function f(a) {
    debugger;
    return a+1;
}
document.write(f(t));

Start up Venkman, and reload the Mozilla window, Venkman should instantly come back up, waiting at line 6.

Figure 24. Venkman stops whenever the keyword debugger is encountered (click for unscaled version).

You'll note, that you weren't bothered with the lines, such as t = 1 + 3; and the function declaration and calling. Venkman (or rather, Mozilla) executed all the lines normally, up to the debugger keyword. From here, it's standard operating procedure. Step through the code if you wish, use the various panel, to investigate (more on using the panels coming up), or just press "Continue", to get the script on it's way again.

It's important to note, that using the debugger keyword will not cause an error to appear in Mozillas that don't have Venkman running. Note however, that this is only true for Mozilla and Internet Explorer on Windows, the only two browsers, that I'm aware of, that support debuggers. In these browser, the keyword will be silently ignored (== no errors), if no debugger is active. It will cause an error in other browsers, so take it out from production code!

Leaving stuff out & a note on DHTML

Of course, Venkman allows you to skip past code you don't care about at all, by omitting both files and individual functions from debugging. This example will be a bit different from all the other examples on this page, in that it'll be "Dynamic HTML" (well, mock DHTML anyway.) We'll see how to exclude stuff from debugging, and also how Venkman acts with "live" code.

In Mozilla, move to the next file, venkman_example_mock_dhtml.html. The file is really small, but it will do, for demostrating Venkmans ability to skip either specific functions, or entire files. Firing Venkman up, you'll notice some things right away. You'll see, that the example consists of a linked file, which contains a single small function:

function getPx(elm) {
    return parseInt(elm.style.left);
}

And it's really only there, to show how this works with files. Basicly, the init function is called onload of the window (and anytime you press the "start" button in Mozilla), it proceeds to set a interval, repeatedly calling shiftLeft. shiftLeft is the code, that simply moves the block to the left, until it reaches 500 pixels, and then starts over at 100, simple. shiftLeft calls the function getPx, to parse out the current pixel number from the red box's style setting. clearDHTML is the function that stops the box, by clearing the timeout set in init.

Figure 25. Showing what files are loaded into Venkman for the "mock_dhtml" example.

We will start with excluding a function from being debugged. If you look at the function clearDHTML, you'll see it contains the keyword debugger, to cause Venkman to halt. Let's pretend we don't want this. Right click the function in the Loaded Scripts panel, and bring up the function submenu.

Figure 26. How to disable a single function from being debugged.

You will see the function turn red, and appear in italics, as a result, indicating it's being skipped. Also note how the file name shows that it contains a function being skipped.

Figure 27. How to disable a single function from being debugged. Note the indication, via red text and italics.

If you return back to Mozilla, and now press the "stop" button, you'll notice that Venkman doesn't popup. I suggest you remove the check (just go to the same submenu, and uncheck the choice), and then start the script again (press "start"), and then try "stop" again. You'll notice that Venkman this times reacts, and comes up.

More intesting perhaps, is the example of how you can exclude functions, from being debugged, and in which case you won't even step into them. To illustrate this, set a breakpoint (much more on these later, for now, just follow the instructions), on line 21. Do this by clicking in the far left margin, it should turn into a red "B". As soon as you do, you'll also notice that Venkman stops at that line (because a breakpoint is an instruction to Venkman to stop at that line, when it gets to it, and remember that this is a DHTML script, it's continually looping.)

Figure 28. Stopped at a script line, using a so called "breakpoint".

Remove the breakpoint again, by click the red "B" twice (it'll turn into an orange "F" first, and then it'll be gone). And then press "step into", you'll notice, that you'll be taken to the function getPx, in the linked .js file. Press step into a few more times, and you'll go out again. Keep pressing "step into", and you'll notice you're moving in a cycle. Now, let's try and not get that "bothersome" swicth to the getPx file. And for this exercise, we'll exclude the entire file, as seen in figure 29.

Figure 29. Exclusing a whole file from being debugged.

And if you then go back to stepping in Venkman, you'll notice that it no longer shifts to the linked .js file containing getPx. If you want to debug the file again, it's as simple as going into the same submenu, and select "Debug contained functions".

You've now learned some very basic usage of Venkman. Stepping through code, setting breakpoints (sorta, alot more on breakpoints later). You should now know enough to make use of Venkman, in actual debugging, but Venkman offers so many other ways of looking up information. Read the next section, to learn how to get information out of Venkman (and remember, getting information, is crucial for finding those elusive bugs).