Using the FoneMonkey Console

Creating and Editing Scripts with the FoneMonkey Console

When you launch an application that has been linked with FoneMonkey (see Setup Guide), the FoneMonkey Console is displayed on top of the application’s window.



To begin recording, touch the Record button. The FoneMonkey console will hide and you can manually test your application. As you interact with it, FoneMonkey records FoneMonkey commands corresponding to each user interface gesture.

If you stop interacting with the application for longer than the timeout interval (by default, 2.5 seconds), the FoneMonkey console will reappear on top of your application window.
If you are not yet done recording, click any where over the application to hide the FoneMonkey console and resume recording.

Touching the Pause button hides the FoneMonkey window and lets you interact with your application without recording. The console will reappear after the timeout interval. Touch anywhere on your application to re-hide the console and continue without recording.
Touch the More button to view the list of recorded commands.



Commands are displayed in the Command List table. The Timeout slider can be used to set the timeout interval anywhere from 2 to 10 seconds. If the console is reappearing more quickly than you want it to while the console is recording or paused, make the timeout longer.

Touch the Play button to begin playback. The console hides and FoneMonkey executes each command in sequence, generating user interface actions corresponding to each command.
By default, FoneMonkey pauses .5 seconds between commands. Sometimes you may need FoneMonkey to wait additional time at certain points in a script. For example, a command might need to wait until an animation finishes running. Use Pause commands (see command reference) to insert pauses between commands during playback.

Editing Recorded Commands

To edit a recorded command, touch the Edit button on the row in the command list to be edited. The Command Editor will be displayed.



Using the command editor, you can change the Command, Component Class, Monkey ID, or any of the associated parameters. When you’re finished editing, touch the Done button.

Inserting and Deleting Commands

Commands can be inserted and deleted using the Insert and Delete toolbar buttons, which display the Insert or Delete buttons in each row of the displayed script.
Saving a Script

To save a script, touch the Save Script button. The Save Script dialog will be displayed.

Enter a name for the script and hit the Save button. Scripts are saved in the application's Documents directory.

Running a Saved Script

To run a saved script, touch the Open Script button. The Saved Script List will open displaying all saved scripts.


To open a script, touch its name in the list. The script will open in the console and can be played and edited.

Recording a New Script

To clear the currently opened script and begin creating a new one, click the Open Script button and then touch the New button displayed above the Saved Script List.

Deleting a Saved Script

To delete a saved script, touch the Open Script button and then click the Edit button displayed above the Saved Script List. You may then delete a saved script by touching the associated Delete Icon.

Working with FoneMonkey Command Scripts

FoneMonkey plays FoneMonkey commands. For each kind of user interface action there is a corresponding command. Some examples of commands are Touch, Scroll, and Shake. (See the FoneMonkey Command Reference for a complete list).

User interface actions are directed to components. For example, you Touch a UIButton, or Scroll a UITableView to Row 5. FlexMonkey commands identify the action to be performed, and the component to receive the action. Components are identified by a combination of their Object-C class name (or superclass name) and a string identifier called a monkeyID.

All commands are written as:

CommandName ComponentType "MonkeyID" Parameters, ...

where

CommandName identifies the command to be executed.
ComponentType is the Objective-C class name of the component to receive the command. If componentType is omitted, it defaults to UIView (ie, any component).
"MonkeyID" is a quoted string that uniquely identifies which instance of the component's class should receive the command. If there is only one instance of a particular type, monkeyID may be omitted.
Parameters, .... are zero or more command-specific parameter values in CSV format.

By overriding recording and playback methods, it's easy to add your own commands to FoneMonkey or customize existing commands. See the FoneMonkey Extension Guide for more information.

Some Command Examples

Touch the "Done" button:

Touch UIButton "Done"

Touch the PaintingView at coordinate (25, 75):

Touch PaintingView 25, 75

Enter text into the "FirstName" field:

InputText UITextField "FirstName" fred

Identifying Components by ClassName and MonkeyID

As mentioned above, commands correspond to user interface actions, and actions are directed to components. For example, a command might specify to Touch a UIButton. If there is only one UIButton on the screen, FoneMonkey knows which button the command is referring to. If there are multiple buttons, however, we must tell FoneMonkey which one to use. In addition to the component's Objective-C classname, and a unique identifier called a monkeyID that's generated by FoneMonkey extensions for various UIKit classes. For any command, you can specify just a className or a monkeyID, or you can specify both.

Component Identification Examples

If there are multiple buttons on the screen:

Touch UIButton "Done"

If there is just one button on the screen:

Touch UIButton

If threre is just one button on the screen with a monkeyID of "Done":

Understanding MonkeyID's

FoneMonkey's UIView extensions provide the default monkeyID for all components. By default, the monkeyID of a component is the value of its accessbilityLabel property, if one exists, its tag property if it's non-zero, and otherwise FoneMonkey generates a unique identifier as explained below. Many component types provide specialized monkeyID's. For example, UIButton returns its titleLabel.text as its monkeyID, UITextField returns its placeholder value.

See the FoneMonkey Command Reference for a description of the monkeyID's returned by each component type.

If a component provides no monkeyID, FoneMoney generates an identifier by assigning an ordinal to each instance of each class on the screen FoneMonkey generated monkeyID's are prefix with a #-sign.

Examples of Generated MonkeyID's

Touch the first button:

Touch UIButton #0


Touch the second button:

Touch UIButton #1

Validating Tests with the Verify Command

You insert Verify commands into your script to validate during playback that actual results match expected ones. The Verify command has the following syntax:

Verify ClassName "monkeyID" propertyPath, expectedValue

As with all FoneMonkey commands, you can specify either ClassName or monkeyID or both to identify the component.

propertyPath is any valid key path to a property.
expectedValue is the expected value of the property identified by the propertyPath.

Verify Command Examples

Check that the last name label is "Smith"

Verify UILable "Last Name" text, Smith

Check that the button says "Hello"

Verify UIButton titleLabel.text, Hello

If a verify command fails, a message is displayed in the FoneMonkey Command List.

Inserting Pauses into a Script

By default, FoneMonkey pauses .5 seconds between commands during playback. Sometimes you may need a longer delay between commands, for example if an animation needs to finish running before a component is displayed.

You can insert pause commands to allow additional time between the execution of commands. It has the following syntax:

Pause milliseconds

where milliseconds is the number of milliseconds to pause before executing the next command.

The Pause command ignores class name and monkey ID, if any are supplied.

Pause Example

Pause for 1 second:

Pause 1000

FoneMonkey: New Fat Library

Thanks to some helpful advice from Victor Costan about building fat libraries, the latest FoneMonkey library can be used to build applications for both the iPhone device and simulator. The fat library contains code for both arm7 (iPhone) and i386 (simulator) architectures, so you can reference the same library binary from either your simulator of device builds. Note that the linker will strip out unreferenced code so the convenience of the single library does not come at the expensive of a bloated application binary.

The download is available here.

FoneMonkey: The Update

This release of FoneMonkey, the world's first and only free and open source testing automation tool for the iPhone, fixes various bugs, adds support for additional Cocoa Touch components, and can be run on an actual iPhone device in addition to the simulator.

The latest FoneMonkey download and release instructions can be found here.

We expect to have the official FoneMonkey project site online later this month!