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