Debug your application

Both running and debugging use a configuration to control how applications are launched. When you debug your application, you run the debug version of the application file. See Debug version of the application.

You can edit the launch configuration to change the default main application file. You can also modify the default launch path to run or debug in the stand-alone Flash Player rather than in a web browser. See Run the application SWF file in the stand-alone Flash Player.

While debugging mobile applications, you use the launch configuration to specify whether to launch the application on the desktop or on a device connected to your computer.

    Start a debugging session

    To begin a debugging session, you run the application launch configuration in the Flash Debug perspective.

    Debug an application

    1. In the Flex Package Explorer, select the project to debug.

    2. Click on the main workbench toolbar.

      Note: The Debug button has two elements: the main action button and a drop-down list. The drop-down list shows the application files in the project that can be run or debugged. When you click the main action button, the project’s default application file is debugged. You can alternatively click the drop-down list and select any of the application files in the project to debug. You can also access the launch configuration dialog box and create or edit a launch configuration by selecting the Debug command.

      You can also select Run > Debug.

      If your project has not been built yet, Adobe® Flash® Builder™ builds and runs it in debug mode.

    3. Your application appears in your default web browser or the stand-alone Flash Player and you can then use the Flash Builder debugger to interact with it.

    4. When a breakpoint is reached, the Flash Debug perspective is activated in the workbench.

    Start a debugging session in the plug-in configuration

    The Debug command works differently in the plug-in configuration of Flash Builder. Instead of running the selected project, it debugs the most recently launched configuration. You can also select from a list of recently launched configurations.

    Debug an Adobe AIR application

    Flash Builder provides full debugging support for Adobe AIR applications.

    1. Open a source file for the application (such as an MXML file) in Flash Builder.

    2. Click on the main workbench toolbar.

    The application launches and runs in the ADL application (the AIR Debugger Launcher). The Flash Builder debugger catches any breakpoints or runtime errors and you can debug the application like any other application that is built in Flex.

    You can also debug an application from the command line, using the AIR Debug Launcher command-line tool. For more information, see Using the AIR Debug Launcher (ADL) in the AIR documentation.

    Debug an application with ActionScript workers

    Flash Builder supports debugging applications with multiple ActionScript workers. The main thread as well as all the supported worker threads are displayed in the Debug view as follows:

    View full size graphic

    You can set breakpoints in your worker files. While debugging, Flash Builder lets you step into or out of statements for a specific worker.

    You can suspend or resume a specific worker by selecting it and using the appropriate buttons in the Debug View toolbar.
    Important: You cannot terminate a specific worker thread. If you choose to terminate it, the debug session is terminated and the application running on your desktop or device is killed.

    Each ActionScript worker thread can have its own running state, call stack, and variables. Select the call stack to display variables from that worker. The Expressions view displays only those expressions relevant to the selected call stack.

    All other debugging features also work based on the call stack that you select. For example, if you are evaluating an expression, the first part of the expression is resolved using the selected call stack. After that, subsequent debug actions on the expression, like member access, function calls, and such, are based on the worker ID determined from the first part of the expression.

    Add and remove breakpoints

    You use breakpoints to suspend the execution of your application. By doing so, you can inspect your code and use the Flash Builder debugging tools to explore options to fix any errors. You add breakpoints in the code editor and then manage them in the Breakpoints view when you debug your applications.

    You add breakpoints to executable lines of code. The debugger stops only at breakpoints set on lines that contain the following:

    • MXML tags that contain an ActionScript event handler, such as <mx:Button click="dofunction()" ...>

    • ActionScript lines such as those enclosed in an <mx:Script> tag or in an ActionScript file

    • Any executable line of code in an ActionScript file

    You can set breakpoints as you write code or while you debug.

    Set a breakpoint in the code editor

    1. Open a project file that contains ActionScript code.

    2. Locate the line of code on which you want to set a breakpoint, and double-click in the marker bar to add a breakpoint.

      The marker bar is along the left edge of the code editor.

      A breakpoint marker is added to the marker bar and to the list of breakpoints in the Breakpoints view of the Flash Debug perspective.

    When the debugger encounters a breakpoint, the application is suspended, the Flash Debug perspective is displayed, and the line of code is marked with a breakpoint. The line of code is highlighted in the code editor. You then use the debugging commands in the Breakpoints view toolbar to interact with the code. See Breakpoints view.

    Remove a breakpoint in the code editor

     In the marker bar, double-click an existing breakpoint.

    The breakpoint is removed from the marker bar and the Breakpoints view of the Flash Debug perspective.

    Remove breakpoints in the Breakpoints view

    You can remove one, a few, or all of the breakpoints in the Breakpoints view from the Breakpoints toolbar.

    • Select one or more breakpoints from the list of breakpoints, and then click Remove Selected Breakpoints.

    • To remove all the breakpoints in a single action, click Remove All Breakpoints.

    You can also disable the breakpoints and re-enable them at a later time.

    Set conditional breakpoints

    You can specify conditions for breakpoints to stop the debugger from executing when specific conditions are met. When you set a conditional breakpoint, you specify an ActionScript expression that is evaluated during the debugging session. You configure the conditional breakpoint to stop execution for any of the following conditions:

    • The expression evaluates to true.

    • The value of the expression changes.

    • A specified Hit Count has been reached.

    How to set a conditional breakpoint

    1. From the context menu for a breakpoint, select Breakpoint Properties.

    2. In the Breakpoint Properties dialog, specify any of the following:

      • Enabled

        Toggle to enable or disable the breakpoint.

      • Hit Count

        Select Hit Count to enable a counter for the breakpoint. Specify a number for the Hit Count.

        If you specify both Hit Count and Enable Condition, the Hit Count is the number of times that the specified condition is met (evaluates to true or the value of the condition changes).

        If you specify Hit Count only, then Hit Count is the number of times the breakpoint has been reached.

      • Enable Condition

        Select Enable Condition and enter an ActionScript expression to evaluate. See Examples of expressionsfor information on types of expressions supported for evaluation.
        Note: Flash Builder checks the syntax of the expression and notifies you of syntax errors. If you have an assignment operator in the expression, Flash Builder displays a warning.

      • Suspend when:

        Specify when to stop execution, either when the expression for the condition evaluates to true or the value of the expression changes.

    Manage variables in the Variables view

      Change the value of a variable

      1. Select the variable to modify.

      2. Right-click (Control-click on Macintosh) to display the context menu and select Change Value.

      3. Enter the new value and click OK.

        The variable contains the new value.

      Modified variables are displayed in red.

      Find variables

       To locate a variable or variable member in the Variables view, with the Variables view selected, begin entering the name of the variable you’re looking for. You can also use the wildcard character (*) to search for words that occur anywhere within a variable name (for example, “*color”).

      Use the Expressions view

      While debugging, you can inspect and modify the value of the variables that you selected to watch. You can also add watch expressions, which are code expressions that are evaluated whenever debugging is suspended. Watch expressions are useful for watching variables that may go out of scope when you step into a different function and are therefore not visible in the view.

      You can also hover the pointer over an expression or variable in the source editor to see the value of that expression or variable as a tooltip. You can add the expression to the Expressions view by right-clicking and selecting Watch from the menu.

      Examples of expressions

      The Flash Builder Debugger supports a wide range of simple and complex expressions. The following table lists examples of expressions that can be evaluated during a debugging session. This is not the complete list of expressions supported, but just a sampling of what you can do.

      Examples of supported expressions

      Expression

      Description

      myString.length

      Returns the length of a string.

      myString.indexOf(‘@’)

      Tracks the index of the ‘@’ character.

      "constant string".charAt(0)

      Tracks the character at a specific position in a string. String constants are supported.

      employees.employee.@name

      employees is an XML variable. This type of expression is useful for debugging E4X applications.

      x == null

      Reserved words representing values in expressions.

      user1 === user2

      Most ActionScript operators are supported.

      MyClass.myStaticFunc()

      Functions resolved to a class.

      this.myMemberFunc()

      Functions resolved using the keyword this.

      String.fromCharCode(33)

      String is actually a function, not a class, and String.fromCharCode is actually a dynamic member of that function.

      myStaticFunc()

      Can be valuated only if myStaticFunc is visible from the current scope chain

      myMemberFunc()

      Can be valuated only if myMemberFunc is visible from the current scope chain.

      Math.max(1,2,3)

      Math functions are supported.

      mystring.search(/myregex/i)

      Regular expressions are supported.

      ["my", "literal", "array"]

      Creation of arrays.

      new MyClass()

      Instantiation of classes.

      "string" + 3

      Correctly handles string plus Integer.

      x >>> 2

      Logical shift operations supported.

      3.5 + 2

      Performs arithmetic operations correctly.

      Limitations of expression evaluation

      There are some limitations to expression evaluation.

      • Namespaces are not supported.

      • Inline objects are not supported.

      • The keyword super is not supported.

      • Fully qualified class names are not supported.

        For example, you cannot evaluate mx.controls.Button.

        You can refer to the unqualified class name. For example, you can specify Button to refer to mx.controls.Button.

        If a class name is ambiguous (two classes with the same name in different packages,) then you cannot control which class will be evaluated. However, you can specify:

        getDefinitionByName("mx.controls.Button")

      • Most E4X expressions can be evaluated, but E4X filter expressions are not supported.

        For example, you cannot evaluate myxml.(@id=='3')).

      • You cannot call functions that are defined as a variable.

      Use watchpoints

      When debugging an application, you can set watchpoints on specific instances of variables to stop execution when the watched variable changes value. Because watchpoints are set on a specific instance of a variable, you cannot set the watchpoint in the code editor. Instead, you set a watchpoint from the Variables view during a debugging session.

      When setting watchpoints, keep in mind the following:

      • When a debugging session ends, all watchpoints are removed.

      • You cannot set watchpoints on getters, but you can set them on the field of a getter.

        For example, you cannot set a watchpoint on width, but you can set a watchpoint on _width.

      • You cannot set watchpoints on local variables, but you can set watchpoints on members of local variables, as illustrated in the following code fragment.

        public class MyClass 
{ 
   // These are fields of a class, so you can set a watchpoint on 
   // 'memberInt', and on 'memberButton', and on 'memberButton._width': 
   private var memberInt:int = 0; 
   private var memberButton:Button = new Button(); 
 
