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