Setting up travis-ci for automated unit testing of iOS projects on GitHub

This guide is how I set up new projects to run unit tests automatically when I push a commit or merge a branch on GitHub for iOS projects.

The first step is to create a new project in Xcode. I am going to select a single view application and enable storyboards, Automatic Reference Counting and Unit Tests.

Screen Shot 2013-05-06 at 11.42.27 PM

All I’m going to change is the testExample method in the unit testing bundle to something that will pass. For now I have just gone with this:

- (void)testExample
    STAssertNil(nil, @"This object should be nil");

Check that the tests pass by hitting cmd+u. Now that I have my unit tests passing, I’m going to add this project to GitHub. I’ll leave the details out here, as this isn’t the focus of this tutorial but you can find my example project here:

Now we can setup the TravisCI build. I use the xctool to build my projects as it has a nicer output and is easier to use than the built in xcodebuild tool. Add xctool as a submodule to the git repository using the following commands:

git submodule add ./xctool
git submodule update --init
git commit ./xctool -m "Added xctool as a submodule"

Then we need to add a config file so that travis-ci knows how to build our project. This file is named .travis.yml and lives in the root of the git repository. Here is the contents of mine:

language: objective-c
before_install: "git submodule init && git submodule update && sudo gem update --system && sudo gem install bundler && bundle install"
script: "bundle exec rake test --trace"

Then we have to add a Rakefile that tells the xctool which project and target to build:

desc 'Run the tests'
task :test do
   exec('xctool/ -project SettingUpTravisCIForiOS.xcodeproj -scheme SettingUpTravisCIForiOS test')

task :default => :test

And finally the Gemfile

source ''

gem 'rake'

You can then test locally that your project builds using the command rake in your root git repository.
I get build messages, then ** TEST SUCCEEDED: 1 of 1 tests passed ** (25285 ms). Now that we have the unit tests running locally, all that is left is to set up the travis-ci build. Login to with your GitHub account and under account settings select the repository that should be unit tested automatically. This automatically sets up a service hook in GitHub so that every time you push to your repository, it will get unit tested.

You can also use the status images from travis-ci to show the test status directly in your README file on GitHub. Check out my example project here: SettingUpTravisCIForiOS


Developing Xcode 4 Plugins

This is a quick guide that documents how to start developing plugins for Xcode4. You need to have Xcode installed to create plugins.

Step 1 – Xcode Plugin Project Template

  • Grab the Xcode project template for creating plugins from here
  • Create the plugin template folder ~/Library/Developer/Xcode/Templates/Project Templates/Application Plug-in/Xcode4 Plugin.xctemplate if it doesn’t already exist.
  • A quick way to do this is with the following command mkdir -p "~/Library/Developer/Xcode/Templates/Project Templates/Application Plug-in/Xcode4 Plugin.xctemplate"
  • Copy the contents of the GitHub repository to the folder you just created.
  • Restart Xcode.

Step 2 – Create a test project

  • Open Xcode, and select File > New > Project
  • Then under OS X > Templates tap Xcode4 Plugin (shown below)

Screen Shot 2013-04-29 at 3.44.05 PM

From the GitHub repo:

The default plugin file links against AppKit and Foundation, and, when built 
(and Xcode is restarted), creates a menu item labeled "Do Action" in the File menu. 
Pressing the menu item should open an alert. Customize at will!

If we run the project we just created, it will automatically build and copy the plugin to the right location. In this case it is ~/Library/Application Support/Developer/Shared/Xcode/Plug-ins/[Project Name].xcplugin. Restarting Xcode, we get a new menu item under the File menu!

Screen Shot 2013-04-29 at 3.53.02 PM

When we click on the menu item, we get an alert:

Screen Shot 2013-04-29 at 3.53.49 PM


  • Xcode plugins have to be written using Objective-C GC, this means you have to use retain and release calls in your code. (No ARC support).

