mokacoding

unit and acceptance testing, automation, productivity

Running Xcode tests from the terminal

In this post we'll see how to run Xcode tests from the terminal, and why you might want to do it.

If you've installed the Command Line Tools you'll see that from your terminal you can call xcodebuild.

Reading through the output of man xcodebuild, available online here, we find that:

xcodebuild builds one or more targets contained in an Xcode project, or builds a scheme contained in an Xcode workspace or Xcode project.

So the first impression, as the name suggests by the way, is that xcodebuild's purpose is to build Xcode projects. Not really what we're looking for since we want to run tests. But if we keep reading XCODEBUILD(1) we'll find a section listing the possible build actions, and test is one of them.

Test a scheme from the build root (SYMROOT). This requires specifying a scheme and optionally a destination.

After a bit more reading through xcodebuild man page and Apple's Command-Line Testing resource we can write the minimum viable command to run our tests:

xcodebuild \
  -workspace MyAwesomeApp.xcworkspace \
  -scheme MyAwesomeApp \
  -sdk iphonesimulator \
  -destination 'platform=iOS Simulator,name=iPhone 6,OS=8.1' \
  test

Note that we're assuming that MyAwesomeApp uses CocoaPods, therefore we're using the -workspace option, which then requires to use -scheme.

You can use instruments -s devices to see a list of know devices to use in the -destination option, more here.

If you try to do this you'll see something like this:

xcodebuild test output

Not a very pleasant output is it?

This is where xcpretty comes to the rescue. xcpretty is a tool designed to format xcodebuild's output, and make it human readable.

Using xcpretty is very simple:

xcodebuild \
  -workspace MyAwesomeApp.xcworkspace \
  -scheme MyAwesomeApp \
  -sdk iphonesimulator \
  -destination 'platform=iOS Simulator,name=iPhone 6,OS=8.1' \
  test | xcpretty

xcodebuild test with xcpretty output

If you're an RSpec fan like me, that you'll want the green dots in your tests output:

xcodebuild \
  -workspace MyAwesomeApp.xcworkspace \
  -scheme MyAwesomeApp \
  -sdk iphonesimulator \
  -destination 'platform=iOS Simulator,name=iPhone 6,OS=8.1' \
  test | xcpretty --test --color

xcodebuild test with xcpretty RSpec style output

You might now ask "This is all interesting and colorful, but why should I use it?". Here's some reasons why I like running tests from the terminal, and why you might like it too:

That's what the CI is doing

When running tests from CI you'll need to run tests from the terminal. It is very wise to test the behaviour of the CI scripts on your local machine. If something breaks in the pipeline you'll notice before pushing to master and breaking the build.

Better output

The visual feedback that the dots in the terminal give me is much more powerful that the view in Xcode.

Do you really trust Xcode?

I'm a big fan of the terminal and of doing things through CLIs, so for me having to move to it to run the test instead of hitting ⌘U is not a big deal. Regardless of your workflow preferences though, there are cases when automation is needed, and that's when knowing how to run tests form the terminal will come handy.

Note: another tool you might want to try is xctool. I prefer the xcodebuild | xcpretty combo because it adds less overhead. If you're interested have a look at this NSHipster post.

Happy coding, and keep the codebase better than you found it.

Vote on Hacker News