UIAuto is a command line tool for running UI Automation scripts. It improves Apple's
instruments command by assuming reasonable defaults specific to UI Automation.
UIAuto also facilitates the setup of simulator data for running scripts in a repeatable and known state.
- Xcode command line tools
$ gem install uiauto
First, you need to build your app. By default,
uiauto will look for the most recently built app bundle in derived data based on your current working directory. UIAuto also provides commands and can read speical comment headers to setup simulator data. More details below.
Build your project
UIAuto does not build your app. You can use Xcode or
The easiest way to build your app for UIAuto is to use Xcode. Open your app in Xcode then build your project (command+b). This builds your app and places the resulting bundle in derived data.
You can build from the command line using
xcodebuild. The following examples show how to build your iOS 6.1 app for the simulator.
# Example using xcodebuild to build a workspace $ xcodebuild -workspace MyApp.xcworkspace -scheme MyApp -sdk iphonesimulator6.1 # Example using xcodebuild to build a project $ xcodebuild -project MyApp.xcodeproj -sdk iphonesimulator6.1
By building with the commands above, the resulting bundle is placed in derived data. Replace
iphoneos6.1 if you want to build for the device.
Run UI Automation scripts
The command to run automation scripts is simplified if the built app is in derived data and the defaults are used. For special use cases, these defaults may be overridden.
In the same directory as your project's .xcworkspace or .xcodeproj run the following.
$ uiauto exec path_to_your_script.js
This will run
path_to_your_script.js using the app bundle located in derivated data that you just built. The results and trace file are placed in
By placing your scripts in
./uiauto/scripts/, then you can execute them by running the following command.
# This is the same as `uiauto exec uiauto/scripts/` $ uiauto exec
uiauto help exec prints the following message.
Usage: uiauto exec [FILE_OR_DIRECTORY] Options: [--results=RESULTS] # Location where results should be saved. A directory named "Run ##" is created in here. # Default: ./uiauto/results [--trace=TRACE] # Location of trace file. Created if it doesn't exist. # Default: ./uiauto/results/trace [--app=APP] # Location of your application bundle. Defaults to your project's most recent build located in the standard location. [--device=DEVICE] # Run scripts on a connected device. Specify a UDID to target a specific device. [--simulator=SIMULATOR] # Run the simulator for a specific device. # Possible values: iPad, iPad (Retina), iPhone, iPhone (Retina 3.5-inch), iPhone (Retina 4-inch) [--format=FORMAT] # Formatter to use for output. Combine with --require to include a custom formatter. Built-in Formatters: # ColorIndentFormatter: Adds readability to instruments output by filtering noise and adding color and indents. # InstrumentsFormatter: Unmodified instruments output. # Default: ColorIndentFormatter [--listeners=LISTENERS] # Space separated list of class names used to listen to instruments output events. Combine with --require to include custom listeners. [--require=REQUIRE] # Path to a ruby file. Used to require custom formatters or listeners.
If you build your app outside of derived data, then you can specify the
--app flag to tell uiauto where to find the
*.app. You can also override the default locations for the trace file and results. For example, if your build your app in a build directory you can run the following
uiauto exec uiauto/scripts/script_to_run.js --app=build/MyApp.app
--device flag to run on the device.
# Run on a connected device $ uiauto exec uiauto/scripts/script_to_run.js --device # Run on a connected device with a specific udid $ uiauto exec uiauto/scripts/script_to_run.js --device=UDID
Custom formatters and listeners
UIAuto supports custom formats and custom listeners. They can be made available with the
--require option. The difference between a formatter and listener is that a formatter is a specific kind of listener that writes to
STDOUT. There can only be one formatter active at a time. There may be more than one listener active at a time, and a listener must not write to
See lib/uiauto/formatters/README.md for details on how to implement a custom formatter.
See lib/uiauto/listeners/README.md for details on how to implement a custom listener.
simulator subcommand allows you to setup the simulator's applications, settings, and data. This is done by taking a "snapshot" of the simulator's current data by saving the
~/Library/Application Support/iPhone Simulator/(SDK VERSION)/ directory somewhere, then loading it back in when needed.
This is useful for getting the simulator into a known state before running automation scripts.
uiauto simulator command
uiauto simulator prints the following message
Commands: uiauto simulator close # Closes the simulator uiauto simulator help [COMMAND] # Describe subcommands or one specific subcommand uiauto simulator load DATA # Loads previously saved simulator data uiauto simulator open # Opens the simulator uiauto simulator reset # Deletes all applications and settings uiauto simulator save DATA # Saves simulator data
Script comment headers
By placing a special comment header at the top of your script,
uiauto exec will automatically load in a previously saved simulator data dump before running the script.
Let's say you have a TODO list application. You want to script the delete feature, but the problem is that you need tasks to delete first. With UIAuto, you can add a comment header that loads the simulator with your app with its tasks already there. Therefore, your script can safely make this assumption every time that it is ran.
The steps below explain how to do this.
1. Manually add tasks to your app in the simulator
Get data into your app up to the point where you want your script to start. In this case, you want to add some tasks so that your script can delete them later.
2. Save the simulator's current state
$ uiauto simulator save uiauto/simulator_data/with_tasks
This command will save ALL of the data in the simulator including your application's data (and therefore, it'll save the tasks you just created). It is stored in the directory you specified.
3. Add the comment header
Add the following to the top of
// setup_simulator_data "../simulator_data/with_tasks"
Inside the quotes is where you specify the location of the simulator data you want loaded in before running the script. It may be a path relative to the script.
4. Run the script
Build if needed, then run:
$ uiauto exec uiauto/scripts/delete_tasks.js
This will load in the simulator data that was saved in step 2 before running the script.
MIT License. See LICENSE.txt