Where to go from here?

  • This StackOverflow answer has some great ideas on where to go next.
  • You can get a dump of the private headers that Xcode uses by using the class-dump tool
  • brew install class-dump is the quickest way to get it if you have homebrew installed.
  • IDEKit and IDEFoundation are present at
  • DVTKit and DVTFoundation are present at
  • By registering an observer for nil you can see all the notifications that are being called. This is useful to find out which actions are called and when, and what notifications you might need to listen for.

Auto build and deploy iOS apps using Jenkins

We will have a look at a TestProject to get an idea of how jenkins can be used to build, sign and deploy iOS projects. The whole process consists of 4 steps. Note that to deploy an app in this manner, an enterprise distribution certificate is required for each app.
This guide is how I have set up my enterprise builds for my apps that use cocoaPods for dependencies, but most of the same principles apply for any iOS apps.
Because the project uses cocoaPods, it means we have to build a workspace and have a build scheme set up.

Note: Apple Enterprise licenses can ONLY be used for builds internal to your company. I am not responsible for anything that may happen if you try to distribute apps outside your company using an enterprise license.

This guide may be a bit brief, don’t hesitate to ask me any questions. This is mostly for my own reference.

Step 1 – Poll SCM

  • Dev builds poll the SCM looking for changes to the master branch at midnight every night.
  • If no changes have occurred, then the project is not built.
  • If modifications have been made, the next step is executed.

Step 2 – Xcode build

Below is a screenshot from jenkins showing the fields used for the xcode plugin.

Screen Shot 2013-04-23 at 4.01.12 PM

  • Clean before build – we don’t want any cached compiled objects hanging around.
  • Xcode Schema FileTestProjectDev
    • Because of the way we have our project set up, our top level item is a workspace (TestProject.xcworkspace), we have to build based on Schemes as Xcode does not support building a target from a workspace.
    • TestProjectDev specifies the scheme we want to build with.
  • ConfigurationRelease
    • We want the release version. There are several subtle differences between Debug and Release versions. The most notable is that Debug builds are usually built for just one architecture, where Release builds are built for all supported architectures, usually with compile time optimisations as well.
  • Workspace File – This is our top level workspace file (TestProject.xcworkspace) that we build from. If this option wasn’t specified, by default the xcode build would look for the first *.xcodeproj file it can find. This would cause our build to fail.
  • Unlock Keychain
    • This allows us to unlock the keychain which is required for signing or resigning .ipa files.
    • The location of the keychain is the default OSX location

Step 3 – Resigning

  • This step only occurs if previous steps were successful
  • This step only occurs if the text BUILD is present in the log text (basically every build)
  • The result of this build will be escalated to the job status. If this step fails and other steps before it were successful, the job will still fail.

Below is the script used for resigning:


DEVELOPER_NAME="iPhone Distribution: Test Company LTD"

#Sign The .app file and create .ipa file
/usr/bin/xcrun -sdk iphoneos PackageApplication -v  "${PROJECT_BUILDDIR}/${APPLICATION_NAME}.app" -o  "${BUILD_HISTORY_DIR}/${APPLICATION_NAME}.ipa" --sign ${DEVELOPER_NAME} --embed ${PROVISIONING_PROFILE}

#Get the version from the Info.plist file
VERSION=`defaults read ${APP_PATH}/Info CFBundleShortVersionString`
BUNDLE_ID=`defaults read ${APP_PATH}/Info CFBundleIdentifier`

