Eric Owens

Created

13 July 2009

Requirements

Prerequisite knowledge
A basic knowledge of Adobe Flex 3 will be helpful.
 
User level
Intermediate
Sample files
flexmonkey_sample.zip (605 KB)

 
Additional Requirements

 
FlexMonkey 1.0 Air Installer
Without automation, testing the UI components of your Flex application can be tedious and time consuming. Adobe includes an automation framework in Flex to enable developers to create automated tests that operate at the GUI level. FlexMonkey 1.0 is an open source AIR application that leverages the Flex automation framework to record and play back GUI interactions with your Flex application. With FlexMonkey, your tests can drive your application views directly, making it easy to exercise the view components and the logic behind them. Integration with the automation framework is under-the-hood; you don't need to make any changes to your application source or compilation method to use FlexMonkey.
 
In this article, I'll show you how to get started using FlexMonkey as part of your development flow. FlexMonkey can launch your Flex application in different ways depending on your needs. It can launch your application directly from your Flex Builder project, it can connect to your application running in a browser, or it can be linked into your application. In this article, you'll learn how to launch it directly from your Flex Builder project.
 

 
Setting up your first FlexMonkey project

When you install FlexMonkey and start it for the first time, you'll see a Welcome dialog box with instructions on getting started (see Figure 1). Click OK.
 
Figure 1. The FlexMonkey welcome screen
Figure 1. The FlexMonkey welcome screen

To create your first FlexMonkey project, download and extract this article's sample files and then follow these steps:
 
  1. Choose File > New Project (see Figure 2).
Figure 2. Creating a new project in FlexMonkey
Figure 2. Creating a new project in FlexMonkey
  1. In the New Project dialog box, select a directory to hold your FlexMonkey project files (see Figure 3). For this example, select the Flex Builder project directory for the sample MonkeyContactsIntroExample project.
  2. Click Select, and FlexMonkey will create files to hold your tests and your project preferences.
3. The New Project dialog box
3. The New Project dialog box
  1. In the Project Properties window, specify the target SWF (that is, the SWF file that you want to test). In this case, click Browse and select MonkeyContacts.swf in the bin-debug directory of the project (see Figure 4).
    Note: If the SWF you want to test is remote, you can just type in the URL.
     
Figure 4. The FlexMonkey Project Properties window
Figure 4. The FlexMonkey Project Properties window
  1. Leave Use Browser unchecked, and click Apply. A window will open displaying the target SWF (see Figure 5).
Figure 5. The target SWF window opens on your desktop
Figure 5. The target SWF window opens on your desktop
  1. Adjust the size of the target SWF window using the Project Properties Width and Height settings and click Apply to see the effect.
  2. When you are satisfied with the size of the target SWF window, click OK. (Leave the FlashVars and Generated AS3 Source Directory settings empty for now.)
FlexMonkey will save your project properties, and it will automatically load them the next time you start FlexMonkey.
 

 
Creating your first test

After you create a new project, the FlexMonkey Console window opens and you are ready to create your first test (see Figure 6).
 
Figure 6. The FlexMonkey Console window
Figure 6. The FlexMonkey Console window

Expand NewTestSuite (by clicking the triangle next to it) and then expand NewTestCase to show NewTest (see Figure 7). If you are familiar with xUnit, you will recognize the standard hierarchical test organization in FlexMonkey. Select NewTest by clicking its row. NewTest is Empty because you haven't added any UI commands to it yet. When you select NewTest, the Record button will be enabled. Click the Record button and it glows red to indicate that you are now in Record mode.
 
Figure 7. The FlexMonkey Console window in Record mode
Figure 7. The FlexMonkey Console window in Record mode

For this example, you will test the Monkey Contact Manager application (see Figure 8); specifically you'll test adding a new contact. While recording is active, every interaction with your application will be recorded by FlexMonkey.
 
