Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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