# Create plist
cat ${HOST_LOCATION}/template.plist | sed -e "s/\${APP_NAME}/$APPLICATION_NAME/" -e "s/\${BUNDLE_ID}/$BUNDLE_ID/" -e "s/\${BUNDLE_VERSION}/$VERSION/" > ${HOST_LOCATION}/${APPLICATION_NAME}.plist
  • The first part of this script sets up the locations and script variables
    • PROJECT_BUILDDIR – The folder that the built .ipa file resides from the previous build step.
    • APPLICATION_NAME – In this case it is TestProjectDev
    • BUILD_HISTORY_DIR – The folder that the re-signed app will be output to
    • DEVELOPER_NAME – Has to match the .mobileprovision file used for signing.
    • PROVISIONING_PROFILE – The location of the .mobileprovision file used for signing. These must be downloaded from the Apple developer website or shown in Finder from the Xcode organizer.
    • HOST_LOCATION – Where the final signed app will exist
  • The next stage of the build process is actually re-signing the app using the Xcode command line tool called xcrun. Note that the version in /usr/bin/ is a symlink to the Xcode version that has been selected by the xcodeselect command line tool. This is important if more than one version of xcode is installed. Each version of Xcode stores command line tools inside the .app file in applications.
  • After re-signing, we grab the version, and bundle-id. These are used in the next part
    • APP_PATH – The full path including the .app extension of the re-signed app
    • VERSION – This is the CFBundleShortVersionString. This value is set when you change the version in Xcode for each of the build schemes.
    • BUNDLE_ID – The CFBundleIdentifier for the built app. For TestProject, this will be These can be set by modifying the build Schemes, but shouldn’t be changed for existing applications. Production has a different bundleId, which is what allows for both the dev and prod versions to exist on a single iPad at the same time.
  • We then auto generate the enterprise install PLIST file. This is needed to install apps from a URL location and acts as a “description” of the app that is about to be installed.
    • The actual creation of this file is quite simple, we use cat to copy the template.plist file to the new location and then using sed we replace the BUNDLE_ID and BUNDLE_VERSION values. These values are read from the Apps Info.plist from inside the .app folder.
  • Below is an example template.plist file
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "">
<plist version="1.0">

Step 4 – Copying to host location

  • This step simple grabs the signed .ipa file and puts it in the host location so that the macmini website can serve it over a URL. The host location is /Library/Webserver/Documents/apps

Script looks like this:




And that’s it! The output is a .ipa file and a .plist file. These are both required to install an enterprise app.

Objective-C Style Guide

This is the style guide that I follow when programming in Objective-C, this is for my own reference, but other people may find this useful.


  • Use modern objective-c 2.0 syntax
  • Use ARC whenever possible.
  • Manual memory management should only be used when using older libraries that haven’t been updated yet.
  • Use tabs when indenting, not spaces.

Code Naming Basics

  • Follow the Apple naming guidelines
  • Use descriptive names, even if they are long. Xcode has great code completion features. Use them.
    • Clarity is preferred over all else.
    • E.g. Compare the two methods: [spaceship fly: 10.0f] and [spaceship flyAtSpeed: 10.0f].
    • Note how much clearer the second declaration is, the method describes its intentions and parameter names.
  • Don’t use abbreviations. E.g. bgColor vs. backgroundColor
  • Custom resuseable classes should be prefixed with AFG
    • Application level classes do not have to be prefixed. E.g. ViewControllers
  • All view controllers should be descriptively named and end with ViewController.
    • E.g. CalculatorSettingsViewController


  • Follow the appledoc code formatting style.
  • Only comment the method declarations. E.g. In the @interface or private @interface ... () code blocks.
  • Describe what the method does, the parameter names and the return value and what it signifies. The following is a good example of method commenting:
