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