Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 400 lines (290 sloc) 10.659 kB
ab72884 @dchelimsky more words
dchelimsky authored
1 # rspec-rails-2
8d0199b @dchelimsky generator fixes
dchelimsky authored
2
f30f213 @dchelimsky words
dchelimsky authored
3 rspec-2 for rails-3 with lightweight extensions to each
46cae15 @dchelimsky explain that the README aligns with the code in git HEAD
dchelimsky authored
4
6ab0bb6 @dchelimsky cleanup and add some rdoc
dchelimsky authored
5 NOTE: Use rspec-rails-1.3.x for rails-2.
bb43457 @dchelimsky links to docs
dchelimsky authored
6
43229ac @dchelimsky words
dchelimsky authored
7 ## Install
8d0199b @dchelimsky generator fixes
dchelimsky authored
8
bb43457 @dchelimsky links to docs
dchelimsky authored
9 gem install rspec-rails
c560b15 @dchelimsky words
dchelimsky authored
10
8d0199b @dchelimsky generator fixes
dchelimsky authored
11 This installs the following gems:
12
99b7c5c @dchelimsky words
dchelimsky authored
13 rspec
14 rspec-core
15 rspec-expectations
16 rspec-mocks
17 rspec-rails
8d0199b @dchelimsky generator fixes
dchelimsky authored
18
6ab0bb6 @dchelimsky cleanup and add some rdoc
dchelimsky authored
19 ## Configure
8b32de7 @dchelimsky words
dchelimsky authored
20
f2be768 @dchelimsky refine notes from last commit
dchelimsky authored
21 Add `rspec-rails` to the `:test` and `:development` groups in the Gemfile:
8b32de7 @dchelimsky words
dchelimsky authored
22
1bec8ff @dchelimsky use github-flavored-markdown in the readme
dchelimsky authored
23 ```ruby
24 group :test, :development do
25 gem "rspec-rails", "~> 2.6"
26 end
27 ```
8b32de7 @dchelimsky words
dchelimsky authored
28
64c16fe @dchelimsky add note about Gemfile groups to README
dchelimsky authored
29 It needs to be in the `:development` group to expose generators and rake
30 tasks without having to type `RAILS_ENV=test`.
31
62ad935 @lucascaton Adjusts in README file
lucascaton authored
32 Now you can run:
8b32de7 @dchelimsky words
dchelimsky authored
33
6ab0bb6 @dchelimsky cleanup and add some rdoc
dchelimsky authored
34 rails generate rspec:install
8b32de7 @dchelimsky words
dchelimsky authored
35
291973b @dchelimsky remove generator doc from readme (you can see it running rails g)
dchelimsky authored
36 This adds the spec directory and some skeleton files, including
62ad935 @lucascaton Adjusts in README file
lucascaton authored
37 the "rake spec" task.
bdc6d83 @dchelimsky more about generators in README
dchelimsky authored
38
39 ### Generators
40
41 If you type `script/rails generate`, the only RSpec generator you'll actually
42 see is `rspec:install`. That's because RSpec is registered with Rails as the
43 test framework, so whenever you generate application components like models,
5d3ca6b @dchelimsky explain a bit about how generators work
dchelimsky authored
44 controllers, etc, RSpec specs are generated instead of Test::Unit tests.
8b32de7 @dchelimsky words
dchelimsky authored
45
6ab0bb6 @dchelimsky cleanup and add some rdoc
dchelimsky authored
46 Please note that the generators are there to help you get started, but they are
47 no substitute for writing your own examples, and they are only guaranteed to
48 work out of the box for the default scenario (`ActiveRecord` + `Webrat`).
bdc6d83 @dchelimsky more about generators in README
dchelimsky authored
49
9bf3e32 @dchelimsky rdoc
dchelimsky authored
50 ### Webrat and Capybara
51
52 You can choose between webrat or capybara for simulating a browser, automating
53 a browser, or setting expectations using the matchers they supply. Just add
54 your preference to the Gemfile:
55
56 ```ruby
57 gem "webrat"
58 gem "capybara"
59 ```
60
092e125 @dchelimsky add autotest config info to README
dchelimsky authored
61 ### Autotest
62
6ab0bb6 @dchelimsky cleanup and add some rdoc
dchelimsky authored
63 The `rspec:install` generator creates an `.rspec` file, which tells Autotest
64 that you're using RSpec and Rails. You'll also need to add the ZenTest gem to
65 your Gemfile:
092e125 @dchelimsky add autotest config info to README
dchelimsky authored
66
1bec8ff @dchelimsky use github-flavored-markdown in the readme
dchelimsky authored
67 ```ruby
68 gem "ZenTest"
69 ```
092e125 @dchelimsky add autotest config info to README
dchelimsky authored
70
38ffe5f @dchelimsky more about autotest
dchelimsky authored
71 At this point, if all of the gems in your Gemfile are installed in system
72 gems, you can just type `autotest`. If, however, Bundler is managing any gems
73 for you directly (i.e. you've got `:git` or `:path` attributes in the `Gemfile`),
74 you'll need to run `bundle exec autotest`.
75
273e124 @dchelimsky words
dchelimsky authored
76 ## Living on edge
77
99b7c5c @dchelimsky words
dchelimsky authored
78 Bundler makes it a snap to use the latest code for any gem your app depends on. For
79 rspec-rails, you'll need to point bundler to the git repositories for `rspec-rails`
80 and the other rspec related gems it depends on:
273e124 @dchelimsky words
dchelimsky authored
81
1bec8ff @dchelimsky use github-flavored-markdown in the readme
dchelimsky authored
82 ```ruby
83 gem "rspec-rails", :git => "git://github.com/rspec/rspec-rails.git"
84 gem "rspec", :git => "git://github.com/rspec/rspec.git"
85 gem "rspec-core", :git => "git://github.com/rspec/rspec-core.git"
86 gem "rspec-expectations", :git => "git://github.com/rspec/rspec-expectations.git"
87 gem "rspec-mocks", :git => "git://github.com/rspec/rspec-mocks.git"
88 ```
273e124 @dchelimsky words
dchelimsky authored
89
99b7c5c @dchelimsky words
dchelimsky authored
90 Run `bundle install` and you'll have whatever is in git right now. Any time you
91 want to update to a newer head, just run `bundle update`.
92
93 Keep in mind that each of these codebases is under active development, which
94 means that its entirely possible that you'll pull from these repos and they won't
95 play nice together. If playing nice is important to you, stick to the published
96 gems.
273e124 @dchelimsky words
dchelimsky authored
97
ab72884 @dchelimsky more words
dchelimsky authored
98 ## Backwards compatibility
99
100 This is a complete rewrite of the rspec-rails extension designed to work with
101 rails-3.x and rspec-2.x. It will not work with older versions of either rspec
102 or rails. Many of the APIs from rspec-rails-1 have been carried forward,
103 however, so upgrading an app from rspec-1/rails-2, while not pain-free, should
104 not send you to the doctor with a migraine.
8d0199b @dchelimsky generator fixes
dchelimsky authored
105
43229ac @dchelimsky words
dchelimsky authored
106 ## Known issues
8d0199b @dchelimsky generator fixes
dchelimsky authored
107
9387d57 @dchelimsky words
dchelimsky authored
108 See http://github.com/rspec/rspec-rails/issues
109
110 # Request Specs
111
f30f213 @dchelimsky words
dchelimsky authored
112 Request specs live in spec/requests.
113
1bec8ff @dchelimsky use github-flavored-markdown in the readme
dchelimsky authored
114 ```ruby
115 describe "widgets resource" do
116 describe "GET index" do
117 it "contains the widgets header" do
118 get "/widgets/index"
119 response.should have_selector("h1", :content => "Widgets")
f30f213 @dchelimsky words
dchelimsky authored
120 end
1bec8ff @dchelimsky use github-flavored-markdown in the readme
dchelimsky authored
121 end
122 end
123 ```
f30f213 @dchelimsky words
dchelimsky authored
124
125 Request specs mix in behavior from Rails' integration tests. See the
126 docs for ActionDispatch::Integration::Runner for more information.
8d0199b @dchelimsky generator fixes
dchelimsky authored
127
43229ac @dchelimsky words
dchelimsky authored
128 # Controller Specs
0dcfce7 @dchelimsky words
dchelimsky authored
129
3d173af @dchelimsky words
dchelimsky authored
130 Controller specs live in spec/controllers, and mix in
131 ActionController::TestCase::Behavior. See the documentation
132 for ActionController::TestCase to see what facilities are
133 available from Rails.
0dcfce7 @dchelimsky words
dchelimsky authored
134
3d173af @dchelimsky words
dchelimsky authored
135 You can use RSpec expectations/matchers or Test::Unit assertions.
38df36b @dchelimsky more words
dchelimsky authored
136
435c181 @dchelimsky add upgrade notes about methods that changed to README
dchelimsky authored
137 ## `render_views`
9bf3e32 @dchelimsky rdoc
dchelimsky authored
138
61f5bcc @dchelimsky Stub template content in controller specs instead of using NullResolver
dchelimsky authored
139 By default, controller specs do not render views. This supports specifying
140 controllers without concern for whether the views they render work correctly
2d89bc9 @dchelimsky use md for markdown files
dchelimsky authored
141 (NOTE: the template must exist, unlike rspec-rails-1. See Upgrade.md for more
142 information about this). If you prefer to render the views (a la Rails'
61f5bcc @dchelimsky Stub template content in controller specs instead of using NullResolver
dchelimsky authored
143 functional tests), you can use the `render_views` declaration in each example
144 group:
43229ac @dchelimsky words
dchelimsky authored
145
1bec8ff @dchelimsky use github-flavored-markdown in the readme
dchelimsky authored
146 ```ruby
147 describe SomeController do
148 render_views
149 # ...
150 ```
43229ac @dchelimsky words
dchelimsky authored
151
9bf3e32 @dchelimsky rdoc
dchelimsky authored
152 ### Upgrade note
435c181 @dchelimsky add upgrade notes about methods that changed to README
dchelimsky authored
153
154 `render_views` replaces `integrate_views` from rspec-rails-1.3
155
156 ## `assigns`
157
158 Use `assigns(key)` to express expectations about instance variables that a controller
159 assigns to the view in the course of an action:
160
1bec8ff @dchelimsky use github-flavored-markdown in the readme
dchelimsky authored
161 ```ruby
162 get :index
163 assigns(:widgets).should eq(expected_value)
164 ```
435c181 @dchelimsky add upgrade notes about methods that changed to README
dchelimsky authored
165
9387d57 @dchelimsky words
dchelimsky authored
166 # View specs
167
168 View specs live in spec/views, and mix in ActionView::TestCase::Behavior.
169
1bec8ff @dchelimsky use github-flavored-markdown in the readme
dchelimsky authored
170 ```ruby
171 describe "events/index.html.erb" do
172 it "renders _event partial for each event" do
173 assign(:events, [stub_model(Event), stub_model(Event)])
174 render
175 view.should render_template(:partial => "_event", :count => 2)
176 end
177 end
178
179 describe "events/show.html.erb" do
180 it "displays the event location" do
181 assign(:event, stub_model(Event,
182 :location => "Chicago"
183 ))
184 render
185 rendered.should contain("Chicago")
186 end
187 end
188 ```
cbf623a @wincent doc: note that ActionView::TestCase auto-propagates ivars
wincent authored
189
732a922 @dchelimsky Infer controller.request.path_params["controller"] from the file being
dchelimsky authored
190 View specs infer the controller name and path from the path to the view
191 template. e.g. if the template is "events/index.html.erb" then:
192
1bec8ff @dchelimsky use github-flavored-markdown in the readme
dchelimsky authored
193 ```ruby
194 controller.controller_path == "events"
195 controller.request.path_parameters[:controller] == "events"
196 ```
732a922 @dchelimsky Infer controller.request.path_params["controller"] from the file being
dchelimsky authored
197
198 This means that most of the time you don't need to set these values. When
199 spec'ing a partial that is included across different controllers, you _may_
200 need to override these values before rendering the view.
201
30d998c @rgarner Explicit template/layout render example
rgarner authored
202 To provide a layout for the render, you'll need to specify _both_ the template
203 and the layout explicitly. For example:
204
1bec8ff @dchelimsky use github-flavored-markdown in the readme
dchelimsky authored
205 ```ruby
206 render :template => "events/show", :layout => "layouts/application"
207 ```
30d998c @rgarner Explicit template/layout render example
rgarner authored
208
435c181 @dchelimsky add upgrade notes about methods that changed to README
dchelimsky authored
209 ## `assign(key, val)`
210
211 Use this to assign values to instance variables in the view:
212
1bec8ff @dchelimsky use github-flavored-markdown in the readme
dchelimsky authored
213 ```ruby
214 assign(:widget, stub_model(Widget))
215 render
216 ```
cbf623a @wincent doc: note that ActionView::TestCase auto-propagates ivars
wincent authored
217
435c181 @dchelimsky add upgrade notes about methods that changed to README
dchelimsky authored
218 The code above assigns `stub_model(Widget)` to the `@widget` variable in the view, and then
219 renders the view.
220
cbf623a @wincent doc: note that ActionView::TestCase auto-propagates ivars
wincent authored
221 Note that because view specs mix in `ActionView::TestCase` behavior, any
222 instance variables you set will be transparently propagated into your views
223 (similar to how instance variables you set in controller actions are made
224 available in views). For example:
225
1bec8ff @dchelimsky use github-flavored-markdown in the readme
dchelimsky authored
226 ```ruby
227 @widget = stub_model(Widget)
228 render # @widget is available inside the view
229 ```
cbf623a @wincent doc: note that ActionView::TestCase auto-propagates ivars
wincent authored
230
231 RSpec doesn't officially support this pattern, which only works as a
232 side-effect of the inclusion of `ActionView::TestCase`. Be aware that it may be
233 made unavailable in the future.
234
9bf3e32 @dchelimsky rdoc
dchelimsky authored
235 ### Upgrade note
435c181 @dchelimsky add upgrade notes about methods that changed to README
dchelimsky authored
236
1bec8ff @dchelimsky use github-flavored-markdown in the readme
dchelimsky authored
237 ```ruby
238 # rspec-rails-1.x
239 assigns[key] = value
240
241 # rspec-rails-2.x
242 assign(key, value)
243 ```
435c181 @dchelimsky add upgrade notes about methods that changed to README
dchelimsky authored
244
245 ## `rendered`
246
247 This represents the rendered view.
248
1bec8ff @dchelimsky use github-flavored-markdown in the readme
dchelimsky authored
249 ```ruby
250 render
251 rendered.should =~ /Some text expected to appear on the page/
252 ```
99ba346 @dchelimsky Revert "Use Github Flavored Markdown"
dchelimsky authored
253
9bf3e32 @dchelimsky rdoc
dchelimsky authored
254 ### Upgrade note
435c181 @dchelimsky add upgrade notes about methods that changed to README
dchelimsky authored
255
1bec8ff @dchelimsky use github-flavored-markdown in the readme
dchelimsky authored
256 ```ruby
257 # rspec-rails-1.x
258 render
259 response.should xxx
260
261 # rspec-rails-2.x
262 render
263 rendered.should xxx
264 ```
9387d57 @dchelimsky words
dchelimsky authored
265
9bf3e32 @dchelimsky rdoc
dchelimsky authored
266 # Model specs
267
268 Model specs live in spec/models.
269
270 ```ruby
271 describe Articles do
272 describe ".recent" do
273 it "includes articles published less than one week ago" do
274 article = Article.create!(:published_at => Date.today - 1.week + 1.second)
275 Article.recent.should eq([article])
276 end
277
278 it "excludes articles published at midnight one week ago" do
279 article = Article.create!(:published_at => Date.today - 1.week)
280 Article.recent.should be_empty
281 end
282
283 it "excludes articles published more than one week ago" do
284 article = Article.create!(:published_at => Date.today - 1.week - 1.second)
285 Article.recent.should be_empty
286 end
287 end
288 end
289 ```
290
f504614 @dchelimsky words
dchelimsky authored
291 # Routing specs
292
293 Routing specs live in spec/routing.
294
1bec8ff @dchelimsky use github-flavored-markdown in the readme
dchelimsky authored
295 ```ruby
296 describe "routing to profiles" do
297 it "routes /profile/:username to profile#show for username" do
298 { :get => "/profiles/jsmith" }.should route_to(
299 :controller => "profiles",
300 :action => "show",
301 :username => "jsmith"
302 )
303 end
304
305 it "does not expose a list of profiles" do
306 { :get => "/profiles" }.should_not be_routable
307 end
308 end
309 ```
f504614 @dchelimsky words
dchelimsky authored
310
9bf3e32 @dchelimsky rdoc
dchelimsky authored
311 ### Upgrade note
cd4dcbd @dchelimsky note about route_for being removed
dchelimsky authored
312
313 `route_for` from rspec-rails-1.x is gone. Use `route_to` and `be_routable` instead.
314
9387d57 @dchelimsky words
dchelimsky authored
315 # Helper specs
316
317 Helper specs live in spec/helpers, and mix in ActionView::TestCase::Behavior.
318
1bec8ff @dchelimsky use github-flavored-markdown in the readme
dchelimsky authored
319 ```ruby
320 describe EventsHelper do
321 describe "#link_to_event" do
322 it "displays the title, and formatted date" do
323 event = Event.new("Ruby Kaigi", Date.new(2010, 8, 27))
324 # helper is an instance of ActionView::Base configured with the
325 # EventsHelper and all of Rails' built-in helpers
326 helper.link_to_event.should =~ /Ruby Kaigi, 27 Aug, 2010/
9387d57 @dchelimsky words
dchelimsky authored
327 end
1bec8ff @dchelimsky use github-flavored-markdown in the readme
dchelimsky authored
328 end
329 end
330 ```
f30f213 @dchelimsky words
dchelimsky authored
331
332 # Matchers
333
334 rspec-rails exposes domain-specific matchers to each of the example group types. Most
335 of them simply delegate to Rails' assertions.
336
337 ## `be_a_new`
338 * Available in all specs.
339 * Primarily intended for controller specs
340
1bec8ff @dchelimsky use github-flavored-markdown in the readme
dchelimsky authored
341 ```ruby
f30f213 @dchelimsky words
dchelimsky authored
342 object.should be_a_new(Widget)
1bec8ff @dchelimsky use github-flavored-markdown in the readme
dchelimsky authored
343 ```
344
f30f213 @dchelimsky words
dchelimsky authored
345
346 Passes if the object is a `Widget` and returns true for `new_record?`
347
348 ## `render_template`
349 * Delegates to Rails' assert_template.
350 * Available in request, controller, and view specs.
351
352 In request and controller specs, apply to the response object:
353
1bec8ff @dchelimsky use github-flavored-markdown in the readme
dchelimsky authored
354 ```ruby
355 response.should render_template("new")
356 ```
f30f213 @dchelimsky words
dchelimsky authored
357
358 In view specs, apply to the view object:
359
1bec8ff @dchelimsky use github-flavored-markdown in the readme
dchelimsky authored
360 ```ruby
361 view.should render_template(:partial => "_form", :locals => { :widget => widget } )
362 ```
f30f213 @dchelimsky words
dchelimsky authored
363
364 ## `redirect_to`
365 * Delegates to assert_redirect
366 * Available in request and controller specs.
367
1bec8ff @dchelimsky use github-flavored-markdown in the readme
dchelimsky authored
368 ```ruby
f30f213 @dchelimsky words
dchelimsky authored
369 response.should redirect_to(widgets_path)
1bec8ff @dchelimsky use github-flavored-markdown in the readme
dchelimsky authored
370 ```
f30f213 @dchelimsky words
dchelimsky authored
371
372 ## `route_to`
373
374 * Delegates to Rails' assert_routing.
375 * Available in routing and controller specs.
376
1bec8ff @dchelimsky use github-flavored-markdown in the readme
dchelimsky authored
377 ```ruby
f30f213 @dchelimsky words
dchelimsky authored
378 { :get => "/widgets" }.should route_to(:controller => "widgets", :action => "index")
1bec8ff @dchelimsky use github-flavored-markdown in the readme
dchelimsky authored
379 ```
f30f213 @dchelimsky words
dchelimsky authored
380
381 ## `be_routable`
382
383 Passes if the path is recognized by Rails' routing. This is primarily intended
384 to be used with `should_not` to specify routes that should not be routable.
385
1bec8ff @dchelimsky use github-flavored-markdown in the readme
dchelimsky authored
386 ```ruby
387 { :get => "/widgets/1/edit" }.should_not be_routable
388 ```
6e90564 @dchelimsky words
dchelimsky authored
389
9bf3e32 @dchelimsky rdoc
dchelimsky authored
390 # Contribute
6e90564 @dchelimsky words
dchelimsky authored
391
392 See [http://github.com/rspec/rspec-dev](http://github.com/rspec/rspec-dev)
393
9bf3e32 @dchelimsky rdoc
dchelimsky authored
394 # Also see
6e90564 @dchelimsky words
dchelimsky authored
395
396 * [http://github.com/rspec/rspec](http://github.com/rspec/rspec)
397 * [http://github.com/rspec/rspec-core](http://github.com/rspec/rspec-core)
398 * [http://github.com/rspec/rspec-expectations](http://github.com/rspec/rspec-expectations)
399 * [http://github.com/rspec/rspec-mocks](http://github.com/rspec/rspec-mocks)
Something went wrong with that request. Please try again.