Friday, January 22, 2010

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, ...


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

No comments: