I recently decided to tackle a long-postponed refactoring of my source base: to move from my own, custom CFNetwork-based “URL request” class, to something based on the modern NSURLConnection or NSURLSession classes from Apple.

When I first started writing networking code for OS X, NSURLConnection didn’t exist yet. If you wanted a class that approximated the convenience of NSURLConnection as we know it today, you had to write your own wrappers around the lower-level CFNetwork HTTP library functions. If you needed to have precise control over the loading of network resources from the web, you simply had to use CFNetwork (or the 3rd-party open-source libcurl library, which some folks did do!.)

When I acquired MarsEdit from NewsGator in early 2007, I wasn’t surprised to learn that Brent Simmons (the original author) had also implemented his own CFNetwork-based HTTP class: RSHTTPDownloader. I took a look at it and my own class, RSHTTPRequest, and ended up migrating the best parts of his with the best parts of mine, keeping the name I had grown accustomed to: RSHTTPRequest. (It was a great convenience that Brent’s Ranchero Software and and my Red Sweater adopted the same class-name prefix).

Fun fact: I actually worked briefly on the CFNetwork team at Apple, and learned the ropes of that somewhat-daunting, low-level API. Suffice to say, I was less scared off by CFNetwork than some people, but even I didn’t consider it to be perfectly simple to use. However, it worked well enough and when NSURLConnection debuted later in 2007, I found it somewhat wanting. I can’t remember the details but there were little things that I’d come to appreciate about having direct access to the “streams” and I lost that by moving to NSURLConnection. So I stuck with RSHTTPRequest.

Fast-forward more than seven years and I’m still on RSHTTPRequest. But now, it’s clearly to my detriment. Not only has Apple been improving NSURLConnection and the rest of the networking stack all this time, a couple years ago they introduced the all new NSURLSession, which makes the whole setup easier to use and more powerful at the same time. Capping off the incentives is the fact that new functionality such as background network loading sessions are essentially required if you want to make good use of recent technologies such as Share Extensions. In short, it’s a great time to switch to NSURLSession.

Just Switch to NSURLSession!

The only problem is I’ve spent more than seven years building a pretty complex network-oriented app around this one, I hesitate to say little anymore, this one disgusting evolution of what started out as a simple wrapper around CFNetwork’s HTTP loading mechanism. RSHTTPRequest has every manner of convenience method, special cases, not to mention subclasses covering highly specialized networking operations such as POST’ing HTTP forms, communicating with most blogging APIs on the planet, etc. You get the idea: I can’t just switch to NSURLSession. So what am I going to do?

I’m a very paranoid person when it comes to code, and it soothes me to take small, predictable, measurably safe steps when it comes to situations like this. I already have a number of unit tests on RSHTTPRequest that verify its behavior to a reasonable extent. The basics are covered, and as I’ve discovered and addressed bugs over the years, I’ve usually taken the time to add unit tests covering the nuances. So to be perfectly clear, the main impediments to my switching to NSURLSession are:

1. The interface to NSURLSession is totally different from my custom class.
2. The default behavior of NSURLSession is totally different from my custom class.

So I could hunker down for a long weekend, write a new NSURLSession-based helper, RSSpiffyRequest, and then change every single line of code that deals with RSHTTPRequest to instead use the pertinent methods on the new class. One problem with this approach is that I have to come up with the all new RSSpiffyRequest interface from scratch, before I change a single line of code. The other problem is even if I come up with the perfect interface for my new class, I’ll inherit all the unpredictably different behaviors of NSURLSession. Things will randomly not work. Crashes will probably happen. It will suck.

The only way forward, to my paranoid mind, is to find a way to slow down the transition so that fewer parts are changing at once. Since RSHTTPRequest already satisfies a contract with countless clients, and because it’s already covered by a moderate number of unit tests, the safest way forward is to change RSHTTPRequest so that it’s based on NSURLSession.

But hold on, that’s too fast for me, too. I don’t want to reimplement RSHTTPRequest’s whole interface at once, hold my breath, and hope that all the code still works. Instead, I need a new class that implements the interface of RSHTTPRequest, can be tested like RSHTTPRequest, and can be moved to by client code gradually, as the expected behavior is confirmed.

Parallel Request Classes

The approach I decided to take is to add a new class, RSLegacyHTTPRequest. The name is future-proofed: the presence of the word “Legacy” in the name is to remind me that it’s not the end-all be-all NSURLSession subclass. It’s not the ideal, convenient networking object that should be used across my source base. Instead, it’s the nasty, pragmatic, full-of-history class interface of RSHTTPRequest that happens to be implemented on top of NSURLSession.

This gives me the freedom to willy-nilly switch client code from RSHTTPRequest to RSLegacyHTTPRequest, just to see what happens. A great place to start was in the RSHTTPRequest unit tests class I mentioned. It currently verifies the behavior of RSHTTPRequest for most all niggling network details I’ve encountered over seven years. I switched it from testing RSHTTPRequest to testing RSLegacyHTTPRequest by simply adding this to the top of the test file:

#define RSHTTPRequest RSLegacyHTTPRequest

Boom! Everything fails. That’s a nice start, and makes for an easy challenge to chip away at. Pick a failing unit test, and make it work. In my case this involved discovering how to simulate or approximate the interface of the old RSHTTPRequest, but on top of NSURLSession. Slowly but surely, I came to a point where I had a new RSLegacyHTTPRequest class, completely based on NSURLConnection, that passes all my existing tests.

I was far from done. I have other classes that use RSHTTPRequest, and themselves have unit tests of their own. I pulled a similar trick to uncover other unit testing edge cases that should have been in RSHTTPRequest, but weren’t. I was beefing up my test class, in some cases even finding residual bugs from my old implementation.

I got to a point today where I realized I had a more-or-less “fully” functional RSLegacyHTTPRequest class, but I am still not ready to abandon RSHTTPRequest. I have other clients to meander through, verifying that they behave as expected when switched over to the new class. In the mean time, I was stuck wondering whether the unit tests, those golden unit tests, should be left testing the old RSHTTPRequest or testing the new RSLegacyHTTPRequest? Answer: they’re both in use, so both should be tested.

Multi-Class Unit Tests

Finally we get to the namesake of this article’s title: how do I use the same precious collection of unit testing code but apply it to two (or more!) classes that happen to share the same interface? The answer is to subclass. When you implement and run unit tests in an Xcode project, the testing system looks at runtime for any classes in the test bundle that “have methods that start with -test”. What this means is that, if you wanted to, you could redundantly run all the unit tests in one of your test cases twice simply by subclassing it and leaving the subclass empty. If “MyTests2” is a subclass of “MyTests”, then at runtime, it’s going to find and execute all the tests in each of the classes, which will happen to be exactly the same tests.

For my situation, I want to run all the tests twice, but I want to run them on instances of different class. I decided to accomplish this by making some modest edits to the test class, replacing every alloc/init pair for RSHTTPRequest:

[[RSHTTPRequest alloc] init...]

With a bottleneck method that instantiates the class from an overridable Class object:

- (Class) classForHTTPRequestInstances
{
	return [RSHTTPRequest class];
}

- (RSHTTPRequest*) requestForTestingWithURL:(NSURL*)theURL
{
	return [[[self classForHTTPRequestInstances] alloc] init...];
}

I then added a new unit test class called “RSLegacyHTTPRequestTests”, which merely implements -classForHTTPRequestInstances to return RSHLegacyHTTPRequest. Now when I build and run unit tests, every single, painstakingly collected unit test gets run twice, once for each of the super-important URL request wrapper classes in my framework.

Over time, hopefully over a short period of time, I’ll move away from RSHTTPRequest to RSLegacyHTTPRequest. And then, hopefully over a similarly short period of time, I’ll start moving to RSSpiffyRequest. All the while, however, I’ll rest easy at night, knowing that to a very great extent, all the functionality I’ve come to expect over years of developing this code is being constantly confirmed by this glorious set of unit tests.

Some Xcode projects use a handy feature for extending the build process called a Run Script build phase. These build phases can be added to the linear list of steps that Xcode steps through when building a target, such that custom tasks such as preparing dynamically generated source code, verifying build results, etc., can call be done as part of Xcode’s standard build routine.

A problem you might run into is that a long-running script phase can be a real drag to wait through every single time you build. You can work around this problem in a few ways, depending on what makes sense for your project. Two of the simplest options are:

1. Check the box to run the script only “when installing.”

This is particularly handy if the stuff that’s happening in the build phase really doesn’t need to be there until the final release build, or if you are willing to manually perform the steps during development.

2. Add logic to your build phase script to detect the build configuration, and either perform a more expedient version of the task, or skip it altogether. For example, a build phase that does laborious profiling of your finished product may not need to be done on “Debug” builds, so you could add a clause to the script:

   if [ ${CONFIGURATION} == Profiling ] ; then
   	echo "Running a very long profiling task!"
   	...
   	echo "Finished running a very long profiling task!"
   else
   	echo "Skipping long profiling task! Whoo!"
   fi
   

   (Note: you don’t have to use bash for your shell script phases. In fact, you can run whatever interpreter you like. I typically use Python, but used bash here as a canonical example).

These tricks work out fine when a script phase is clearly only needed under special circumstances, but what about script phases that have to be done every time you build, rely upon files that may change over time, and take a considerable amount of time to finish? For this we can take advantage of another nuanced feature of Xcode script phases, which is the ability to specify arbitrary input and output files for the script. I think it’s time for an illustrative screenshot:

Here’s the low down on the impact of specifying input and output files with script phases in Xcode:

1. Lack of modification to any of the listed input files encourages Xcode not to run the script phase. Hooray! Fastness!
2. Non-existence of any listed output file compels Xcode to run your script phase.
3. The number of input and output file paths is passed to the script as ${SCRIPT_INPUT_FILE_COUNT} and ${SCRIPT_OUTPUT_FILE_COUNT} environment variables.
4. Each input and output path is passed as e.g. ${SCRIPT_INPUT_FILE_0}, ${SCRIPT_OUTPUT_FILE_1}, etc.

In practice, what does this mean when you go looking to speed up your script phase? It means you should:

1. List as an input every file or folder that may affect the results of your script phase.
2. List at least one output, even if your script doesn’t leave any reliable artifacts.

One frustrating bug I should point out here is that Xcode (as of at least Xcode 6.0 and including 6.2 betas) is not as attentive as it should be about changes to the the input and output file lists. If you make changes to these lists, rebuild several times, and don’t see the efficiencies you expect being applied, you should close and reopen your Xcode project document. It seems to cache its notion about script phase dependencies, and will stubbornly stick to those rules until forced to re-evaluate them from scratch. I reported this to Apple as Radar #19233769.

Referring back to the screenshot above, you can that in this contrived example I have listed two input “files,” but in this case they are actually directories. This is to illustrate that if you list a directory, Xcode will trigger a re-running of your script phase whenever any shallow change occurs in that directory. For example, if I add, delete, or modify any files in ImportantStuff”, the script will run on the next build. However, if I modify a file within “ImportantStuff/Goodies”, it will not trigger the script to run because Xcode does not monitor for changes recursively.

You will also see that I’ve gone to the trouble of artificially adding a bogus file to the derived files folder, indicating the script has run. That has the effect of causing a “clean” of the project to wipe out the artificial file and thus cause the script phase to run again even though none of the input files may have changed. If I wanted to ensure that the script phase is skipped as aggressively as possible, I could provide e.g. a path to an output file that is guaranteed to exist, such as a stable file in my project like “$(SRCROOT)main.m”. Because the designation “Output File” in this case is only a hint to the Xcode build system, you don’t have to worry (and can’t expect) that the file will be created or altered unless you do so yourself in the script. This feels a little dodgy to me though, because Apple could choose to change the behavior in the future to e.g. imply that “clean” should delete all listed output files for a script phase.

Script build phases are a woefully under-documented, incredibly useful component of the Xcode build system. They are especially useful when they run blazingly fast or are skipped completely if not needed. I hope this information gives you the resources you need to take full advantage of them.