Tracing Unit Tests with the XCode 3 Debugger
2008-02-07
XCode has a nifty integrated debugger which is really a pretty wrapper around gdb . It lets you point and click, and drill down on things within the gui with ease, but still preserves access to the underlying raw gdb console and output. You can create breakpoints and watches, both literal and dynamic, step through your application as it runs, all the usual stuff.
I'm not the world's greatest user of debuggers. I'm more likely to trace through things until they make sense using some combination of logging, print statements, paper and pencil, or my absolute favourite, just explaining your mystery problem out loud to a nearby third party, embarrassing yourself by spotting the obvious bug mid-flow. That last one sometimes even works with the dog. Sometimes though, you're stumped, and you want to set some watchpoints, step through your program as it executes, or just generally prod things mid-run, and poke around under digital rocks.
Something I've been trying to practice recently is Test Driven Development . XCode 3 ships with support for the OCUnit testing framework built in. You can add a Testing target to your XCode project, and build up test case classes that use this framework, and the build tools know how to run these through the test harness. And so you progress, write a test for a feature, run the test harness, write code to pass the test harness, repeat. It's a great way of not only catching certain classes of bug before they happen, but perhaps more interestingly imposing a more minimal design focus on your application as you build it; you're automatically casting yourself more in the mind of a consumer of your application services, something I find really helps avoid over-design.
At some point though you are likely to run into some kind of hard to understand failure case within a unit test, and find yourself reaching for the debugger. And then finding that the debugger doesn't work. This is because the runtime of your unit testing target is actually the separate test harness framework, and not your application target. The test harness is a regular application that's dynamically loading your test classes and running them. In order to be able to use the IDE to debug your unit tests, you just need to do a little extra configuration within your XCode project, as follows.
The tool that runs the tests is called otest . You need to add this to your XCode Unit Test target as the executable. You can do this with the command ' New Custom Executable ' in the Project menu. Add /Developer/Tools/otest .
Once it is added, set it as the active executable for the Unit Testing target, using Set active executable , in the Project menu. A green tick badge appears over the active exectuable in the xcode source list.
The otest tool expects to be run with a certain environment, and arguments. There's a man page that describes them. You could run gdb against the otest executable from a shell in this fashion, but it means switching away from XCode. Alternatively, you can set up XCode to provide these when it runs your target by double clicking the otest executable in the source list to bring up it's inspector. The runtime settings you need to set are all on the Arguments tab.
Add two arguments -SenTest Self and the name of your Unit test bundle, which will be the name of the Unit Test target with a '.octest' suffix e.g. "My Unit Tests.octest" . The quotes are important, if you have whitespace in your bundle name. Make sure that the order in the inspector list has '-SenTest Self' as the first element, and the bundle name the second, so that when they are concatenated to a command line, the switches come before the bundle name.
You also need to set two environment variables, in the lower pane of the arguments inspector, so that the dynamic linker can resolve your test components. The lower pane of the Arguments tab covers variables. Add two items to this list, DYLDLIBRARYPATH and DYLDFRAMEWORKPATH . Set both of these to be $(BUILTPRODUCTSDIR) which is the variable xcode build will populate with the correct destination of your compiled test cases object code.
With all of this set, you can just use the debugger within XCode. Click to set break points within the editor as you write your test cases, and the debugger will spring into action appropriately, whenever you build and run the test target.