Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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