Skip to content

HTTPS clone URL

Subversion checkout URL

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