CoverStory is a great little application that will allow you to see how much of your code is being tested. This is referred to as code coverage, hence the clever name.

To use it, you have to configure your unit test target to generate coverage records (*.gcda and *.gcno files). How to do this will depend on the version of Xcode you are running.

For older Xcode version (using gcc):

1. Add -fprofile-arcs and -ftest-coverage to Other C Flags
2. Link /Developer/usr/lib/libprofile_rt.dylib into your app

For Xcode version 4.5 and newer:

1. Set the “Generate Test Coverage Files” build setting to Yes.
2. Set the “Instrument Program Flow” build setting to Yes.

Once you’ve configured your build settings:

1. Rebuild your app and run the unit tests.
2. Locate where the generated *.gcda and *.gcno files were put
   (Organizer -> Projects -> Derived Data -> look in directories below)
3. Start CoverStory and open the directory containing teh *.gcda and *.gcno files.

Cover story will list all of the files built by your project except those identified as Unit Test files. By default these are files matching *Test.[hHmM]. In my case though, I tend to name my unit test files using the plural *Tests.[hHmM], so the default report lists coverage for these also. This is just clutter.

To remedy this, I just had to add another entry to CoverStory->Preferences->Test Files to include the string “*Tests.[hHmM]”.

In addition, I’m using AFNetworking, so these files are reported also. To eliminate 3rd party code like this, use CoverStory->Preferences->SDK Files to exclude their directory/path. In this case, I added the line “*/AFNetworking/*”.

Another option that I’m exploring is moving the untestable code into a separately, clearly identified file (eg. ViewController+Untested). These files can then be filtered from reporting by adding “*Untested.[hHmM]” also.

After rebuilding your code each time, remember to click CoverStory’s refresh button to see the updated coverage report. Also be careful that you do not accidentally click on of the “Show…” buttons when moving the window around. I had done this, which causes those hidden test files to be displayed, leading me to think that there was a bug in CoverStory’s filtering. Turns out the bug was me 🙂

One of the questions that will arise once you start really using unit testing is “How much of my code is actually tested?”. iOS and CoverStory make determining this fairly simple.

During compile, setting the profile-arcs and test-coverage flags and including the libprofile_rt.dylib causes the compiler to generate gcov records that report statistics about test coverage.

CoverStory can then be used to display the information from those records. Refer to the instructions for CoverStory for details on how to download, install, and run CoverStory.

Now I need to investigate how to make this work when using GHUnit…