Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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