In the MonkeyContacts.swf window, type a new name, select a phone type from the combo box, enter a phone number, leave the birthday field blank, and click Add.
 
Figure 8. The Contact Manager application to be tested
Figure 8. The Contact Manager application to be tested

When you have finished adding the contact in the MonkeyContacts.swf window, click the Record button again to toggle Record mode off. Figure 9 shows the FlexMonkey console window after recording the new test.
 
Figure 9. The Console window shows the UI commands that were recorded
Figure 9. The Console window shows the UI commands that were recorded

As you can see, FlexMonkey inserted a sequence of UI commands into NewTest. In the second column, there are entries for Open and Select events, keyboard input, and mouse clicks. In the third column, the id of the target component for the UI command is listed.
 
In the contact manager application, the id property of the Name field is inName, the id property of the Phone Type field is inType, and the id property of the Phone field is inPhone.
 

 
Adding assertions

Now you're ready to add an assertion to your test. With the last command in the test (Click Add) still selected, click the Add Verify button, which is the green check mark in the tool bar. The Take Snapshot dialog box will appear over the FlexMonkey Console window indicating that FlexMonkey is in Snapshot mode (see Figure 10).
 
Figure 10 . FlexMonkey in Snapshot mode
Figure 10 . FlexMonkey in Snapshot mode

While in Snapshot mode, move your mouse cursor over the target SWF window. FlexMonkey highlights the visible Flex components in red to make it easy to select one. Clicking a red-highlighted component makes it the target for your assertions. For this example click the data grid (see Figure 11).
 
Figure 11. The data grid of the Contact Manager application highlighted in Snapshot mode
Figure 11. The data grid of the Contact Manager application highlighted in Snapshot mode

After you select a target component for your assertions, FlexMonkey displays the Spy window, which shows the current properties and styles for the target component. Click the selectedIndex property, which is currently set to 0 (see Figure 12). Click OK, and FlexMonkey will add an assertion that the selectedIndex property of the data grid will be 0 when the Verify command executes.
 
Figure 12. The FlexMonkey Spy window
Figure 12. The FlexMonkey Spy window

Back in the FlexMonkey Console window, you can see the added assertion on the right. The detail view for the Verify command shows that the selectedIndex property is expected to be equal to 0 when the command executes (see Figure 13).
 
Figure 13. The detail view of the Verify command

Figure 13. The detail view of the Verify command

Running your test

Now it's time to have FlexMonkey play back the test. First, select NewTest as shown in Figure 14. Click Play (the button just to the right of the Record button), and FlexMonkey will execute all of the UI commands in NewTest.
 
Figure 14. Select NewTest and then click Play to run the test
Figure 14. Select NewTest and then click Play to run the test

When FlexMonkey is playing, the Play button will glow green as shown in Figure 15. As FlexMonkey plays, it highlights each UI command in the console window as it is executing. Of course, you can also watch as the commands are executed in the target SWF window.
 
Figure 15. UI commands are highlighted as they are executed
Figure 15. UI commands are highlighted as they are executed

When FlexMonkey is finished playing the last command of the test, the Play button will stop glowing green and the results for the test will be updated.
 
Figure 16. FlexMonkey displaying the results of NewTest

Figure 16. FlexMonkey displaying the results of NewTest

Save your work and shut down

You can save your work at any time by clicking the Save button (the blue diskette at the far right of the tool bar). If you don't, and you quit FlexMonkey, you'll be prompted to save your work (see Figure 17).
 
Figure 17. FlexMonkey prompts you to save changes
Figure 17. FlexMonkey prompts you to save changes

The next time you open FlexMonkey, it will reopen this project, and load the test file and target SWF.
 

 
Where to go from here

In this article, I covered setting up a FlexMonkey project, creating tests, adding assertions, and running tests.
 
I encourage you to play with FlexMonkey on the sample application or on your own Flex application to record and play back UI tests.
 
You can use the following links and resources to learn more about FlexMonkey: