MonkeyTalk Documentation

MonkeyTalk Documentation

DocumentationBelow you can find all you'll ever want or need to know about MonkeyTalk. If you're stuck or have a question, check out the MonkeyTalkFAQ. If you want a guided tour on installing and using MonkeyTalk's basic features, read the Quick Start. If you want more in-depthinformation about even those most obscure aspects of MonkeyTalk, the User Guide is for you. Finally, if you just want a few simplesummary of MonkeyTalk's functionality, you'll find all that and more in the Specification.

MonkeyTalk FAQGeneral

How does it all work?

MonkeyTalk is a complete functional testing platform for mobile applications. Currently, it supports testing native iOS and Androidapps. The platform has three fundamental pieces: the MonkeyTalk IDE, the MonkeyTalk Agent, and MonkeyTalk scripts.

MonkeyTalk IDE - desktop app for record/playback/creation of test scriptsMonkeyTalk Agent - library that must be added to app to enable testingMonkeyTalk scripts - beautiful, understandable, maintainable test scripts

First, you must link the appropriate agent into your app (see the MonkeyTalk Agent for iOS Installation Guide or the MonkeyTalkAgent for Android Installation Guide). Then you can use the IDE to record and playback tests. Just follow the MonkeyTalk QuickStart and you'll be testing in no time.

1.

Does it run on real hardware or only in the Simulator/Emulator?

Yes. MonkeyTalk can test apps running on real hardware, and it can also test apps running in the iOS Simulator or the AndroidEmulator. Furthermore, it can run on tethered devices and untethered devices connected to the network.

2.

Do I need to jailbreak or root my device?

Absolutely not. Testing an app with MonkeyTalk only requires the MonkeyTalk Agent to be installed into the app under test.

3.

Is it free?

Yes. MonkeyTalk is free to download and free to use.

4.

Is it open source?

Yes. MonkeyTalk is licensed under the GNU Affero General Public License v3 (AGPL v3) open source license. Additionally, wewelcome contributions from the community in the form of feedback and suggestions and especially patches.

The AGPL is basically identical to the GPL, but includes one very important additional provision that requires releasing the source ifyou modify MonkeyTalk for use on the server. The GPL permits making a modified version and letting the public access it on aserver without ever releasing its source code to the public. The AGPL closes this hole, such that public use of a modified version, ona publicly accessible server, gives the public access to the source code of the modified version. If you have any questions, read theAGPL v3 license and talk to your lawyer.

5.

Is it cross-platform? Can I record on iOS and playback on Android? Can I record on Android and playback on iOS?

Yes. If you have logically identical apps on iOS and Android, you should be able to record tests against one OS and play them backon another. Because MonkeyTalk records events at the highest level, logically identical apps do not have to be visually identical forcross-platform record and playback. For example, if your Android app uses the "hardware" back button and your iOS app uses a backbutton in the navigation bar, they are still logically identical. In both cases, recording on either OS would record a "Back" action, andplayback would work as intended.

6.

Can I test an app without the source code?7.

MonkeyTalk Documentation http://www.gorillalogic.com/book/export/html/2287

1 of 44 4/24/12 11:24 AM

No. You must install the MonkeyTalk Agent into the app under test during the build process, which requires access to the app sourcecode. But, once a MonkeyTalk-enabled build of the app has been created (either by a developer, or by some continuous integrationbuild job), you can test it using MonkeyTalk without any access to the source code.

Can I test 3rd party apps (Camera, Browser, etc.)?

No. Testing an app with MonkeyTalk requires the MonkeyTalk Agent to be installed in the app, which requires access to the app’ssource code.

8.

Can I test HTML5 web apps?

No. Our initial release of MonkeyTalk comes with an iOS Agent and an Android Agent. That being said, we understand theimportance of HTML5 apps, particularly in the mobile space. So don’t be surprised if you see an HTML5 Agent some time in thefuture.

9.

Can I test desktop apps? Windows Phone 7? BlackBerry? Flex Mobile?

No. Our initial release of MonkeyTalk comes with a native iOS Agent and a native Android Agent. That being said, we hope to addmore agents in the future.

10.

Can I test mobile games?

It depends. Most games rely on random number generators, which makes reliable functional testing difficult. In the future we mayrelease a version of MonkeyTalk that overrides random number generators and integrates with popular game engines, making testingmore reliable. You should still be able to test the non-random components of your game with MonkeyTalk if you use standard appcomponents.

11.

Can I test tablets or only phones?

Yes. MonkeyTalk can test apps running on all iOS devices (iPhone, iPad, iPod Touch) and most (all?) Android devices. If you havean iOS or Android device that doesn’t work with MonkeyTalk, please let us know about it.

12.

Can tests be fully automated? Can I run in CI? Can tests run outside the IDE? Can I run tests from the commandline?

Yes. MonkeyTalk tests can be run via Ant on the commandline -- see MonkeyTalk with Ant for details. We use Hudson/Jenkins asour CI server for running our internal tests and it works great. Most fully automated tests use the Simulator/Emulator to run the appunder test because it’s easy to guarantee a repeatable starting state.

13.

Can I publish a MonkeyTalk-enabled app into the store?

Maybe, but it’s definitely not recommended. Instead, we recommend you produce a MonkeyTalk-enabled app (an app with theMonkeyTalk Agent installed) only as a developer build.

14.

Can I test embedded web pages (UIWebView on iOS, WebView on Android)? Can I run Selenium tests against a web page?

No. Embedded web pages are completely opaque to MonkeyTalk and cannot be tested. We hope to address this in a future release.

15.

IDE

How do I record a test?

Open the IDE1.Create a new test project (right-click > New > MonkeyTalk Project) if you haven’t already.2.Create a new test script (right-click > New > Test)3.Connect to the app4.Click the record button5.Use the app and watch recorded commands coming in...6.

1.

How do I connect to the Emulator/Simulator?

Open the IDE1.Start up your Android or iOS emulator/simulator and load it with your MonkeyTalk enabled app.2.Click on the connection dropdown button on the tool bar (on initial start up it will be the green android icon).3.Choose "Android Emulator" or "iOS Simulator", depending on your platform of choice.4.

2.


2 of 44 4/24/12 11:24 AM

If connection was successful, a message to that effect should appear in the console.5.

How do I connect to a device?

Open the IDE1.Start up your Android or iOS device, load it with your MonkeyTalk enabled app, and let it connect to your wireless network.2.Click on the connection dropdown button on the tool bar (on initial start up it will be the green android icon).3.Choose "Networked Android or iOS device...".4.Enter the IP address of the mobile device.5.If connection was successful, a message to that effect should appear in the console.6.

3.

I'm having device connection issues. Record doesn't work on a device. Help?

Connection issues are pretty common, so you're not alone. Here's a quick tip that everyone should follow to help resolve connectionissues to real devices:

The PC running the MonkeyTalk IDE and the device running the app under test MUST be on the same wifi network.

This not really true, but unless you or your network engineer have a good understanding of subnets, routers, NATing, etc. it isprobably easiest to just be on the same wifi network. Also, if you are having connectivity issues with devices, we recommendbeginning your testing adventures in the Simulator/Emulator as it is a little easier to get started and the odds of connection issues arebasically zero.

4.

iOS Agent

What versions of iOS are supported?

The MonkeyTalk Agent for iOS requires iOS 4.0 or greater. If you have a version of iOS that doesn’t work with MonkeyTalk, pleaselet us know about it.

1.

How do I install the MonkeyTalk Agent in my iOS app?

See the MonkeyTalk Agent for iOS Installation Guide.

2.

Can I test on a tethered iOS device without Wi-Fi?

No. MonkeyTalk tests can only run over the network to real iOS devices, even if they are tethered. If you are in a location withoutWi-Fi, you can only test on the Simulator.

3.

Do I need to put accessibilityLabel on all of my components?

No, but it is recommended. MonkeyTalk does it’s best to pick a understandable monkeyId when recording, but it’s even better to set itto a known value.

4.

I'm seeing a crazy dyld: Library not loaded: /usr/lib/libc++abi.dylib error trying to run on the Simulator 4.3. Whatgives?

Apparently there's a missing library. We recommend downloading libc++abi.dylib found here and just copy it into /usr/lib .

5.

Can I test iOS app on Windows PC?

Yes. You must use Mac hardware to develop the app and compile it the MonkeyTalk Agent. But once that is done, you can use anover-the-air app distribution mechanism (like TestFlight) to publish the app to any iOS device. Your testers can then run theMonkeyTalk IDE on a Windows PC and connect to their iOS device over the network. They can then record and playback tests asusual -- all from a Windows PC.

6.

Android Agent

What versions of Android are supported?1.


3 of 44 4/24/12 11:24 AM

The MonkeyTalk Agent for Android requires Android 2.2 (Froyo) or greater. If you have a version or vendor flavor of Android thatdoesn’t work with MonkeyTalk, please let us know about it. New Android releases frequently include new UI components, and whilewe endeavor to support recording and playback on all standard UI components, we sometimes miss a few. So, please let us knowabout any stock components that don’t work.

How do I install the MonkeyTalk Agent in my Android app?

See the MonkeyTalk Agent for Android Installation Guide.

2.

Can I run MonkeyTalk tests against a debug version of the app under test? Why is Android playback so slow?

Yes, it can be very useful to run MonkeyTalk tests with breakpoints in the app under test. When running a debug version of the appunder test in the Emulator, be aware that the app can appear extremely slow in some cases (10+ seconds per command). Since theslowdown appears to be Emulator and adb related, we highly recommend running on real hardware

3.

Can I test on a tethered Android device?

Yes. Sometimes just unplugging and re-pluging a tethered device will help it connect. You can not run tests on a tethered devicewhile the Emulator is running or vice versa. Lastly, if testing on a tethered device is an issue, testing works great on a un-tethereddevice over the Wi-Fi network.

4.

Do I need to put contentDescription on all of my components?

No, but it is recommended. MonkeyTalk does it’s best to pick a understandable monkeyId when recording, but it’s even better to set itto a known value.

5.

I can't get the MonkeyTalk Android demo to work! What's wrong?

These are the steps you should follow to get the MonkeyTalk Android demo working properly: 1) In Eclipse, File > Import... >choose Existing Projects into Workspace > Navigate to the Android project demo1. 2) Right click on project > Properties > checkEnable project specific settings > pick Compiler compliance level: 1.6.

6.

MonkeyTalk Scripts

What is the MonkeyTalk functional testing language?

MonkeyTalk is a powerful functional testing language. MonkeyTalk is keyword-driven -- you can directly add new commands to thelanguage. MonkeyTalk is data-driven -- any command can be looped with CSV data file. MonkeyTalk is readable -- commands arerecorded at the highest level (tap a button, select a row from a table, check a checkbox). MonkeyTalk is maintainable -- scripts arereadable so it's easy to update them when the app is updated.

1.

Can I see a brief example of a MonkeyTalk script?

Here’s a simple login script (enter credentials then click the button):

Input username EnterText [email protected] password EnterText "my secret password"Button LOGIN Tap

Next, here’s a parametrized version of the same script:

Vars * Define usr pwdInput username EnterText ${usr}Input password EnterText ${pwd}Button LOGIN Tap

Here’s how to invoke the parameterized login script from another script:

Script login.mt Run [email protected] "my secret password"

For many more examples, see the MonkeyTalk Spec.

2.

Do I have to use the MonkeyTalk IDE?

No. While the IDE contains many nice features for record, playback, test debugging, test creation, etc., it’s not necessary. You caneasily create MonkeyTalk scripts in your favorite text editor and play them back via Ant. See MonkeyTalk with Ant for details.

3.


4 of 44 4/24/12 11:24 AM

Can I convert MonkeyTalk test scripts into Javascript?

Yes. Furthermore, MonkeyTalk supports selective Javascript overrides at the individual script level, so you can have most of yourtests in MonkeyTalk and just those that demand a full programming language in Javascript.

4.

Can I see a brief Javascript example?

Here's the Javascript version of the simple login script from above:

var app = new MT.Application("localhost",16862);app.input("username").enterText("[email protected]");app.input("password").enterText("my secret password");app.button("LOGIN").tap();

5.

What other language bindings does MonkeyTalk support?

Currently, MonkeyTalk test scripts can be converted to Javascript. No other language bindings are supported.

6.

MonkeyTalk Quick Start

Quick StartThe Quick Start is for users who want to get up and running with MonkeyTalk and play around with its most commonly used features asquickly as possible.

IDE Install

Install the MonkeyTalk IDE

Download the zip file here. This download contains the IDE, the Agents (which you will need for the next step), and sampleapplications.

1.

Unzip it wherever you want, but remember where you put it because you'll need it later.2.On OS X, move the entire MonkeyTalkIDE folder into your applications folder and double click on MonkeyTalk.app to run.3.On Windows, move the entire MonkeyTalkIDE folder into your Program Files folder and double click on MonkeyTalk.exe to run.(Note: If you choose to put MonkeyTalkIDE in your Program Files folder, you will have to choose a different location for yourworkspace.)

4.

Copy this folder to your ideal destination.

Next step: Install the MonkeyTalk Agent.

Agent InstallHow to Install the MonkeyTalk Agent


5 of 44 4/24/12 11:24 AM

If you want to jump right in to MonkeyTalk, you can try out our sample apps. You can find the apps in the samples directory of theMonkeyTalk installation zip file. These applications already have the MonkeyTalk agent installed, so you can load them up and skip right toConnecting Your Device. Otherwise, if you want to set up MonkeyTalk with your own application, please continue with this step.

You can find the Agents in the Agents folder in the MonkeyTalk installation zip file, each in their individual folders labeled "iOS" and"Android. Installing the MonkeyTalk Agent is unique for each mobile platform. To proceed, pick either Android or iOS for specificinstructions.

iOS

Installing the MonkeyTalk iOS Agent

1. Download and unzip the MonkeyTalk zip file for your OS.

2. Open your application's project in Xcode.

3. Duplicate your application's build target by right-clicking on it and selecting Duplicate from the menu. A new target will be createdcalled YourApp copy.

Rename YourApp copy to something like YourAppMonkey.


6 of 44 4/24/12 11:24 AM

so it looks like this:

You may also want to rename the Scheme from the Manage Schemes window:


7 of 44 4/24/12 11:24 AM

4. Add the downloaded MonkeyTalk lib to your project File > Add to “YourApp”... from the menu.


8 of 44 4/24/12 11:24 AM

5. When the dialog box appears, navigate to the directory where you unzipped the MonkeyTalk zip file, and select the MonkeyTalk iOS libfrom pathToMonkeyTalkFolder/agents/iOS.

6. Recursively create groups for any added folders option. Note: It is up to you whether or not you want to Copy items into destinationgroup's folder.

7. In the Add to Targets box, deselect YourApp and select YourAppMonkey.


9 of 44 4/24/12 11:24 AM

8. Click Add.

9. The MonkeyTalk lib should now be visible in your project.

Configuring Libraries and Build Settings1. Right-click on the YourAppMonkey build target, and select the Build Phases tab.

2. On the Link Binaries With Libraries tab, you will need to add libsqlite3.dylib CFNetwork.framework andQuartzCore.framework if your application is not already using them. (These frameworks are required by the MonkeyTalk).

3. XCode will have added references to the libMonkeyTalk.a library.

4. On the Build Settings tab, scroll down to the Linking section and add to your Other Linker Flags: -all_load -lstdc++


10 of 44 4/24/12 11:24 AM

5. Choose your duplicated test target from the Scheme menu in Xcode and Run on the Simulator or Device.

Log output will show that MonkeyTalk has successfully loaded in your app (as seen below)


11 of 44 4/24/12 11:24 AM

Android

Installing the MonkeyTalk Android Agent

Open your Android Project in Eclipse and follow these instructions.

Convert your Android project to AspectJ1.

MonkeyTalk-agent.jar can be found in the "agents" folder in the MonkeyTalk package you downloaded earlier, and can bedownloaded here. The exact name of the jar might vary depending on the version, but it should always start with "MonkeyTalk-agent".

2.

Create a "libs" folder in your Android project, if you don't already have one.3.Copy the .jar into the libs folder4.Right click on MonkeyTalk-agent.jar > AspectJ Tools > Add to Aspectpath.5.

Update your AndroidManifest.xml to include the following two permissions:android.permission.INTERNET1.android.permission.GET_TASKS2.

6.


12 of 44 4/24/12 11:24 AM

Deploy your application to an Android device or emulator.7.

Creating a Testing ProjectA MonkeyTalk Project is a folder that contains all your test scripts, suites, and reports.

The first time you start MonkeyTalk, the Welcome Page will be displayed.

Tip: You can return to the Welcome Screen by selecting Help > Welcome from the main menu.

Click on the Create Your First Project. The New Project wizard will be displayed.

Enter a name for your project and click Finish. The workbench window will open.


13 of 44 4/24/12 11:24 AM

To create a test script, right-click on the project folder and select New > Test. The MonkeyTalk test editor will open with a new empty test.


14 of 44 4/24/12 11:24 AM

You are now ready to begin recording.

ConnectConnecting to Emulator, Simulator, or Hardware

Android Emulator / iOS Simulator

Open the IDE1.Start up your Android or iOS emulator/simulator and load it with your MonkeyTalk enabled app.2.Click on the connection dropdown button on the tool bar (on initial start up it will be the green android icon).3.

Choose "Android Emulator" or "iOS Simulator", depending on your platform of choice.If you are connecting to an Android device for the first time, you will be prompted to point the MonkeyTalk IDE to your localAndroid SDK. Check the "Include Android Testing?" checkbox and point it to the SDK. You can also set this in yourMonkeyTalk Preferences.

1.4.



15 of 44 4/24/12 11:24 AM

Android and iOS Hardware

Open the IDE1.Start up your Android or iOS device, connect it to your local wireless network, and load it with your MonkeyTalk enabled app.2.Click on the connection dropdown button on the tool bar (on initial start up it will be the green android icon).3.Choose "Networked Android or iOS device...".4.Enter the IP address of the mobile device.5.If connection was successful, a message to that effect should appear in the console.6.

Record

Recording through the MonkeyTalk IDE

Connect to your device.1.Pull up your application on the device.2.Click “Record” on the MonkeyTalk IDE. If “Record” is not active, then double check that you are connected to your device byclicking on the “Connect” button.

3.

Interact with your application. MonkeyTalk should record the actions you took as a script.4.To stop recording, click the “Stop” button.5.

If the Record button is not lighting up, it may be one of two things:

You are not properly connected to a device. To read more on connecting to a device, go here.1.Your application is not properly set up for MonkeyTalk. To read more on installing the MonkeyTalk agent and setting your app upcorrectly, go here.

2.

Playback

Playing Back a Recorded MonkeyTalk Script

Restart your app. (Not necessary, but useful for starting at the same point as before.)1.Click the “Play” button. It should repeat the actions in your script.2.

Editing Scripts

You can currently edit MonkeyTalk script in two different ways: through the table view and through the MonkeyTalk view. The Table Viewprovides assistance with creating MonkeyTalk commands, and is ideal for new users. The MonkeyTalk view is intended formore-experienced users and provides for editing MonkeyTalk commands directly with a text editor.


16 of 44 4/24/12 11:24 AM

To edit through the table view, right click on the table and choose "Append row." Click in each cell to enter your new command. Youcan also use the drop down menus to select from a list of options.

1.

To edit through the MonkeyTalk view, switch to the MonkeyTalk tab and edit the textual commands directly.2.

If you wish to know more about MonkeyTalk commands, you can start by reading about the Command Syntax or the User Guide entry forPlayback.

Verify

Verification in MonkeyTalk

During script playback, MonkeyTalk verifies that each referenced UI component exists and then executes the associated action. If anexpected component doesn't exist, MonkeyTalk will report a script failure. For example, if your script attempts to tap on an OK button, andno OK button is currently displayed, the script will fail.

Additionally, you can use MonkeyTalk's Verify commands to add explicit verification steps to your script to check that expected valuesmatch actual ones.

For example,

Perform an action through recording or editing the MonkeyTalk script.1.Check that the action was performed correctly with a verify. This is a very simple example, and you can do much more with creativeverifies. Suppose we have an application where the user can set a value using a Slider control, and there is an associated label thatshows the selected value. The following script moves the slider to the value 8000 and then tests that the label has updated.

2.

#set slider to 8000Slider * Select 8000

#verify that label called "CurrentValue" displays 8000Label CurrentValue Verify 8000

Now run the script as normal by pressing the Play button. The script's success or failure is reported in the console.1.

You can do more than just Verify for simple values. Read the Test Specification or the User Guide entry for Tests for more information.

Next StepsCongratulations on learning how to setup your application and how to record, playback, and add verification steps to a test script.

See the MonkeyTalk User Guide to learn about additional MonkeyTalk capabilities including:

Creating test suitesExtending MonkeyTalk with custom commandsParameterizing scripts to create reusable test componentsData-driving scripts with CSV filesExtending MonkeyTalk with JavaScriptIntegrating MonkeyTalk tests into build and continuous integration environments


17 of 44 4/24/12 11:24 AM

MonkeyTalk Spec

MonkeyTalk 1.0MonkeyTalk is a functional testing language composed of a simple set of commands for user interface scripting. It’s easy enough to be usedby QA engineers and requirements analysts with little or no programming experience. Scripts can be created from scratch as simple textfiles, or can be created automatically by recording tools such as the MonkeyTalk IDE.

MonkeyTalk is platform neutral and defines a logical API that can be easily implemented with any standard programming language.

Command Syntax

Command SyntaxThe syntax has been designed to be easily understood by non-programmers. It’s fairly readable and straightforward to specify manuallyusing a simple text file editor or even a spreadsheet. Additionally, MonkeyTalk has been designed to be displayed and edited within tabularconsoles such as the MonkeyTalk IDE.

MonkeyTalk commands are newline terminated and have the following syntax:ComponentType MonkeyId Action Args… Modifiers…

Collectively, ComponentType, MonkeyId, Action, Args, Modifers are known as command parts. Furthermore, ComponentType.Action isknown as the command name.

ComponentType (required) – The type of component on which to perform the action. Examples include Button and TextArea. Componenttypes are not case sensitive. ComponentTypes can extend other ComponentTypes, as described below, and inherit any defined actions aswell as Arguments. ComponentTypes are typically the logical name of the UI component (like Button rather than UIButton), but can alsohave platform-specific aliases. ComponentType may be specified as an asterisk (*), which essentially means any component.

MonkeyId (required) - An identifier that is used to distinguish between components of the same type being displayed simultaneously.MonkeyId can be specified as asterisk (*), which finds the first matching component.

MonkeyId’s can also be specified as a 1-based (not zero-based) index of the form #N. In this case, the MonkeyId identifies the Nthcomponent of the specified type that’s currently displayed. Components are indexed according to upper-left-most position, i.e., by sortingcomponents by (x,y) coordinate.

Action (required) – The action to be performed. Examples include Tap, Select, and EnterText. Actions are not case sensitive.

Arguments/Args (required according to ComponentType and Action) – A space-separated list of one or more arguments. Arguments areassumed to begin at the fourth token. Although always specified as strings, args are interpreted as necessary by the command. If anArgument is required but not specified (left off the end of the list), it takes on a default value. An Arg may be specified as an asterisk (*) toforce it to take on it’s default value,

Modifiers… (optional) - A space-separated list of named arguments of the form %name=value, where the % prefix identifies it as aModifier. There are three system-defined modifiers:

%timeout - how long in ms to continue retrying a command before timing out%thinktime - how long in ms to wait before executing the command for the first time%retrydelay - how long in ms to delay between retry attempts

Command Examples

Command ExamplesAll tokens are space-separated. Values with embedded blanks must be enclosed in quotes. Embedded quotes are escaped with backslash, asis backslash itself.

Tap on the Button with the label “OK”:


18 of 44 4/24/12 11:24 AM

Button OK Tap

Use a numbered MonkeyId to tap on the first button:Button #1 Tap

No MonkeyId, so it defaults to #1:Button * Tap

No ComponentType or MonkeyId, so tap on the first component:* * Tap

With some args and embedded blanks:Input address EnterText “123 Main St.”

MonkeyIds and Args are case-sensitive, but CommandTypes and Actions are not:input address ENTERTEXT “123 Main St.”

Using the timeout Modifier:Input address Verify “123 Main St.” %timeout=5000

Comments can be specified by beginning a line with a #, for example:# this is a comment# another commentButton OK Tap

Newlines are specified as \n, for example:Input shipping EnterText “John Smith\n123 Main St.\nAnytown, USA 12345”

Scripts

ScriptsPut one or more MonkeyTalk commands in a file and save it with .mt file extension and now you have a MonkeyTalk Script.

For example, a login.mt script might look like this:

# simple script to login as joeInput username EnterText [email protected] password EnterText “i like cheese”Button LOGIN Tap

From within another script, we can invoke our login.mt script using the Script command with the file name as the MonkeyId, like this:Script login.mt Run

Variables

VariablesScripts may contain named substitution variables which are written as ${name} and can be specified anywhere in a MonkeyTalk command.They may also contain built-in variables, written as %{var}. The available built-in variable are %{componentType}, %{monkeyId},%{action}, and any args are %{1}, %{2}, etc. Variables may only be used within a command part, so inside ComponentType, MonkeyId,etc.

For example, a named variable can be used for the Arg:Input username EnterText ${usr}

Or the Arg and the MonkeyId:Input ${foo} EnterText ${bar}

Or even everything:${foo} ${bar} ${baz}

Variables can be embedded inside some text, but not within another variable, for example:Input username EnterText ${usr}@example.com


19 of 44 4/24/12 11:24 AM

But this would be illegal (a variable within a variable):Input username EnterText ${foo${bar}}

Parameterized Scripts

Parameterized ScriptsUsing the Vars.Define command we can specify named variables and their default values for a script. Let’s parameterize our login.mt scriptlike this:

Vars * Define usr="default-at-example.com" pwdInput username EnterText ${usr}Input password EnterText ${pwd}Button LOGIN Tap

We set up two named variables, ${usr} and ${pwd}, and set the default value of ${usr} to default-at-example.com. The default value of${pwd} is unspecified, so it defaults to <pwd> (the name of the variable surrounded by angle brackets).

We can invoke our parametrized login.mt script like this:Script login.mt Run joe-at-doe.com "i like cheese"

Or leave off the Args to use the default values:Script login.mt Run

Or use just the default value for ${usr} with an asterisk:Script login.mt Run * password1

Also note that variables are limited to the script in which they are defined, so ${usr} and ${pwd} are relevant only inside login.mt, unless ofcourse, you use variables when invoking a child script.

Data-driven Scripts

Data-driven ScriptsParametrized scripts are just the beginning, MonkeyTalk allows for full data-driven scripts simply by using the RunWith action instead ofRun, and setting a data file as the first Arg.

Using our parametrized login.mt script, we first write a data file, credentials.csv, in CSV format like this:

usr, pwdjoe-at-doe.com, "i like cheese"alpha-at-beta.net, password1charlie-at-dog.org, abc123

Where the first row specifies the variable names (exactly as they are named in the Vars.Define command in login.mt), and the followingrows give the values.

Now, we can data-drive our script like this: Script login.mt RunWith credentials.csv

This will run the login.mt script once for each row of data in the data file. So in the case of the above credentials.csv data file, it wouldinvoke login.mt three times, first with usr = joe-at-doe.com and pwd = "i like cheese", second with usr = alpha-at-beta.netand pwd = password1, and third with usr = charlie-at-dog.org and pwd = abc123.

Custom Commands

Custom CommandsThe MonkeyTalk language can be extended directly by adding new custom commands with custom ComponentTypes and custom Actions.Any script saved with a two-part filename, in the form of <componentType>.<action>.mt, becomes a custom command. For example, if


20 of 44 4/24/12 11:24 AM

we renamed login.mt to login.perform.mt we would add a new Login component type that has a Perform action.

And we invoke our new custom command in the standard fashion:login * perform

And we can pass in arguments, because our command is still parameterized:login * perform [email protected] "i like cheese"

We can still invoke it as a script:Script login.perform.mt Run [email protected] "i like cheese"

And we can still data-drive it:Script login.perform.mt RunWith credentials.csv

This type of script invocation, known as a custom command, is incredibly powerful as it allows MonkeyTalk to be arbitrarily extended. Thecustom command syntax effectively enables testers to build up a library of application-specific commands.

Tests

TestsA test is just the invocation of a script with the Test componentType instead of Script. Test results are written to a report file in thestandard JUnit-compatible xml report format.

The successful execution of each command verifies the existence of some expected user interface component. In addition, you canexplicitly test that actual values of components match expected ones by adding Verify actions to your script. First, we again rewritelogin.mt to include some Verify actions like this:

Vars * Define usr="default-at-example.com" pwd nameInput username EnterText ${usr}Input password EnterText ${pwd}Button LOGIN TapLabel welcome Verify "Welcome, ${name}!"Button LOGOUT Verify

Now, we can run login.mt as a test like this, but note that we need a third argument since we added a third named variable, ${name}, to helpverify a successful login:Test login.mt Run joe-at-doe.com "i like cheese" "Joe Doe"

And we can data-drive our test just as you would expect (again note that we need to add a third column to credentials.csv):

Test login.mt RunWith credentials.csv

VerifyThe Verify action exists on all components (except Script and Device) and is used to check if the actual value matches the expected value.In its base form, verify accepts three optional arguments: expectedValue, propPath, and failMessage.

Without any parameters Verify just verifies the existence of the given component:

Button LOGIN Verify

With just an expectedValue, Verify checks the component’s value, where value is just the logical value of the component (value of aButton is its label, value of an Input is its text, value of a CheckBox is "on" or "off", etc.):

Button LOGIN Verify LOGIN

With an expectedValue plus a propPath, Verify checks the given component property. Some propPaths such as value and item arelogical MonkeyTalk-specific property paths and are supported cross-platform (they don't begin with a dot). Component-specific propPath'sare platform-specific (and always begin with a dot).

Verify the font name on an iOS Button:Button LOGIN Verify Helvetica .font.fontName

Verify the total number of stars on an Android RatingBar:


21 of 44 4/24/12 11:24 AM

RatingBar reviewRating Verify 5 .numStars

And the failMessage just provides extra feedback if the Verify fails:Input username Verify joe-at-doe.com value "bad username!!!"

Suites

SuitesTests only be run from a suite, and only a suite can contain tests. Furthermore, suites must have the .mts file extension to distinguish themfrom scripts. Suites may only contain Test, Setup, and Teardown component types, and also comments.

For example, the suite, myapp.mts, might look like this:

# setup runs before every testSetup login.mt Run [email protected] “i like cheese”

# teardown runs after every testTearDown logout.mt Run

# the tests...Test add_contact.mt RunWith contacts.csvTest remove_contact.mt RunWith contacts.csv

Here we use Setup and Teardown commands to specify scripts to be run before and after every Test command invocation.

Command Execution

Command ExecutionUnless otherwise specified, MonkeyTalk commands are automatically retried until the timeout is reached. The timeout value has a globaldefault value of two seconds, but it can be overridden on a per command basis by using the timeout Modifier.

For example:Button OK Tap %timeout=5000 %thinktime=2000 %retrydelay=123

Which will wait for 2 seconds, before trying to tap the OK button, then retry every 123ms before timeout eventually occurs after 5 seconds(7 total seconds after the command started playback).

Javascript

JavascriptExporting to Javascript is intended as a tool for introducing common programming contructs into MonkeyTalk. This could include thingslike loops, control statments, and random numbers.

To export to Javascript, create a MonkeyTalk script and click on the "JavaScript" tab at the bottom of the viewer. There you will find an"Export" button. Click that button and MonkeyTalk will create a .js file with the same name as the .mt file. (E.g. Login.mt -> Login.js).

To execute the new Monkeytalk-Javascript file, run it just like you would a normal MonkeyTalk script, like so:

Script Login.js Run

You can also run it without the file extension. Running a script without an extension will always default to running the Javascript, if oneexists.

Script Login Run

Once a MonkeyTalk script is exprted to Javascript, the user is free to edit it however they like. For example, here is a script that enters arandom username and password if none are provided:


22 of 44 4/24/12 11:24 AM

if (typeof Test == "undefined") {load("libs/Test.js");

};

Test.Login.prototype.run = function(usr, pwd) {usr = usr || randStr();pwd = pwd || randStr();

this.app.input("username").enterText(usr);this.app.input("password").enterText(pwd);this.app.button("LOGIN").tap();

};

function randStr(){ var text = ""; var possible = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";

for( var i=0; i < 5; i++ ) text += possible.charAt(Math.floor(Math.random() * possible.length));

return text;}

Javascript API

Javascript APIHere is a list of all MonkeyTalk components for Javascript. All components inherit from View and thus inherit all of View's actions too.

In most cases when you export to Javascript, your MonkeyTalk script will have a 1:1 correlation. That is, "Button LOGIN Tap" will convertto "this.app.input("LOGIN").tap();".

Buttoninherited from View

ButtonSelectorselect(value:String):void - Select an item by value.

value - the value of the item to select.selectIndex(itemNumber:int):void - Selects an item by index.

itemNumber - the index of the item to select.longSelectIndex(itemNumber:int):void - Long press an item by index.

itemNumber - the index of the item to long press.inherited from View

CheckBoxinherited from View

DatePickerenterDate(date:String):void - Change the current date value.

date - A date with the format YYYY-MM-DD where YYYY is the year, MM is the month (01-12), and DD is the day(01-31).

inherited from ViewDevice

shake():void - Shake the device.rotate(direction:String):void - Change the device orientation.

direction - Left or Right (case insensitive)back():void - Navigate back. iOS: Pops the current UINavigationItem (if there is one). Android: Presses the hardware devicekey.forward():void - Navigate forward. iOS: Pushes the next UINavigationItem, if there is one. Android: ignored.search():void - Press the search key. iOS: ignored. Android: Presses the device search key.menu():void - Press the menu key. iOS: ignored. Android: Presses the device menu key.

Docvars(args:String):void - Document the named variables used in the script.


23 of 44 4/24/12 11:24 AM

args - the named variables and their doc, in the form of: var='some doc' var2='other doc'script(doc:String):void - Document the script itself.

doc - the docIndexedSelector

selectIndex(itemNumber:int):void - Selects an item by index.itemNumber - the index of the item to select.

longSelectIndex(itemNumber:int):void - Long press an item by index.itemNumber - the index of the item to long press.

inherited from ViewInput

enterText(text:String, hitDone:boolean):void - Enter text into the input field.text - the text to enterhitDone - iOS: if true, hit Done key after entering text. Android: ignored.

clear():void - Clear text from the input field. iOS: Clears the field. Android: ignored.inherited from View

ItemSelectorselect(value:String):void - Select an item by value.




Labelinherited from View

Menuselect(value:String):void - Select an item by value.




NumericSelectorselect(value:float):void - Select a numeric component value

value - the value to selectinherited from View

RatingBarselect(value:float):void - Select a numeric component value


Scriptrun(args:String):String - Run the script with the given args.

args - the argumentsrunWith(args:String):void - Data-drive the test script with the given CSV data file.

args - the arguments (where the first arg is the data file filename)Scroller

scroll(x:int, y:int):void - Scroll to the specified coordinates.x - the x-coordinate (horizontal)y - the y-coordinate (vertical)

inherited from ViewSetup

run(args:String):String - Run the setup script with the given args.args - the arguments

runWith(args:String):void - Data-drive the setup script with the given CSV data file.args - the arguments (where the first arg is the data file filename)

Sliderselect(value:float):void - Select a numeric component value


TabBarselect(value:String):void - Select an item by value.

value - the value of the item to select.


24 of 44 4/24/12 11:24 AM



inherited from ViewTable

selectRow(row:int, section:int):void - Select a row.row - the row to selectsection - the section containing the row. (Ignored on Android)

scrollToRow(row:int, section:int):void - Scroll to a row by row number.row - the row to selectsection - the section containing the row. (Ignored on Android)

scrollToRow(value:String):void - Scroll to a row by value.value - the value of the row to scroll to.

setEditing(enabled:boolean):void - Enable/disable table editing. iOS: Enabled editing mode for table. Android: ignored.enabled - if true, enable editing, else disable editing.

insert(row:int, section:int):void - Insert a row into the table. iOS: Inserts a row. Android: Ignored.row - the index of the row after which to insert a new row.section - the section containing the row.

remove(row:int, section:int):void - Remove a row from the table. iOS: Deletes the row. Android: Ignored.row - the index of the row to be removed.section - the section containing the row.

move(from:int, to:int):void - Move a row. iOS: Moves a row. Android: Ignored.from - the index of the row to be moved.to - the destination row for the move.

select(value:String):void - Select an item by value.value - the value of the item to select.



inherited from ViewTeardown

run(args:String):String - Run the teardown script with the given args.args - the arguments

runWith(args:String):void - Data-drive the teardown script with the given CSV data file.args - the arguments (where the first arg is the data file filename)

Testrun(args:String):String - Run the test script with the given args.

args - the argumentsrunWith(args:String):void - Data-drive the test script with the given CSV data file.

args - the arguments (where the first arg is the data file filename)TextArea



Toggleinherited from View

ToolBarselectIndex(itemNumber:int):void - Selects an item by index.



Varsdefine(args:String):void - Define the named variables used in the script.

args - the named variables (and optional default value), in the form of: var1 var2=defaultVideoPlayer

play():void - Play the video from the current playback point.pause():void - Stop the video at the current playback point.stop():void - Stop the video and set playback to the starting point.


25 of 44 4/24/12 11:24 AM

inherited from ViewView

verify(expectedValue:String, propPath:String, failMessage:String):void - Verifies that a property of the component hassome expected value.

expectedValue - the expected value of the property. If null, verifies the existence of the component.propPath - the property name or property path expression (defaults to 'value')failMessage - the custom failure message

verifyNot(expectedValue:String, propPath:String, failMessage:String):void - Verifies that a property of the componentdoes not have some value.

expectedValue - the value the component shouldn't have. If null, verifies the non-existence of the component.propPath - the property name or property path expression (defaults to 'value')failMessage - the custom failure message

verifyRegex(regex:String, propPath:String, failMessage:String):void - Verifies that a property of the component matchessome regular expression.

regex - the regular expression to matchpropPath - the property name or property path expression (defaults to 'value')failMessage - the custom failure message

verifyNotRegex(regex:String, propPath:String, failMessage:String):void - Verifies that a property of the component doesnot have a value matching a regular expression.

regex - the regular expression that should not match.propPath - the property name or property path expression (defaults to 'value')failMessage - the custom failure message

verifyWildcard(wildcard:String, propPath:String, failMessage:String):void - Verifies that a property of the componentmatches some wildcard expression.

wildcard - the wildcard expression to matchpropPath - the property name or property path expression (defaults to 'value')failMessage - the custom failure message

verifyNotWildcard(wildcard:String, propPath:String, failMessage:String):void - Verifies that a property of the componentdoes not have a value matching some wildcard expression.

wildcard - the wildcard expression that should not matchpropPath - the property name or property path expression (defaults to 'value')failMessage - the custom failure message

tap():void - Taps on the component. On Android, plays a 'click'. On iOS, plays a TouchDown/TouchMove/TouchUp sequence.longPress():void - Performs a long press on the component. On Android, plays a 'longClick'. On iOS, plays a longPushgesture.touchDown(x:int, y:int):void - Start touching the component.

x - x-coordinate of the touchy - y-coordinate of the touch

touchMove(coords:int):void - Drag across the componentcoords - one or more (x,y) coordinate pairs specifying the path of the drag gesture

touchUp(x:int, y:int):void - Stop touching the component.x - x-coordinate of where touch is releasedy - y-coordinate of where touch is released

pinch(scale:float, velocity:float):void - Pinch the component.scale - The scale factor relative to the points of the two touches in screen coordinatesvelocity - The velocity of the pinch in scale factor per second (read-only)

swipe(direction:String):void - Swipe the component.direction - Left, Right, Up, or Down (case insensitive)

drag(x1:int, y1:int, x2:int, y2:int):void - Touch down, drag across the component, then upx1 - starting x-coordinatey1 - starting y-coordinatex2 - ending x-coordinatey2 - ending y-coordinate

get(variable:String, propPath:String):String - Gets the value of the given property from the component, and set it into thegiven variable name.

variable - the name of the variable to setpropPath - the property name or path expression (defaults to 'value')

exec(method:String, args:String):String - Call a method on a component. The method must take zero or more Stringarguments and return a String result.

method - the method to callargs - the String args to be supplied to the method


26 of 44 4/24/12 11:24 AM

Javascript Lib

Javascript Scripts

MonkeyTalk Wire Protocol

MonkeyTalk Wire ProtocolMonkeyTalk uses a simple HTTP protocol for recording and playback. All requests are HTTP POSTs to the url, http://<host>:<port>/monkeytalk, with a JSON payload. Additionally, all responses return a JSON payload.

Definitions:

Remote - this is the MonkeyTalk IDE side of the wire, typically running on a PCAgent - this is the app under test side of the wire, typically a mobile device or a PC running a simulator/emulator

There are only three commands that travel the wire:

PING - sent from remote to agent. A ping command sends recording status (ON or OFF) and expects just an OK or an OK plus somedevice metadata. This command is typically sent as a heartbeat every few seconds.PLAY - sent from remote to agent. A play command sends a MonkeyTalk command to be played back by the app under test. Itexpects an OK, ERROR, or FAILURE, plus a message.RECORD - sent from agent to remote. A record command sends a MonkeyTalk command to be recorded by the test recorder. Itexpects an OK.

PLAYPLAYJSON payload:

{

mtversion:1,mtcommand:"PLAY",componentType:"Button",monkeyId:"OK",action:"Tap",args:["17","33"],modifiers:{timeout:"123",thinktime:"654"

}

}

mtversion “1”, currently the only possible value

mtcommand “PLAY” for playback

componentType the MonkeyTalk componentType as a String

monkeyId the MonkeyTalk monkeyId as a String


27 of 44 4/24/12 11:24 AM

action the MonkeyTalk action as a String

args (optional) the MonkeyTalk argument list as an JSON Array

modifiers (optional) the MonkeyTalk modifiers as a JSON Hash with String keys and String values

Returns:

{

result:"OK",message:"Some message"

}

result either OK, ERROR, FAILURE where FAILURE only occurs on a failed Verify action

message (optional) usually blank on OK (except for the Get action), otherwise contains an error description

PINGPINGJSON payload:

{

mtversion:1,

mtcommand:"PING",

record:"ON"

}


mtcommand “PING” for ping

record either ON to start recording (or to alert the agent that recording is in progress) or OFF to stop recording

recordhost (optional) tells the agent where to send recorded commands

recordport (optional) tells the agent where to send recorded commands

Returns:

{

result:OK,message:{ os:"iOS", record:"ON", ...more... }

}


28 of 44 4/24/12 11:24 AM

result either OK or ERROR

message on OK return the OS (either iOS or Android) and the current record state (either ON or OFF); on ERROR return the errordescription

RECORDRecordJSON payload:{

mtversion:1,mtcommand:"RECORD",componentType:"Button",monkeyId:"OK",action:"Click",args:["17","33"],modifiers:{thinktime:"654"

},timestamp:1328806752

}

timestamp (optional) the Unix timestamp when the command is sent


mtcommand “RECORD” for recording

componentType the MonkeyTalk componentType as a String

monkeyId the MonkeyTalk monkeyId as a String

action the MonkeyTalk action as a String

args (optional) the MonkeyTalk args list as an JSON Array

modifiers (optional) the MonkeyTalk modifiers as a JSON Hash with String keys and String values.

Returns: {

result:"OK"

}

result either OK or ERROR


29 of 44 4/24/12 11:24 AM

Command Reference

Command ReferenceHere is a list of all MonkeyTalk components, with all available actions. All components inherit from View and thus inherit all of View'sactions too.

Buttoninherited from View

ButtonSelectorselect(value:String):void - Select an item by value.




CheckBoxinherited from View

DatePickerenterDate(date:String):void - Change the current date value.

date - A date with the format YYYY-MM-DD where YYYY is the year, MM is the month (01-12), and DD is the day(01-31).

inherited from ViewDevice

shake():void - Shake the device.rotate(direction:String):void - Change the device orientation.

direction - Left or Right (case insensitive)back():void - Navigate back. iOS: Pops the current UINavigationItem (if there is one). Android: Presses the hardware devicekey.forward():void - Navigate forward. iOS: Pushes the next UINavigationItem, if there is one. Android: ignored.search():void - Press the search key. iOS: ignored. Android: Presses the device search key.menu():void - Press the menu key. iOS: ignored. Android: Presses the device menu key.

Docvars(args:String):void - Document the named variables used in the script.

args - the named variables and their doc, in the form of: var='some doc' var2='other doc'script(doc:String):void - Document the script itself.

doc - the docIndexedSelector



inherited from ViewInput



ItemSelectorselect(value:String):void - Select an item by value.




Labelinherited from View

Menu


30 of 44 4/24/12 11:24 AM

select(value:String):void - Select an item by value.value - the value of the item to select.



inherited from ViewNumericSelector

select(value:float):void - Select a numeric component valuevalue - the value to select

inherited from ViewRatingBar

select(value:float):void - Select a numeric component valuevalue - the value to select

inherited from ViewScript

run(args:String):String - Run the script with the given args.args - the arguments

runWith(args:String):void - Data-drive the test script with the given CSV data file.args - the arguments (where the first arg is the data file filename)

Scrollerscroll(x:int, y:int):void - Scroll to the specified coordinates.

x - the x-coordinate (horizontal)y - the y-coordinate (vertical)

inherited from ViewSetup

run(args:String):String - Run the setup script with the given args.args - the arguments

runWith(args:String):void - Data-drive the setup script with the given CSV data file.args - the arguments (where the first arg is the data file filename)

Sliderselect(value:float):void - Select a numeric component value


TabBarselect(value:String):void - Select an item by value.




TableselectRow(row:int, section:int):void - Select a row.

row - the row to selectsection - the section containing the row. (Ignored on Android)

scrollToRow(row:int, section:int):void - Scroll to a row by row number.row - the row to selectsection - the section containing the row. (Ignored on Android)

scrollToRow(value:String):void - Scroll to a row by value.value - the value of the row to scroll to.

setEditing(enabled:boolean):void - Enable/disable table editing. iOS: Enabled editing mode for table. Android: ignored.enabled - if true, enable editing, else disable editing.

insert(row:int, section:int):void - Insert a row into the table. iOS: Inserts a row. Android: Ignored.row - the index of the row after which to insert a new row.section - the section containing the row.

remove(row:int, section:int):void - Remove a row from the table. iOS: Deletes the row. Android: Ignored.row - the index of the row to be removed.section - the section containing the row.

move(from:int, to:int):void - Move a row. iOS: Moves a row. Android: Ignored.from - the index of the row to be moved.to - the destination row for the move.

select(value:String):void - Select an item by value.


31 of 44 4/24/12 11:24 AM




Teardownrun(args:String):String - Run the teardown script with the given args.

args - the argumentsrunWith(args:String):void - Data-drive the teardown script with the given CSV data file.

args - the arguments (where the first arg is the data file filename)Test

run(args:String):String - Run the test script with the given args.args - the arguments

runWith(args:String):void - Data-drive the test script with the given CSV data file.args - the arguments (where the first arg is the data file filename)

TextAreaenterText(text:String, hitDone:boolean):void - Enter text into the input field.

text - the text to enterhitDone - iOS: if true, hit Done key after entering text. Android: ignored.


Toggleinherited from View

ToolBarselectIndex(itemNumber:int):void - Selects an item by index.



Varsdefine(args:String):void - Define the named variables used in the script.

args - the named variables (and optional default value), in the form of: var1 var2=defaultVideoPlayer

play():void - Play the video from the current playback point.pause():void - Stop the video at the current playback point.stop():void - Stop the video and set playback to the starting point.inherited from View

Viewverify(expectedValue:String, propPath:String, failMessage:String):void - Verifies that a property of the component hassome expected value.

expectedValue - the expected value of the property. If null, verifies the existence of the component.propPath - the property name or property path expression (defaults to 'value')failMessage - the custom failure message

verifyNot(expectedValue:String, propPath:String, failMessage:String):void - Verifies that a property of the componentdoes not have some value.

expectedValue - the value the component shouldn't have. If null, verifies the non-existence of the component.propPath - the property name or property path expression (defaults to 'value')failMessage - the custom failure message

verifyRegex(regex:String, propPath:String, failMessage:String):void - Verifies that a property of the component matchessome regular expression.

regex - the regular expression to matchpropPath - the property name or property path expression (defaults to 'value')failMessage - the custom failure message

verifyNotRegex(regex:String, propPath:String, failMessage:String):void - Verifies that a property of the component doesnot have a value matching a regular expression.

regex - the regular expression that should not match.propPath - the property name or property path expression (defaults to 'value')failMessage - the custom failure message

verifyWildcard(wildcard:String, propPath:String, failMessage:String):void - Verifies that a property of the componentmatches some wildcard expression.

wildcard - the wildcard expression to matchpropPath - the property name or property path expression (defaults to 'value')


32 of 44 4/24/12 11:24 AM

failMessage - the custom failure messageverifyNotWildcard(wildcard:String, propPath:String, failMessage:String):void - Verifies that a property of the componentdoes not have a value matching some wildcard expression.

wildcard - the wildcard expression that should not matchpropPath - the property name or property path expression (defaults to 'value')failMessage - the custom failure message

tap():void - Taps on the component. On Android, plays a 'click'. On iOS, plays a TouchDown/TouchMove/TouchUp sequence.longPress():void - Performs a long press on the component. On Android, plays a 'longClick'. On iOS, plays a longPushgesture.touchDown(x:int, y:int):void - Start touching the component.

x - x-coordinate of the touchy - y-coordinate of the touch

touchMove(coords:int):void - Drag across the componentcoords - one or more (x,y) coordinate pairs specifying the path of the drag gesture

touchUp(x:int, y:int):void - Stop touching the component.x - x-coordinate of where touch is releasedy - y-coordinate of where touch is released

pinch(scale:float, velocity:float):void - Pinch the component.scale - The scale factor relative to the points of the two touches in screen coordinatesvelocity - The velocity of the pinch in scale factor per second (read-only)

swipe(direction:String):void - Swipe the component.direction - Left, Right, Up, or Down (case insensitive)

drag(x1:int, y1:int, x2:int, y2:int):void - Touch down, drag across the component, then upx1 - starting x-coordinatey1 - starting y-coordinatex2 - ending x-coordinatey2 - ending y-coordinate

get(variable:String, propPath:String):String - Gets the value of the given property from the component, and set it into thegiven variable name.

variable - the name of the variable to setpropPath - the property name or path expression (defaults to 'value')

exec(method:String, args:String):String - Call a method on a component. The method must take zero or more Stringarguments and return a String result.

method - the method to callargs - the String args to be supplied to the method

MonkeyTalk User Guide

User GuideBelow is a list of topics intended to give the user more detailed instructions on how to use MonkeyTalk.

InstallationInstalling MonkeyTalk

First, you must install the MonkeyTalkIDE. See the MonkeyTalkIDE Installation Guide for detailed instructions.1.Next, you'll need to install the MonkeyTalk Agent in your iOS app or Android app or both for cross-platform testing. See theMonkeyTalk Agent for iOS Installation Guide or the MonkeyTalk Agent for Android Installation Guide depending on your platform.

2.

SpecificationSpecification


33 of 44 4/24/12 11:24 AM

If you want to see the detailed technical standard, please consult the MonkeyTalk Specification. The Spec includes detailed informationabout the MonkeyTalk functional testing language, how to write MonkeyTalk scripts, how to use data-driving, how to extend MonkeyTalkwith new keywords, and a complete Command Reference.

RecordRecording

ConnectConnecting to Emulator, Simulator, or Hardware

Android Emulator / iOS Simulator

Open the IDE1.Start up your Android or iOS emulator/simulator and load it with your MonkeyTalk enabled app.2.Click on the connection dropdown button on the tool bar (on initial start up it will be the green android icon).3.

Choose "Android Emulator" or "iOS Simulator", depending on your platform of choice.If you are connecting to an Android device for the first time, you will be prompted to point the MonkeyTalk IDE to your localAndroid SDK. You can also set this in your MonkeyTalk Preferences.

1.4.


Android and iOS Hardware

Open the IDE1.Start up your Android or iOS device, load it with your MonkeyTalk enabled app, and let it connect to your wireless network.2.Click on the connection dropdown button on the tool bar (on initial start up it will be the green android icon).3.Choose "Networked Android or iOS device...".4.Enter the IP address of the mobile device.5.If connection was successful, a message to that effect should appear in the console.6.

Start and Stop Recording

Start and Stop Recording

Connect to your device.1.Pull up your application on the device.2.Click “Record” on the MonkeyTalk IDE. If “Record” is not active, then double check that you are connected to your device byclicking on the “Connect” button.

3.


34 of 44 4/24/12 11:24 AM

Interact with your application. MonkeyTalk should record the actions you took as a script.4.To stop recording, click the “Stop” button.5.

If the Record button is not lighting up, it may be one of two things:

You are not properly connected to a device. To read more on connecting to a device, go here.1.Your application is not properly set up for MonkeyTalk. To read more on installing the MonkeyTalk agent and setting your app upcorrectly, go here.

2.

Filtering

Filtering

While recording, you can control what level of events recorded, including Touch Up, Touch Down, and Move, and Drag events. By default,low level event such as these are toggled off because they can be very spammy, but you can turn them on by clicking the filter button.

The filter options are:

Touch Up/Down/Move - When toggled on, records all low level events such as Touch Up, Touch Down, and Move.Gestures - When toggled on, interprets events as gestures such as Swipe, Drag, Tap, etc.

The default configuration has Touch Up/Down/Move toggled off and Gestures turned on.

This is a screenshot of recording with both Touch Up/Down/Move and Gestures toggled on.


35 of 44 4/24/12 11:24 AM

When you choose to display just Touch Up/Down/Move and not Gestures, MonkeyTalk will only print Touch Up/Down/Move events andwill not interpret these events into gestures.

PlaybackPlaying Back

Play All

Playing All of a MonkeyTalk Script

Restart your app. (Not necessary, but useful for starting at the same point as before.)1.Click the “Play” button. It should replay your entire script.2.

Play Single

Playing a Single Line of a MonkeyTalk Script

Select / highlight the row you wish to play.1.Right click on the row, choose the "Play Row" option.2.

Play Select Rows

Playing Selected Lines of a MonkeyTalk Script

Select / highlight the rows you wish to play (you can use shift+click and ctrl/cmd+click to select rows).1.Right click on the row, choose the "Play Rows" option.2.


36 of 44 4/24/12 11:24 AM

Script Editing

Editing the MonkeyTalk Script

Creating a New MonkeyTalk Project

Creating a New MonkeyTalk Project

File > New... > MonkeyTalk Project1.

Enter project name.2.Click "finish"3.

Creating a New MonkeyTalk Test

Creating a New MonkeyTalk Test

File > New... > MonkeyTalk Test1.Select parent project and enter test name.2.Click "finish"3.

You can also just create a new file with the .mt extension.

Editing Commands

Editing Commands

You can currently edit MonkeyTalk script in two different ways: through the table view and through the MonkeyTalk view. The Table Viewis optimal for playback and offers dropdown menus with components and actions. The MonkeyTalk view lets you enter script freely.


37 of 44 4/24/12 11:24 AM

To edit through the table view, right click on the table and choose "Append row." Click in each cell to enter your new command. Youcan also use the drop down menus to select from a list of options.

1.

To edit through the MonkeyTalk view, switch to the MonkeyTalk tab and you can type freely.2.

Inserting and Deleting Commands

Inserting and Deleting Commands

Table View Right-Click Context Menu Options

Append Row - Add a row at the bottom of the MonkeyTalk script.Insert Row Above - Add a row above currently selected row in script.Delete Row - Delete currently selected row.

Tool Bar Options

Delete All - Deletes all content in current MonkeyTalk script.

If you switch to the MonkeyTalk view, you can edit the scripts freely, but be sure you're adhering to the proper MonkeyTalk commandguidelines.

TestsTests

VerificationTypes of Verification

Verify - Verify that the component's value is equal to the argument.VerifyNot - Verify that the component's value is NOT equal to the argument.VerifyRegex - Verify that the component's value matches the Regular Expression provided in the argument.VerifyNotRegex - Verify that the component's value does NOT match the Regular Expression provided in the argument.VerifyWildcard - Verify that the component's value matches some wildcard expression provided in the argument.VerifyNotWildcard - Verify that the component's value does NOT match some wildcard expression provided in the argument.

Test SuitesTest Suites

A Suite is a special script where every command is a test. It contains a setup and teardown, which it runs before and after every single test(respectfully). All MonkeyTalk test suites use the extension .mts.

To create a complete test suite:


38 of 44 4/24/12 11:24 AM

Make a new test suite file. Leave it blank for now. (Right click New TestSuite)1.Write a setup file. Setup (and tear down) scripts are just regular MonkeyTalk scripts that prepare a test script or reset an app to itsstarting place.

2.

Write a test script (or two).3.Write a tear down file. Similar to a setup file, the tear down script should undo any changes the test scripts did and should reset theapp to its starting place.

4.

Put all these components into the test suite. The syntax in a suite is pretty specialized, and the only “components” you ever use areSetup, Teardown, and Test. Here is an example:

5.

ZooPanelSuite.mts

Setup ZooPanelSetup.mt RunTeardown ZooPanelTeardown.mt Run

Test SyncTest.mt RunTest RatingBarTest.mt Run

You can run your test suite just like a normal script, by clicking the Play button. The setup will run before every test, and theteardown will run after every test. At the end of a test, a JUnit dialog will appear and document each test.

6.

JavascriptJavascript

If you want to include common programming structures like flow control, loops, and random number generators, then exporting toJavascript is a good way to do so.

To get started with exporting to Javascript, click on the Javascript tab at the bottom of a MonkeyTalk script. You should see a screen that'ssimilar to this:

Click "Export". Once you do so, the MonkeyTalk IDE will generate a new .js file that does the same thing as your MonkeyTalk script.

How to use the MonkeyTalk JS file


39 of 44 4/24/12 11:24 AM

You can run a MonkeyTalk JS file just like a normal MonkeyTalk file. For example, if I create a file, login.mt, and export it to Javascript,login.js, I can run the javascript file like this:

LoginWrapper.mt

Script login Run

Note that if I call "login" as opposed to "login.mt" or "login.js", it will default to running login.js.

Now let's make our MonkeyTalk JS File do something special...Let's say we started out with this MT script.

Login.mt

Vars * Define [email protected] pwdInput username EnterText ${usr}Input password EnterText ${pwd}Button LOGIN TapButton LOGOUT Tap %timeout=3000 %thinktime=5000

That script exports to this Javascript:

Login.js


};

Test.Login.prototype.run = function(usr, pwd) {usr = usr || "[email protected]";pwd = pwd || null;

this.app.input("username").enterText(usr);this.app.input("password").enterText(pwd);this.app.button("LOGIN").tap();this.app.button("LOGOUT").tap();

};

Now we can edit login.js to include a random string generator.


};

Test.Login.prototype.run = function(usr, pwd) {usr = usr || randStr();pwd = pwd || randStr();

this.app.input("username").enterText(usr);this.app.input("password").enterText(pwd);this.app.button("LOGIN").tap();this.app.button("LOGOUT").tap();

};

function randStr(){ var text = ""; var possible = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";


40 of 44 4/24/12 11:24 AM

for( var i=0; i < 5; i++ ) text += possible.charAt(Math.floor(Math.random() * possible.length));

return text;}

Now if we run LoginWrapper.mt with this modified Login.js and no parameters passed it, it will use a random username and password foreach log in attempt.

AntAnt

MonkeyTalk scripts can be run via Ant from the commandline, and Ant can be easily integrated into a CI environment like Jenkins. Thecombination of an Ant runner for MonkeyTalk scripts, plus a CI server like Jenkins can provide a fully automated testing solution.

Installing the MonkeyTalk Ant Tasks

There are a few options when installing an Ant library.

