Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 370 lines (258 sloc) 12.061 kb
cd4198e Back to RDoc for Readme
Dennis Rogenius and Jonas Nicklas authored
1 = capybara
8435d19 Initial checkin
Jonas Nicklas and Kevin Fitzpatrick authored
2
6b099a4 renamed to capybara
Theo Hultberg and Jonas Nicklas authored
3 * http://github.com/jnicklas/capybara
8435d19 Initial checkin
Jonas Nicklas and Kevin Fitzpatrick authored
4
cd4198e Back to RDoc for Readme
Dennis Rogenius and Jonas Nicklas authored
5 == Description:
8435d19 Initial checkin
Jonas Nicklas and Kevin Fitzpatrick authored
6
586ce21 @jnicklas Vastly improved README
jnicklas authored
7 Capybara aims to simplify the process of integration testing Rack applications,
d2265a3 @jnicklas Readme is markdown instead
jnicklas authored
8 such as Rails, Sinatra or Merb. It is inspired by and aims to replace Webrat as
9 a DSL for interacting with a webapplication. It is agnostic about the driver
2f8c5e9 @jnicklas Improved README
jnicklas authored
10 running your tests and currently comes bundled with rack-test, Culerity,
11 Celerity and Selenium support built in.
8435d19 Initial checkin
Jonas Nicklas and Kevin Fitzpatrick authored
12
988d4c9 @jnicklas Moved up installation instructions
jnicklas authored
13 == Install:
14
aec11e2 @jnicklas add note about libffi to readme
jnicklas authored
15 Install as a gem:
988d4c9 @jnicklas Moved up installation instructions
jnicklas authored
16
17 sudo gem install capybara
18
ecdc2bd @jnicklas visit now allow fully qualified URLs.
jnicklas authored
19 On OSX you may have to install libffi, you can install it via MacPorts with:
aec11e2 @jnicklas add note about libffi to readme
jnicklas authored
20
21 sudo port install libffi
22
27ee5af @jnicklas added note about development to README
jnicklas authored
23 == Development:
24
25 * Source hosted at {GitHub}[http://github.com/jnicklas/capybara].
26 * Please direct questions, discussions at the {mailing list}[http://groups.google.com/group/ruby-capybara].
6a1595b @jnicklas missing issues link
jnicklas authored
27 * Report issues on {GitHub Issues}[http://github.com/jnicklas/capybara/issues]
28 * Pull requests are very welcome!
27ee5af @jnicklas added note about development to README
jnicklas authored
29
cd4198e Back to RDoc for Readme
Dennis Rogenius and Jonas Nicklas authored
30 == Using Capybara with Cucumber
8435d19 Initial checkin
Jonas Nicklas and Kevin Fitzpatrick authored
31
586ce21 @jnicklas Vastly improved README
jnicklas authored
32 Capybara is built to work nicely with Cucumber. The API is very similar to
6ce66ed @jnicklas Updated setup instructions for cuke-rails 0.2
jnicklas authored
33 Webrat, so if you know Webrat you should feel right at home. Support for
34 Capybara is built into cucumber-rails 0.2. In your Rails app, just run:
8435d19 Initial checkin
Jonas Nicklas and Kevin Fitzpatrick authored
35
6ce66ed @jnicklas Updated setup instructions for cuke-rails 0.2
jnicklas authored
36 script/generate cucumber --capybara
8435d19 Initial checkin
Jonas Nicklas and Kevin Fitzpatrick authored
37
6ce66ed @jnicklas Updated setup instructions for cuke-rails 0.2
jnicklas authored
38 And everything should be set up and ready to go.
586ce21 @jnicklas Vastly improved README
jnicklas authored
39
6ce66ed @jnicklas Updated setup instructions for cuke-rails 0.2
jnicklas authored
40 If you want to use Capybara with Cucumber outside Rails (for example with Merb
41 or Sinatra), you'll need require capybara and set the Rack app manually:
586ce21 @jnicklas Vastly improved README
jnicklas authored
42
43 require 'capybara/cucumber'
44 Capybara.app = MyRackApp
45
46 Now you can use it in your steps:
47
48 When /I sign in/ do
49 within("//form[@id='session']") do
50 fill_in 'Login', :with => 'user@example.com'
51 fill_in 'Password', :with => 'password'
52 end
53 click_link 'Sign in'
e06e04e Some more info in README
Jonas Nicklas and Kevin Fitzpatrick authored
54 end
8435d19 Initial checkin
Jonas Nicklas and Kevin Fitzpatrick authored
55
cd4198e Back to RDoc for Readme
Dennis Rogenius and Jonas Nicklas authored
56 == Default and current driver
586ce21 @jnicklas Vastly improved README
jnicklas authored
57
d2265a3 @jnicklas Readme is markdown instead
jnicklas authored
58 You can set up a default driver for your features. For example if you'd prefer
59 to run Selenium, you could do:
586ce21 @jnicklas Vastly improved README
jnicklas authored
60
61 require 'capybara/rails'
62 require 'capybara/cucumber'
63 Capybara.default_driver = :selenium
64
65 You can change the driver temporarily:
66
67 Capybara.current_driver = :culerity
68 Capybara.use_default_driver
69
cb809f9 Slight README improvements
CJ Kihlbom and Jonas Nicklas authored
70 You can do this in Before and After blocks to temporarily switch to a different
71 driver. Note that switching driver creates a new session, so you may not be able
72 to switch in the middle of a Scenario.
73
cd4198e Back to RDoc for Readme
Dennis Rogenius and Jonas Nicklas authored
74 == Cucumber and Tags
586ce21 @jnicklas Vastly improved README
jnicklas authored
75
7f1a86f @jnicklas Wee, Culerity passes all specs!
jnicklas authored
76 Capybara sets up some {tags}[http://wiki.github.com/aslakhellesoy/cucumber/tags]
cb809f9 Slight README improvements
CJ Kihlbom and Jonas Nicklas authored
77 for you to use in Cucumber. Often you'll want to run only some scenarios with a
78 driver that supports JavaScript, Capybara makes this easy: simply tag the
cd4198e Back to RDoc for Readme
Dennis Rogenius and Jonas Nicklas authored
79 scenario (or feature) with <tt>@javascript</tt>:
586ce21 @jnicklas Vastly improved README
jnicklas authored
80
81 @javascript
82 Scenario: do something AJAXy
83 When I click the AJAX link
84 ...
85
86 You can change which driver Capybara uses for JavaScript:
87
88 Capybara.javascript_driver = :culerity
89
cb809f9 Slight README improvements
CJ Kihlbom and Jonas Nicklas authored
90 There are also explicit <tt>@selenium</tt>, <tt>@culerity</tt> and
91 <tt>@rack_test</tt> tags set up for you.
586ce21 @jnicklas Vastly improved README
jnicklas authored
92
2f8c5e9 @jnicklas Improved README
jnicklas authored
93 == Selenium
586ce21 @jnicklas Vastly improved README
jnicklas authored
94
2f8c5e9 @jnicklas Improved README
jnicklas authored
95 At the moment, Capybara supports Webdriver, also called Selenium 2.0, *not*
96 Selenium RC. Provided Firefox is installed, everything is set up for you, and
97 you should be able to start using Selenium right away.
586ce21 @jnicklas Vastly improved README
jnicklas authored
98
2f8c5e9 @jnicklas Improved README
jnicklas authored
99 == Celerity
586ce21 @jnicklas Vastly improved README
jnicklas authored
100
2f8c5e9 @jnicklas Improved README
jnicklas authored
101 Celerity only runs on JRuby, so you'll need to install the celerity gem under
102 JRuby:
586ce21 @jnicklas Vastly improved README
jnicklas authored
103
2f8c5e9 @jnicklas Improved README
jnicklas authored
104 jruby -S gem install celerity
586ce21 @jnicklas Vastly improved README
jnicklas authored
105
2f8c5e9 @jnicklas Improved README
jnicklas authored
106 Note that some specs currently fail on celerity 0.7.5, due to a bug in recent
107 versions of HTMLUnit. It is recommended you use celerity 0.7.4 for the time
108 being.
586ce21 @jnicklas Vastly improved README
jnicklas authored
109
2f8c5e9 @jnicklas Improved README
jnicklas authored
110 == Culerity
586ce21 @jnicklas Vastly improved README
jnicklas authored
111
2f8c5e9 @jnicklas Improved README
jnicklas authored
112 Install celerity as noted above, make sure JRuby is in your path. Note that
113 Culerity doesn't seem to be working under Ruby 1.9 at the moment.
586ce21 @jnicklas Vastly improved README
jnicklas authored
114
2f8c5e9 @jnicklas Improved README
jnicklas authored
115 == The DSL
586ce21 @jnicklas Vastly improved README
jnicklas authored
116
2f8c5e9 @jnicklas Improved README
jnicklas authored
117 Capybara's DSL is inspired by Webrat. While backwards compatibility is retained
118 in a lot of cases, there are certain important differences.
fb71b29 @denro added documentation on the evaluate_script method
denro authored
119
2f8c5e9 @jnicklas Improved README
jnicklas authored
120 Unlike in Webrat, all searches in Capybara are *case sensitive*. This is because
121 Capybara heavily uses XPath, which doesn't support case insensitivity.
fb71b29 @denro added documentation on the evaluate_script method
denro authored
122
2f8c5e9 @jnicklas Improved README
jnicklas authored
123 === Navigating
124
125 You can use the <tt>visit</tt> method to navigate to other pages:
126
127 visit('/projects')
128 visit(post_comments_path(post))
129
130 The visit method only takes a single parameter, the request method is *always*
131 GET.
132
133 === Clicking links and buttons
134
135 You can interact with the webapp by following links and buttons. Capybara
136 automatically follows any redirects, and submits forms associated with buttons.
137
138 click_link('id-of-link')
139 click_link('Link Text')
140 click_button('Save')
141 click('Link Text') # Click either a link or a button
142 click('Button Value')
143
144 === Interacting with forms
145
146 Forms are everywhere in webapps, there are a number of tools for interacting
147 with the various form elements:
148
149 fill_in('First Name', :with => 'John')
150 fill_in('Password', :with => 'Seekrit')
151 fill_in('Description', :with => 'Really Long Text…')
152 choose('An Option')
153 check('A Checkbox')
154 uncheck('A Checkbox')
155 attach_file('Image', '/path/to/image.jpg')
156 select('Option', :from => 'Select Box')
157
158 === Scoping
159
160 Capybara makes it possible to restrict certain actions, such as interacting with
161 forms or clicking links and buttons, to within a specific area of the page. For
162 this purpose you can use the generic <tt>within</tt> method. Optionally you can
163 specify which kind of selector (CSS or XPath to use).
164
165 within("//li[@id='employee']") do
166 fill_in 'Name', :with => 'Jimmy'
167 end
168
169 within(:css, "li#employee") do
170 fill_in 'Name', :with => 'Jimmy'
171 end
172
173 You can choose which kind of selector Capybara uses by default, by setting
174 <tt>Capybara.default_selector</tt>.
175
176 There are special methods for restricting the scope to a specific fieldset,
177 identified by either an id or the text of the fieldet's legend tag, and to a
178 specific table, identified by either idea or text of the table's caption tag.
179
180 within_fieldset('Employee') do
181 fill_in 'Name', :with => 'Jimmy'
182 end
183
184 within_table('Employee') do
185 fill_in 'Name', :with => 'Jimmy'
186 end
187
188 === Querying
189
190 Capybara has a rich set of options for querying the page for the existence of
191 certain elements, and working with and manipulating those elements.
192
193 page.has_xpath?('//table/tr')
194 page.has_css?('table tr.foo')
195 page.has_content?('foo')
196
197 You can use with RSpecs magic matchers:
198
199 page.should have_xpath('//table/tr')
200 page.should have_css('table tr.foo')
201 page.should have_content('foo')
4f2da02 @jnicklas Added a long note about asynchronous JS to README
jnicklas authored
202 page.should have_no_content('foo')
203
204 Note that <tt>page.should have_no_xpath</tt> is preferred over
205 <tt>page.should_not have_xpath</tt>. Read the section on asynchronous JavaScript
206 for an explanation.
2f8c5e9 @jnicklas Improved README
jnicklas authored
207
208 You can also find specific elements, in order to manipulate them:
209
210 find_field('First Name').value
211 find_link('Hello').visible?
212 find_button('Send').click
213
214 find('//table/tr').click
215 wait_for("//*[@id='overlay'").find("//h1").click
216 all('a').each { |a| a[:href] }
217
218 === Scripting
219
220 In drivers which support it, you can easily evaluate JavaScript:
221
222 result = page.evaluate_script('4 + 4');
223
224 === Debugging
225
226 It can be useful to take a snapshot of the page as it currently is and take a
227 look at it:
586ce21 @jnicklas Vastly improved README
jnicklas authored
228
229 save_and_open_page
230
4f2da02 @jnicklas Added a long note about asynchronous JS to README
jnicklas authored
231 == Asynchronous JavaScript (AJAX and friends)
232
233 When working with asynchronous JavaScript, you might come across situations
234 where you are attempting to interact with an element which is not yet present
235 on the page. Capybara automatically deals with this by waiting for elements
236 to appear on the page.
237
238 When issuing instructions to the DSL such as:
239
240 click_link('foo')
241 click_link('bar')
242 page.should have_content('baz')
243
244 If clicking on the *foo* link causes triggers an asynchronous process, such as
245 an AJAX request, which, when complete will add the *bar* link to the page,
246 clicking on the *bar* link would be expeced to fail, since that link doesn't
247 exist yet. However Capybara is smart enought to retry finding the link for a
248 brief period of time before giving up and throwing an error. The same is true of
249 the next line, which looks for the content *baz* on the page; it will retry
250 looking for that content for a brief time. You can adjust how long this period
251 is (the default is 2 seconds):
252
253 Capybara.default_wait_time = 5
254
255 Be aware that because of this behaviour, the following two statements are *not*
256 identical, and you should *always* use the latter!
257
258 page.should_not have_xpath('//a')
259 page.should have_no_xpath('//a')
260
261 The former would incorrectly wait for the content to appear, since the
262 asynchronous process has not yet removed the element from the page, it would
263 therefore fail, even though the code might be working correctly. The latter
264 correctly wait for the element to disappear from the page.
265
cd4198e Back to RDoc for Readme
Dennis Rogenius and Jonas Nicklas authored
266 == Using the DSL outside cucumber
586ce21 @jnicklas Vastly improved README
jnicklas authored
267
268 You can mix the DSL into any context, for example you could use it in RSpec
269 examples. Just load the dsl and include it anywhere:
8435d19 Initial checkin
Jonas Nicklas and Kevin Fitzpatrick authored
270
6b099a4 renamed to capybara
Theo Hultberg and Jonas Nicklas authored
271 require 'capybara'
272 require 'capybara/dsl'
586ce21 @jnicklas Vastly improved README
jnicklas authored
273
6b099a4 renamed to capybara
Theo Hultberg and Jonas Nicklas authored
274 include Capybara
275 Capybara.default_driver = :culerity
e06e04e Some more info in README
Jonas Nicklas and Kevin Fitzpatrick authored
276
277 within("//form[@id='session']") do
278 fill_in 'Login', :with => 'user@example.com'
279 fill_in 'Password', :with => 'password'
280 end
281 click_link 'Sign in'
282
cd4198e Back to RDoc for Readme
Dennis Rogenius and Jonas Nicklas authored
283 == Using the sessions manually
e06e04e Some more info in README
Jonas Nicklas and Kevin Fitzpatrick authored
284
586ce21 @jnicklas Vastly improved README
jnicklas authored
285 For ultimate control, you can instantiate and use a session manually.
e06e04e Some more info in README
Jonas Nicklas and Kevin Fitzpatrick authored
286
586ce21 @jnicklas Vastly improved README
jnicklas authored
287 require 'capybara'
e06e04e Some more info in README
Jonas Nicklas and Kevin Fitzpatrick authored
288
586ce21 @jnicklas Vastly improved README
jnicklas authored
289 session = Capybara::Session.new(:culerity, my_rack_app)
290 session.within("//form[@id='session']") do
291 session.fill_in 'Login', :with => 'user@example.com'
292 session.fill_in 'Password', :with => 'password'
e06e04e Some more info in README
Jonas Nicklas and Kevin Fitzpatrick authored
293 end
586ce21 @jnicklas Vastly improved README
jnicklas authored
294 session.click_link 'Sign in'
e06e04e Some more info in README
Jonas Nicklas and Kevin Fitzpatrick authored
295
aa9889b @jnicklas Typo in README
jnicklas authored
296 == XPath and CSS
7313511 @jnicklas Added section about selectors to README
jnicklas authored
297
298 Capybara does not try to guess what kind of selector you are going to give it,
299 if you want to use CSS with your 'within' declarations for example, you'll need
300 to do:
fb71b29 @denro added documentation on the evaluate_script method
denro authored
301
7313511 @jnicklas Added section about selectors to README
jnicklas authored
302 within(:css, 'ul li') { ... }
303
304 Alternatively you can set the default selector to CSS, which may help if you are
305 moving from Webrat and used CSS a lot, or simply generally prefer CSS:
306
307 Capybara.default_selector = :css
308 within('ul li') { ... }
309
cd4198e Back to RDoc for Readme
Dennis Rogenius and Jonas Nicklas authored
310 == Gotchas:
e06e04e Some more info in README
Jonas Nicklas and Kevin Fitzpatrick authored
311
d2265a3 @jnicklas Readme is markdown instead
jnicklas authored
312 * Domain names (including subdomains) don't work under rack-test. Since it's a
313 pain to set up subdomains for the other drivers anyway, you should consider an
314 alternate solution. You might use
bac7257 @jnicklas yet more changes to Culerity instructions
jnicklas authored
315 {default_url_options}[https://gist.github.com/643a758320a2926bd2ed] in Rails
d2265a3 @jnicklas Readme is markdown instead
jnicklas authored
316 for example.
586ce21 @jnicklas Vastly improved README
jnicklas authored
317
d2265a3 @jnicklas Readme is markdown instead
jnicklas authored
318 * Access to session, request and response from the test is not possible. Maybe
319 we'll do response headers at some point in the future, but the others really
320 shouldn't be touched in an integration test anyway.
8435d19 Initial checkin
Jonas Nicklas and Kevin Fitzpatrick authored
321
cd4198e Back to RDoc for Readme
Dennis Rogenius and Jonas Nicklas authored
322 * Access to Rails specific stuff (such as <tt>controller</tt>) is unavailable,
323 since we're not using Rails' integration testing.
d2265a3 @jnicklas Readme is markdown instead
jnicklas authored
324
cd4198e Back to RDoc for Readme
Dennis Rogenius and Jonas Nicklas authored
325 * <tt><a href="#"></tt> Will cause problems under rack-test, please do
326 <tt><a href="/same/url#"></tt> instead. You can achieve this in Rails with
327 <tt>link_to('foo', :anchor => '')</tt>
d2265a3 @jnicklas Readme is markdown instead
jnicklas authored
328
df188f9 @jnicklas Added list of contributors
jnicklas authored
329 == Contributors:
330
331 The following people have dedicated their time and effort to Capybara:
332
333 * Jonas Nicklas
334 * Dennis Rogenius
335 * Rob Holland
4363452 @jnicklas added wincent to contributors
jnicklas authored
336 * Wincent Colaiuta
cde0453 @jnicklas added Andrea Fazzi to collaborators
jnicklas authored
337 * Andrea Fazzi
3355fb8 @jnicklas Added Aslak to contributors
jnicklas authored
338 * Aslak Hellesøy
026299f @jnicklas added Andrew Brown to contributors
jnicklas authored
339 * Andrew Brown
18185c4 @jnicklas Added Lenny Marks to contributors
jnicklas authored
340 * Lenny Marks
c95d351 @jnicklas Added Aaron Patterson to contributors
jnicklas authored
341 * Aaron Patterson
31021bc @jnicklas Added Dan Dofter to contributors
jnicklas authored
342 * Dan Dofter
98e1410 @jnicklas Added Thorbjørn Hermansen to contributors
jnicklas authored
343 * Thorbjørn Hermansen
67e8342 @jnicklas Added Louis T. to contributors
jnicklas authored
344 * Louis T.
df188f9 @jnicklas Added list of contributors
jnicklas authored
345
cd4198e Back to RDoc for Readme
Dennis Rogenius and Jonas Nicklas authored
346 == License:
8435d19 Initial checkin
Jonas Nicklas and Kevin Fitzpatrick authored
347
348 (The MIT License)
349
350 Copyright (c) 2009 Jonas Nicklas
351
352 Permission is hereby granted, free of charge, to any person obtaining
353 a copy of this software and associated documentation files (the
354 'Software'), to deal in the Software without restriction, including
355 without limitation the rights to use, copy, modify, merge, publish,
356 distribute, sublicense, and/or sell copies of the Software, and to
357 permit persons to whom the Software is furnished to do so, subject to
358 the following conditions:
359
360 The above copyright notice and this permission notice shall be
361 included in all copies or substantial portions of the Software.
362
363 THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
364 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
365 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
366 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
367 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
368 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
fb71b29 @denro added documentation on the evaluate_script method
denro authored
369 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Something went wrong with that request. Please try again.