How to run and debug unit tests for an iPhone application

Question

NOTE: Unit testing is a lot easier to setup nowadays. This tutorial is not really relevant for Xcode version 5 and above.

It took me quite some time but I finally managed to make it work for my project. To create the "logic" tests I followed Apple guidelines on creating logic tests. This works fine once you understand that the logic tests are run during build.

To be able to debug those tests it is required to create a custom executable that will call those tests. The article by Sean Miceli on the Grokking Cocoa blog provides all the information to do this. Following it however did not yield immediate success and needed some tweaking.

I will go over the main steps presented in Sean's tutorial providing some "for dummies" outline which took me some time to figure out:

1. Setup a target that contains the unit tests but DOES NOT run them
2. Setup the otest executable to run the tests
3. Setup the otest environment variables so that otest can find your unit tests

The following was performed with XCode 3.2.5

Note for XCode 4

In XCode 4 it is possible to debug your unit tests DIRECTLY. Just write your test, add it to your target as one of the tests and set a breakpoint in it. That's all. More will come.

Step 1 - Setting up the target

1. Duplicate your unit tests target located under your project Targets. This will also create a duplicate of your unit tests product (.octest file). In the figure below "LogicTest" is the original target.
2. Rename both the unit tests target and the unit tests product (.octest file) to the same name. In the figure below "LogicTestsDebug" is the duplicate target.
3. Delete the RunScript phase of the new target

The name of both can be anything but I would avoid spaces.

Step 2 - Setting up otest

The most important point here is to get the correct otest, i.e. the one for your current iOS and not the default Mac version. This is well described in Sean's tutorial. Here are a few more details which helped me setting things right:

1. Go Project->New Custom Executable. This will pop open a window prompting you to enter an Executable Name and an Executable Path.
2. Type anything you wish for the name.
3. Copy paste the path to your iOS otest executable. In my case this was /Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator4.2.sdk/Developer/usr/bin/otest
4. Press enter. This will bring you to the configuration page of your executable.
5. The only thing to change at this point is to select "Path Type: Relative to current SDK". Do not type in the path, this was done at step 3.

Step 3 - Setting up the otest arguments and environment variables

The otest arguments are straightforward to setup... But this proved to be my biggest problem. I initially had named my logic test target "LogicTests Debug". With this name and "LogicTests Debug.octest" (with quotes) as argument to otest I kept having otest terminating with exit code 1 and NEVER stopping into my code...

The solution: no space in your target name!

The arguments to otest are:

1. -SenTest Self (or All or a test name - type man otest in terminal to get the list)
2. {LogicTestsDebug}.octest - Where {LogicTestsDebug} needs to be replaced by your logic test bundle name.

Here is the list of environment variables for copy/pasting:

• DYLD_ROOT_PATH: $SDKROOT
• DYLD_FRAMEWORK_PATH: "${BUILD_PRODUCTS_DIR}: ${SDK_ROOT}:${DYLD_FRAMEWORK_PATH}"
• IPHONE_SIMULATOR_ROOT: $SDKROOT
• CFFIXED_USER_HOME: "${HOME}/Library/Application Support/iPhone Simulator/User"
• DYLD_LIBRARY_PATH: ${BUILD_PRODUCTS_DIR}:${DYLD_LIBRARY_PATH}
• DYLD_NEW_LOCAL_SHARED_REGIONS: YES
• DYLD_NO_FIX_PREBINDING: YES

Note that I also tried the DYLD_FORCE_FLAT_NAMESPACE but this simply made otest crash.

Step 4 - Running your otest executable

To run your otest executable and start debugging your tests you need to:

1. Set your active target to your unit test target (LogicTestsDebug in my case)
2. Set your active executable to your otest executable

You can build and run your executable and debug your tests with breakpoints.

As a side note if you are having problems running your otest executable it can be related to:

1. Faulty path. I had lots of problem initially because I was pointing to the mac otest. I kept crashing on launch with termination code 6.
2. Faulty arguments. Until I removed the space from bundle (.octest) name I kept having otest crash with exit code 1.
3. Wrong path in environment variables. Sean tutorial has lots of follow-up questions giving some insight on what other people tried. The set I have now seems to work so I suggest you start with this.

You may get some message in the console which might lead you to think something is wrong with your environment variables. You may notice a message regarding CFPreferences. This message is not preventing the tests from running properly so don't focus on it f you have problems running otest.

Last once everything is working you will be able to stop at breakpoints in your tests.

One last thing...

I've read on many blogs that the main limitation of the integrated XCode SenTestKit is that tests cannot be run while building the application. Well as it turns out this is in fact quite easy to manage. You simply need to add your Logic tests bundle as a dependency to your application project. This will make sure your logic tests bundle is built, i.e. all tests are run, before your application is built.

To do this you can drag and drop your logic test bundle onto your application target.

Extant

Where are the figures mentioned? – Daughterinlaw

I could not include them due to low privileges... – Extant

I appreciate your effort to write a how-to article, but could you please also post an answer and mark it accordingly? Otherwise this post will stay at the top of the "unanswered questions" list forever. The only other way out is to close this question, which does not seem to do justice to your good intention. – Mascarenas

@adrian. An answer is written and the question closed – Extant

Could you mention the Xcode version this how-to applies to? I looks like 3.x, right? Any luck with Xcode 4? You should also add [ios] tag. – Cynth

@palimondo. Done. Thanks for the comment. Xcode is version 3.2.5. I have not tested it with Xcode 4 yet but I'll update the entry as required. – Extant

How does this post only have six upvotes? – Goof

@Goof Well maybe unit testing with OCUnit is not so popular after all... But thanks for the attention. – Extant

Answer 1

This post is intended as a "How-to" more than a real question. Therefore this answer is just meant to allow me to mark the "How-to" as "answered". This will probably be flagged by the community as irregular. I'm up for suggestions on where to post future "How-to" articles.

One final note though on this topic. For those who still wonder whether writing unit tests is worth it I would definitely say Yes!

I am currently writing an application with CoreData and retrieval of data from a web service (xml parsing). The complete model can be tested and debugged without having to:

1. run the actual application on the simulator or device. Not having to use the device to run the tests is a huge gain of time. It's the difference between 2 minutes and 5 seconds per run.
2. without the need to create views or controllers when testing the model. The complete development and testing can focus on the model only in the first iteration. Once the model is cleared for integration the rest of the development can follow.

To debug the xml parsing I can simply use "hard-coded" files which I completely control.

The crux is of course to write the tests as you implement features in the code. It really is a time saver down the line in terms of debugging of the complete application.

Voilà, I'll leave it at that.

Extant

Thanks again for the how-to. StackOverflow is an excellent place to post such articles. I'd just suggest asking a question (in this case "How can I run and debug unit tests for an iPhone application?") and then to write the how-to article as the answer to your own question. I know you can only mark it as THE answer after 48 hours, but this does seem the best way to post a how-to and play by the rules on SO... Sorry again for criticizing your post, I know you were only trying to help. – Mascarenas

@Adrian. That's a good point. I'll handle it this way for future How-To. Don't be sorry though I am still learning. So thanks for the comments. – Extant

Do you have any advice for application tests? Application tests fail in the simulator if run with the "Test" scheme, and they don't stop at breakpoints if run with the "Run" scheme on a device. According to developer.apple.com/library/ios/#documentation/Xcode/Conceptual/… "Because application tests run only on a device, you can also use these tests to perform hardware testing, such as getting the location of the device." – Hoofer

Nevermind. I must have done something wrong when I tested. I can debug normally as your article mentions. – Hoofer

Answer 2

I was able to run the test case in debugger in the following simple steps:

1. Product > Build For > Testing
2. Put a break point in part of the test you want to debug
3. Product > Test

This is on Xcode 6.0.1 and seems much more convenient than the long procedure described above.

Sporty