Option #1 - The easiest thing to do is copy monkeytalk-ant.jar into your Ant lib/ folder. Then you only need to reference it with anamespace like this:

<project xmlns:monkeytalk="antlib:com.gorillalogic.monkeytalk.ant"> ...</project>

Option #2 - Alternately, you can just put monkeytalk-ant.jar anywhere and reference it from Ant with a taskdef like this:

<project xmlns:monkeytalk="antlib:com.gorillalogic.monkeytalk.ant"> ... <path id="monkeytalk.classpath" path="path/to/monkeytalk-ant.jar" /> <typedef resource="com/gorillalogic/monkeytalk/ant/antlib.xml" uri="antlib:com.gorillalogic.monkeytalk.ant" classpathref="monkeytalk.classpath" /> ...</project>

Writing a build.xml

Once you have monkeytalk-ant.jar in place, you can add targets and run monkeytalk commands just like you can through the IDE byusing monkeytalk:run and the following parameters.

Parameters

Attribute Description Required?

agent Either "Android" or "iOS" Yes

adb Complete path to ADB within your local Android SDK. For example, adb="/Users/tori/DevTools/android-sdk-macosx/platform-tools/adb"

Yes if the agent is Android,no otherwise

script Local path to .mt script you wish to run. Either "script", "suite", orinline script

