Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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