Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 857 lines (641 sloc) 25.959 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 capabi…
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 Rai…
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 Rai…
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/capyba…
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/capyba…
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 capabi…
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 capabi…
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 capabi…
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 capabi…
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 Add current_path to dsl
Paul Elliott authored
363
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
364 ```ruby
365 current_path.should == post_comments_path(post)
366 ```
db16a19 Add current_path to dsl
Paul Elliott 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')
410 page.has_no_selector?(:content)
520a42a @jnicklas Added has_selector? method
authored
411
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
412 page.has_xpath?('//table/tr')
413 page.has_css?('table tr.foo')
bf748fd @joliss Refer to has_content rather than has_text for now
joliss authored
414 page.has_content?('foo')
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
415 ```
4305776 Update README adding explaination for using app_host to call remote w…
Joseph Wilk and Matt Wynne authored
416
7a856b7 @joliss Remove/update outdated README sections
joliss authored
417 **Note:** The negative forms like `has_no_selector?` are different from `not
418 has_selector?`. Read the section on asynchronous JavaScript for an explanation.
419
0466f37 @joliss Improve documentation on RSpec, Rails, and Rack in README.
joliss authored
420 You can use these with RSpec's magic matchers:
2f8c5e9 @jnicklas Improved README
authored
421
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
422 ```ruby
423 page.should have_selector('table tr')
424 page.should have_selector(:xpath, '//table/tr')
425 page.should have_no_selector(:content)
520a42a @jnicklas Added has_selector? method
authored
426
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
427 page.should have_xpath('//table/tr')
428 page.should have_css('table tr.foo')
bd87f75 @joliss Typo. Thanks @khustochka!
joliss authored
429 page.should have_content('foo')
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
430 ```
9fb05c9 @mkdynamic add has_text matcher based on Element#text
mkdynamic authored
431
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
432 ### Finding
970fd49 @jnicklas Explain new scoping behaviour in readme
authored
433
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
434 _Full reference: [Capybara::Node::Finders](http://rubydoc.info/github/jnicklas/capybara/master/Capybara/Node/Finders)_
a0e5811 @joliss README and History housekeeping
joliss authored
435
436 You can also find specific elements, in order to manipulate them:
2f8c5e9 @jnicklas Improved README
authored
437
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
438 ```ruby
439 find_field('First Name').value
440 find_link('Hello').visible?
441 find_button('Send').click
4305776 Update README adding explaination for using app_host to call remote w…
Joseph Wilk and Matt Wynne authored
442
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
443 find(:xpath, "//table/tr").click
444 find("#overlay").find("h1").click
445 all('a').each { |a| a[:href] }
446 ```
2f8c5e9 @jnicklas Improved README
authored
447
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
448 **Note**: `find` will wait for an element to appear on the page, as explained in the
a0e5811 @joliss README and History housekeeping
joliss authored
449 Ajax section. If the element does not appear it will raise an error.
322ecd3 @jnicklas Explain the difference between find and locate
authored
450
970fd49 @jnicklas Explain new scoping behaviour in readme
authored
451 These elements all have all the Capybara DSL methods available, so you can restrict them
452 to specific parts of the page:
453
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
454 ```ruby
455 find('#navigation').click_link('Home')
456 find('#navigation').should have_button('Sign out')
457 ```
970fd49 @jnicklas Explain new scoping behaviour in readme
authored
458
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
459 ### Scoping
970fd49 @jnicklas Explain new scoping behaviour in readme
authored
460
461 Capybara makes it possible to restrict certain actions, such as interacting with
462 forms or clicking links and buttons, to within a specific area of the page. For
f5f444b @joliss Improve README
joliss authored
463 this purpose you can use the generic
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
464 <tt>[within](http://rubydoc.info/github/jnicklas/capybara/master/Capybara/Session#within-instance_method)</tt>
f5f444b @joliss Improve README
joliss authored
465 method. Optionally you can specify which kind of selector to use.
970fd49 @jnicklas Explain new scoping behaviour in readme
authored
466
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
467 ```ruby
468 within("li#employee") do
469 fill_in 'Name', :with => 'Jimmy'
470 end
970fd49 @jnicklas Explain new scoping behaviour in readme
authored
471
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
472 within(:xpath, "//li[@id='employee']") do
473 fill_in 'Name', :with => 'Jimmy'
474 end
475 ```
970fd49 @jnicklas Explain new scoping behaviour in readme
authored
476
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
477 **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
478
970fd49 @jnicklas Explain new scoping behaviour in readme
authored
479 There are special methods for restricting the scope to a specific fieldset,
24a523a @Erkan-Yilmaz typos; delete doubled: at
Erkan-Yilmaz authored
480 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
481 specific table, identified by either id or text of the table's caption tag.
482
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
483 ```ruby
484 within_fieldset('Employee') do
485 fill_in 'Name', :with => 'Jimmy'
486 end
970fd49 @jnicklas Explain new scoping behaviour in readme
authored
487
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
488 within_table('Employee') do
489 fill_in 'Name', :with => 'Jimmy'
490 end
491 ```
970fd49 @jnicklas Explain new scoping behaviour in readme
authored
492
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
493 ### Scripting
2f8c5e9 @jnicklas Improved README
authored
494
7458357 @jnicklas Added separate execute_script method, closes #71
authored
495 In drivers which support it, you can easily execute JavaScript:
496
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
497 ```ruby
498 page.execute_script("$('body').empty()")
499 ```
7458357 @jnicklas Added separate execute_script method, closes #71
authored
500
501 For simple expressions, you can return the result of the script. Note
502 that this may break with more complicated expressions:
2f8c5e9 @jnicklas Improved README
authored
503
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
504 ```ruby
505 result = page.evaluate_script('4 + 4');
506 ```
2f8c5e9 @jnicklas Improved README
authored
507
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
508 ### Debugging
2f8c5e9 @jnicklas Improved README
authored
509
510 It can be useful to take a snapshot of the page as it currently is and take a
511 look at it:
586ce21 @jnicklas Vastly improved README
authored
512
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
513 ```ruby
514 save_and_open_page
515 ```
586ce21 @jnicklas Vastly improved README
authored
516
c4247f9 @joliss Advertise page.html in the Debugging section, not in the Querying sec…
joliss authored
517 You can also retrieve the current state of the DOM as a string using
518 <tt>[page.html](http://rubydoc.info/github/jnicklas/capybara/master/Capybara/Session#html-instance_method)</tt>.
519
520 ```ruby
521 print page.html
522 ```
523
524 This is mostly useful for debugging. You should avoid testing against the
525 contents of `page.html` and use the more expressive finder methods instead.
526
502aa85 @joliss Improve save_screenshot documentation
joliss authored
527 Finally, in drivers that support it, you can save a screenshot:
528
529 ```ruby
530 page.save_screenshot('screenshot.png')
531 ```
532
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
533 ## Transactions and database setup
b7a460c @joliss added some preliminary documentation about transactional fixtures
joliss authored
534
37ba641 @jnicklas Rewrite section on databases and transactions, closes #494
authored
535 Some Capybara drivers need to run against an actual HTTP server. Capybara takes
536 care of this and starts one for you in the same process as your test, but on
537 another thread. Selenium is one of those drivers, whereas RackTest is not.
538
24a523a @Erkan-Yilmaz typos; delete doubled: at
Erkan-Yilmaz authored
539 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
540 transaction, which is rolled back at the end of the test, rspec-rails does this
541 by default out of the box for example. Since transactions are usually not
542 shared across threads, this will cause data you have put into the database in
543 your test code to be invisible to Capybara.
544
545 Cucumber handles this by using truncation instead of transactions, i.e. they
546 empty out the entire database after each test. You can get the same behaviour
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
547 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
548
549 It is also possible to force your ORM to use the same transaction for all
550 threads. This may have thread safety implications and could cause strange
551 failures, so use caution with this approach. It can be implemented in
552 ActiveRecord through the following monkey patch:
553
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
554 ```ruby
555 class ActiveRecord::Base
556 mattr_accessor :shared_connection
557 @@shared_connection = nil
37ba641 @jnicklas Rewrite section on databases and transactions, closes #494
authored
558
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
559 def self.connection
560 @@shared_connection || retrieve_connection
561 end
562 end
563 ActiveRecord::Base.shared_connection = ActiveRecord::Base.connection
564 ```
b7a460c @joliss added some preliminary documentation about transactional fixtures
joliss authored
565
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
566 ## Asynchronous JavaScript (Ajax and friends)
4f2da02 @jnicklas Added a long note about asynchronous JS to README
authored
567
568 When working with asynchronous JavaScript, you might come across situations
569 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
570 on the page. Capybara automatically deals with this by waiting for elements
4f2da02 @jnicklas Added a long note about asynchronous JS to README
authored
571 to appear on the page.
572
573 When issuing instructions to the DSL such as:
574
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
575 ```ruby
576 click_link('foo')
577 click_link('bar')
bf748fd @joliss Refer to has_content rather than has_text for now
joliss authored
578 page.should have_content('baz')
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
579 ```
4f2da02 @jnicklas Added a long note about asynchronous JS to README
authored
580
b4a7da0 Clarify new automatic reload behaviour
Jonas Nicklas and Kim Burgestrand authored
581 If clicking on the *foo* link triggers an asynchronous process, such as
a0e5811 @joliss README and History housekeeping
joliss authored
582 an Ajax request, which, when complete will add the *bar* link to the page,
76c8e8d @jmccartie Minor spelling typo fix
jmccartie authored
583 clicking on the *bar* link would be expected to fail, since that link doesn't
4f2da02 @jnicklas Added a long note about asynchronous JS to README
authored
584 exist yet. However Capybara is smart enought to retry finding the link for a
585 brief period of time before giving up and throwing an error. The same is true of
586 the next line, which looks for the content *baz* on the page; it will retry
587 looking for that content for a brief time. You can adjust how long this period
588 is (the default is 2 seconds):
589
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
590 ```ruby
591 Capybara.default_wait_time = 5
592 ```
4f2da02 @jnicklas Added a long note about asynchronous JS to README
authored
593
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
594 Be aware that because of this behaviour, the following two statements are **not**
595 equivalent, and you should **always** use the latter!
b5c20fb More clarification in the README
Adam McCrea authored
596
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
597 ```ruby
598 !page.has_xpath?('a')
599 page.has_no_xpath?('a')
600 ```
b5c20fb More clarification in the README
Adam McCrea authored
601
602 The former would immediately fail because the content has not yet been removed.
603 Only the latter would wait for the asynchronous process to remove the content
604 from the page.
605
606 Capybara's Rspec matchers, however, are smart enough to handle either form.
607 The two following statements are functionally equivalent:
608
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
609 ```ruby
610 page.should_not have_xpath('a')
611 page.should have_no_xpath('a')
612 ```
b5c20fb More clarification in the README
Adam McCrea authored
613
b4a7da0 Clarify new automatic reload behaviour
Jonas Nicklas and Kim Burgestrand authored
614 Capybara's waiting behaviour is quite advanced, and can deal with situations
615 such as the following line of code:
616
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
617 ```ruby
bf748fd @joliss Refer to has_content rather than has_text for now
joliss authored
618 find('#sidebar').find('h1').should have_content('Something')
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
619 ```
b4a7da0 Clarify new automatic reload behaviour
Jonas Nicklas and Kim Burgestrand authored
620
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
621 Even if JavaScript causes `#sidebar` to disappear off the page, Capybara
b4a7da0 Clarify new automatic reload behaviour
Jonas Nicklas and Kim Burgestrand authored
622 will automatically reload it and any elements it contains. So if an AJAX
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
623 request causes the contents of `#sidebar` to change, which would update
624 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
625 pass. If you do not want this behaviour, you can set
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
626 `Capybara.automatic_reload` to `false`.
b4a7da0 Clarify new automatic reload behaviour
Jonas Nicklas and Kim Burgestrand authored
627
9031671 @nruth Highlight general-purpose nature of the DSL in the readme.
nruth authored
628 ## Using the DSL elsewhere
586ce21 @jnicklas Vastly improved README
authored
629
5462955 @joliss Stop falsely advertising spec/acceptance, fix typos. Closes #483.
joliss authored
630 You can mix the DSL into any context by including <tt>Capybara::DSL</tt>:
8435d19 Initial checkin
Jonas Nicklas and Kevin Fitzpatrick authored
631
9031671 @nruth Highlight general-purpose nature of the DSL in the readme.
nruth authored
632
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
633 ```ruby
634 require 'capybara'
635 require 'capybara/dsl'
586ce21 @jnicklas Vastly improved README
authored
636
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
637 Capybara.default_driver = :webkit
e06e04e Some more info in README
Jonas Nicklas and Kevin Fitzpatrick authored
638
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
639 module MyModule
640 include Capybara::DSL
360088a @jnicklas don't suggest including Capybara in the global object, closes #63
authored
641
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
642 def login!
643 within("//form[@id='session']") do
644 fill_in 'Login', :with => 'user@example.com'
645 fill_in 'Password', :with => 'password'
e06e04e Some more info in README
Jonas Nicklas and Kevin Fitzpatrick authored
646 end
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
647 click_link 'Sign in'
648 end
649 end
650 ```
e06e04e Some more info in README
Jonas Nicklas and Kevin Fitzpatrick authored
651
9031671 @nruth Highlight general-purpose nature of the DSL in the readme.
nruth authored
652 This enables its use in unsupported testing frameworks, and for general-purpose scripting.
653
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
654 ## Calling remote servers
4305776 Update README adding explaination for using app_host to call remote w…
Joseph Wilk and Matt Wynne authored
655
657b9c5 @jnicklas Some updates to README
authored
656 Normally Capybara expects to be testing an in-process Rack application, but you
657 can also use it to talk to a web server running anywhere on the internets, by
658 setting app_host:
4305776 Update README adding explaination for using app_host to call remote w…
Joseph Wilk and Matt Wynne authored
659
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
660 ```ruby
661 Capybara.current_driver = :selenium
662 Capybara.app_host = 'http://www.google.com'
663 ...
664 visit('/')
665 ```
4305776 Update README adding explaination for using app_host to call remote w…
Joseph Wilk and Matt Wynne authored
666
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
667 **Note**: the default driver (`:rack_test`) does not support running
a0e5811 @joliss README and History housekeeping
joliss authored
668 against a remote server. With drivers that support it, you can also visit any
669 URL directly:
5616235 @jnicklas More about remote servers in README
authored
670
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
671 ```ruby
672 visit('http://www.google.com')
673 ```
5616235 @jnicklas More about remote servers in README
authored
674
657b9c5 @jnicklas Some updates to README
authored
675 By default Capybara will try to boot a rack application automatically. You
676 might want to switch off Capybara's rack server if you are running against a
677 remote application:
5616235 @jnicklas More about remote servers in README
authored
678
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
679 ```ruby
680 Capybara.run_server = false
681 ```
5616235 @jnicklas More about remote servers in README
authored
682
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
683 ## Using the sessions manually
e06e04e Some more info in README
Jonas Nicklas and Kevin Fitzpatrick authored
684
a0e5811 @joliss README and History housekeeping
joliss authored
685 For ultimate control, you can instantiate and use a
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
686 [Session](http://rubydoc.info/github/jnicklas/capybara/master/Capybara/Session)
a0e5811 @joliss README and History housekeeping
joliss authored
687 manually.
e06e04e Some more info in README
Jonas Nicklas and Kevin Fitzpatrick authored
688
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
689 ```ruby
690 require 'capybara'
e06e04e Some more info in README
Jonas Nicklas and Kevin Fitzpatrick authored
691
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
692 session = Capybara::Session.new(:webkit, my_rack_app)
693 session.within("//form[@id='session']") do
694 session.fill_in 'Login', :with => 'user@example.com'
695 session.fill_in 'Password', :with => 'password'
696 end
697 session.click_link 'Sign in'
698 ```
e06e04e Some more info in README
Jonas Nicklas and Kevin Fitzpatrick authored
699
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
700 ## XPath, CSS and selectors
7313511 @jnicklas Added section about selectors to README
authored
701
702 Capybara does not try to guess what kind of selector you are going to give it,
f5f444b @joliss Improve README
joliss authored
703 and will always use CSS by default. If you want to use XPath, you'll need to
704 do:
fb71b29 @denro added documentation on the evaluate_script method
denro authored
705
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
706 ```ruby
707 within(:xpath, '//ul/li') { ... }
708 find(:xpath, '//ul/li').text
709 find(:xpath, '//li[contains(.//a[@href = "#"]/text(), "foo")]').value
710 ```
7313511 @jnicklas Added section about selectors to README
authored
711
59ba5d9 @jnicklas Update README, some really outdated stuff here :(
authored
712 Alternatively you can set the default selector to XPath:
7313511 @jnicklas Added section about selectors to README
authored
713
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
714 ```ruby
715 Capybara.default_selector = :xpath
716 find('//ul/li').text
717 ```
7313511 @jnicklas Added section about selectors to README
authored
718
fed2c5b @jnicklas Add section about custom selectors to README
authored
719 Capybara allows you to add custom selectors, which can be very useful if you
720 find yourself using the same kinds of selectors very often:
721
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
722 ```ruby
723 Capybara.add_selector(:id) do
724 xpath { |id| XPath.descendant[XPath.attr(:id) == id.to_s] }
725 end
b13e4d3 @jnicklas changed Selector API. Now more like RSpec matchers
authored
726
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
727 Capybara.add_selector(:row) do
728 xpath { |num| ".//tbody/tr[#{num}]" }
729 end
fed2c5b @jnicklas Add section about custom selectors to README
authored
730
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
731 Capybara.add_selector(:flash_type) do
732 css { |type| "#flash.#{type}" }
733 end
734 ```
455c051 @ordinaryzelig Add custom matcher css method like xpath.
ordinaryzelig authored
735
b13e4d3 @jnicklas changed Selector API. Now more like RSpec matchers
authored
736 The block given to xpath must always return an XPath expression as a String, or
737 an XPath expression generated through the XPath gem. You can now use these
738 selectors like this:
fed2c5b @jnicklas Add section about custom selectors to README
authored
739
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
740 ```ruby
741 find(:id, 'post_123')
742 find(:row, 3)
743 find(:flash_type, :notice)
744 ```
fed2c5b @jnicklas Add section about custom selectors to README
authored
745
b13e4d3 @jnicklas changed Selector API. Now more like RSpec matchers
authored
746 You can specify an optional match option which will automatically use the
747 selector if it matches the argument:
fed2c5b @jnicklas Add section about custom selectors to README
authored
748
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
749 ```ruby
750 Capybara.add_selector(:id) do
751 xpath { |id| XPath.descendant[XPath.attr(:id) == id.to_s] }
752 match { |value| value.is_a?(Symbol) }
753 end
754 ```
fed2c5b @jnicklas Add section about custom selectors to README
authored
755
756 Now use it like this:
757
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
758 ```ruby
759 find(:post_123)
760 ```
fed2c5b @jnicklas Add section about custom selectors to README
authored
761
762 This :id selector is already built into Capybara by default, so you don't
763 need to add it yourself.
764
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
765 ## Beware the XPath // trap
6c5935c @jnicklas Added a note about the XPath // confusion
authored
766
767 In XPath the expression // means something very specific, and it might not be what
768 you think. Contrary to common belief, // means "anywhere in the document" not "anywhere
769 in the current context". As an example:
770
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
771 ```ruby
772 page.find(:xpath, '//body').all(:xpath, '//script')
773 ```
6c5935c @jnicklas Added a note about the XPath // confusion
authored
774
775 You might expect this to find all script tags in the body, but actually, it finds all
776 script tags in the entire document, not only those in the body! What you're looking
777 for is the .// expression which means "any descendant of the current node":
778
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
779 ```ruby
780 page.find(:xpath, '//body').all(:xpath, './/script')
781 ```
0d76d06 @jnicklas Add note about within to // section of README
authored
782 The same thing goes for within:
783
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
784 ```ruby
785 within(:xpath, '//body') do
786 page.find(:xpath, './/script')
787 within(:xpath, './/table/tbody') do
788 ...
789 end
790 end
791 ```
0d76d06 @jnicklas Add note about within to // section of README
authored
792
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
793 ## Configuring and adding drivers
d536eea @jnicklas added section on configuring drivers to readme
authored
794
795 Capybara makes it convenient to switch between different drivers. It also exposes
796 an API to tweak those drivers with whatever settings you want, or to add your own
797 drivers. This is how to switch the selenium driver to use chrome:
798
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
799 ```ruby
800 Capybara.register_driver :selenium do |app|
801 Capybara::Selenium::Driver.new(app, :browser => :chrome)
802 end
803 ```
d536eea @jnicklas added section on configuring drivers to readme
authored
804
805 However, it's also possible to give this a different name, so tests can switch
806 between using different browsers effortlessly:
807
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
808 ```ruby
809 Capybara.register_driver :selenium_chrome do |app|
810 Capybara::Selenium::Driver.new(app, :browser => :chrome)
811 end
812 ```
d536eea @jnicklas added section on configuring drivers to readme
authored
813
814 Whatever is returned from the block should conform to the API described by
815 Capybara::Driver::Base, it does not however have to inherit from this class.
816 Gems can use this API to add their own drivers to Capybara.
817
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
818 The [Selenium wiki](http://code.google.com/p/selenium/wiki/RubyBindings) has
6a1a109 @jarib Add Selenium wiki link to the README.
jarib authored
819 additional info about how the underlying driver can be configured.
820
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
821 ## Gotchas:
e06e04e Some more info in README
Jonas Nicklas and Kevin Fitzpatrick authored
822
59ba5d9 @jnicklas Update README, some really outdated stuff here :(
authored
823 * Access to session and request is not possible from the test, Access to
824 response is limited. Some drivers allow access to response headers and HTTP
825 status code, but this kind of functionality is not provided by some drivers,
826 such as Selenium.
8435d19 Initial checkin
Jonas Nicklas and Kevin Fitzpatrick authored
827
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
828 * Access to Rails specific stuff (such as `controller`) is unavailable,
cd4198e Back to RDoc for Readme
Dennis Rogenius and Jonas Nicklas authored
829 since we're not using Rails' integration testing.
d2265a3 @jnicklas Readme is markdown instead
authored
830
7669134 @jnicklas Added note about time freezing in README
authored
831 * Freezing time: It's common practice to mock out the Time so that features
832 that depend on the current Date work as expected. This can be problematic,
a0e5811 @joliss README and History housekeeping
joliss authored
833 since Capybara's Ajax timing uses the system time, resulting in Capybara
7669134 @jnicklas Added note about time freezing in README
authored
834 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
835 use gems which allow you to travel in time, rather than freeze time.
ab754ab @jamie link to correct TimeCop repo
jamie authored
836 One such gem is [Timecop](http://github.com/travisjeffery/timecop).
7669134 @jnicklas Added note about time freezing in README
authored
837
8c2a0d9 @trevorturk Document gotcha about visiting absolute URLs
trevorturk authored
838 * When using Rack::Test, beware if attempting to visit absolute URLs. For
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
839 example, a session might not be shared between visits to `posts_path`
840 and `posts_url`. If testing an absolute URL in an Action Mailer email,
841 set `default_url_options` to match the Rails default of
842 `www.example.com`.
8c2a0d9 @trevorturk Document gotcha about visiting absolute URLs
trevorturk authored
843
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
844 ## Development
015a7f9 @joliss Move Development section to the bottom
joliss authored
845
846 To set up a development environment, simply do:
847
8f39e56 @gmile Update README with GF Markdown notion
gmile authored
848 ```bash
849 git submodule update --init
850 bundle install
851 bundle exec rake # run the test suite
852 ```
81d2ab3 @joliss Link CONTRIBUTING.md from README
joliss authored
853
854 See
855 [CONTRIBUTING.md](https://github.com/jnicklas/capybara/blob/master/CONTRIBUTING.md)
856 for how to send issues and pull requests.
Something went wrong with that request. Please try again.