suite Local path to .mts suite you wish to run. Either "script", "suite", orinline script


41 of 44 4/24/12 11:24 AM

host Set as "localhost" if connecting to emulator/simulator or tethered device; or the device's IPaddress if connecting to networked device. Defaults to localhost. No

port By default, iOS port is set to 16863, Android port is set to 16862 No

reportdir Directory to log JUnit xml test output from a suite. If not specified, defaults to currentdirectory. No

Here is a simple example:

<project name="Test" default="testSuiteOnAndroidDevice" xmlns:monkeytalk="antlib:com.gorillalogic.monkeytalk.ant">

<property environment="env" /> <property name="version" value="1.0.4-SNAPSHOT" /> <property name="adb" value="/Users/tgilbertson/DevelopmentTools/android-sdk-macosx/platform-tools/adb" /> <property name="host" value="0.0.0.0" /> <path id="monkeytalk.classpath" path="${env.M2_REPO}/com/gorillalogic/monkeytalk/monkeytalk-ant/${version}/monkeytalk-ant-${version}.jar" /> <typedef resource="com/gorillalogic/monkeytalk/ant/antlib.xml" uri="antlib:com.gorillalogic.monkeytalk.ant" classpathref="monkeytalk.classpath" /> <target name="testScriptOniOSSimulator"> <monkeytalk:run agent="iOS" > Input username EnterText "Bo Bo" Input password EnterText password Button LOGIN Tap Button LOGOUT Verify %timeout=3000 Label * Verify "Welcome, Bo Bo!" Button LOGOUT Tap </monkeytalk:run> </target> <target name="testSuiteOnAndroidDevice"> <monkeytalk:run agent="android" adb="${adb}" suite="suite.mts" host="${host}" reportdir="reports" /> </target> <target name="debug"> <property name="debug" refid="monkeytalk.classpath" /> <echo message="debug=${debug}" /> </target>

</project>

Running with Ant

To run, you execute just like a normal ant file. For example, if I was using the above code I would navigate to where that build.xml file waslocated, start up my iOS simulator with my app, and run ant testScriptOniOSSimulator.

Just like when you're using the MonkeyTalk IDE, you need to have the same resources available, such as running an emulator/simulator anddeploying your MonkeyTalk-enabled app. You don't need the IDE to run MonkeyTalk ant.

Here is what one of the ant tests from above looks like after being successfully executed.


42 of 44 4/24/12 11:24 AM

Understanding MonkeyTalk CommandsUnderstanding MonkeyTalk Commands

The syntax has been designed to be easily understood by non-programmers. It’s fairly readable and straightforward to specify manuallyusing a simple text file editor or even a spreadsheet. Additionally, MonkeyTalk has been designed to be displayed and edited within tabularconsoles such as the MonkeyTalk IDE.

MonkeyTalk commands are newline terminated and have the following syntax:ComponentType MonkeyId Action Args… Modifiers…

Collectively, ComponentType, MonkeyId, Action, Args, Modifers are known as command parts. Furthermore, ComponentType.Action isknown as the command name.

For more information on each of the command parts, follow the links below, or read the Command Reference.

Component

ComponentType

Required

The type of component on which to perform the action. Examples include Button and TextArea. Component types are not case sensitive.ComponentTypes can extend other ComponentTypes, as described below, and inherit any defined actions as well as Arguments.ComponentTypes are typically the logical name of the UI component (like Button rather than UIButton), but can also have platform-specific aliases. ComponentType may be specified as an asterisk (*), which essentially means any component.

MonkeyId

MonkeyId

Required

An identifier that is used to distinguish between components of the same type being displayed simultaneously. MonkeyId can be specifiedas asterisk (*), which finds the first matching component.

MonkeyId’s can also be specified as a 1-based (not zero-based) index of the form #N. In this case, the MonkeyId identifies the Nthcomponent of the specified type that’s currently displayed. Components are indexed according to upper-left-most position, i.e., by sortingcomponents by (x,y) coordinate.

Action

Action

Required

The action to be performed. Examples include Tap, Select, and EnterText. Actions are not case sensitive.

Arguments


43 of 44 4/24/12 11:24 AM

Arguments

Required according to ComponentType and Action

A space-separated list of one or more arguments. Arguments are assumed to begin at the fourth token. Although always specified as strings,args are interpreted as necessary by the command. If an Argument is required but not specified (left off the end of the list), it takes on adefault value. An Arg may be specified as an asterisk (*) to force it to take on it’s default value,

Thinktime

Thinktime

Optional

How long in milliseconds (ms) to wait before executing the command for the first time. You can use this modifier to simulate humanreaction time. Written as %thinktime=TIME_IN_MILLISECONDS.

For example, building upon the Timeout Interval example from earlier, if we want to wait 2 seconds before pressing the LOGOUT button,we will use this script. Remember that both thinktime and timout start counting down at the same time, so if you want the LOGOUT buttonpress to happen 2 seconds after the timeout, you have to add that time to the think time. This means that thinktime should be 5 seconds forthis example.

Button LOGIN TapButton LOGOUT Tap %timeout=3000 %thinktime=5000

Timeout Interval

Timeout Interval

Optional

How long in milliseconds (ms) to continue retrying a command before timing out. Written as %timeout=TIME_IN_MILLISECONDS.

For example, if we have an app that waits for 2.5 seconds after pressing the button "LOGIN", and after 2.5 seconds a new "LOGOUT"button appears, we can write a script that will press the "LOGIN" button, wait 3.0 seconds, and then press the "LOGOUT" button.

Button LOGIN TapButton LOGOUT Tap %timeout=3000

Retry Delay

Retry Delay

Optional

How long in milliseconds (ms) to delay between retry attempts. Written as %retrydelay=TIME_IN_MILLISECONDS.


44 of 44 4/24/12 11:24 AM

MonkeyTalk Documentation

Documents

monkeytalk faqgeneralhow

monkeytalk quickstart

monkeytalk ide desktop

ios app

obscure aspects of monkeytalk

monkeytalk records events

android app

public use