Introducing the ActionScript 3.0 debugger

With the release of Adobe Flash CS3, the debugging capabilities of the Flash authoring environment have greatly improved.

This article give you a tour of the new interface and the different features of the new debugger. I also discuss how to use it when you're troubleshooting issues with ActionScript 3.0 classes and frame scripts in your FLA files.

Debugging basics

To start you out on the right track, let's first start with the basics of debugging. You'll learn all about breakpoints, how to use them in your ActionScript 3.0 code, and the role they play in debugging your Flash application.

Setting up breakpoints

Whenever you use a debugger, it is very important to be able to run through the script line by line in order to isolate the area of the code that is causing an error or a function that is returning an unexpected value. Rather than simply playing the script from beginning to end (as it would run in Flash Player), it is very helpful to add breakpoints to specific lines of code in your script. Breakpoints allow you to define a point at runtime where the SWF will pause when viewed in the debugger.

The ability to pause the code at a specified line makes it possible to investigate the progress of the script, so that you can closely examine what is happening—both visually and by researching the values assigned to variables (more about that later). Breakpoints work the same way in an ActionScript class and the ActionScript editor for frame scripts in the timeline of an FLA file.

Setting up breakpoints is easy. To add a breakpoint, simply click in the left margin of the line of you want to put a breakpoint. The breakpoint is displayed as a red dot next to the code (see Figure 1).

To remove a single breakpoint, click the red dot to remove the breakpoint. To remove all breakpoints at once, select Debug > Remove All Breakpoints from the top menu.

Breakpoints are persistent. When you save a FLA file or an ActionScript class with breakpoints defined, they appear again the next time you open the file.

Running the debugger

To run your code through the debugger, simply select Debug > Debug Movie from the top menu. If you attempt to debug a FLA file that does not contain any code, a warning message will appear: "You cannot debug this SWF because it does not contain ActionScript" (see Figure 2).

There are two ways to include code in your Flash project. You can either write code as frame scripts on a timeline of the FLA or you can reference an external ActionScript class from the FLA file.

First, let's examine a simple FLA file that contains a dynamic text field with an instance name artists_txt. For this example, imagine that the following snippet of ActionScript exists on Frame 1 of the main Timeline:

This example is designed to show how useful it is to use breakpoints and evaluate the values assigned to variables when a FLA is run through the ActionScript 3.0 debugger. In the code snippet above, an array containing the names of the four members of the Beatles is defined. A variable named current_artist is declared and then a for loop is used to assign the value associated with the current index of the array. This text is displayed in the dynamic text field.

If you were to run this movie in Flash Player by selecting Control > Test Movie, the movie would play and the dynamic text field would display Ringo Starr.

Go back to the FLA and add a breakpoint next to line 6. This is the line of code where the artist_txt text field is assigned a value. By setting a breakpoint on line 6, you can pause the script at that specific point to see what happens. If you run the debugger now (Debug > Debug Movie) you'll see the FLA file compile to a SWF. The movie launches in a window running the debug version of Flash Player and the interface changes to reveal the debugging interface (see Figure 3).

You may set as many breakpoints as you'd like, so that you can evaluate each line of code in the movie as desired. The interface provides valuable feedback about the variables, and the values it returns help you troubleshoot issues within the code. If Flash Player were used to run the movie, the code would execute so quickly that it would be difficult to tell exactly where the code was misbehaving.

It's time now to add breakpoints to an ActionScript class. The example below is a simple StringUtils class that includes a method to reverse a given string:

To evaluate what the code is doing, add a breakpoint on line 11. This is the section of the script where the tmp_string variable is returned by the reverse method of the class (see Figure 4).

Now that you've added the breakpoint, create a new FLA file that uses the StringUtils class. This is necessary because the FLA file is the movie that runs through the debugger. On Frame 1 of the main Timeline, add the following line of code:

If you run this Flash project using the regular Flash Player (Control > Test Movie), you won't see anything. This is because the return value from reverse method of the StringUtils class was not coded to display or do anything. However, if you run the FLA file through the debugger (Debug > Debug Movie), you'll see the debugger interface reveal a great deal of information that describes what is happening in the compiled SWF behind the scenes (see Figure 5).

Exploring the debugger interface

Taking a closer look at the debugger interface will help you see what you can do when evaluating ActionScript code.

The two main panels of the debugger interface display the variables and call stack in the FLA. They sit alongside the Output panel, which may be familiar to you if you have used it before to trace statements in your code.

Controlling playback

Before we examine these two panels in more detail, here's a quick note about how to control the playback of the movie as you debug it.

