Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 260 lines (189 sloc) 9.914 kb
7063235 Better README
Adam Milligan authored
1 # Cedar
21944d3 README
Adam Milligan authored
2
3 BDD-style testing using Objective-C
4
5
7063235 Better README
Adam Milligan authored
6 ## Usage
21944d3 README
Adam Milligan authored
7
b6228cb Updated README
Adam Milligan & Mike Gehard authored
8 ### Non-iPhone testing
9
497f5bf Pending specs
Adam Milligan authored
10 * Build the Cedar framework. Note that you must build for an Objective-C
11 runtime that supports blocks; this means Mac OS X 10.6, or a runtime from
21944d3 README
Adam Milligan authored
12 Plausible Labs (see below).
13 * Create a command-line executable target for your tests in your project. Name
14 this target Specs, unless you have another name you'd prefer.
b6228cb Updated README
Adam Milligan & Mike Gehard authored
15 * Add the Cedar framework to your project, and link your Specs target with it.
21944d3 README
Adam Milligan authored
16 * Do the Copy Framework Dance:
17 - Add a Copy Files build phase to your Specs target.
18 - Select the Frameworks destination for the build phase.
19 - Add Cedar to the new build phase.
b6228cb Updated README
Adam Milligan & Mike Gehard authored
20 * Add a main.m to your Specs target that looks like this:
21944d3 README
Adam Milligan authored
21
8890faf Added spec target for running specs on a device/simulator.
Adam Milligan & Mike Gehard authored
22 #import <Cedar/Cedar.h>
497f5bf Pending specs
Adam Milligan authored
23
b10501d Even better README
Adam Milligan authored
24 int main (int argc, const char *argv[]) {
25 return runAllSpecs();
26 }
21944d3 README
Adam Milligan authored
27
28 * Write your specs. Cedar provides the SpecHelper.h file with some minimal
29 macros to remove as much distraction as possible from your specs. A spec
30 file need not have a header file, and looks like this:
31
b6228cb Updated README
Adam Milligan & Mike Gehard authored
32 #import <Cedar/SpecHelper.h>
497f5bf Pending specs
Adam Milligan authored
33
7063235 Better README
Adam Milligan authored
34 SPEC_BEGIN(FooSpec)
35 describe(@"Foo", ^{
36 beforeEach(^{
37 ...
38 });
497f5bf Pending specs
Adam Milligan authored
39
7063235 Better README
Adam Milligan authored
40 it(@"should do something", ^{
41 ...
42 });
43 });
44 SPEC_END
21944d3 README
Adam Milligan authored
45
46 * Build and run. Note that, unlike OCUnit, you must run your executable in
3b2657f README updates.
Adam Milligan authored
47 order to run your specs. Also unlike OCUnit this allows you to use the
48 debugger when running specs.
21944d3 README
Adam Milligan authored
49
b6228cb Updated README
Adam Milligan & Mike Gehard authored
50 ### iPhone testing
51
52 * Build the Cedar-iPhone static framework. This framework contains a univeral
53 binary that will work both on the simulator and the device.
54 * Create a Cocoa Touch executable target for your tests in your project. Name
55 this target UISpecs, or something similar.
56 * Add the Cedar-iPhone static framework to your project, and link your UISpecs
57 target with it.
d8366e8 Clarification in the iPhone specific testing instructions
Adam Milligan & Mike Gehard authored
58 * Add -ObjC, -lstdc++ and -all_load to the Other Linker Flags build setting for the
b6228cb Updated README
Adam Milligan & Mike Gehard authored
59 UISpecs target. This is necessary for the linker to correctly load symbols
60 for Objective-C classes from static libraries.
61 * Add a main.m to your UISpecs target that looks like this:
62
63 #import <UIKit/UIKit.h>
64 #import <Cedar-iPhone/Cedar.h>
65
66 int main(int argc, char *argv[]) {
67 NSAutoreleasePool * pool = [[NSAutoreleasePool alloc] init];
68
69 int retVal = UIApplicationMain(argc, argv, nil, @"CedarApplicationDelegate");
70 [pool release];
71 return retVal;
72 }
73
74 * Build and run. The simulator (or device) should start and display the status
75 of each of your spec classes in a table view. You can navigate the hierarchy
76 of your examples by clicking on the table cells.
77 * If you would like to use OCHamcrest or OCMock in your UI specs, Pivotal has
d8366e8 Clarification in the iPhone specific testing instructions
Adam Milligan & Mike Gehard authored
78 created static frameworks which will work on the iPhone for both. These must
79 be built so you can add them as available frameworks in your specs. See the
07dd7fd Updated links in README
Adam Milligan & Mike Gehard authored
80 sections below on Matchers and Mocks for links to the relevant projects.
b6228cb Updated README
Adam Milligan & Mike Gehard authored
81 * If you would like to run specs both in your UI spec target and your non-UI
82 spec target, you'll need to conditionally include the appropriate Cedar
83 headers in your spec files depending on the target SDK. For example:
84
85 #define HC_SHORTHAND
86 #if TARGET_OS_IPHONE
87 #import <Cedar-iPhone/SpecHelper.h>
88 #import <OCMock-iPhone/OCMock.h>
89 #import <OCHamcrest-iPhone/OCHamcrest.h>
90 #else
91 #import <Cedar/SpecHelper.h>
92 #import <OCMock/OCMock.h>
93 #import <OCHamcrest/OCHamcrest.h>
94 #endif
95
21944d3 README
Adam Milligan authored
96
7063235 Better README
Adam Milligan authored
97 ## Matchers
21944d3 README
Adam Milligan authored
98
497f5bf Pending specs
Adam Milligan authored
99 Cedar does not provide matchers, but it works with the fine array of matchers
07dd7fd Updated links in README
Adam Milligan & Mike Gehard authored
100 provided by the [Hamcrest project](http://code.google.com/p/hamcrest/); you can
497f5bf Pending specs
Adam Milligan authored
101 fetch the Objective-C port from the Hamcrest SVN repo. Build and link the
102 Hamcrest framework by following their instructions, and add the following at
21944d3 README
Adam Milligan authored
103 the top of your spec files:
104
7063235 Better README
Adam Milligan authored
105 #define HC_SHORTHAND
106 #import <OCHamcrest/OCHamcrest.h>
21944d3 README
Adam Milligan authored
107
07dd7fd Updated links in README
Adam Milligan & Mike Gehard authored
108 Pivotal also has a fork of a [GitHub import of the OCHamcrest codebase](http://github.com/pivotal/OCHamcrest).
109 This fork contains our iPhone-specific static framework target.
3b2657f README updates.
Adam Milligan authored
110
111
af2871d Added shared example group bit to README.
Adam Milligan authored
112 ## Shared example groups
113
114 Cedar supports shared example groups; you can declare them in one of two ways:
115 either inline with your spec declarations, or separately.
116
117 Declaring shared examples inline with your specs is the simplest:
118
119 SPEC_BEGIN(FooSpecs)
120
121 sharedExamplesFor(@"a similarly-behaving thing", ^(NSDictionary *context) {
122 it(@"should do something common", ^{
123 ...
124 });
125 });
126
127 describe(@"Something that shares behavior", ^{
f70dd61 Shared example groups now use a shared context dictionary, stored on the...
Adam Milligan authored
128 itShouldBehaveLike(@"a similarly-behaving thing");
af2871d Added shared example group bit to README.
Adam Milligan authored
129 });
130
131 describe(@"Something else that shares behavior", ^{
f70dd61 Shared example groups now use a shared context dictionary, stored on the...
Adam Milligan authored
132 itShouldBehaveLike(@"a similarly-behaving thing");
af2871d Added shared example group bit to README.
Adam Milligan authored
133 });
134
135 SPEC_END
136
137 Sometimes you'll want to put shared examples in a separate file so you can use
138 them in several specs across different files. You can do this using macros
139 specifically for declaring shared example groups:
140
141 SHARED_EXAMPLE_GROUPS_BEGIN(GloballyCommon)
142
143 sharedExamplesFor(@"a thing with globally common behavior", ^(NSDictionary *context) {
144 it(@"should do something really common", ^{
145 ...
146 });
147 });
148
149 SHARED_EXAMPLE_GROUPS_END
150
151 The context dictionary allows you to pass example-specific state into the shared
f70dd61 Shared example groups now use a shared context dictionary, stored on the...
Adam Milligan authored
152 example group. You can populate the context dictionary available on the SpecHelper
153 object, and each shared example group will receive it:
154
155 sharedExamplesFor(@"a red thing", ^(NSDictionary *context) {
156 it(@"should be red", ^{
157 Thing *thing = [context objectForKey:@"thing"];
158 assertThat(thing.color, equalTo(red));
159 });
160 });
161
162 describe(@"A fire truck", ^{
163 beforeEach(^{
164 [[SpecHelper specHelper].sharedExampleContext setObject:[FireTruck fireTruck] forKey:@"thing"];
165 });
166 itShouldBehaveLike(@"a red thing");
167 });
168
169 describe(@"An apple", ^{
170 beforeEach(^{
171 [[SpecHelper specHelper].sharedExampleContext setObject:[Apple apple] forKey:@"thing"];
172 });
173 itShouldBehaveLike(@"a red thing");
174 });
175
176 Previously, you needed to instantiate and pass in your own dictionary, but this
177 led to confusion and unavoidable memory leaks. You should change any code that
178 uses a local context dictionary to use the global shared example context
179 dictionary.
af2871d Added shared example group bit to README.
Adam Milligan authored
180
181
3b2657f README updates.
Adam Milligan authored
182 ## Mocks and stubs
183
07dd7fd Updated links in README
Adam Milligan & Mike Gehard authored
184 Cedar works fine with OCMock. You can download and use the [OCMock framework](http://www.mulle-kybernetik.com/software/OCMock/).
185 Pivotal also has a fork of a [GitHub import of the OCMock codebase](http://github.com/pivotal/OCMock),
186 which contains our iPhone-specific static framework target.
3b2657f README updates.
Adam Milligan authored
187
21944d3 README
Adam Milligan authored
188
497f5bf Pending specs
Adam Milligan authored
189 ## Pending specs
190
191 If you'd like to specify but not implement an example you can do so like this:
192
193 it(@"should do something eventually", PENDING);
194
195 The spec runner will not try to run this example, but report it as pending. The
196 PENDING keyword simply references a nil block pointer; if you prefer you can
197 explicitly pass nil as the second parameter. The parameter is necessary because
198 C, and thus Objective-C, doesn't support function parameter overloading or
199 default parameters.
200
f44f3a9 Added Cedar-specific macros for Xcode; removed useless pch file.
Adam Milligan authored
201 ## Macros
202
203 The project root contains a file named MACROS, which contains some useful Xcode
204 macros for writing Cedar specs. To load the macros copy the contents of the
205 file into this file:
206
207 ~/Library/Application\ Support/Developer/Shared/Xcode/Specifications/ObjectiveC.xctxtmacro
208
209 You may need to create that file. If the file already exists, and contains pre-
210 existing macros, be careful to insert the Cedar macros inside the existing
211 parentheses properly.
212
213 To use the macros, type the shortcut string, followed by Ctrl-. or Ctrl-, As an
214 example, typing 'cdesc' followed by Ctrl-. will expand to:
215
216 describe(@"<#!subject under test!#>", ^{
217 <#!content!#>
218 });
219
497f5bf Pending specs
Adam Milligan authored
220
af2871d Added shared example group bit to README.
Adam Milligan authored
221 ## But I'm writing a pre-4.0 iPhone app!
21944d3 README
Adam Milligan authored
222
223 Unfortunately, Apple has made Objective-C blocks, upon which Cedar depends,
af2871d Added shared example group bit to README.
Adam Milligan authored
224 only available in the Mac OS X 10.6 and iOS 4 runtime. This means if you're not
225 building on a Snow Leopard machine and targeting the desktop runtime or
226 targeting a device or simulator that is running less than iOS 4 then anything
227 using blocks will fail to compile. There are a couple ways around this:
21944d3 README
Adam Milligan authored
228
d8366e8 Clarification in the iPhone specific testing instructions
Adam Milligan & Mike Gehard authored
229 * Plausible Labs provides patched versions of the [GCC compiler and runtime for
230 Leopard and iPhone OS](http://code.google.com/p/plblocks/). This link
231 has instructions for installing this compiler and framework. I wrote most of
21944d3 README
Adam Milligan authored
232 Cedar on a Leopard machine with the 10.5 PLBlocks runtime.
233
497f5bf Pending specs
Adam Milligan authored
234 * Split your project into OS-dependent and OS-independent targets. Domain
21944d3 README
Adam Milligan authored
235 models and business logic shouldn't (theoretically) depend on the available
236 UI frameworks. Test everything that doesn't require UIKit/CoreGraphics/etc.
237 using Cedar; test the UI using something else.
238
b6228cb Updated README
Adam Milligan & Mike Gehard authored
239 * We're open to suggestions.
21944d3 README
Adam Milligan authored
240
3b2657f README updates.
Adam Milligan authored
241 The Cedar-iPhone target builds a framework specifically designed for specs on
242 the iPhone device. It includes a static library that includes builds targeting
243 both the simulator and device runtimes.
7a1445a README update with iPhone static library information
Adam Milligan authored
244
b6228cb Updated README
Adam Milligan & Mike Gehard authored
245 We've created a sample iPhone application that runs Cedar specs both on and off
07dd7fd Updated links in README
Adam Milligan & Mike Gehard authored
246 the device. You can check it out [here](http://github.com/pivotal/StoryAccepter).
7a1445a README update with iPhone static library information
Adam Milligan authored
247
3b2657f README updates.
Adam Milligan authored
248 See the Pivotal forks of OCHamcrest and OCMock on GitHub for iPhone-specific
249 static framework targets.
250
21944d3 README
Adam Milligan authored
251
3b2657f README updates.
Adam Milligan authored
252 ## Contributions and feedback
21944d3 README
Adam Milligan authored
253
07dd7fd Updated links in README
Adam Milligan & Mike Gehard authored
254 Welcomed! Feel free to join and contribute to the public Tracker project [here](http://www.pivotaltracker.com/projects/77775).
21944d3 README
Adam Milligan authored
255
07dd7fd Updated links in README
Adam Milligan & Mike Gehard authored
256 The [public Google group](http://groups.google.com/group/cedar-discuss) for Cedar is cedar-discuss@googlegroups.com.
257 Or, you can follow the growth of Cedar on Twitter: [@cedarbdd](http://twitter.com/cedarbdd).
3b2657f README updates.
Adam Milligan authored
258
5a66c18 Moved MIT License to separate file to match other projects
Todd Persen authored
259 Copyright (c) 2010 Pivotal Labs. This software is licensed under the MIT License.
Something went wrong with that request. Please try again.