Testing and debugging

Flash Builder offers options for testing and debugging your mobile application on the device or on the desktop using the AIR Debug Launcher (ADL). In either case, you can use the Flash Builder debugging capabilities, including setting breakpoints and examining the application's state using the Variables and Expressions panels.

    Test and debug a mobile application on the desktop

    For initial testing or debugging, or if you don’t have a mobile device, Flash Builder lets you test and debug applications on the desktop using the AIR Debug Launcher (ADL).

    Before you test or debug a mobile application for the first time, you define a launch configuration. Specify the target platform and On Desktop as the launch method. See Manage launch configurations.

    Configure device information for desktop preview

    The properties of a device configuration determine how the application appears in the ADL.

    Set device configurations lists the supported configurations. Device configurations do not affect the application’s appearance on the device.

    Screen density

    Flash Builder uses a screen density of 240 DPI when you preview your application on your development desktop. An application’s appearance during preview sometimes differs from its appearance on a device that supports a different pixel density.

    Preview applications with ADL

    When you preview applications on the desktop, Flash Builder launches the application using the ADL. The ADL provides a Device menu with corresponding shortcuts to emulate buttons on the device.

    For example, to emulate the back button on a device, select Device > Back. Select Device > Rotate Left or Device > Rotate Right to emulate rotating the device. Rotate options are disabled if you have not selected auto orientation.

    Drag in a list to emulate scrolling the list on a device.

     Adobe Certified Expert in Flex, Brent Arnold, created a video tutorial on using ADL to preview a mobile application on the desktop.

    Test and debug an iOS application on a simulator

    The iOS Simulator offers a fast way to run and debug iOS applications without using a device. The iOS simulator can simulate iOS devices, like iPhone and iPad, and different iOS versions.

    Important: You use the iOS Simulator to run your iOS application only on a Mac.; the iOS simulator is not supported on Windows.

    When testing with the iOS simulator, you do not need a developer certificate or a provisioning profile. However, you must still create a p12 certificate.

    Prepare to debug on the iOS simulator

    Before you test or debug your application on the iOS simulator, ensure the following:

    • The application uses an SDK that contains Adobe AIR 3.4.

    • You download the latest available Xcode developer toolset from the Apple Developer site. The toolset includes the Xcode package, the iOS simulator, and all the required tools and framework to run the simulator.

    Debug an application on the iOS simulator

    Note: This feature needs AIR 3.4 or higher
    You can debug an iOS application using the Debug Configurations dialog.

    1. In Flash Builder, select Debug > Debug Configurations.

    2. In the Profile Configurations dialog box, select the Target Platform as Apple iOS and the Launch Method as On iOS Simulator.

    3. Select the Simulator SDK location and version.

      For Mac OS 10.6 or a lower version, the iOS simulator is installed by default at /Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs

      For Mac OS 10.7 or a higher version, the iOS simulator is installed by default at

      /Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs

    4. Click the Default Device drop-down list and select the device that you want to simulate when you debug the application. Any change you make to the default device when the simulator is running is reflected only when you launch the simulator again.

      Note: To select a different device when the simulator is running, select Hardware > Device in the iOS simulator, and choose the device.

    5. Click Configure Package Settings and select the p12 certificate.

      If you don’t have a p12 certificate that Apple has issued, you can create a user-signed certificate. User-signed certificates, however, can be used to launch applications only on the simulator and not on Apple iOS devices.

    6. Click Debug to launch the iOS Simulator and debug the application. The application is automatically launched on the iOS simulator by default.

      For more information on using the iOS simulator, see Using iOS Simulator.

    Test and debug a mobile application on a device

    You can use Flash Builder to test or debug a mobile application from your development desktop or from a device.

    You test and debug applications based on a launch configuration that you define. Flash Builder shares the launch configuration between running and debugging the application. When you use Flash Builder to debug an application on a device, Flash Builder installs a debug version of the application on the device.

    Note: If you export a release build to a device, you install a non-debug version of the application. The non-debug version is not suitable for debugging.

    For more information, see Create or edit launch configurations to run or debug mobile applications.

    Debug an application on a Google Android device

    On an Android device, debugging requires Android 2.2 or later.

    You can debug in either of the following scenarios:

    Debug over USB
    To debug an application over a USB connection, you connect the device to the host machine via a USB port. When you debug over USB, Flash Builder always packages the application, then installs and launches it on the device before the debugging starts. Ensure that your device is connected to the host machine’s USB port during the entire debugging session.

    Debug over a network
    When you debug an application over the network, the device and the host machine must be on the same network. The device and the host machine can be connected to the network via Wi-Fi, ethernet, or Bluetooth.

    When you debug over a network, Flash Builder lets you debug an application that is already installed on a connected device without reinstalling the application. Connect the device to the host machine via a USB port only during packaging and while installing the application on the device. You can unplug the device from the USB port during debugging. However, ensure that there is a network connection between the device and the host machine during the entire debugging session.

    Prepare to debug the application

    Before you begin debugging over USB or over a network, follow these steps:

    1. (Windows) Ensure that the proper USB driver is installed.

      On Windows, install the Android USB driver. See the documentation accompanying the Android SDK build for more information. For more information, see Install USB device drivers for Android devices (Windows).

    2. Ensure that USB debugging is enabled on your device.

      In device Settings, go to Applications > Development, and enable USB debugging.

    Check for connected devices

    When you run or debug a mobile application on a device, Flash Builder checks for connected devices. If Flash Builder finds a single connected device online, Flash Builder deploys and launches the application. Otherwise, Flash Builder launches the Choose Device dialog for these scenarios:

    • No connected device found

    • Single connected device found that is offline or its OS version is not supported

    • Multiple connected devices found

    If multiple devices are found, the Choose Device dialog lists the devices and their state (online or offline). Select the device to launch.

    The Choose Device dialog lists the OS version and the Adobe AIR version. If Adobe AIR is not installed on the device, Flash Builder installs it automatically.

    Configure network debugging

    Follow these steps only if you debug an application over a network.

    Prepare to debug over the network

    Before you debug an application over the network, follow these steps:

    1. On Windows, open port 7935 (Flash Player debugger port) and port 7 (echo/ping port).

      For detailed instructions, see this Microsoft TechNet article.

      On Windows Vista, deselect the Wireless Network Connection in Windows Firewall > Change Settings > Advanced.

    2. On your device, configure wireless settings in Settings > Wireless and Network.

    Select a primary network interface

    Your host machine can be connected to multiple network interfaces simultaneously. However, you can select a primary network interface to use for debugging. You select this interface by adding a host address in the Android APK package file.

    1. In Flash Builder, open Preferences.

    2. Select Flash Builder > Target Platforms.

      The dialog lists all the network interfaces available on the host machine.

    3. Select the network interface that you want to embed in the Android APK package.

    Ensure that the selected network interface is accessible from the device. If the device cannot access the selected network interface while it establishes a connection, Flash Builder displays a dialog requesting the IP address of the host machine.

    Debug the application

    1. Connect the device over a USB port or over a network connection.

    2. Select Run > Debug Configurations to configure a launch configuration for debugging.

      • For the Launch Method, select On Device.

      • Select Debug via USB or Debug via Network.

        The first time that you debug the application over a network, you can install the application on the device over USB. To do so, select Install The Application On The Device Over USB, and connect the device to the host machine via a USB port.

        Once the application is installed, if you don’t want to connect over USB for subsequent debugging sessions, deselect Install The Application On The Device Over USB.

      • (Optional) Clear application data on each launch.

        Select this option if you want to keep the state of the application for each debugging session. This option applies only if sessionCachingEnabled is set to True in your application.

    3. Select Debug to begin a debugging session.

      The debugger launches and waits for the application to start. The debugging session starts when the debugger establishes a connection with the device.

      When you try to debug on a device over a network, the application sometimes displays a dialog requesting an IP address. This dialog indicates that the debugger could not connect. Ensure that the device is properly connected to the network, and that the computer running Flash Builder is accessible from that network.

      Note: On a corporate, hotel, or other guest network, sometimes the device cannot connect to the computer, even if the two are on the same network.

      If you are debugging via network, and the application was previously installed on the device, start debugging by typing the IP address of the host machine.

     Adobe Certified Expert in Flex, Brent Arnold, created a video tutorial about debugging an application over USB for an Android device.

    Debug an application on an Apple iOS device

    You can debug an iOS application on an Apple iOS device in either of the following scenarios:
    Note: You can debug over USB only if you have Adobe AIR SDK 3.4 or higher.
    Debug over USB
    To debug an application over a USB connection, connect the iOS device to the host machine via a USB port. When you debug over USB, Flash Builder packages the debug iOS package (IPA file) and installs the IPA file on the device. You need to launch the application on the iOS device manually to start the debugging. Ensure that your device is connected to the host machine’s USB port during the entire debugging session.

    Debug over a network
    When you debug an application over the network, the device and the host machine must be on the same network. The device and the host machine can be connected to the network via Wi-Fi, ethernet, or Bluetooth.

    Prepare to debug the application

    Before you debug an application on an iOS device, ensure that you have a provisioning file from Apple and an Apple-issued developer certificate that you need to convert into P12 format. For more information, follow the steps described in Prepare to build, debug, or deploy an iOS application.

    To debug an iOS application over USB, ensure that:

    • The application uses an SDK that contains Adobe AIR 3.4.

    • iTunes is installed on your development computer. iTunes installs the necessary device drivers required for debugging over USB.

    Debug the application

    1. Connect the Apple iOS device to your development computer.

    2. In Flash Builder, select Run > Debug Configurations.

    3. In the Debug Configurations dialog, follow these steps:

      1. Select the application that you want to debug.

      2. Select the target platform as Apple iOS.

      3. Select the launch method as On Device.

      4. Select one of the following packaging methods:

        Standard
        Use this method to package a release-quality version of your application that can run on Apple iOS devices. The application performance with this method is similar to the performance of the final release package and can be submitted to the Apple App Store.

        However, this method of creating a debug iOS (IPA) file takes several minutes.

        Fast
        Use this method to create an IPA file quickly, and then run and debug the file on the device. This method is suitable for application testing purposes. The application performance with this method is not release quality, and it is not suitable for submission to the Apple App Store.

      5. Click Configure to select the appropriate code signing certificate, provisioning file, and package contents.

      6. Select Debug Via USB or Debug Via Network.

        When you debug over USB, a debug port that is freely available is selected and added to the debug iOS package.

        When you debug over the network, click Configure Network Debugging to select the network interface that you want to add in the debug iOS package.

        Note: Your host machine can be connected to multiple network interfaces simultaneously. However, you can select a primary network interface to use for debugging.

      7. Before you begin to debug the application, check if you have previously installed this application on your device. If so, uninstall the previously installed application.

      8. Click Debug. Flash Builder displays a dialog requesting for a password. Enter your P12 certificate password.

      Flash Builder generates the debug IPA file and installs it on the device.
      Note: Flash Builder installs the IPA file on the device only if you are using Adobe AIR SDK 3.4 or higher. If you are using an Adobe AIR SDK version lesser than 3.4, you need to use iTunes to install the application on the device. For more information, see this Help topic.

    4. Launch the application on the iOS device.

    5. Flash Builder attempts connection to the host address specified in the debug IPA file. If the application cannot connect to the host address, Flash Builder displays a dialog requesting the IP address of the host machine.

      Note: If you have not changed your code or assets since the last debug IPA package was generated, Flash Builder skips the packaging and debugs the application. That is, you can launch the installed application on your device and click Debug to connect to the Flash Builder debugger. This way, you can debug repeatedly without packaging the application every time.

    Change Application ID while testing or debugging

    Every application has a unique Application ID, which you specify in the application descriptor XML file.

    When you run or debug an iOS application, you generate an Application ID in the iOS Provisioning Portal. The Application ID that you generate is based on the Application ID specified in the application descriptor file. For example, if your Application ID is com.myDomain.*, the ID in the application descriptor file must start with com.myDomain. This application ID is used in the provisioning file used for testing or debugging the application. For more information, see Apple iOS development process using Flash Builder.

    In general, when you run or debug an application, Flash Builder creates a copy of the application descriptor file and internally modifies the Application ID by adding a .debug extension. For example, if your application ID is com.myDomain, it is modified to com.myDomain.debug. Flash Builder makes this change so that while testing or debugging an application on a device, you don’t replace an installed application with the same name.

    This internal change that Flash Builder makes can, however, cause a mismatch between the Application ID specified in the application descriptor XML file and the Application ID specified in the provisioning file. To overcome this mismatch, Flash Builder lets you modify the Application ID as required from the Run/Debug Configurations dialog box. When you change the Application ID for an application file in the project, Flash Builder persists the mapping information and uses it across multiple debugging sessions.
    Note: The Application ID appears blank in the Run/Debug Configurations dialog if a bin-debug folder has not yet been created for your project. The value you enter for the Application ID is updated in the Application Descriptor file the next time you launch the application by clicking Run or Debug.