Installation

Available installation methods

You can add Cedar to your project using Carthage, CocoaPods, or as a cross-project submodule dependency using git.

Carthage method

Carthage is intended to be the simplest way to add frameworks to your Cocoa application according to the project's home page. Quite simply, it will build your dependencies as dynamic frameworks and allow you to integrate them into your project as you see fit.

• If Carthage is not already installed on your system, install it using Homebrew with brew install carthage
• Create or add a line to your project's Cartfile.private file (for test dependencies), such as github "cedarbdd/Cedar" ~> 1.0
• Run carthage update (note, this command has many sub-options; read its help page for more info on caching builds, etc.)
• Add the generated Cedar.framework to your test suite's linker phase, as well as the Carthage copy frameworks phase outlined in Carthage's getting started instructions.
• That's it! Start writing specs using Cedar!

CocoaPods method

CocoaPods is a dependency manager for Swift and Objective-C Cocoa projects, which automates and simplifies the process of using 3rd-party libraries in your projects.

Using CocoaPods is the easiest way to install and get started with Cedar. It'll allow you to add Cedar to an existing test bundle in your project and start writing specs immediately.

• If CocoaPods is not already installed on your system then gem install cocoapods
• Run pod init in the root of your project if it doesn't already have a Podfile
• If you're using Swift, you have to build your pods as frameworks, so make sure to add use_frameworks! to the Podfile
• Assuming you are working with a newly-created Xcode project named 'MyApp', add the Cedar pod as a dependecy of it's tests in the Podfile like so:

target 'MyAppTests' do
  pod 'Cedar'
end

If your test bundle target has a different name, enter it in place of MyAppTests in the example above. You may also want to use the podspec from Cedar's git repo, as the CocoaPods/Specs repo may not be up to date.

target 'MyAppTests' do
  pod 'Cedar', git: 'https://github.com/pivotal/cedar.git'
end

Now run pod install in a terminal in the root of your project.

If you haven't already, close the project in Xcode and re-open the workspace created (and required) by CocoaPods. You should now be able to create Cedar specs in your test bundle, and they should run when you run your tests. They must be Objective-C++ (with a .mm extension) to use all of Cedar's features. Here's an example for MudSpec.mm:

#import <Cedar/Cedar.h>

using namespace Cedar::Matchers;
using namespace Cedar::Doubles;

SPEC_BEGIN(MudSpec)

describe(@"My name", ^{
    __block NSString *string;

    beforeEach(^{
        string = @"My name";
    });

    it(@"should be Mud", ^{
        string should contain(@"Mud");
    });
});

SPEC_END

Installation of file templates is recommended, as it will simplify creation of Cedar spec files. Check out Getting Started for next steps on using Cedar.

Cross-project submodule dependency method

Installing cedar as a git submodule is useful if you want access to it's git history (if you are working on a contribution, for example). Unless you need this, we recommend using the CocoaPods approach.

1. Add cedar as a submodule to your project

    $ git submodule add git://github.com/pivotal/cedar.git Externals/cedar
   

2. Add the Cedar.xcodeproj project in the Externals/Cedar directory to your Xcode project.

3. If you don't already have a tests target for your app, add one (Cocoa Touch Testing Bundle for iOS, Cocoa Testing Bundle for OS X).

4. Edit the settings of the bundle target by selecting it in Xcode.

5. Under 'Build Settings', find 'Other Linker Flags' and add -all_load and -ObjC

6. For iOS:

   1. Under 'Build Phases', add Cedar-StaticLib in the 'Target Dependencies' section.

      This tells Xcode that building this library is necessary to build the target.

   2. Under 'Build Phases', add libCedar-StaticLib.a in the 'Link Binary With Libraries' section.

      This tells Xcode to link against the library and make its object code available.

   3. Under 'Build Phases', add UIKit.framework in the 'Link Binary With Libraries' section if it isn't present.

      This tells Xcode to link against UIKit so that Cedar can extend it.

   4. Under 'Build Settings', find 'Header Search Paths' and add $(SRCROOT)/Externals/cedar/source/headers, marking it as recursive. If you used Xcode to initialize a git repo when creating the project, the SRCROOT macro will expand to a different location. In that case, use the following instead $(SRCROOT)/../Externals/cedar/source/headers.

      This allows Xcode to find your header files since they aren't packaged with a static library. You should #import Cedar with "Cedar.h" instead of <Cedar/Cedar.h>.

7. For OS X:

   1. Under 'Build Phases', add Cedar in the 'Target Dependencies' section.

      This tells Xcode that building this framework is necessary to build the target.

   2. Under 'Build Phases', add Cedar.framework in the 'Link Binary With Libraries' section.

      This tells Xcode to link against the framework and make its object code available.

You can now select different branches or selectively upgrade your Cedar submodule. Check out Getting Started to start using Cedar right now.

Installing templates and snippets

Installation of file templates and snippets is recommended, as it will simplify creation of Cedar spec files. The Getting Started page has a list of them and what they do. Here's how to install the latest released version of these into Xcode:

• Install the Xcode command line tools package (Under the Preferences tab 'Downloads') if you haven't already done so.

• Run the following in a terminal:

    $ curl -L https://raw.github.com/pivotal/cedar/master/install.sh | bash
  

If you want the latest development versions of these templates, you can install these with this command instead:

    $ curl -L https://raw.github.com/pivotal/cedar/master/install.sh | bash -s head

Installing without running arbitrary scripts

If you're paranoid about running arbitrary scripts you can follow this procedure instead:

• Clone the Cedar repository from github:

    $ git clone https://github.com/pivotal/cedar.git && cd cedar
  

• Build and install templates:

    $ ./installCodeSnippetsAndTemplates # or rake install
  

• Restart Xcode

Dependency on XCTest / SenTestingKit

In the usages described above, Cedar extends Xcode's built-in test frameworks (XCTest [Xcode 5+] and SenTestingKit). Depending on your needs, you may want to run Cedar standalone, without relying on these frameworks. Check out Standalone Setup for more details.