Skip to content

HTTPS clone URL

Subversion checkout URL

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