When you choose Debug > Debug Movie, the SWF automatically pauses at the first breakpoint it encounters so that you can take your time and read the information provided in the panels. When you wish to resume playback, click the green play icon in the Debug Console panel (see Figure 6). This causes the SWF to resume playing exactly where it stopped until it encounters the next breakpoint. Clicking the red X icon in the Debug Console panel ends your debug session.

The Debug Console panel also contains buttons that allow you to Step Over, Step In, and Step Out:

Step Over makes the debugger move to the very next line of code and pause there, as though it has encountered a breakpoint. You can click this button repeatedly to slowly go line by line through your code. This is an ideal approach for finding the exact line of code in a method that is causing you problems.

Step In is very similar to Step Over, except instead of moving ahead to the very next line of code in the script, it jumps to the definition of any function referenced on that breakpoint and then allows you to step through the code of the function line by line.

Step Out moves the debugger ahead to the point in time where the current function returns a value, whether a breakpoint exists there or not. This allows you to check the values quickly to make sure they are correct.

Variables panel

The Variables panel is your best friend whenever you run a movie in debug mode. As you step through your code, the Variables panel shows you the exact value of every variable in your SWF at that point in time.

As you step through the breakpoints, you can see how the values change, which makes it possible to tell whether your code is behaving properly.

Even more exciting, the Variables panel doesn't only allow you to see the values at runtime. It also allows you to change the values currently assigned to each variable.

The ability to change values of variables at runtime is a tremendously powerful feature. This enables you to see how your application behaves under different conditions by simply changing some of the values.

Let's go back to the first example in this article, where an array contains the names of the four members of the Beatles. This time, run the FLA through the debugger and examine the code that loops through the array. As you step through the breakpoints, notice that the value assigned to the variable current_artist changes (see Figure 7).

Rename the value Ringo Starr to Ozzy Osbourne and step through the code line by line until the end of the movie. You'll see that you've just changed your data at runtime. Perfect!

Call stack

The call stack is another powerful feature available as you debug your Flash project. The call stack displays references to the methods, in the order that they were called so that you can make sure they happen in the correct sequence. You can access the call stack through the Debug Console panel.

Let's return to the second example in this article. If you run the StringUtils example through the debugger, notice that the call stack is populated in the Debug Console panel. As you click the references in the panel, the ActionScript editor jumps to the corresponding method definition in the file, timeline, or frame where it is located (see Figure 8).

As you click back through the call stack, you can actually follow along in the Variables panel to evaluate the values at that point in the movie. While you can't change the values of any of these variables at an earlier point in time, this is a great way to monitor what is happening in your Flash application. This strategy allows you to pinpoint any bugs in your code accurately.

Remote debugging

Everything I've covered so far is related to debugging your Flash project locally. You may be wondering if it is possible to perform remote debugging sessions—that is, debug code in a SWF that is running on a server.

To enable the ability to remotely debug your SWF, check the Permit Debugging option in the Publish Settings dialog box (File > Publish Settings > Flash) to allow this (see Figure 9).

When the Permit Debugging option is checked, breakpoints and other debugging information is saved into the compiled SWF. This results in a slightly higher file size. With that in mind, depending on your situation, you may decide to deploy your final SWF without debugging enabled.

To start a remote debug session, make sure you have Flash CS3 Professional open and from the main menu choose Debug > Begin Remote Debug Session > ActionScript 3.0.

The interface changes to the debug mode as described in this article. A message in the Output panel will appear: "Waiting for Player to connect...".

Then if you launch the SWF in a browser or in the stand-alone debug Flash Player, a dialog box asks you to specify where the debugger is running (see Figure 10).

For the purposes of this article, select the Localhost option because you have Flash open on your own machine. However, it is important to note that you could connect to the IP of another machine that has the ActionScript 3.0 debugger open.

Remote debugging can be very useful in situations when you want to test your Flash content running in a test environment on an actual server.

Where to go from here

The Flash engineering team has done a tremendous job improving the debugging capabilities in Flash CS3 Professional and bringing it in line with the functionality found in Flex Builder 2.

After exploring the powerful features in the ActionScript 3.0 debugger, you may find that you no longer need to use trace statements as often—because the Variables panel, in combination with the call stack, provides you with a much better alternative.

Give it a try and see how much easier it is to debug your Flash content using the ActionScript 3.0 debugger and get immediate feedback that will help you troubleshoot issues in your SWF files.

For more information about ActionScript 3.0, check out the resources available in the ActionScript Technology Center as well as the ActionScript-related Quick Starts in the Flash Developer Center.