Contributor guide

We welcome your contributions - Thanks for helping make Cedar a better project for everyone. Please review the backlog, issues list and discussion list before reporting issues or starting work. What you're looking for may already have been done. If it hasn't, the community can help make your contribution better.

Reporting issues

Please report problems to the issues list.

Updating documentation

This wiki belongs to the community. Please feel free to improve the documentation found here.

Making changes

In order to make changes, you need to get your development environment set up, make your changes on a fork of the Cedar repository and then issue a pull request. Please follow the advice below to ensure that your contribution will be readily accepted.

Development environment setup

• Please use the latest release (not beta) version of Xcode and ensure you have installed the command line tools and iOS simulator 5.1
• Install ios-sim from npm or github
• Fork the cedar repository at github
• Clone the forked repository locally
• Run rake in a terminal in the directory where you cloned the repo to ensure all tests pass before you begin

Make your changes

• Create a branch for your changes (optional, but highly encouraged)
• Write tests for your changes; Cedar is used to test itself
• Make your tests pass by implementing your changes
• Ensure all tests still pass when you run rake
• Push your changes up to your fork at github

Make a pull request

When you have finished making your changes and testing them, go to your forked repo on github and issue a pull request for the branch containing your changes. Please keep in mind the following before submitting your pull request:

• We favor pull requests with very small, single commits with a single purpose. If you have many changes, they'll be more readily received as separate pull requests
• Please include tests. They help us understand your intent and prevent future changes from breaking your work. Changes without tests are usually ignored
• Please ensure all tests pass (via rake) before making a pull request. Your contribution shouldn't break Cedar for other users
• Please ensure all trailing whitespace characters are removed from your changes.

Background

Directory layout

Cedar Code

• Cedar code itself resides in the Source directory and should be added to the Cedar and Cedar-StaticLib targets
• Cedar code specific to testing on iOS resides in Source/iPhone and should only be added to the Cedar-StaticLib target
• All headers should live in Source/Headers. Public headers should be added to the Cedar and Cedar-iOS targets
• Headers for code specific to testing on iOS resides in Source/Headers/iPhone. Public headers should only be added to the Cedar-iOS target

Tests

• Tests reside in the Spec directory and should be added to the Specs and iOSSpecs targets
• Tests specific to iOS reside in the Spec/iPhone directory and should only be added to the iOSSpecs target

History

Cedar is a long running project. Together with Apple's recent advancements to the development tools, some design decisions existed before Apple's tooling was significantly improved for testing. A perfect example of this are Spec Suites and Test Bundles.

In earlier versions of Xcode, Test Bundles lacked a lot of features that drove the need for Spec Suites:

• Test Bundles couldn't test iOS apps
• Test Bundles couldn't be debugged
• Test Bundles couldn't run focused tests easily
• Test Bundles couldn't run on the command line as easily
• Test Bundles didn't work for Frameworks or Static Libraries

With more recent changes (Xcode 5 + 6), Test Bundles became more first class and resolved most of the problems above. But there are still other issues currently which Spec Suites are still useful.

• It is difficult to run a Test Bundle under instruments
• Test Bundles get injected after your application starts, so you must be cognizant of production-code execution before the tests starts