Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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