Skip to content

HTTPS clone URL

Subversion checkout URL

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