Running Tests

Learn how to run UIAutomation tests using Tuneup JS

There are three primary ways to run UIAutomation tests using tuneup.

Using Bwoken (recommended!)

Bwoken is a robust command-line executable for running UIAutomation tests. It has nearly all of the benefits of tuneup’s built-in test runner plus:

  • built-in support for CoffeeScript
  • automatic device-detection
  • integration with Rake

Install Bwoken using Bundler. Once you have it installed, adjust your #import statement according to how you installed tuneup. If you’re using CocoaPods, your import path should be #import "../../../../Pods/tuneup_js/tuneup.js".

Using The Built-in Test Runner (deprecated)

Tuneup JS comes with its own test-runner script. It hides a lot of the ugly complexity of the instruments command-line executable. It also provides for better formatting of output. For details on running tests with this tool, execute test_runner/run -h in a terminal window for a detailed explanation of the command-line usage and options.

Note that, while the built-in test runner works and has had a lot of great contributions made, further support of it has been deprecated because Bwoken provides a much more robust feature-set.

Starting in iOS 5, Apple provided a way to run Instruments from the command-line. However, it's a bit fiddly and is very general-purpose so doing anything useful with the output is kind of a pain.

Tuneup provides a Ruby script (test_runner/run) to run your test scripts. The runner will parse the output of your test and produce a proper UNIX exit code based on whether or not your tests succeeded. It also provides some niceties like automatically specifying the full-path to your test script if you don't provide one.

Have a look at test_runner/run --help to be sure you're not missing any newly added features like fancy colors.

To use the runner, invoke it like so:

[path to tuneup]/test_runner/run <app bundle> <test script> <output directory> [optional args]

Normally the name of the app bundle will suffice for the <app bundle> argument. If you're running your tests on the simulator the newest bundle will be located automatically. If that fails, or if you want to manually specify the bundle to be used, you need to provide a fully-qualified path to the app bundle, which will be buried somewhere in ~/Library/Developer/Xcode/DerivedData.

The <test script> argument specifies the JavaScript test file and the <output directory> is where the resulting Instruments output like screenshots and reports should go.

Run the script with -h or --help for a full explanation of supported options.

Device or Simulator

If you provide the optional argument -d DEVICE, you can tell Instruments to run your test against a real device (identified by UDID). You can also pass dynamic and tuneup will find the UDID at runtime. If this argument is not provided, the runner will run against the simulator.


The Instruments preprocessor causes a lot of headache due to its inability to handle #import statements properly. If you pass -p, the script will create a temp file, resolve any imports and inline the referenced files (only once).

Selecting Tests

If you don't want to run your whole test suite, you can selectively run tests by specifying the argument -r TEST. Whatever you pass for TEST will be used as regex to match any title of your tests.

XML reports

Tuneup can generate Xunit style reports that can be analyzed by any compatible tool, like Jenkins. Given the parameter -x a XML report will be generated in the output directory.

Using Instruments

There’s nothing special required to run tuneup within Instruments aside from getting the path correct in your initial #import statement.