/** This method asks the delegate if the AFGContainerViewController should pop the current view from the view stack.
 @param - The current AFGContainerViewController object
 @return A BOOL value indicating if the current view controller should be removed from the AFGContainerViewController's view stack.
-(BOOL) AFGContainerViewControllerShouldPopContainerViewController: (AFGContainerViewController*) containerViewController;


-(void) performOperationWithObject: (NSObject*) objectName {

  NSLog(@"This is a well spaced method");
  [objectName performSomeOperation];
  • No space between the class or instance specifier (+,-)
  • Single space between the return type and method name
  • Single spaces between method signature, object types and object names
  • Brace on the same line as the method signature.
  • Optional newline below the method signature for readability
  • No newline before the closing brace

Variables and Initializers

  • Variable names should always start with lower case.
    • Good: numberOfObjects
    • Bad: NumberOfObjects
  • Clearly identify the designated initializer for the class
    • All other initializers should propagate up to and use the designated initializer.
  • Override the superclass’ designated initializer.
  • Initialization method should be at the top of the @implementation
  • Don’t explicitly initialize variables to nil. Under ARC this happens automatically.


  • Don’t @synthesize properties. ARC does this automatically.
  • Always start with a lower case letter.
  • NSString properties should always be copy
  • IBOutlets should always be weak

Other readings

These are some good references / starting points for creating your own style guide or just to see other coding styles.

Objective-C Runtime

It is pretty rare to actually have to dive into the objc-runtime for any day to day coding. Most developers wont have to touch the runtime, however it is helpful to know what is possible and be able to use it if required. The objective-c runtime is written in C and is how the underlying parts of the objective-c language work including message sending, ivars and properties. This post shows an example of where I have used the Objective-C runtime in one of my projects.

One example of where I have used the runtime in my projects is the validation code in DBValidator. The validation code is implemented as a category on NSObject called NSObject+DBValidator. This is so we can add validation rules to any objective-c object. The only problem with this approach is that you can’t add any properties or ivars to an object using a category.

We can work around this limitation by using the objective-c runtime directly.

Below is the implementation of the NSObject+DBValidator category:

#import "NSObject+DBValidator.h"
#import <objc/runtime.h>

#define VALIDATION_RULES_KEY @"validationruleskey"

@implementation NSObject (DBValidator)

-(void) setValidationRules:(NSMutableArray *)validationRules {
    objc_setAssociatedObject(self, VALIDATION_RULES_KEY, validationRules, OBJC_ASSOCIATION_RETAIN_NONATOMIC);

-(NSMutableArray*) validationRules {
    NSMutableArray *validationRules = objc_getAssociatedObject(self, VALIDATION_RULES_KEY);
    if (!validationRules)
        validationRules = [NSMutableArray array];
    return validationRules;

-(void) addValidationRule: (DBValidationRule*) validationRule {

    NSMutableArray *validationRules = self.validationRules;
    if (validationRule)
        [validationRules addObject:validationRule];
    self.validationRules = validationRules;

-(void) removeAllValidationRules {
    NSMutableArray *validationRules = self.validationRules;
    [validationRules removeAllObjects];
    self.validationRules = validationRules;

-(NSMutableArray*) validate {
    NSMutableArray *failureMessages = [NSMutableArray array];
    for (DBValidationRule *rule in self.validationRules) {
        BOOL isValid = [rule passesValidation];
        if (!isValid)
             [failureMessages addObject: rule.failureMessage];
    return failureMessages;


We have a @property defined in the header called validationRules and we override both the setter and getter in the implementation. In the setValidationRules: method we use a C function from the objective-c runtime called objc_setAssociatedObject. This function allows us to set a reference on the self object. We give it a key, the object (in this case the validationRules passed to the method) and the association policy.

The valid options for the association policy are:

enum {

Notice how these options map directly to @property storage options! We are using OBJC_ASSOCIATION_RETAIN_NONATOMIC because we want our NSObject to retain the validation rules that are set on it.

In our validationRules method, we use a similar call from the objective-c runtime called objc_getAssociatedObject. This allows us to retrieve the object we set a reference to in the preious method. We have to pass the parent object and the key for the associated object we want. We return an empty array if validation rules are not yet set for this object.

Check out the full source code in the DBValidator GitHub Project

General purpose validation library for objective-c and iOS

This is a simple validation framework that I created for one of my projects that I am releasing under an open source MIT license.

The framework supports a number of different types of validations including string length, number range, email validation, regex validation and equality.

Validation rules can be added to any keypath of any object that inherits from NSObject, as well as having multiple validation rules per object. Here is a screenshot:


And here is the project on Github – DBValidator