Skip to content
This repository
Newer
Older
100644 495 lines (369 sloc) 13.249 kb
ab72884d »
2010-05-01 more words
1 # rspec-rails-2
8d0199ba »
2010-01-24 generator fixes
2
f30f2131 »
2010-06-24 words
3 rspec-2 for rails-3 with lightweight extensions to each
46cae151 »
2010-06-20 explain that the README aligns with the code in git HEAD
4
0e6b1853 »
2011-12-08 rdoc
5 Note: Use [rspec-rails-1.3](http://github.com/dchelimsky/rspec-rails) for rails-2.
bb434571 »
2010-10-22 links to docs
6
43229ac1 »
2010-05-01 words
7 ## Install
8d0199ba »
2010-01-24 generator fixes
8
0e6b1853 »
2011-12-08 rdoc
9 ```
10 gem install rspec-rails
11 ```
c560b159 »
2010-02-07 words
12
8d0199ba »
2010-01-24 generator fixes
13 This installs the following gems:
14
0e6b1853 »
2011-12-08 rdoc
15 ```
16 rspec
17 rspec-core
18 rspec-expectations
19 rspec-mocks
20 rspec-rails
21 ```
8d0199ba »
2010-01-24 generator fixes
22
6ab0bb66 »
2011-10-16 cleanup and add some rdoc
23 ## Configure
8b32de78 »
2010-02-15 words
24
f2be7681 »
2010-08-12 refine notes from last commit
25 Add `rspec-rails` to the `:test` and `:development` groups in the Gemfile:
8b32de78 »
2010-02-15 words
26
1bec8ff8 »
2011-12-04 use github-flavored-markdown in the readme
27 ```ruby
28 group :test, :development do
29 gem "rspec-rails", "~> 2.6"
30 end
31 ```
8b32de78 »
2010-02-15 words
32
64c16fe2 »
2010-08-12 add note about Gemfile groups to README
33 It needs to be in the `:development` group to expose generators and rake
34 tasks without having to type `RAILS_ENV=test`.
35
62ad9350 »
2011-07-11 Adjusts in README file
36 Now you can run:
8b32de78 »
2010-02-15 words
37
0e6b1853 »
2011-12-08 rdoc
38 ```
39 rails generate rspec:install
40 ```
8b32de78 »
2010-02-15 words
41
291973b4 »
2010-02-20 remove generator doc from readme (you can see it running rails g)
42 This adds the spec directory and some skeleton files, including
62ad9350 »
2011-07-11 Adjusts in README file
43 the "rake spec" task.
bdc6d831 »
2010-09-02 more about generators in README
44
45 ### Generators
46
47 If you type `script/rails generate`, the only RSpec generator you'll actually
48 see is `rspec:install`. That's because RSpec is registered with Rails as the
49 test framework, so whenever you generate application components like models,
5d3ca6b1 »
2010-08-20 explain a bit about how generators work
50 controllers, etc, RSpec specs are generated instead of Test::Unit tests.
8b32de78 »
2010-02-15 words
51
6ab0bb66 »
2011-10-16 cleanup and add some rdoc
52 Please note that the generators are there to help you get started, but they are
53 no substitute for writing your own examples, and they are only guaranteed to
80febb5b »
2011-12-07 Consolidate rdoc for example groups to README
54 work out of the box for the default scenario (`ActiveRecord` & `Webrat`).
bdc6d831 »
2010-09-02 more about generators in README
55
9bf3e32e »
2011-12-04 rdoc
56 ### Webrat and Capybara
57
58 You can choose between webrat or capybara for simulating a browser, automating
59 a browser, or setting expectations using the matchers they supply. Just add
60 your preference to the Gemfile:
61
62 ```ruby
63 gem "webrat"
64 gem "capybara"
65 ```
66
273e1249 »
2010-05-17 words
67 ## Living on edge
68
99b7c5c7 »
2010-09-04 words
69 Bundler makes it a snap to use the latest code for any gem your app depends on. For
70 rspec-rails, you'll need to point bundler to the git repositories for `rspec-rails`
71 and the other rspec related gems it depends on:
273e1249 »
2010-05-17 words
72
1bec8ff8 »
2011-12-04 use github-flavored-markdown in the readme
73 ```ruby
74 gem "rspec-rails", :git => "git://github.com/rspec/rspec-rails.git"
75 gem "rspec", :git => "git://github.com/rspec/rspec.git"
76 gem "rspec-core", :git => "git://github.com/rspec/rspec-core.git"
77 gem "rspec-expectations", :git => "git://github.com/rspec/rspec-expectations.git"
78 gem "rspec-mocks", :git => "git://github.com/rspec/rspec-mocks.git"
79 ```
273e1249 »
2010-05-17 words
80
99b7c5c7 »
2010-09-04 words
81 Run `bundle install` and you'll have whatever is in git right now. Any time you
82 want to update to a newer head, just run `bundle update`.
83
84 Keep in mind that each of these codebases is under active development, which
85 means that its entirely possible that you'll pull from these repos and they won't
86 play nice together. If playing nice is important to you, stick to the published
87 gems.
273e1249 »
2010-05-17 words
88
ab72884d »
2010-05-01 more words
89 ## Backwards compatibility
90
91 This is a complete rewrite of the rspec-rails extension designed to work with
92 rails-3.x and rspec-2.x. It will not work with older versions of either rspec
93 or rails. Many of the APIs from rspec-rails-1 have been carried forward,
94 however, so upgrading an app from rspec-1/rails-2, while not pain-free, should
95 not send you to the doctor with a migraine.
8d0199ba »
2010-01-24 generator fixes
96
43229ac1 »
2010-05-01 words
97 ## Known issues
8d0199ba »
2010-01-24 generator fixes
98
9387d57f »
2010-05-27 words
99 See http://github.com/rspec/rspec-rails/issues
100
101 # Request Specs
102
6a87a0ba »
2011-12-20 beef up README section on Request Specs
103 Request specs live in spec/requests, and mix in behavior
104 [ActionDispatch::Integration::Runner](http://api.rubyonrails.org/classes/ActionDispatch/Integration/Runner.html),
105 which is the basis for [Rails' integration
106 tests](http://guides.rubyonrails.org/testing.html#integration-testing). The
107 intent is to specify one or more request/response cycles from end to end using
108 a black box approach.
f30f2131 »
2010-06-24 words
109
1bec8ff8 »
2011-12-04 use github-flavored-markdown in the readme
110 ```ruby
6a87a0ba »
2011-12-20 beef up README section on Request Specs
111 describe "home page" do
6207edc5 »
2012-02-20 Update README.md
112 it "displays the user's username after successful login" do
6a87a0ba »
2011-12-20 beef up README section on Request Specs
113 user = User.create!(:username => "jdoe", :password => "secret")
114 get "/login"
115 assert_select "form.login" do
116 assert_select "input[name=?]", "username"
117 assert_select "input[name=?]", "password"
118 assert_select "input[type=?]", "submit"
f30f2131 »
2010-06-24 words
119 end
6a87a0ba »
2011-12-20 beef up README section on Request Specs
120
121 post "/login", :username => "jdoe", :password => "secret"
122 assert_select ".header .username", :text => "jdoe"
1bec8ff8 »
2011-12-04 use github-flavored-markdown in the readme
123 end
124 end
125 ```
f30f2131 »
2010-06-24 words
126
6a87a0ba »
2011-12-20 beef up README section on Request Specs
127 This example uses only standard Rails and RSpec API's, but many RSpec/Rails
128 users like to use extension libraries like FactoryGirl and Capybara:
129
130 ```ruby
131 describe "home page" do
6207edc5 »
2012-02-20 Update README.md
132 it "displays the user's username after successful login" do
6a87a0ba »
2011-12-20 beef up README section on Request Specs
133 user = Factory(:user, :username => "jdoe", :password => "secret")
134 visit "/login"
135 fill_in "Username", :with => "jdoe"
136 fill_in "Password", :with => "secret"
03a2f6f9 »
2012-01-21 Fix method name type 'click_buton'
137 click_button "Log in"
6a87a0ba »
2011-12-20 beef up README section on Request Specs
138
70c23015 »
2012-01-08 Capybara uses :text, not :content as the option to have_selector. Any…
139 page.should have_selector(".header .username", :text => "jdoe")
6a87a0ba »
2011-12-20 beef up README section on Request Specs
140 end
141 end
142 ```
143
144 FactoryGirl decouples this example from changes to validation requirements,
145 which can be encoded into the underlying factory definition without requiring
146 changes to this example.
147
148 Among other benefits, Capybara binds the form post to the generated HTML, which
149 means we don't need to specify them separately.
150
151 There are several other Ruby libs that implement the factory pattern or provide
152 a DSL for request specs (a.k.a. acceptance or integration specs), but
153 FactoryGirl and Capybara seem to be the most widely used. Whether you choose
154 these or other libs, we strongly recommend using something for each of these
155 roles.
8d0199ba »
2010-01-24 generator fixes
156
43229ac1 »
2010-05-01 words
157 # Controller Specs
0dcfce75 »
2010-02-25 words
158
3d173af2 »
2010-04-27 words
159 Controller specs live in spec/controllers, and mix in
80febb5b »
2011-12-07 Consolidate rdoc for example groups to README
160 ActionController::TestCase::Behavior, which is the basis for Rails' functional
161 tests.
0dcfce75 »
2010-02-25 words
162
0e6b1853 »
2011-12-08 rdoc
163 ## with fixtures
80febb5b »
2011-12-07 Consolidate rdoc for example groups to README
164
165 ```ruby
166 describe WidgetsController do
167 describe "GET index" do
168 fixtures :widgets
169
170 it "assigns all widgets to @widgets" do
171 get :index
172 assigns(:widgets).should eq(Widget.all)
173 end
174 end
175 end
176 ```
177
0e6b1853 »
2011-12-08 rdoc
178 ## with a factory
80febb5b »
2011-12-07 Consolidate rdoc for example groups to README
179
180 ```ruby
181 describe WidgetsController do
182 describe "GET index" do
183 it "assigns all widgets to @widgets" do
184 widget = Factory(:widget)
185 get :index
186 assigns(:widgets).should eq([widget])
187 end
188 end
189 end
190 ```
191
192 ## with stubs
193
194 ```ruby
195 describe WidgetsController do
196 describe "GET index" do
197 it "assigns all widgets to @widgets" do
198 widget = stub_model(Widget)
199 Widget.stub(:all) { [widget] }
200 get :index
201 assigns(:widgets).should eq([widget])
202 end
203 end
204 end
205 ```
206
0e6b1853 »
2011-12-08 rdoc
207 ## matchers
80febb5b »
2011-12-07 Consolidate rdoc for example groups to README
208
209 In addition to the stock matchers from rspec-expectations, controller
210 specs add these matchers, which delegate to rails' assertions:
211
212 ```ruby
213 response.should render_template(*args)
214 # => delegates to assert_template(*args)
215
216 response.should redirect_to(destination)
217 # => delegates to assert_redirected_to(destination)
218 ```
219
0e6b1853 »
2011-12-08 rdoc
220 ## isolation from views
80febb5b »
2011-12-07 Consolidate rdoc for example groups to README
221
222 RSpec's preferred approach to spec'ing controller behaviour is to isolate
223 the controller from its collaborators. By default, therefore, controller
224 example groups do not render the views in your app. Due to the way Rails
225 searches for view templates, the template still needs to exist, but it
226 won't actually be loaded.
227
228 NOTE that this is different from rspec-rails-1 with rails-2, which did not
229 require the presence of the file at all. Due to changes in rails-3, this
230 was no longer feasible in rspec-rails-2.
38df36b3 »
2010-02-25 more words
231
435c1816 »
2010-06-13 add upgrade notes about methods that changed to README
232 ## `render_views`
9bf3e32e »
2011-12-04 rdoc
233
80febb5b »
2011-12-07 Consolidate rdoc for example groups to README
234 If you prefer a more integrated approach, similar to that of Rails'
235 functional tests, you can tell controller groups to render the views in the
236 app with the `render_views` declaration:
43229ac1 »
2010-05-01 words
237
1bec8ff8 »
2011-12-04 use github-flavored-markdown in the readme
238 ```ruby
80febb5b »
2011-12-07 Consolidate rdoc for example groups to README
239 describe WidgetsController do
1bec8ff8 »
2011-12-04 use github-flavored-markdown in the readme
240 render_views
241 # ...
242 ```
43229ac1 »
2010-05-01 words
243
9bf3e32e »
2011-12-04 rdoc
244 ### Upgrade note
435c1816 »
2010-06-13 add upgrade notes about methods that changed to README
245
246 `render_views` replaces `integrate_views` from rspec-rails-1.3
247
248 ## `assigns`
249
250 Use `assigns(key)` to express expectations about instance variables that a controller
251 assigns to the view in the course of an action:
252
1bec8ff8 »
2011-12-04 use github-flavored-markdown in the readme
253 ```ruby
254 get :index
255 assigns(:widgets).should eq(expected_value)
256 ```
435c1816 »
2010-06-13 add upgrade notes about methods that changed to README
257
9387d57f »
2010-05-27 words
258 # View specs
259
260 View specs live in spec/views, and mix in ActionView::TestCase::Behavior.
261
1bec8ff8 »
2011-12-04 use github-flavored-markdown in the readme
262 ```ruby
ff96af6b »
2012-02-01 remove rendering engine and mime type from calls to describe and rend…
263 describe "events/index" do
1bec8ff8 »
2011-12-04 use github-flavored-markdown in the readme
264 it "renders _event partial for each event" do
265 assign(:events, [stub_model(Event), stub_model(Event)])
266 render
267 view.should render_template(:partial => "_event", :count => 2)
268 end
269 end
270
ff96af6b »
2012-02-01 remove rendering engine and mime type from calls to describe and rend…
271 describe "events/show" do
1bec8ff8 »
2011-12-04 use github-flavored-markdown in the readme
272 it "displays the event location" do
273 assign(:event, stub_model(Event,
274 :location => "Chicago"
275 ))
276 render
277 rendered.should contain("Chicago")
278 end
279 end
280 ```
cbf623a2 »
2010-07-13 doc: note that ActionView::TestCase auto-propagates ivars
281
732a9222 »
2010-08-22 Infer controller.request.path_params["controller"] from the file being
282 View specs infer the controller name and path from the path to the view
283 template. e.g. if the template is "events/index.html.erb" then:
284
1bec8ff8 »
2011-12-04 use github-flavored-markdown in the readme
285 ```ruby
286 controller.controller_path == "events"
287 controller.request.path_parameters[:controller] == "events"
288 ```
732a9222 »
2010-08-22 Infer controller.request.path_params["controller"] from the file being
289
290 This means that most of the time you don't need to set these values. When
291 spec'ing a partial that is included across different controllers, you _may_
292 need to override these values before rendering the view.
293
30d998c4 »
2010-11-25 Explicit template/layout render example
294 To provide a layout for the render, you'll need to specify _both_ the template
295 and the layout explicitly. For example:
296
1bec8ff8 »
2011-12-04 use github-flavored-markdown in the readme
297 ```ruby
298 render :template => "events/show", :layout => "layouts/application"
299 ```
30d998c4 »
2010-11-25 Explicit template/layout render example
300
435c1816 »
2010-06-13 add upgrade notes about methods that changed to README
301 ## `assign(key, val)`
302
303 Use this to assign values to instance variables in the view:
304
1bec8ff8 »
2011-12-04 use github-flavored-markdown in the readme
305 ```ruby
306 assign(:widget, stub_model(Widget))
307 render
308 ```
cbf623a2 »
2010-07-13 doc: note that ActionView::TestCase auto-propagates ivars
309
435c1816 »
2010-06-13 add upgrade notes about methods that changed to README
310 The code above assigns `stub_model(Widget)` to the `@widget` variable in the view, and then
311 renders the view.
312
cbf623a2 »
2010-07-13 doc: note that ActionView::TestCase auto-propagates ivars
313 Note that because view specs mix in `ActionView::TestCase` behavior, any
314 instance variables you set will be transparently propagated into your views
315 (similar to how instance variables you set in controller actions are made
316 available in views). For example:
317
1bec8ff8 »
2011-12-04 use github-flavored-markdown in the readme
318 ```ruby
319 @widget = stub_model(Widget)
320 render # @widget is available inside the view
321 ```
cbf623a2 »
2010-07-13 doc: note that ActionView::TestCase auto-propagates ivars
322
323 RSpec doesn't officially support this pattern, which only works as a
324 side-effect of the inclusion of `ActionView::TestCase`. Be aware that it may be
325 made unavailable in the future.
326
9bf3e32e »
2011-12-04 rdoc
327 ### Upgrade note
435c1816 »
2010-06-13 add upgrade notes about methods that changed to README
328
1bec8ff8 »
2011-12-04 use github-flavored-markdown in the readme
329 ```ruby
330 # rspec-rails-1.x
331 assigns[key] = value
332
333 # rspec-rails-2.x
334 assign(key, value)
335 ```
435c1816 »
2010-06-13 add upgrade notes about methods that changed to README
336
337 ## `rendered`
338
339 This represents the rendered view.
340
1bec8ff8 »
2011-12-04 use github-flavored-markdown in the readme
341 ```ruby
342 render
343 rendered.should =~ /Some text expected to appear on the page/
344 ```
99ba3460 »
2011-08-29 Revert "Use Github Flavored Markdown"
345
9bf3e32e »
2011-12-04 rdoc
346 ### Upgrade note
435c1816 »
2010-06-13 add upgrade notes about methods that changed to README
347
1bec8ff8 »
2011-12-04 use github-flavored-markdown in the readme
348 ```ruby
349 # rspec-rails-1.x
350 render
351 response.should xxx
352
353 # rspec-rails-2.x
354 render
355 rendered.should xxx
356 ```
9387d57f »
2010-05-27 words
357
9bf3e32e »
2011-12-04 rdoc
358 # Model specs
359
360 Model specs live in spec/models.
361
362 ```ruby
363 describe Articles do
364 describe ".recent" do
365 it "includes articles published less than one week ago" do
366 article = Article.create!(:published_at => Date.today - 1.week + 1.second)
367 Article.recent.should eq([article])
368 end
369
370 it "excludes articles published at midnight one week ago" do
371 article = Article.create!(:published_at => Date.today - 1.week)
372 Article.recent.should be_empty
373 end
374
375 it "excludes articles published more than one week ago" do
376 article = Article.create!(:published_at => Date.today - 1.week - 1.second)
377 Article.recent.should be_empty
378 end
379 end
380 end
381 ```
382
f5046143 »
2010-06-18 words
383 # Routing specs
384
385 Routing specs live in spec/routing.
386
1bec8ff8 »
2011-12-04 use github-flavored-markdown in the readme
387 ```ruby
388 describe "routing to profiles" do
389 it "routes /profile/:username to profile#show for username" do
390 { :get => "/profiles/jsmith" }.should route_to(
391 :controller => "profiles",
392 :action => "show",
393 :username => "jsmith"
394 )
395 end
396
397 it "does not expose a list of profiles" do
398 { :get => "/profiles" }.should_not be_routable
399 end
400 end
401 ```
f5046143 »
2010-06-18 words
402
9bf3e32e »
2011-12-04 rdoc
403 ### Upgrade note
cd4dcbd5 »
2010-08-30 note about route_for being removed
404
405 `route_for` from rspec-rails-1.x is gone. Use `route_to` and `be_routable` instead.
406
9387d57f »
2010-05-27 words
407 # Helper specs
408
409 Helper specs live in spec/helpers, and mix in ActionView::TestCase::Behavior.
410
80febb5b »
2011-12-07 Consolidate rdoc for example groups to README
411 Provides a `helper` object which mixes in the helper module being spec'd, along
412 with `ApplicationHelper` (if present).
413
1bec8ff8 »
2011-12-04 use github-flavored-markdown in the readme
414 ```ruby
415 describe EventsHelper do
416 describe "#link_to_event" do
417 it "displays the title, and formatted date" do
418 event = Event.new("Ruby Kaigi", Date.new(2010, 8, 27))
419 # helper is an instance of ActionView::Base configured with the
420 # EventsHelper and all of Rails' built-in helpers
421 helper.link_to_event.should =~ /Ruby Kaigi, 27 Aug, 2010/
9387d57f »
2010-05-27 words
422 end
1bec8ff8 »
2011-12-04 use github-flavored-markdown in the readme
423 end
424 end
425 ```
f30f2131 »
2010-06-24 words
426
427 # Matchers
428
429 rspec-rails exposes domain-specific matchers to each of the example group types. Most
430 of them simply delegate to Rails' assertions.
431
432 ## `be_a_new`
433 * Available in all specs.
434 * Primarily intended for controller specs
435
1bec8ff8 »
2011-12-04 use github-flavored-markdown in the readme
436 ```ruby
f30f2131 »
2010-06-24 words
437 object.should be_a_new(Widget)
1bec8ff8 »
2011-12-04 use github-flavored-markdown in the readme
438 ```
439
f30f2131 »
2010-06-24 words
440
441 Passes if the object is a `Widget` and returns true for `new_record?`
442
443 ## `render_template`
444 * Delegates to Rails' assert_template.
445 * Available in request, controller, and view specs.
446
447 In request and controller specs, apply to the response object:
448
1bec8ff8 »
2011-12-04 use github-flavored-markdown in the readme
449 ```ruby
450 response.should render_template("new")
451 ```
f30f2131 »
2010-06-24 words
452
453 In view specs, apply to the view object:
454
1bec8ff8 »
2011-12-04 use github-flavored-markdown in the readme
455 ```ruby
456 view.should render_template(:partial => "_form", :locals => { :widget => widget } )
457 ```
f30f2131 »
2010-06-24 words
458
459 ## `redirect_to`
460 * Delegates to assert_redirect
461 * Available in request and controller specs.
462
1bec8ff8 »
2011-12-04 use github-flavored-markdown in the readme
463 ```ruby
f30f2131 »
2010-06-24 words
464 response.should redirect_to(widgets_path)
1bec8ff8 »
2011-12-04 use github-flavored-markdown in the readme
465 ```
f30f2131 »
2010-06-24 words
466
467 ## `route_to`
468
469 * Delegates to Rails' assert_routing.
470 * Available in routing and controller specs.
471
1bec8ff8 »
2011-12-04 use github-flavored-markdown in the readme
472 ```ruby
f30f2131 »
2010-06-24 words
473 { :get => "/widgets" }.should route_to(:controller => "widgets", :action => "index")
1bec8ff8 »
2011-12-04 use github-flavored-markdown in the readme
474 ```
f30f2131 »
2010-06-24 words
475
476 ## `be_routable`
477
478 Passes if the path is recognized by Rails' routing. This is primarily intended
479 to be used with `should_not` to specify routes that should not be routable.
480
1bec8ff8 »
2011-12-04 use github-flavored-markdown in the readme
481 ```ruby
482 { :get => "/widgets/1/edit" }.should_not be_routable
483 ```
6e90564e »
2010-07-07 words
484
9bf3e32e »
2011-12-04 rdoc
485 # Contribute
6e90564e »
2010-07-07 words
486
487 See [http://github.com/rspec/rspec-dev](http://github.com/rspec/rspec-dev)
488
9bf3e32e »
2011-12-04 rdoc
489 # Also see
6e90564e »
2010-07-07 words
490
491 * [http://github.com/rspec/rspec](http://github.com/rspec/rspec)
492 * [http://github.com/rspec/rspec-core](http://github.com/rspec/rspec-core)
493 * [http://github.com/rspec/rspec-expectations](http://github.com/rspec/rspec-expectations)
494 * [http://github.com/rspec/rspec-mocks](http://github.com/rspec/rspec-mocks)
Something went wrong with that request. Please try again.