   public function myFunction():void { 
      // You CANNOT set a watchpoint on 'i', because it is local: 
      var i:int = 0; 
 
      // You CANNOT set a watchpoint on 'someButton', because it is local; 
      // but you CAN set a watchpoint on 'someButton._width': 
      var someButton:Button = new Button(); 
 
... 
}

      • Execution stops for a watchpoint when the original value of an object instance changes.

        This differs from using an expression in a conditional breakpoint to stop execution whenever a variable changes value.

      Set watchpoints

       In a debugging session, there are two ways to set a watchpoint:

      • In the Variables view, open the context menu for a variable, and select Toggle Watchpoint

      • From the Flash Builder Run menu, select Add Watchpoint.

        From the Add Watchpoint dialog, select the variable you want to watch.

      The Variables view displays a “pencil icon” to indicate that a watchpoint has been set on that variable.
      Note: If you attempt to set a watchpoint on a getter, Flash Builder opens a dialog suggesting a valid variable for the watchpoint. If you delete the suggested variable, the dialog lists all valid variables for the object.

      Use Run to Line

      Flash Builder provides the Run to Line command to break out of a loop during a debugging session.

      While debugging, you sometimes find that your code is executing a loop that repeats many times. To break out of this loop, use the Run to Line command, available from the Run menu.