pxctest

Parallel XCTest - Execute XCTest suites in parallel on multiple iOS Simulators.

Installation

To install via Homebrew you can use the plu/homebrew-pxctest tap:

brew tap plu/pxctest
brew install pxctest

Usage

Compile your tests with build-for-testing, example:

xcodebuild \
  -IDEBuildLocationStyle=Custom \
  -IDECustomBuildLocationType=Absolute \
  -IDECustomBuildProductsPath="$PWD/build/Products" \
  -scheme 'MyApp' \
  -workspace 'MyApp.xcworkspace' \
  -destination 'platform=iOS Simulator,name=iPhone 5,OS=10.1' \
  build-for-testing

In build/Products you should find a .xctestrun file. This can then be passed to pxctest:

pxctest \
  run-tests \
  --destination 'name=iPhone 5,os=iOS 9.3' \
  --destination 'name=iPhone 5,os=iOS 10.1' \
  --testrun build/Products/MyApp_iphonesimulator10.1-i386.xctestrun

The --destination option can be passed in several times and will execute the tests in parallel on all Simulators.

run-tests options

--testrun - Path to the .xctestrun file.
--deviceset - Path to the Simulator device set.
--locale - Locale to set for the Simulator.
--preferences - Path to some preferences.json to be applied with the Simulator.
--only - Comma separated list of tests that should be executed only. Example: TestClass1/testFoo,TestClass2/testBar
--destination - A comma-separated set of key=value pairs describing the destination to use, just like xcodebuild -destination.
--timeout - Timeout in seconds for the test execution to finish.

Most of the options should be self explanatory. If not, please open an issue or submit pull requests. However the --preferences option needs a special section here.

run-tests --preferences

This option expects a path to a file, which contains some JSON. After loading the file, its content gets applied to the Simulator's preferences property list file located at Library/Preferences/com.apple.Preferences.plist.

Example: You can turn off all keyboard settings that you can find in the Simulator's Settings app by using this JSON content:

{
  "KeyboardAllowPaddle": false,
  "KeyboardAssistant": false,
  "KeyboardAutocapitalization": false,
  "KeyboardAutocorrection": false,
  "KeyboardCapsLock": false,
  "KeyboardCheckSpelling": false,
  "KeyboardPeriodShortcut": false,
  "KeyboardPrediction": false,
  "KeyboardShowPredictionBar": false
}

For this operation being successful, the Simulator must not be launched yet when using the --preferences option.

Development

After cloning the repository run this script:

scripts/bootstrap.sh

FBSimulatorControl

The functionality provided by pxctest would not be possible without the great FBSimulatorControl Framework provided by Lawrence Lomax at Facebook.

There are two command line tools that come with FBSimulatorControl:

fbsimctl - command line interface to the FBSimulatorControl Framework
fbxctest - test runner for running iOS testing bundles for the iOS Simulator Platform

Both of them are more flexible than pxctest, so it might be worth having a look at them.

License

BSD-licensed

drptbl/pxctest