Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 817 lines (611 sloc) 24.518 kb
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
1 # Capybara
8435d19 Initial checkin
Jonas Nicklas and Kevin Fitzpatrick authored
2
f788061 @jnicklas add Travis CI status image
authored
3 [![Build Status](https://secure.travis-ci.org/jnicklas/capybara.png)](http://travis-ci.org/jnicklas/capybara)
85f8d57 @laserlemon Add dependency status (already green) to the README
laserlemon authored
4 [![Dependency Status](https://gemnasium.com/jnicklas/capybara.png)](https://gemnasium.com/jnicklas/capybara)
f788061 @jnicklas add Travis CI status image
authored
5
de76d8a @joliss Make README more terse and readable
joliss authored
6 Capybara helps you test Rails and Rack applications by simulating how a real
7 user would interact with your app. It is agnostic about the driver running your
8 tests and comes with Rack::Test and Selenium support built in. WebKit is
9 supported through an external gem.
8435d19 Initial checkin
Jonas Nicklas and Kevin Fitzpatrick authored
10
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
11 **Need help?** Ask on the mailing list (please do not open an issue on
1ce930b @joliss Be more adamant about where to ask for help
joliss authored
12 GitHub): http://groups.google.com/group/ruby-capybara
8435d19 Initial checkin
Jonas Nicklas and Kevin Fitzpatrick authored
13
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
14 ## Setup
8435d19 Initial checkin
Jonas Nicklas and Kevin Fitzpatrick authored
15
de76d8a @joliss Make README more terse and readable
joliss authored
16 To install, type
8dc27c2 @jnicklas Added note about rdoc.info to README
authored
17
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
18 ```bash
19 sudo gem install capybara
20 ```
988d4c9 @jnicklas Moved up installation instructions
authored
21
de76d8a @joliss Make README more terse and readable
joliss authored
22 If you are using Rails, add this line to your test helper file:
988d4c9 @jnicklas Moved up installation instructions
authored
23
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
24 ```ruby
25 require 'capybara/rails'
26 ```
988d4c9 @jnicklas Moved up installation instructions
authored
27
de76d8a @joliss Make README more terse and readable
joliss authored
28 If you are not using Rails, set Capybara.app to your rack app:
aec11e2 @jnicklas add note about libffi to readme
authored
29
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
30 ```ruby
31 Capybara.app = MyRackApp
32 ```
aec11e2 @jnicklas add note about libffi to readme
authored
33
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
34 ## Using Capybara with Cucumber
8435d19 Initial checkin
Jonas Nicklas and Kevin Fitzpatrick authored
35
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
36 The `cucumber-rails` gem comes with Capybara support built-in. If you
37 are not using Rails, manually load the `capybara/cucumber` module:
586ce21 @jnicklas Vastly improved README
authored
38
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
39 ```ruby
40 require 'capybara/cucumber'
41 Capybara.app = MyRackApp
42 ```
586ce21 @jnicklas Vastly improved README
authored
43
de76d8a @joliss Make README more terse and readable
joliss authored
44 You can use the Capybara DSL in your steps, like so:
586ce21 @jnicklas Vastly improved README
authored
45
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
46 ```ruby
47 When /I sign in/ do
48 within("#session") do
49 fill_in 'Login', :with => 'user@example.com'
50 fill_in 'Password', :with => 'password'
51 end
52 click_link 'Sign in'
53 end
54 ```
55
56 You can switch to the `Capybara.javascript_driver` (`:selenium`
57 by default) by tagging scenarios (or features) with `@javascript`:
58
59 ```ruby
60 @javascript
61 Scenario: do something Ajaxy
62 When I click the Ajax link
63 ...
64 ```
65
66 There are also explicit `@selenium` and `@rack_test`
05400cd @sobrinho Remove references to akephalos, culerity and celerity from README
sobrinho authored
67 tags set up for you.
aa46894 Add RSpec support in Capybara itself, closes #187
Anders Törnqvist authored
68
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
69 ## Using Capybara with RSpec
aa46894 Add RSpec support in Capybara itself, closes #187
Anders Törnqvist authored
70
de76d8a @joliss Make README more terse and readable
joliss authored
71 Load RSpec 2.x support by adding the following line (typically to your
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
72 `spec_helper.rb` file):
aa46894 Add RSpec support in Capybara itself, closes #187
Anders Törnqvist authored
73
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
74 ```ruby
75 require 'capybara/rspec'
76 ```
aa46894 Add RSpec support in Capybara itself, closes #187
Anders Törnqvist authored
77
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
78 If you are using Rails, put your Capybara specs in `spec/requests` or
79 `spec/integration`.
de76d8a @joliss Make README more terse and readable
joliss authored
80
81 If you are not using Rails, tag all the example groups in which you want to use
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
82 Capybara with `:type => :request`.
de76d8a @joliss Make README more terse and readable
joliss authored
83
095a118 @mcmire Clear things up in README again as :type => :request specs become Rai…
mcmire authored
84 You can now write your specs like so:
aa46894 Add RSpec support in Capybara itself, closes #187
Anders Törnqvist authored
85
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
86 ```ruby
87 describe "the signup process", :type => :request do
88 before :each do
89 User.make(:email => 'user@example.com', :password => 'caplin')
90 end
a00435d @jnicklas Added :headers option to rack_test driver, closes #328
authored
91
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
92 it "signs me in" do
93 within("#session") do
94 fill_in 'Login', :with => 'user@example.com'
95 fill_in 'Password', :with => 'password'
aa46894 Add RSpec support in Capybara itself, closes #187
Anders Törnqvist authored
96 end
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
97 click_link 'Sign in'
98 end
99 end
100 ```
aa46894 Add RSpec support in Capybara itself, closes #187
Anders Törnqvist authored
101
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
102 Use `:js => true` to switch to the `Capybara.javascript_driver`
103 (`:selenium` by default), or provide a `:driver` option to switch
de76d8a @joliss Make README more terse and readable
joliss authored
104 to one specific driver. For example:
aa46894 Add RSpec support in Capybara itself, closes #187
Anders Törnqvist authored
105
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
106 ```ruby
107 describe 'some stuff which requires js', :js => true do
108 it 'will use the default js driver'
109 it 'will switch to one specific driver', :driver => :webkit
110 end
111 ```
aa46894 Add RSpec support in Capybara itself, closes #187
Anders Törnqvist authored
112
095a118 @mcmire Clear things up in README again as :type => :request specs become Rai…
mcmire authored
113 Finally, Capybara also comes with a built in DSL for creating descriptive acceptance tests:
f4897f8 Added DSL for acceptance tests in RSpec
Jonas Nicklas and Nicklas Ramhöj authored
114
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
115 ```ruby
116 feature "Signing up" do
117 background do
118 User.make(:email => 'user@example.com', :password => 'caplin')
119 end
f4897f8 Added DSL for acceptance tests in RSpec
Jonas Nicklas and Nicklas Ramhöj authored
120
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
121 scenario "Signing in with correct credentials" do
122 within("#session") do
123 fill_in 'Login', :with => 'user@example.com'
124 fill_in 'Password', :with => 'caplin'
f4897f8 Added DSL for acceptance tests in RSpec
Jonas Nicklas and Nicklas Ramhöj authored
125 end
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
126 click_link 'Sign in'
127 end
128 end
129 ```
f4897f8 Added DSL for acceptance tests in RSpec
Jonas Nicklas and Nicklas Ramhöj authored
130
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
131 `feature` is in fact just an alias for `describe ..., :type => :request`,
132 `background` is an alias for `before`, and `scenario` for `it`.
aa46894 Add RSpec support in Capybara itself, closes #187
Anders Törnqvist authored
133
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
134 ## Using Capybara with Test::Unit
112be58 @joliss added documentation for Test::Unit integration
joliss authored
135
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
136 * If you are using Rails, add `database_cleaner` to your Gemfile:
112be58 @joliss added documentation for Test::Unit integration
joliss authored
137
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
138 ```ruby
139 group :test do
140 gem 'database_cleaner'
141 end
142 ```
143
144 Then add the following code in your `test_helper.rb` file to make
145 Capybara available in all test cases deriving from
146 `ActionDispatch::IntegrationTest`:
147
148 ```ruby
149 # Transactional fixtures do not work with Selenium tests, because Capybara
150 # uses a separate server thread, which the transactions would be hidden
151 # from. We hence use DatabaseCleaner to truncate our test database.
152 DatabaseCleaner.strategy = :truncation
153
154 class ActionDispatch::IntegrationTest
155 # Make the Capybara DSL available in all integration tests
156 include Capybara::DSL
9230440 @joliss Expand Test::Unit README section
joliss authored
157
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
158 # Stop ActiveRecord from wrapping tests in transactions
159 self.use_transactional_fixtures = false
160
161 teardown do
162 DatabaseCleaner.clean # Truncate the database
163 Capybara.reset_sessions! # Forget the (simulated) browser state
164 Capybara.use_default_driver # Revert Capybara.current_driver to Capybara.default_driver
9230440 @joliss Expand Test::Unit README section
joliss authored
165 end
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
166 end
167 ```
9230440 @joliss Expand Test::Unit README section
joliss authored
168
169 * If you are not using Rails, define a base class for your Capybara tests like
170 so:
171
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
172 ```ruby
173 class CapybaraTestCase < Test::Unit::TestCase
174 include Capybara::DSL
9230440 @joliss Expand Test::Unit README section
joliss authored
175
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
176 def teardown
177 Capybara.reset_sessions!
178 Capybara.use_default_driver
9230440 @joliss Expand Test::Unit README section
joliss authored
179 end
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
180 end
181 ```
9230440 @joliss Expand Test::Unit README section
joliss authored
182
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
183 Remember to call `super` in any subclasses that override
184 `teardown`.
9230440 @joliss Expand Test::Unit README section
joliss authored
185
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
186 To switch the driver, set `Capybara.current_driver`. For instance,
112be58 @joliss added documentation for Test::Unit integration
joliss authored
187
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
188 ```ruby
189 class BlogTest < ActionDispatch::IntegrationTest
190 setup do
191 Capybara.current_driver = Capybara.javascript_driver # :selenium by default
192 end
9230440 @joliss Expand Test::Unit README section
joliss authored
193
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
194 test 'shows blog posts'
195 # ... this test is run with Selenium ...
196 end
197 end
198 ```
1b44e0b @joliss added documentation on driver switching with Test::Unit
joliss authored
199
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
200 ## Using Capybara with MiniTest::Spec
6af5a5a @ordinaryzelig Add MiniTest::Spec section in README.
ordinaryzelig authored
201
9230440 @joliss Expand Test::Unit README section
joliss authored
202 Set up your base class as with Test::Unit. (On Rails, the right base class
203 could be something other than ActionDispatch::IntegrationTest.)
6af5a5a @ordinaryzelig Add MiniTest::Spec section in README.
ordinaryzelig authored
204
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
205 The capybara_minitest_spec gem ([Github](https://github.com/ordinaryzelig/capybara_minitest_spec),
206 [rubygems.org](https://rubygems.org/gems/capybara_minitest_spec)) provides MiniTest::Spec
6af5a5a @ordinaryzelig Add MiniTest::Spec section in README.
ordinaryzelig authored
207 expectations for Capybara. For example:
208
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
209 ```ruby
210 page.must_have_content('Important!')
211 ```
6af5a5a @ordinaryzelig Add MiniTest::Spec section in README.
ordinaryzelig authored
212
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
213 ## Drivers
586ce21 @jnicklas Vastly improved README
authored
214
1fa8aee @joliss Better documentation for drivers
joliss authored
215 Capybara uses the same DSL to drive a variety of browser and headless drivers.
216
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
217 ### Selecting the Driver
1fa8aee @joliss Better documentation for drivers
joliss authored
218
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
219 By default, Capybara uses the `:rack_test` driver, which is fast but does not
1fa8aee @joliss Better documentation for drivers
joliss authored
220 support JavaScript. You can set up a different default driver for your
221 features. For example if you'd prefer to run everything in Selenium, you could
222 do:
586ce21 @jnicklas Vastly improved README
authored
223
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
224 ```ruby
225 Capybara.default_driver = :selenium
226 ```
586ce21 @jnicklas Vastly improved README
authored
227
1fa8aee @joliss Better documentation for drivers
joliss authored
228 However, if you are using RSpec or Cucumber, you may instead want to consider
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
229 leaving the faster `:rack_test` as the __default_driver__, and marking only those
230 tests that require a JavaScript-capable driver using `:js => true` or
231 `@javascript`, respectively. By default, JavaScript tests are run using the
232 `:selenium` driver. You can change this by setting
233 `Capybara.javascript_driver`.
1fa8aee @joliss Better documentation for drivers
joliss authored
234
1b44e0b @joliss added documentation on driver switching with Test::Unit
joliss authored
235 You can also change the driver temporarily (typically in the Before/setup and
236 After/teardown blocks):
586ce21 @jnicklas Vastly improved README
authored
237
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
238 ```ruby
239 Capybara.current_driver = :webkit # temporarily select different driver
240 ... tests ...
241 Capybara.use_default_driver # switch back to default driver
242 ```
586ce21 @jnicklas Vastly improved README
authored
243
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
244 **Note**: switching the driver creates a new session, so you may not be able to
1fa8aee @joliss Better documentation for drivers
joliss authored
245 switch in the middle of a test.
cb809f9 Slight README improvements
CJ Kihlbom and Jonas Nicklas authored
246
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
247 ### RackTest
a00435d @jnicklas Added :headers option to rack_test driver, closes #328
authored
248
249 RackTest is Capybara's default driver. It is written in pure Ruby and does not
250 have any support for executing JavaScript. Since the RackTest driver works
0351f30 @r00k Fix typo.
r00k authored
251 directly against the Rack interface, it does not need any server to be started,
258ffc5 Grammatical error in README.md
Ra'Shaun Stovall authored
252 it can work directly against any Rack app. This means that if your
a00435d @jnicklas Added :headers option to rack_test driver, closes #328
authored
253 application is not a Rack application (Rails, Sinatra and most other Ruby
254 frameworks are Rack applications) then you cannot use this driver. You cannot
255 use the RackTest driver to test a remote application.
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
256 [capybara-mechanize](https://github.com/jeroenvandijk/capybara-mechanize)
a00435d @jnicklas Added :headers option to rack_test driver, closes #328
authored
257 intends to provide a similar driver which works against remote servers, it is a
258 separate project.
259
260 RackTest can be configured with a set of headers like this:
261
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
262 ```ruby
263 Capybara.register_driver :rack_test do |app|
264 Capybara::RackTest::Driver.new(app, :browser => :chrome)
265 end
266 ```
a00435d @jnicklas Added :headers option to rack_test driver, closes #328
authored
267
268 See the section on adding and configuring drivers.
269
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
270 ### Selenium
586ce21 @jnicklas Vastly improved README
authored
271
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
272 At the moment, Capybara supports [Selenium 2.0
273 (Webdriver)](http://seleniumhq.org/docs/01_introducing_selenium.html#selenium-2-aka-selenium-webdriver),
1fa8aee @joliss Better documentation for drivers
joliss authored
274 *not* Selenium RC. Provided Firefox is installed, everything is set up for you,
275 and you should be able to start using Selenium right away.
586ce21 @jnicklas Vastly improved README
authored
276
b4a7da0 Clarify new automatic reload behaviour
Jonas Nicklas and Kim Burgestrand authored
277 Capybara can block and wait for Ajax requests to finish after you've interacted
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
278 with the page. To enable this behaviour, set the `:resynchronize` driver
279 option to `true`. This should normally not be necessary, since
b4a7da0 Clarify new automatic reload behaviour
Jonas Nicklas and Kim Burgestrand authored
280 Capybara's automatic reloading should take care of any asynchronicity problems.
281 See the section on Asynchronous JavaScript for details.
021b87f Selenium driver automatically waits for AJAX requests to finish
Jonas Nicklas and Nicklas Ramhöj authored
282
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
283 **Note**: drivers which run the server in a different thread may not work share the
37ba641 @jnicklas Rewrite section on databases and transactions, closes #494
authored
284 same transaction as your tests, causing data not to be shared between your test
285 and test server, see "Transactions and database setup" below.
b7a460c @joliss added some preliminary documentation about transactional fixtures
joliss authored
286
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
287 ### Capybara-webkit
fe87359 Add capybara-webkit to the driver section
Adman65 authored
288
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
289 The [capybara-webkit driver](https://github.com/thoughtbot/capybara-webkit) is for true headless
8a153c6 @jc00ke Needs an 'r' & it's QtWebkit not WebkitQt.
jc00ke authored
290 testing. It uses QtWebKit to start a rendering engine process. It can execute JavaScript as well.
fe87359 Add capybara-webkit to the driver section
Adman65 authored
291 It is significantly faster than drivers like Selenium since it does not load an entire browser.
292
293 You can install it with:
294
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
295 ```bash
296 gem install capybara-webkit
297 ```
fe87359 Add capybara-webkit to the driver section
Adman65 authored
298
299 And you can use it by:
300
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
301 ```ruby
302 Capybara.javascript_driver = :webkit
303 ```
fe87359 Add capybara-webkit to the driver section
Adman65 authored
304
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
305 ## The DSL
586ce21 @jnicklas Vastly improved README
authored
306
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
307 *A complete reference is available at
308 [at rubydoc.info](http://rubydoc.info/github/jnicklas/capybara/master)*.
de76d8a @joliss Make README more terse and readable
joliss authored
309
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
310 **Note**: All searches in Capybara are *case sensitive*. This is because
de76d8a @joliss Make README more terse and readable
joliss authored
311 Capybara heavily uses XPath, which doesn't support case insensitivity.
fb71b29 @denro added documentation on the evaluate_script method
denro authored
312
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
313 ### Navigating
2f8c5e9 @jnicklas Improved README
authored
314
f5f444b @joliss Improve README
joliss authored
315 You can use the
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
316 [#visit](http://rubydoc.info/github/jnicklas/capybara/master/Capybara/Session#visit-instance_method)
f5f444b @joliss Improve README
joliss authored
317 method to navigate to other pages:
2f8c5e9 @jnicklas Improved README
authored
318
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
319 ```ruby
320 visit('/projects')
321 visit(post_comments_path(post))
322 ```
2f8c5e9 @jnicklas Improved README
authored
323
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
324 The visit method only takes a single parameter, the request method is **always**
2f8c5e9 @jnicklas Improved README
authored
325 GET.
326
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
327 You can get the [current path](http://rubydoc.info/github/jnicklas/capybara/master/Capybara/Session#current_path-instance_method)
f5f444b @joliss Improve README
joliss authored
328 of the browsing session for test assertions:
db16a19 Add current_path to dsl
Paul Elliott authored
329
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
330 ```ruby
331 current_path.should == post_comments_path(post)
332 ```
db16a19 Add current_path to dsl
Paul Elliott authored
333
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
334 ### Clicking links and buttons
2f8c5e9 @jnicklas Improved README
authored
335
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
336 *Full reference: [Capybara::Node::Actions](http://rubydoc.info/github/jnicklas/capybara/master/Capybara/Node/Actions)*
a0e5811 @joliss README and History housekeeping
joliss authored
337
2f8c5e9 @jnicklas Improved README
authored
338 You can interact with the webapp by following links and buttons. Capybara
339 automatically follows any redirects, and submits forms associated with buttons.
340
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
341 ```ruby
342 click_link('id-of-link')
343 click_link('Link Text')
344 click_button('Save')
345 click_on('Link Text') # clicks on either links or buttons
346 click_on('Button Value')
347 ```
2f8c5e9 @jnicklas Improved README
authored
348
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
349 ### Interacting with forms
2f8c5e9 @jnicklas Improved README
authored
350
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
351 *Full reference: [Capybara::Node::Actions](http://rubydoc.info/github/jnicklas/capybara/master/Capybara/Node/Actions)*
a0e5811 @joliss README and History housekeeping
joliss authored
352
353 There are a number of tools for interacting with form elements:
2f8c5e9 @jnicklas Improved README
authored
354
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
355 ```ruby
356 fill_in('First Name', :with => 'John')
357 fill_in('Password', :with => 'Seekrit')
358 fill_in('Description', :with => 'Really Long Text...')
359 choose('A Radio Button')
360 check('A Checkbox')
361 uncheck('A Checkbox')
362 attach_file('Image', '/path/to/image.jpg')
363 select('Option', :from => 'Select Box')
364 ```
2f8c5e9 @jnicklas Improved README
authored
365
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
366 ### Querying
2f8c5e9 @jnicklas Improved README
authored
367
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
368 *Full reference: [Capybara::Node::Matchers](http://rubydoc.info/github/jnicklas/capybara/master/Capybara/Node/Matchers)*
a0e5811 @joliss README and History housekeeping
joliss authored
369
2f8c5e9 @jnicklas Improved README
authored
370 Capybara has a rich set of options for querying the page for the existence of
a0e5811 @joliss README and History housekeeping
joliss authored
371 certain elements, and working with and manipulating those elements.
2f8c5e9 @jnicklas Improved README
authored
372
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
373 ```ruby
374 page.has_selector?('table tr')
375 page.has_selector?(:xpath, '//table/tr')
376 page.has_no_selector?(:content)
520a42a @jnicklas Added has_selector? method
authored
377
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
378 page.has_xpath?('//table/tr')
379 page.has_css?('table tr.foo')
bf748fd @joliss Refer to has_content rather than has_text for now
joliss authored
380 page.has_content?('foo')
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
381 ```
4305776 Update README adding explaination for using app_host to call remote w…
Joseph Wilk and Matt Wynne authored
382
7a856b7 @joliss Remove/update outdated README sections
joliss authored
383 **Note:** The negative forms like `has_no_selector?` are different from `not
384 has_selector?`. Read the section on asynchronous JavaScript for an explanation.
385
0466f37 @joliss Improve documentation on RSpec, Rails, and Rack in README.
joliss authored
386 You can use these with RSpec's magic matchers:
2f8c5e9 @jnicklas Improved README
authored
387
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
388 ```ruby
389 page.should have_selector('table tr')
390 page.should have_selector(:xpath, '//table/tr')
391 page.should have_no_selector(:content)
520a42a @jnicklas Added has_selector? method
authored
392
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
393 page.should have_xpath('//table/tr')
394 page.should have_css('table tr.foo')
bd87f75 @joliss Typo. Thanks @khustochka!
joliss authored
395 page.should have_content('foo')
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
396 ```
9fb05c9 @mkdynamic add has_text matcher based on Element#text
mkdynamic authored
397
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
398 ### Finding
970fd49 @jnicklas Explain new scoping behaviour in readme
authored
399
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
400 _Full reference: [Capybara::Node::Finders](http://rubydoc.info/github/jnicklas/capybara/master/Capybara/Node/Finders)_
a0e5811 @joliss README and History housekeeping
joliss authored
401
402 You can also find specific elements, in order to manipulate them:
2f8c5e9 @jnicklas Improved README
authored
403
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
404 ```ruby
405 find_field('First Name').value
406 find_link('Hello').visible?
407 find_button('Send').click
4305776 Update README adding explaination for using app_host to call remote w…
Joseph Wilk and Matt Wynne authored
408
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
409 find(:xpath, "//table/tr").click
410 find("#overlay").find("h1").click
411 all('a').each { |a| a[:href] }
412 ```
2f8c5e9 @jnicklas Improved README
authored
413
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
414 **Note**: `find` will wait for an element to appear on the page, as explained in the
a0e5811 @joliss README and History housekeeping
joliss authored
415 Ajax section. If the element does not appear it will raise an error.
322ecd3 @jnicklas Explain the difference between find and locate
authored
416
970fd49 @jnicklas Explain new scoping behaviour in readme
authored
417 These elements all have all the Capybara DSL methods available, so you can restrict them
418 to specific parts of the page:
419
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
420 ```ruby
421 find('#navigation').click_link('Home')
422 find('#navigation').should have_button('Sign out')
423 ```
970fd49 @jnicklas Explain new scoping behaviour in readme
authored
424
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
425 ### Scoping
970fd49 @jnicklas Explain new scoping behaviour in readme
authored
426
427 Capybara makes it possible to restrict certain actions, such as interacting with
428 forms or clicking links and buttons, to within a specific area of the page. For
f5f444b @joliss Improve README
joliss authored
429 this purpose you can use the generic
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
430 <tt>[within](http://rubydoc.info/github/jnicklas/capybara/master/Capybara/Session#within-instance_method)</tt>
f5f444b @joliss Improve README
joliss authored
431 method. Optionally you can specify which kind of selector to use.
970fd49 @jnicklas Explain new scoping behaviour in readme
authored
432
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
433 ```ruby
434 within("li#employee") do
435 fill_in 'Name', :with => 'Jimmy'
436 end
970fd49 @jnicklas Explain new scoping behaviour in readme
authored
437
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
438 within(:xpath, "//li[@id='employee']") do
439 fill_in 'Name', :with => 'Jimmy'
440 end
441 ```
970fd49 @jnicklas Explain new scoping behaviour in readme
authored
442
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
443 **Note**: `within` will scope the actions to the _first_ (not _any_) element that matches the selector.
e92ef27 @joliss Clarify in README that "within" scopes to the first element
joliss authored
444
970fd49 @jnicklas Explain new scoping behaviour in readme
authored
445 There are special methods for restricting the scope to a specific fieldset,
446 identified by either an id or the text of the fieldet's legend tag, and to a
447 specific table, identified by either id or text of the table's caption tag.
448
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
449 ```ruby
450 within_fieldset('Employee') do
451 fill_in 'Name', :with => 'Jimmy'
452 end
970fd49 @jnicklas Explain new scoping behaviour in readme
authored
453
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
454 within_table('Employee') do
455 fill_in 'Name', :with => 'Jimmy'
456 end
457 ```
970fd49 @jnicklas Explain new scoping behaviour in readme
authored
458
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
459 ### Scripting
2f8c5e9 @jnicklas Improved README
authored
460
7458357 @jnicklas Added separate execute_script method, closes #71
authored
461 In drivers which support it, you can easily execute JavaScript:
462
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
463 ```ruby
464 page.execute_script("$('body').empty()")
465 ```
7458357 @jnicklas Added separate execute_script method, closes #71
authored
466
467 For simple expressions, you can return the result of the script. Note
468 that this may break with more complicated expressions:
2f8c5e9 @jnicklas Improved README
authored
469
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
470 ```ruby
471 result = page.evaluate_script('4 + 4');
472 ```
2f8c5e9 @jnicklas Improved README
authored
473
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
474 ### Debugging
2f8c5e9 @jnicklas Improved README
authored
475
476 It can be useful to take a snapshot of the page as it currently is and take a
477 look at it:
586ce21 @jnicklas Vastly improved README
authored
478
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
479 ```ruby
480 save_and_open_page
481 ```
586ce21 @jnicklas Vastly improved README
authored
482
c4247f9 @joliss Advertise page.html in the Debugging section, not in the Querying sec…
joliss authored
483 You can also retrieve the current state of the DOM as a string using
484 <tt>[page.html](http://rubydoc.info/github/jnicklas/capybara/master/Capybara/Session#html-instance_method)</tt>.
485
486 ```ruby
487 print page.html
488 ```
489
490 This is mostly useful for debugging. You should avoid testing against the
491 contents of `page.html` and use the more expressive finder methods instead.
492
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
493 ## Transactions and database setup
b7a460c @joliss added some preliminary documentation about transactional fixtures
joliss authored
494
37ba641 @jnicklas Rewrite section on databases and transactions, closes #494
authored
495 Some Capybara drivers need to run against an actual HTTP server. Capybara takes
496 care of this and starts one for you in the same process as your test, but on
497 another thread. Selenium is one of those drivers, whereas RackTest is not.
498
499 If you are using an SQL database, it is common to run every test in a
500 transaction, which is rolled back at the end of the test, rspec-rails does this
501 by default out of the box for example. Since transactions are usually not
502 shared across threads, this will cause data you have put into the database in
503 your test code to be invisible to Capybara.
504
505 Cucumber handles this by using truncation instead of transactions, i.e. they
506 empty out the entire database after each test. You can get the same behaviour
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
507 by using a gem such as [database_cleaner](https://github.com/bmabey/database_cleaner).
37ba641 @jnicklas Rewrite section on databases and transactions, closes #494
authored
508
509 It is also possible to force your ORM to use the same transaction for all
510 threads. This may have thread safety implications and could cause strange
511 failures, so use caution with this approach. It can be implemented in
512 ActiveRecord through the following monkey patch:
513
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
514 ```ruby
515 class ActiveRecord::Base
516 mattr_accessor :shared_connection
517 @@shared_connection = nil
37ba641 @jnicklas Rewrite section on databases and transactions, closes #494
authored
518
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
519 def self.connection
520 @@shared_connection || retrieve_connection
521 end
522 end
523 ActiveRecord::Base.shared_connection = ActiveRecord::Base.connection
524 ```
b7a460c @joliss added some preliminary documentation about transactional fixtures
joliss authored
525
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
526 ## Asynchronous JavaScript (Ajax and friends)
4f2da02 @jnicklas Added a long note about asynchronous JS to README
authored
527
528 When working with asynchronous JavaScript, you might come across situations
529 where you are attempting to interact with an element which is not yet present
b4a7da0 Clarify new automatic reload behaviour
Jonas Nicklas and Kim Burgestrand authored
530 on the page. Capybara automatically deals with this by waiting for elements
4f2da02 @jnicklas Added a long note about asynchronous JS to README
authored
531 to appear on the page.
532
533 When issuing instructions to the DSL such as:
534
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
535 ```ruby
536 click_link('foo')
537 click_link('bar')
bf748fd @joliss Refer to has_content rather than has_text for now
joliss authored
538 page.should have_content('baz')
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
539 ```
4f2da02 @jnicklas Added a long note about asynchronous JS to README
authored
540
b4a7da0 Clarify new automatic reload behaviour
Jonas Nicklas and Kim Burgestrand authored
541 If clicking on the *foo* link triggers an asynchronous process, such as
a0e5811 @joliss README and History housekeeping
joliss authored
542 an Ajax request, which, when complete will add the *bar* link to the page,
76c8e8d @jmccartie Minor spelling typo fix
jmccartie authored
543 clicking on the *bar* link would be expected to fail, since that link doesn't
4f2da02 @jnicklas Added a long note about asynchronous JS to README
authored
544 exist yet. However Capybara is smart enought to retry finding the link for a
545 brief period of time before giving up and throwing an error. The same is true of
546 the next line, which looks for the content *baz* on the page; it will retry
547 looking for that content for a brief time. You can adjust how long this period
548 is (the default is 2 seconds):
549
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
550 ```ruby
551 Capybara.default_wait_time = 5
552 ```
4f2da02 @jnicklas Added a long note about asynchronous JS to README
authored
553
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
554 Be aware that because of this behaviour, the following two statements are **not**
555 equivalent, and you should **always** use the latter!
b5c20fb More clarification in the README
Adam McCrea authored
556
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
557 ```ruby
558 !page.has_xpath?('a')
559 page.has_no_xpath?('a')
560 ```
b5c20fb More clarification in the README
Adam McCrea authored
561
562 The former would immediately fail because the content has not yet been removed.
563 Only the latter would wait for the asynchronous process to remove the content
564 from the page.
565
566 Capybara's Rspec matchers, however, are smart enough to handle either form.
567 The two following statements are functionally equivalent:
568
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
569 ```ruby
570 page.should_not have_xpath('a')
571 page.should have_no_xpath('a')
572 ```
b5c20fb More clarification in the README
Adam McCrea authored
573
b4a7da0 Clarify new automatic reload behaviour
Jonas Nicklas and Kim Burgestrand authored
574 Capybara's waiting behaviour is quite advanced, and can deal with situations
575 such as the following line of code:
576
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
577 ```ruby
bf748fd @joliss Refer to has_content rather than has_text for now
joliss authored
578 find('#sidebar').find('h1').should have_content('Something')
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
579 ```
b4a7da0 Clarify new automatic reload behaviour
Jonas Nicklas and Kim Burgestrand authored
580
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
581 Even if JavaScript causes `#sidebar` to disappear off the page, Capybara
b4a7da0 Clarify new automatic reload behaviour
Jonas Nicklas and Kim Burgestrand authored
582 will automatically reload it and any elements it contains. So if an AJAX
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
583 request causes the contents of `#sidebar` to change, which would update
584 the text of the `h1` to "Something", and this happened, this test would
b4a7da0 Clarify new automatic reload behaviour
Jonas Nicklas and Kim Burgestrand authored
585 pass. If you do not want this behaviour, you can set
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
586 `Capybara.automatic_reload` to `false`.
b4a7da0 Clarify new automatic reload behaviour
Jonas Nicklas and Kim Burgestrand authored
587
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
588 ## Using the DSL in unsupported testing frameworks
586ce21 @jnicklas Vastly improved README
authored
589
5462955 @joliss Stop falsely advertising spec/acceptance, fix typos. Closes #483.
joliss authored
590 You can mix the DSL into any context by including <tt>Capybara::DSL</tt>:
8435d19 Initial checkin
Jonas Nicklas and Kevin Fitzpatrick authored
591
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
592 ```ruby
593 require 'capybara'
594 require 'capybara/dsl'
586ce21 @jnicklas Vastly improved README
authored
595
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
596 Capybara.default_driver = :webkit
e06e04e Some more info in README
Jonas Nicklas and Kevin Fitzpatrick authored
597
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
598 module MyModule
599 include Capybara::DSL
360088a @jnicklas don't suggest including Capybara in the global object, closes #63
authored
600
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
601 def login!
602 within("//form[@id='session']") do
603 fill_in 'Login', :with => 'user@example.com'
604 fill_in 'Password', :with => 'password'
e06e04e Some more info in README
Jonas Nicklas and Kevin Fitzpatrick authored
605 end
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
606 click_link 'Sign in'
607 end
608 end
609 ```
e06e04e Some more info in README
Jonas Nicklas and Kevin Fitzpatrick authored
610
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
611 ## Calling remote servers
4305776 Update README adding explaination for using app_host to call remote w…
Joseph Wilk and Matt Wynne authored
612
657b9c5 @jnicklas Some updates to README
authored
613 Normally Capybara expects to be testing an in-process Rack application, but you
614 can also use it to talk to a web server running anywhere on the internets, by
615 setting app_host:
4305776 Update README adding explaination for using app_host to call remote w…
Joseph Wilk and Matt Wynne authored
616
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
617 ```ruby
618 Capybara.current_driver = :selenium
619 Capybara.app_host = 'http://www.google.com'
620 ...
621 visit('/')
622 ```
4305776 Update README adding explaination for using app_host to call remote w…
Joseph Wilk and Matt Wynne authored
623
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
624 **Note**: the default driver (`:rack_test`) does not support running
a0e5811 @joliss README and History housekeeping
joliss authored
625 against a remote server. With drivers that support it, you can also visit any
626 URL directly:
5616235 @jnicklas More about remote servers in README
authored
627
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
628 ```ruby
629 visit('http://www.google.com')
630 ```
5616235 @jnicklas More about remote servers in README
authored
631
657b9c5 @jnicklas Some updates to README
authored
632 By default Capybara will try to boot a rack application automatically. You
633 might want to switch off Capybara's rack server if you are running against a
634 remote application:
5616235 @jnicklas More about remote servers in README
authored
635
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
636 ```ruby
637 Capybara.run_server = false
638 ```
5616235 @jnicklas More about remote servers in README
authored
639
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
640 ## Using the sessions manually
e06e04e Some more info in README
Jonas Nicklas and Kevin Fitzpatrick authored
641
a0e5811 @joliss README and History housekeeping
joliss authored
642 For ultimate control, you can instantiate and use a
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
643 [Session](http://rubydoc.info/github/jnicklas/capybara/master/Capybara/Session)
a0e5811 @joliss README and History housekeeping
joliss authored
644 manually.
e06e04e Some more info in README
Jonas Nicklas and Kevin Fitzpatrick authored
645
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
646 ```ruby
647 require 'capybara'
e06e04e Some more info in README
Jonas Nicklas and Kevin Fitzpatrick authored
648
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
649 session = Capybara::Session.new(:webkit, my_rack_app)
650 session.within("//form[@id='session']") do
651 session.fill_in 'Login', :with => 'user@example.com'
652 session.fill_in 'Password', :with => 'password'
653 end
654 session.click_link 'Sign in'
655 ```
e06e04e Some more info in README
Jonas Nicklas and Kevin Fitzpatrick authored
656
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
657 ## XPath, CSS and selectors
7313511 @jnicklas Added section about selectors to README
authored
658
659 Capybara does not try to guess what kind of selector you are going to give it,
f5f444b @joliss Improve README
joliss authored
660 and will always use CSS by default. If you want to use XPath, you'll need to
661 do:
fb71b29 @denro added documentation on the evaluate_script method
denro authored
662
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
663 ```ruby
664 within(:xpath, '//ul/li') { ... }
665 find(:xpath, '//ul/li').text
666 find(:xpath, '//li[contains(.//a[@href = "#"]/text(), "foo")]').value
667 ```
7313511 @jnicklas Added section about selectors to README
authored
668
59ba5d9 @jnicklas Update README, some really outdated stuff here :(
authored
669 Alternatively you can set the default selector to XPath:
7313511 @jnicklas Added section about selectors to README
authored
670
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
671 ```ruby
672 Capybara.default_selector = :xpath
673 find('//ul/li').text
674 ```
7313511 @jnicklas Added section about selectors to README
authored
675
fed2c5b @jnicklas Add section about custom selectors to README
authored
676 Capybara allows you to add custom selectors, which can be very useful if you
677 find yourself using the same kinds of selectors very often:
678
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
679 ```ruby
680 Capybara.add_selector(:id) do
681 xpath { |id| XPath.descendant[XPath.attr(:id) == id.to_s] }
682 end
b13e4d3 @jnicklas changed Selector API. Now more like RSpec matchers
authored
683
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
684 Capybara.add_selector(:row) do
685 xpath { |num| ".//tbody/tr[#{num}]" }
686 end
fed2c5b @jnicklas Add section about custom selectors to README
authored
687
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
688 Capybara.add_selector(:flash_type) do
689 css { |type| "#flash.#{type}" }
690 end
691 ```
455c051 @ordinaryzelig Add custom matcher css method like xpath.
ordinaryzelig authored
692
b13e4d3 @jnicklas changed Selector API. Now more like RSpec matchers
authored
693 The block given to xpath must always return an XPath expression as a String, or
694 an XPath expression generated through the XPath gem. You can now use these
695 selectors like this:
fed2c5b @jnicklas Add section about custom selectors to README
authored
696
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
697 ```ruby
698 find(:id, 'post_123')
699 find(:row, 3)
700 find(:flash_type, :notice)
701 ```
fed2c5b @jnicklas Add section about custom selectors to README
authored
702
b13e4d3 @jnicklas changed Selector API. Now more like RSpec matchers
authored
703 You can specify an optional match option which will automatically use the
704 selector if it matches the argument:
fed2c5b @jnicklas Add section about custom selectors to README
authored
705
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
706 ```ruby
707 Capybara.add_selector(:id) do
708 xpath { |id| XPath.descendant[XPath.attr(:id) == id.to_s] }
709 match { |value| value.is_a?(Symbol) }
710 end
711 ```
fed2c5b @jnicklas Add section about custom selectors to README
authored
712
713 Now use it like this:
714
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
715 ```ruby
716 find(:post_123)
717 ```
fed2c5b @jnicklas Add section about custom selectors to README
authored
718
719 This :id selector is already built into Capybara by default, so you don't
720 need to add it yourself.
721
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
722 ## Beware the XPath // trap
6c5935c @jnicklas Added a note about the XPath // confusion
authored
723
724 In XPath the expression // means something very specific, and it might not be what
725 you think. Contrary to common belief, // means "anywhere in the document" not "anywhere
726 in the current context". As an example:
727
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
728 ```ruby
729 page.find(:xpath, '//body').all(:xpath, '//script')
730 ```
6c5935c @jnicklas Added a note about the XPath // confusion
authored
731
732 You might expect this to find all script tags in the body, but actually, it finds all
733 script tags in the entire document, not only those in the body! What you're looking
734 for is the .// expression which means "any descendant of the current node":
735
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
736 ```ruby
737 page.find(:xpath, '//body').all(:xpath, './/script')
738 ```
0d76d06 @jnicklas Add note about within to // section of README
authored
739 The same thing goes for within:
740
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
741 ```ruby
742 within(:xpath, '//body') do
743 page.find(:xpath, './/script')
744 within(:xpath, './/table/tbody') do
745 ...
746 end
747 end
748 ```
0d76d06 @jnicklas Add note about within to // section of README
authored
749
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
750 ## Configuring and adding drivers
d536eea @jnicklas added section on configuring drivers to readme
authored
751
752 Capybara makes it convenient to switch between different drivers. It also exposes
753 an API to tweak those drivers with whatever settings you want, or to add your own
754 drivers. This is how to switch the selenium driver to use chrome:
755
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
756 ```ruby
757 Capybara.register_driver :selenium do |app|
758 Capybara::Selenium::Driver.new(app, :browser => :chrome)
759 end
760 ```
d536eea @jnicklas added section on configuring drivers to readme
authored
761
762 However, it's also possible to give this a different name, so tests can switch
763 between using different browsers effortlessly:
764
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
765 ```ruby
766 Capybara.register_driver :selenium_chrome do |app|
767 Capybara::Selenium::Driver.new(app, :browser => :chrome)
768 end
769 ```
d536eea @jnicklas added section on configuring drivers to readme
authored
770
771 Whatever is returned from the block should conform to the API described by
772 Capybara::Driver::Base, it does not however have to inherit from this class.
773 Gems can use this API to add their own drivers to Capybara.
774
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
775 The [Selenium wiki](http://code.google.com/p/selenium/wiki/RubyBindings) has
6a1a109 @jarib Add Selenium wiki link to the README.
jarib authored
776 additional info about how the underlying driver can be configured.
777
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
778 ## Gotchas:
e06e04e Some more info in README
Jonas Nicklas and Kevin Fitzpatrick authored
779
59ba5d9 @jnicklas Update README, some really outdated stuff here :(
authored
780 * Access to session and request is not possible from the test, Access to
781 response is limited. Some drivers allow access to response headers and HTTP
782 status code, but this kind of functionality is not provided by some drivers,
783 such as Selenium.
8435d19 Initial checkin
Jonas Nicklas and Kevin Fitzpatrick authored
784
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
785 * Access to Rails specific stuff (such as `controller`) is unavailable,
cd4198e Back to RDoc for Readme
Dennis Rogenius and Jonas Nicklas authored
786 since we're not using Rails' integration testing.
d2265a3 @jnicklas Readme is markdown instead
authored
787
7669134 @jnicklas Added note about time freezing in README
authored
788 * Freezing time: It's common practice to mock out the Time so that features
789 that depend on the current Date work as expected. This can be problematic,
a0e5811 @joliss README and History housekeeping
joliss authored
790 since Capybara's Ajax timing uses the system time, resulting in Capybara
7669134 @jnicklas Added note about time freezing in README
authored
791 never timing out and just hanging when a failure occurs. It's still possible to
1034c64 @rohit timecop is a gem not a plugin
rohit authored
792 use gems which allow you to travel in time, rather than freeze time.
793 One such gem is [Timecop](http://github.com/jtrupiano/timecop).
7669134 @jnicklas Added note about time freezing in README
authored
794
8c2a0d9 @trevorturk Document gotcha about visiting absolute URLs
trevorturk authored
795 * When using Rack::Test, beware if attempting to visit absolute URLs. For
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
796 example, a session might not be shared between visits to `posts_path`
797 and `posts_url`. If testing an absolute URL in an Action Mailer email,
798 set `default_url_options` to match the Rails default of
799 `www.example.com`.
8c2a0d9 @trevorturk Document gotcha about visiting absolute URLs
trevorturk authored
800
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
801 ## Development
015a7f9 @joliss Move Development section to the bottom
joliss authored
802
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
803 If you found a _reproducible_ bug, open a [GitHub
804 Issue](http://github.com/jnicklas/capybara/issues) to submit a bug report.
015a7f9 @joliss Move Development section to the bottom
joliss authored
805
806 Even better, send a pull request! Make sure all changes are well tested,
807 Capybara is a testing tool after all. Topic branches are good.
808
809 To set up a development environment, simply do:
810
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
811 ```bash
812 git submodule update --init
813 gem install bundler
814 bundle install
815 bundle exec rake # run the test suite
816 ```
Something went wrong with that request. Please try again.