nimboids-capybara 1.1.2
Sign up to get free protection for your applications and to get access to all the features.
- data/History.txt +289 -0
- data/README.rdoc +722 -0
- data/lib/capybara.rb +252 -0
- data/lib/capybara/cucumber.rb +28 -0
- data/lib/capybara/driver/base.rb +64 -0
- data/lib/capybara/driver/node.rb +74 -0
- data/lib/capybara/dsl.rb +168 -0
- data/lib/capybara/node/actions.rb +162 -0
- data/lib/capybara/node/base.rb +63 -0
- data/lib/capybara/node/document.rb +25 -0
- data/lib/capybara/node/element.rb +201 -0
- data/lib/capybara/node/finders.rb +197 -0
- data/lib/capybara/node/matchers.rb +417 -0
- data/lib/capybara/node/simple.rb +132 -0
- data/lib/capybara/rack_test/browser.rb +121 -0
- data/lib/capybara/rack_test/driver.rb +80 -0
- data/lib/capybara/rack_test/form.rb +80 -0
- data/lib/capybara/rack_test/node.rb +105 -0
- data/lib/capybara/rails.rb +17 -0
- data/lib/capybara/rspec.rb +26 -0
- data/lib/capybara/rspec/features.rb +22 -0
- data/lib/capybara/rspec/matchers.rb +154 -0
- data/lib/capybara/selector.rb +89 -0
- data/lib/capybara/selenium/driver.rb +163 -0
- data/lib/capybara/selenium/node.rb +91 -0
- data/lib/capybara/server.rb +90 -0
- data/lib/capybara/session.rb +321 -0
- data/lib/capybara/spec/driver.rb +301 -0
- data/lib/capybara/spec/fixtures/capybara.jpg +3 -0
- data/lib/capybara/spec/fixtures/test_file.txt +1 -0
- data/lib/capybara/spec/public/test.js +43 -0
- data/lib/capybara/spec/session.rb +154 -0
- data/lib/capybara/spec/session/all_spec.rb +78 -0
- data/lib/capybara/spec/session/attach_file_spec.rb +73 -0
- data/lib/capybara/spec/session/check_spec.rb +65 -0
- data/lib/capybara/spec/session/choose_spec.rb +26 -0
- data/lib/capybara/spec/session/click_button_spec.rb +304 -0
- data/lib/capybara/spec/session/click_link_or_button_spec.rb +36 -0
- data/lib/capybara/spec/session/click_link_spec.rb +119 -0
- data/lib/capybara/spec/session/current_host_spec.rb +68 -0
- data/lib/capybara/spec/session/current_url_spec.rb +15 -0
- data/lib/capybara/spec/session/fill_in_spec.rb +125 -0
- data/lib/capybara/spec/session/find_button_spec.rb +18 -0
- data/lib/capybara/spec/session/find_by_id_spec.rb +18 -0
- data/lib/capybara/spec/session/find_field_spec.rb +26 -0
- data/lib/capybara/spec/session/find_link_spec.rb +19 -0
- data/lib/capybara/spec/session/find_spec.rb +149 -0
- data/lib/capybara/spec/session/first_spec.rb +105 -0
- data/lib/capybara/spec/session/has_button_spec.rb +32 -0
- data/lib/capybara/spec/session/has_content_spec.rb +106 -0
- data/lib/capybara/spec/session/has_css_spec.rb +243 -0
- data/lib/capybara/spec/session/has_field_spec.rb +192 -0
- data/lib/capybara/spec/session/has_link_spec.rb +37 -0
- data/lib/capybara/spec/session/has_select_spec.rb +129 -0
- data/lib/capybara/spec/session/has_selector_spec.rb +129 -0
- data/lib/capybara/spec/session/has_table_spec.rb +96 -0
- data/lib/capybara/spec/session/has_xpath_spec.rb +123 -0
- data/lib/capybara/spec/session/headers.rb +19 -0
- data/lib/capybara/spec/session/javascript.rb +289 -0
- data/lib/capybara/spec/session/response_code.rb +19 -0
- data/lib/capybara/spec/session/select_spec.rb +113 -0
- data/lib/capybara/spec/session/text_spec.rb +19 -0
- data/lib/capybara/spec/session/uncheck_spec.rb +21 -0
- data/lib/capybara/spec/session/unselect_spec.rb +61 -0
- data/lib/capybara/spec/session/within_spec.rb +178 -0
- data/lib/capybara/spec/test_app.rb +142 -0
- data/lib/capybara/spec/views/buttons.erb +4 -0
- data/lib/capybara/spec/views/fieldsets.erb +29 -0
- data/lib/capybara/spec/views/form.erb +365 -0
- data/lib/capybara/spec/views/frame_one.erb +8 -0
- data/lib/capybara/spec/views/frame_two.erb +8 -0
- data/lib/capybara/spec/views/header_links.erb +7 -0
- data/lib/capybara/spec/views/host_links.erb +12 -0
- data/lib/capybara/spec/views/popup_one.erb +8 -0
- data/lib/capybara/spec/views/popup_two.erb +8 -0
- data/lib/capybara/spec/views/postback.erb +13 -0
- data/lib/capybara/spec/views/tables.erb +122 -0
- data/lib/capybara/spec/views/with_html.erb +78 -0
- data/lib/capybara/spec/views/with_html_entities.erb +1 -0
- data/lib/capybara/spec/views/with_js.erb +48 -0
- data/lib/capybara/spec/views/with_scope.erb +36 -0
- data/lib/capybara/spec/views/with_simple_html.erb +1 -0
- data/lib/capybara/spec/views/within_frames.erb +10 -0
- data/lib/capybara/spec/views/within_popups.erb +25 -0
- data/lib/capybara/util/save_and_open_page.rb +44 -0
- data/lib/capybara/util/timeout.rb +27 -0
- data/lib/capybara/version.rb +3 -0
- data/spec/basic_node_spec.rb +77 -0
- data/spec/capybara_spec.rb +46 -0
- data/spec/driver/rack_test_driver_spec.rb +89 -0
- data/spec/driver/selenium_driver_spec.rb +50 -0
- data/spec/dsl_spec.rb +253 -0
- data/spec/fixtures/selenium_driver_rspec_failure.rb +8 -0
- data/spec/fixtures/selenium_driver_rspec_success.rb +8 -0
- data/spec/rspec/features_spec.rb +45 -0
- data/spec/rspec/matchers_spec.rb +495 -0
- data/spec/rspec_spec.rb +53 -0
- data/spec/save_and_open_page_spec.rb +155 -0
- data/spec/server_spec.rb +89 -0
- data/spec/session/rack_test_session_spec.rb +55 -0
- data/spec/session/selenium_session_spec.rb +26 -0
- data/spec/spec_helper.rb +30 -0
- data/spec/string_spec.rb +77 -0
- data/spec/timeout_spec.rb +28 -0
- metadata +346 -0
data/History.txt
ADDED
@@ -0,0 +1,289 @@
|
|
1
|
+
# Version 1.1.0
|
2
|
+
|
3
|
+
Release date: 2011-09-02
|
4
|
+
|
5
|
+
### Fixed
|
6
|
+
|
7
|
+
* Sensible inspect for Capybara::Session [Jo Liss]
|
8
|
+
* Fix headers and host on redirect [Matt Colyer, Jonas Nicklas, Kim Burgestrand]
|
9
|
+
* using_driver now restores the old driver instead of reverting to the default [Carol Nichols]
|
10
|
+
* Errors when following links relative to the root path under rack-test [Jonas Nicklas, Kim Burgestrand]
|
11
|
+
* Make sure exit codes are propagated properly [Edgar Beigarts]
|
12
|
+
|
13
|
+
### Changed
|
14
|
+
|
15
|
+
* resynchronization is off by default under Selenium
|
16
|
+
|
17
|
+
### Added
|
18
|
+
|
19
|
+
* Elements are automatically reloaded (including parents) during wait [Jonas Nicklas]
|
20
|
+
* Rescue driver specific element errors, such as the dreaded ObsoleteElementError and retry [Jonas Nicklas]
|
21
|
+
* Raise an error if something has frozen time [Jonas Nicklas]
|
22
|
+
* Allow within to take a node instead of a selector [Peter Williams]
|
23
|
+
* Using wait_time_time to change wait time for a block of code [Jonas Nicklas, Kim Burgestrand]
|
24
|
+
* Option for rack-test driver to disable data-method hack [Jonas Nicklas, Kim Burgestrand]
|
25
|
+
|
26
|
+
# Version 1.0.1
|
27
|
+
|
28
|
+
Release date: 2011-08-12
|
29
|
+
|
30
|
+
### Fixed
|
31
|
+
|
32
|
+
* Dependend on selenium-webdriver ~>2.0 and fix deprecations [Thomas Walpole, Jo Liss]
|
33
|
+
* Depend on Launch 2.0 [Jeremy Hinegardner]
|
34
|
+
* Rack-Test ignores fill in on fields with maxlength=""
|
35
|
+
|
36
|
+
# Version 1.0.0
|
37
|
+
|
38
|
+
Release date: 2011-06-14
|
39
|
+
|
40
|
+
### Added
|
41
|
+
|
42
|
+
* Added DSL for acceptance tests, inspired by Luismi Cavallé's Steak [Luismi Cavalle and Jonas Nicklas]
|
43
|
+
* Selenium driver automatically waits for AJAX requests to finish [mgiambalvo, Nicklas Ramhöj and Jonas Nicklas]
|
44
|
+
* Support for switching between multiple named sessions [Tristan Dunn]
|
45
|
+
* failure_message can be specified for Selectors [Jonas Nicklas]
|
46
|
+
* RSpec matchers [David Chelimsky and Jonas Nicklas]
|
47
|
+
* Added save_page to save tempfile without opening in browser [Jeff Kreeftmeijer]
|
48
|
+
* Cucumber now switches automatically to a registered driver if the tag matches the name [Jonas Nicklas]
|
49
|
+
* Added Session#text [Jonas Nicklas and Scott Cytacki]
|
50
|
+
* Added Session#html as an alias for Session#body [Jo Liss]
|
51
|
+
* Added Session#current_host method [Jonas Nicklas]
|
52
|
+
* Buttons can now be clicked by title [Javier Martin]
|
53
|
+
* :headers option for RackTest driver to set custom HTTP headers [Jonas Nicklas]
|
54
|
+
|
55
|
+
### Removed
|
56
|
+
|
57
|
+
* Culerity and Celerity drivers have been removed and split into separate gems [Gabriel Sobrinho]
|
58
|
+
|
59
|
+
### Deprecated
|
60
|
+
|
61
|
+
* `include Capybara` has been deprecated in favour of `include Capybara::DSL` [Jonas Nicklas]
|
62
|
+
|
63
|
+
### Changed
|
64
|
+
|
65
|
+
* Rack test driver class has been renamed from Capybara::Driver::RackTest to Capybara::RackTest::Driver [Jonas Nicklas]
|
66
|
+
* Selenium driver class has been renamed from Capybara::Driver::Selenium to Capybara::Selenium::Driver [Jonas Nicklas]
|
67
|
+
* Capybara now prefers visible elements over hidden elements, disable by setting Capybara.prefer_visible_elements = false [Jonas Nicklas and Nicklas Ramhöj]
|
68
|
+
* For RSpec, :type => :request is now supported (and preferred over :acceptance) [Jo Liss]
|
69
|
+
* Selenium driver tried to wait for AJAX requests to finish before proceeding [Jonas Nicklas and Nicklas Ramhöj]
|
70
|
+
* Session no longer uses method missing, uses explicit delegates instead [Jonas Nicklas]
|
71
|
+
|
72
|
+
### Fixed
|
73
|
+
|
74
|
+
* The Rack::Test driver now respects maxlength on text fields [Guilherme Carvalho]
|
75
|
+
* Allow for more than one save_and_open_page call per second [Jo Liss]
|
76
|
+
* Automatically convert options to :count, :minimum, :maximum, etc. to integers [Keith Marcum]
|
77
|
+
* Rack::Test driver honours maxlength on input fields [Guilherme Carvalho]
|
78
|
+
* Rack::Test now works as expected with domains and subdomains [Jonas Nicklas]
|
79
|
+
* Session is reset more thoroughly between tests. [Jonas Nicklas]
|
80
|
+
* Raise error when uploading non-existant file [Jonas Nicklas]
|
81
|
+
* Rack reponse body should respond to #each [Piotr Sarnacki]
|
82
|
+
* Deprecation warnings with selenium webdriver 0.2.0 [Aaron Gibraltar]
|
83
|
+
* Selenium Chrome no longer YELLS tagname [Carl Jackson & David W. Frank]
|
84
|
+
* Capybara no longer strips encoding before sending to Rack [Jonas Nicklas]
|
85
|
+
* Improve handling of relative URLs [John Barton]
|
86
|
+
* Readd and fix build_rack_mock_session [Jonas Nicklas, Jon Leighton]
|
87
|
+
|
88
|
+
# Version 0.4.1
|
89
|
+
|
90
|
+
Release date: 2011-01-21
|
91
|
+
|
92
|
+
### Added
|
93
|
+
|
94
|
+
* New click_on alias for click_link_or_button, shorter yet unambiguous. [Jonas Nicklas]
|
95
|
+
* Finders now accept :visible => false which will find all elements regardless of Capybara.ignore_hidden_elements [Jonas Nicklas]
|
96
|
+
* Configure how the server is started via Capybara.server { |app, port| ... }. [John Firebough]
|
97
|
+
* Added :between, :maximum and :minimum options to has_selector and friends [James B. Byrne]
|
98
|
+
* New Capybara.string util function which allows matchers on arbitrary strings, mostly for helper and view specs [David Chelimsky and Jonas Nicklas]
|
99
|
+
* Server boot timeout is now configurable, via Capybara.server_boot_timeout [Adam Cigánek]
|
100
|
+
* Built in support for RSpec [Jonas Nicklas]
|
101
|
+
* Capybara.using_driver to switch to a different driver temporarily [Jeff Kreeftmeijer]
|
102
|
+
* Added Session#first which is somewhat speedier than Session#all, use it internally for speed boost [John Firebaugh]
|
103
|
+
|
104
|
+
### Changed
|
105
|
+
|
106
|
+
* Session#within now accepts the same arguments as other finders, like Session#all and Session#find [Jonas Nicklas]
|
107
|
+
|
108
|
+
### Removed
|
109
|
+
|
110
|
+
* All deprecations from 0.4.0 have been removed. [Jonas Nicklas]
|
111
|
+
|
112
|
+
### Fixed
|
113
|
+
|
114
|
+
* Don't mangle URLs in save_and_open_page when using self-closing tags [Adam Spiers]
|
115
|
+
* Catch correct error when server boot times out [Jonas Nicklas]
|
116
|
+
* Celerity driver now properly passes through options, making it configurable [Jonas Nicklas]
|
117
|
+
* Better implementation of attributes in C[ue]lerity, should fix issues with attributes with strange names [Jonas Nicklas]
|
118
|
+
* Session#find no longer swallows errors [Jonas Nicklas]
|
119
|
+
* Fix problems with multiple file inputs [Philip Arndt]
|
120
|
+
* Submit multipart forms as multipart under rack-test even if they contain no files [Ryan Kinderman]
|
121
|
+
* Matchers like has_select? and has_checked_field? now work with dynamically changed values [John Firebaugh]
|
122
|
+
* Preserve order of rack params [Joel Chippindale]
|
123
|
+
* RackTest#reset! is more thorough [Joel Chippindale]
|
124
|
+
|
125
|
+
# Version 0.4.0
|
126
|
+
|
127
|
+
Release date: 2010-10-22
|
128
|
+
|
129
|
+
### Changed
|
130
|
+
|
131
|
+
* The Selector API was changed slightly, use Capybara.add_selector, see README
|
132
|
+
|
133
|
+
### Fixed
|
134
|
+
|
135
|
+
* Celerity driver is registered properly
|
136
|
+
* has_selector? and has_no_selector? added to DSL
|
137
|
+
* Multiple selects return correct values under C[cu]lerity
|
138
|
+
* Naked query strings are handled correctly by rack-test
|
139
|
+
|
140
|
+
# Version 0.4.0.rc
|
141
|
+
|
142
|
+
Release date: 2010-10-12
|
143
|
+
|
144
|
+
### Changed
|
145
|
+
|
146
|
+
* within and find/locate now follow the XPath spec in that //foo finds all nodes in the document, instead of
|
147
|
+
only for the context node. See this post for details: http://groups.google.com/group/ruby-capybara/browse_thread/thread/b129067979df21b3
|
148
|
+
* within now executes within the first found instance of the selector, not in all of them
|
149
|
+
* find now waits for AJAX requests and raises an exception when the element is not found (same as locate used to do)
|
150
|
+
* The default selector is now CSS, not XPath
|
151
|
+
|
152
|
+
### Deprecated
|
153
|
+
|
154
|
+
* Session#click has been renamed click_link_or_button and the old click has been deprecated
|
155
|
+
* Node#node has been renamed native
|
156
|
+
* Node#locate is deprecated in favor of Node#find, which now behaves identically
|
157
|
+
* Session#drag is deprecated, please use Node#drag_to(other_node) instead
|
158
|
+
|
159
|
+
### Added
|
160
|
+
|
161
|
+
* Pretty much everything is properly documented now
|
162
|
+
* It's now possible to call all session methods on nodes, like `find('#foo').fill_in(...)`
|
163
|
+
* Custom selectors can be added with Capybara::Selector.add
|
164
|
+
* The :id selector is added by default, use it lile `find(:id, 'foo')` or `find(:foo)`
|
165
|
+
* Added Node#has_selector? so any kind of selector can be queried.
|
166
|
+
* Added Capybara.configure for less wordy configuration
|
167
|
+
* Added within_window to switch between different windows (currently Selenium only)
|
168
|
+
* Capybara.server_port to provide a fixed port if wanted (defaults to automatic selection)
|
169
|
+
|
170
|
+
### Fixed
|
171
|
+
|
172
|
+
* CSS selectors with multiple selectors, such as "h1, h2" now work correctly
|
173
|
+
* Port is automatically assigned instead of guessing
|
174
|
+
* Strip encodings in rack-test, no more warnings!
|
175
|
+
* RackTest no longer submits disabled fields
|
176
|
+
* Servers no longer output annoying debug information when started
|
177
|
+
* TCP port selection is left to Ruby to decide, no more port guessing
|
178
|
+
* Select boxes now return option value instead of text if present
|
179
|
+
* The default has been changed from localhost to 127.0.0.1, should fix some obscure selenium bugs
|
180
|
+
* RackTest now supports complex field names, such as foo[bar][][baz]
|
181
|
+
|
182
|
+
# Version 0.3.9
|
183
|
+
|
184
|
+
Release date: 2010-07-03
|
185
|
+
|
186
|
+
### Added
|
187
|
+
|
188
|
+
* status_code which returns the HTTP status code of the last response (no Selenium!)
|
189
|
+
* Capybara.save_and_open_page to store tempfiles
|
190
|
+
* RackTest and Culerity drivers now clean up after themselves properly
|
191
|
+
|
192
|
+
### Fixed
|
193
|
+
|
194
|
+
* When no rack app is set and the app is called, a more descriptive error is raised
|
195
|
+
* select now works with optgroups
|
196
|
+
* Don't submit image buttons unless they were clicked under rack-test
|
197
|
+
* Support custom field types under Selenium
|
198
|
+
* Support input fields without a type, treat them as though they were text fields
|
199
|
+
* Redirect now throws an error after 5 redirects, as per RFC
|
200
|
+
* Selenium now properly raises an error when Node#trigger is called
|
201
|
+
* Node#value now returns the correct value for textareas under rack-test
|
202
|
+
|
203
|
+
# Version 0.3.8
|
204
|
+
|
205
|
+
Release date: 2010-05-12
|
206
|
+
|
207
|
+
### Added
|
208
|
+
|
209
|
+
* Within_frame method to execute a block of code within a particular iframe (Selenium only!)
|
210
|
+
|
211
|
+
### Fixed
|
212
|
+
|
213
|
+
* Single quotes are properly escaped with `select` under rack-test and Selenium.
|
214
|
+
* The :text option for searches now escapes regexp special characters when a string is given.
|
215
|
+
* Selenium now correctly checks already checked checkboxes (same with uncheck)
|
216
|
+
* Timing issue which caused Selenium to hang under certain circumstances.
|
217
|
+
* Selenium now resolves attributes even if they are given as a Symbol
|
218
|
+
|
219
|
+
# Version 0.3.7
|
220
|
+
|
221
|
+
Release date: 2010-04-09
|
222
|
+
|
223
|
+
This is a drop in compatible maintainance release. It's mostly
|
224
|
+
important for driver authors.
|
225
|
+
|
226
|
+
### Added
|
227
|
+
|
228
|
+
* RackTest scans for data-method which rails3 uses to change the request method
|
229
|
+
|
230
|
+
### Fixed
|
231
|
+
|
232
|
+
* Don't hang when starting server on Windoze
|
233
|
+
|
234
|
+
### Changed
|
235
|
+
|
236
|
+
* The driver and session specs are now located inside lib! Driver authors can simply require them.
|
237
|
+
|
238
|
+
# Version 0.3.6
|
239
|
+
|
240
|
+
Release date: 2010-03-22
|
241
|
+
|
242
|
+
This is a maintainance release with minor bug fixes, should be
|
243
|
+
drop in compatible.
|
244
|
+
|
245
|
+
### Added
|
246
|
+
|
247
|
+
* It's now possible to load in external drivers
|
248
|
+
|
249
|
+
### Fixed
|
250
|
+
|
251
|
+
* has_content? ignores whitespace
|
252
|
+
* Trigger events when choosing radios and checking checkboxes under Selenium
|
253
|
+
* Make Capybara.app totally optional when running without server
|
254
|
+
* Changed fallback host so it matches the one set up by Rails' integration tests
|
255
|
+
|
256
|
+
# Version 0.3.5
|
257
|
+
|
258
|
+
Release date: 2010-02-26
|
259
|
+
|
260
|
+
This is a mostly backwards compatible release, it does break
|
261
|
+
the API in some minor places, which should hopefully not affect
|
262
|
+
too many users, please read the release notes carefully!
|
263
|
+
|
264
|
+
### Breaking
|
265
|
+
|
266
|
+
* Relative searching in a node (e.g. find('//p').all('//a')) will now follow XPath standard
|
267
|
+
this means that if you want to find descendant nodes only, you'll need to prefix a dot!
|
268
|
+
* `visit` now accepts fully qualified URLs for drivers that support it.
|
269
|
+
* Capybara will always try to run a rack server, unless you set Capybara.run_sever = false
|
270
|
+
|
271
|
+
### Changed
|
272
|
+
|
273
|
+
* thin is preferred over mongrel and webrick, since it is Ruby 1.9 compatible
|
274
|
+
* click_button and click will find <input type="button">, clicking them does nothing in RackTest
|
275
|
+
|
276
|
+
### Added
|
277
|
+
|
278
|
+
* Much improved error messages in a multitude of places
|
279
|
+
* More semantic page querying with has_link?, has_button?, etc...
|
280
|
+
* Option to ignore hidden elements when querying and interacting with the page
|
281
|
+
* Support for multiple selects
|
282
|
+
|
283
|
+
### Fixed
|
284
|
+
|
285
|
+
* find_by_id is no longer broken
|
286
|
+
* clicking links where the image's alt attribute contains the text is now possible
|
287
|
+
* within_fieldset and within_table work when the default selector is CSS
|
288
|
+
* boolean attributes work the same across drivers (return true/false)
|
289
|
+
|
data/README.rdoc
ADDED
@@ -0,0 +1,722 @@
|
|
1
|
+
= Capybara
|
2
|
+
|
3
|
+
* http://github.com/jnicklas/capybara
|
4
|
+
|
5
|
+
== Description:
|
6
|
+
|
7
|
+
Capybara aims to simplify the process of integration testing Rack applications,
|
8
|
+
such as Rails, Sinatra or Merb. Capybara simulates how a real user would
|
9
|
+
interact with a web application. It is agnostic about the driver running your
|
10
|
+
tests and currently comes with Rack::Test and Selenium support built in.
|
11
|
+
HtmlUnit, WebKit and env.js are supported through external gems.
|
12
|
+
|
13
|
+
A complete reference is available at
|
14
|
+
{at rubydoc.info}[http://rubydoc.info/github/jnicklas/capybara/master].
|
15
|
+
|
16
|
+
== Install:
|
17
|
+
|
18
|
+
Install as a gem:
|
19
|
+
|
20
|
+
sudo gem install capybara
|
21
|
+
|
22
|
+
On OSX you may have to install libffi, you can install it via MacPorts with:
|
23
|
+
|
24
|
+
sudo port install libffi
|
25
|
+
|
26
|
+
== Development:
|
27
|
+
|
28
|
+
* Source hosted at {GitHub}[http://github.com/jnicklas/capybara].
|
29
|
+
* Please direct questions, discussion or problems to the {mailing list}[http://groups.google.com/group/ruby-capybara].
|
30
|
+
* If you found a reproducible bug, open a {GitHub Issue}[http://github.com/jnicklas/capybara/issues] to submit a bug report.
|
31
|
+
|
32
|
+
Pull requests are very welcome (and even better than bug reports)! Make sure
|
33
|
+
your patches are well tested, Capybara is a testing tool after all. Please
|
34
|
+
create a topic branch for every separate change you make.
|
35
|
+
|
36
|
+
Capybara uses bundler in development. To set up a development environment, simply do:
|
37
|
+
|
38
|
+
git submodule update --init
|
39
|
+
gem install bundler
|
40
|
+
bundle install
|
41
|
+
|
42
|
+
== Using Capybara with Cucumber
|
43
|
+
|
44
|
+
Capybara is built to work nicely with Cucumber. Support for Capybara is built into
|
45
|
+
cucumber-rails. In your Rails app, just run:
|
46
|
+
|
47
|
+
rails generate cucumber:install --capybara
|
48
|
+
|
49
|
+
And everything should be set up and ready to go.
|
50
|
+
|
51
|
+
If you want to use Capybara with Cucumber outside Rails (for example with Merb
|
52
|
+
or Sinatra), you'll need to require Capybara and set the Rack app manually:
|
53
|
+
|
54
|
+
require 'capybara/cucumber'
|
55
|
+
Capybara.app = MyRackApp
|
56
|
+
|
57
|
+
Now you can use it in your steps:
|
58
|
+
|
59
|
+
When /I sign in/ do
|
60
|
+
within("#session") do
|
61
|
+
fill_in 'Login', :with => 'user@example.com'
|
62
|
+
fill_in 'Password', :with => 'password'
|
63
|
+
end
|
64
|
+
click_link 'Sign in'
|
65
|
+
end
|
66
|
+
|
67
|
+
Capybara sets up some {tags}[http://wiki.github.com/aslakhellesoy/cucumber/tags]
|
68
|
+
for you to use in Cucumber. Often you'll want to run only some scenarios with a
|
69
|
+
driver that supports JavaScript, Capybara makes this easy: simply tag the
|
70
|
+
scenario (or feature) with <tt>@javascript</tt>:
|
71
|
+
|
72
|
+
@javascript
|
73
|
+
Scenario: do something Ajaxy
|
74
|
+
When I click the Ajax link
|
75
|
+
...
|
76
|
+
|
77
|
+
You can change which driver Capybara uses for JavaScript:
|
78
|
+
|
79
|
+
Capybara.javascript_driver = :culerity
|
80
|
+
|
81
|
+
There are also explicit <tt>@selenium</tt>, <tt>@culerity</tt> and
|
82
|
+
<tt>@rack_test</tt> tags set up for you.
|
83
|
+
|
84
|
+
== Using Capybara with RSpec
|
85
|
+
|
86
|
+
If you prefer RSpec to using Cucumber, you can use the built in RSpec support
|
87
|
+
by adding the following line (typically to your <tt>spec_helper.rb</tt> file):
|
88
|
+
|
89
|
+
require 'capybara/rspec'
|
90
|
+
|
91
|
+
You can now write your specs like so:
|
92
|
+
|
93
|
+
describe "the signup process", :type => :request do
|
94
|
+
before :each do
|
95
|
+
User.make(:email => 'user@example.com', :password => 'caplin')
|
96
|
+
end
|
97
|
+
|
98
|
+
it "signs me in" do
|
99
|
+
within("#session") do
|
100
|
+
fill_in 'Login', :with => 'user@example.com'
|
101
|
+
fill_in 'Password', :with => 'password'
|
102
|
+
end
|
103
|
+
click_link 'Sign in'
|
104
|
+
end
|
105
|
+
end
|
106
|
+
|
107
|
+
Capybara is only included in example groups tagged with
|
108
|
+
<tt>:type => :request</tt> (or <tt>:acceptance</tt> for compatibility with Steak).
|
109
|
+
|
110
|
+
If you are testing a Rails app and using the <tt>rspec-rails</tt> gem, these
|
111
|
+
<tt>:request</tt> example groups may look familiar to you. That's because they
|
112
|
+
are RSpec versions of Rails integration tests. So, in this case essentially what you are getting are Capybara-enhanced request specs. This means that you can
|
113
|
+
use the Capybara helpers <i>and</i> you have access to things like named route
|
114
|
+
helpers in your tests (so you are able to say, for instance, <tt>visit
|
115
|
+
edit_user_path(user)</tt>, instead of <tt>visit "/users/#{user.id}/edit"</tt>,
|
116
|
+
if you prefer that sort of thing). A good place to put these specs is
|
117
|
+
<tt>spec/requests</tt>, as <tt>rspec-rails</tt> will automatically tag them with
|
118
|
+
<tt>:type => :request</tt>. (In fact, <tt>spec/integration</tt> and
|
119
|
+
<tt>spec/acceptance</tt> will work just as well.)
|
120
|
+
|
121
|
+
<tt>rspec-rails</tt> will also automatically include Capybara in <tt>:controller</tt> and <tt>:mailer</tt> example groups.
|
122
|
+
|
123
|
+
RSpec's metadata feature can be used to switch to a different driver. Use
|
124
|
+
<tt>:js => true</tt> to switch to the javascript driver, or provide a
|
125
|
+
<tt>:driver</tt> option to switch to one specific driver. For example:
|
126
|
+
|
127
|
+
describe 'some stuff which requires js', :js => true do
|
128
|
+
it 'will use the default js driver'
|
129
|
+
it 'will switch to one specific driver', :driver => :celerity
|
130
|
+
end
|
131
|
+
|
132
|
+
Finally, Capybara also comes with a built in DSL for creating descriptive acceptance tests:
|
133
|
+
|
134
|
+
feature "Signing up" do
|
135
|
+
background do
|
136
|
+
User.make(:email => 'user@example.com', :password => 'caplin')
|
137
|
+
end
|
138
|
+
|
139
|
+
scenario "Signing in with correct credentials" do
|
140
|
+
within("#session") do
|
141
|
+
fill_in 'Login', :with => 'user@example.com'
|
142
|
+
fill_in 'Password', :with => 'caplin'
|
143
|
+
end
|
144
|
+
click_link 'Sign in'
|
145
|
+
end
|
146
|
+
end
|
147
|
+
|
148
|
+
This is, in fact, just a shortcut for making a request spec, where
|
149
|
+
<tt>feature</tt> is an alias for <tt>describe ..., :type => :request</tt>,
|
150
|
+
<tt>background</tt> is an alias for <tt>before</tt>, and <tt>scenario</tt>
|
151
|
+
is an alias for <tt>it</tt>/<tt>specify</tt>.
|
152
|
+
|
153
|
+
Note that Capybara's built in RSpec support only works with RSpec 2.0 or later.
|
154
|
+
You'll need to roll your own for earlier versions of RSpec.
|
155
|
+
|
156
|
+
== Using Capybara with Test::Unit
|
157
|
+
|
158
|
+
To use Capybara with Test::Unit, include the DSL (<tt>include Capybara</tt> up
|
159
|
+
until version 0.4.x, <tt>include Capybara::DSL</tt> for newer versions) in
|
160
|
+
whatever test class you are using. For example, if your classes derive from
|
161
|
+
<tt>ActionDispatch::IntegrationTest</tt>, use
|
162
|
+
|
163
|
+
class ActionDispatch::IntegrationTest
|
164
|
+
include Capybara::DSL
|
165
|
+
end
|
166
|
+
|
167
|
+
Test::Unit does not support selecting the driver through test metadata, but you
|
168
|
+
can switch the driver for specific classes using the <tt>setup</tt> and
|
169
|
+
<tt>teardown</tt> methods. See the section "Selecting the Driver".
|
170
|
+
|
171
|
+
== Using Capybara with Ruby on Rails
|
172
|
+
|
173
|
+
If you are using the Rails framework, add this line to automatically configure
|
174
|
+
Capybara to test against your Rails application:
|
175
|
+
|
176
|
+
require 'capybara/rails'
|
177
|
+
|
178
|
+
== Using Capybara with Rack
|
179
|
+
|
180
|
+
If you're using Capybara with a non-Rails Rack application, set
|
181
|
+
<tt>Capybara.app</tt> to your application class:
|
182
|
+
|
183
|
+
Capybara.app = MyRackApp
|
184
|
+
|
185
|
+
== Drivers
|
186
|
+
|
187
|
+
Capybara uses the same DSL to drive a variety of browser and headless drivers.
|
188
|
+
|
189
|
+
=== Selecting the Driver
|
190
|
+
|
191
|
+
By default, Capybara uses the <tt>:rack_test</tt> driver, which is fast but does not
|
192
|
+
support JavaScript. You can set up a different default driver for your
|
193
|
+
features. For example if you'd prefer to run everything in Selenium, you could
|
194
|
+
do:
|
195
|
+
|
196
|
+
Capybara.default_driver = :selenium
|
197
|
+
|
198
|
+
However, if you are using RSpec or Cucumber, you may instead want to consider
|
199
|
+
leaving the faster <tt>:rack_test</tt> as the +default_driver+, and marking only those
|
200
|
+
tests that require a JavaScript-capable driver using <tt>:js => true</tt> or
|
201
|
+
<tt>@javascript</tt>, respectively. By default, JavaScript tests are run using the
|
202
|
+
<tt>:selenium</tt> driver. You can change this by setting
|
203
|
+
<tt>Capybara.javascript_driver</tt>.
|
204
|
+
|
205
|
+
You can also change the driver temporarily (typically in the Before/setup and
|
206
|
+
After/teardown blocks):
|
207
|
+
|
208
|
+
Capybara.current_driver = :culerity # temporarily select different driver
|
209
|
+
... tests ...
|
210
|
+
Capybara.use_default_driver # switch back to default driver
|
211
|
+
|
212
|
+
Note that switching the driver creates a new session, so you may not be able to
|
213
|
+
switch in the middle of a test.
|
214
|
+
|
215
|
+
=== RackTest
|
216
|
+
|
217
|
+
RackTest is Capybara's default driver. It is written in pure Ruby and does not
|
218
|
+
have any support for executing JavaScript. Since the RackTest driver works
|
219
|
+
directly agains the Rack interface, it does not need any server to be started,
|
220
|
+
it can work directly work against any Rack app. This means that if your
|
221
|
+
application is not a Rack application (Rails, Sinatra and most other Ruby
|
222
|
+
frameworks are Rack applications) then you cannot use this driver. You cannot
|
223
|
+
use the RackTest driver to test a remote application.
|
224
|
+
{capybara-mechanize}[https://github.com/jeroenvandijk/capybara-mechanize]
|
225
|
+
intends to provide a similar driver which works against remote servers, it is a
|
226
|
+
separate project.
|
227
|
+
|
228
|
+
RackTest can be configured with a set of headers like this:
|
229
|
+
|
230
|
+
Capybara.register_driver :rack_test do |app|
|
231
|
+
Capybara::RackTest::Driver.new(app, :browser => :chrome)
|
232
|
+
end
|
233
|
+
|
234
|
+
See the section on adding and configuring drivers.
|
235
|
+
|
236
|
+
=== Selenium
|
237
|
+
|
238
|
+
At the moment, Capybara supports {Selenium 2.0
|
239
|
+
(Webdriver)}[http://seleniumhq.org/docs/01_introducing_selenium.html#selenium-2-aka-selenium-webdriver],
|
240
|
+
*not* Selenium RC. Provided Firefox is installed, everything is set up for you,
|
241
|
+
and you should be able to start using Selenium right away.
|
242
|
+
|
243
|
+
Capybara can block and wait for Ajax requests to finish after you've interacted
|
244
|
+
with the page. To enable this behaviour, set the <tt>:resynchronize</tt> driver
|
245
|
+
option to <tt>true</tt>. This should normally not be necessary, since
|
246
|
+
Capybara's automatic reloading should take care of any asynchronicity problems.
|
247
|
+
See the section on Asynchronous JavaScript for details.
|
248
|
+
|
249
|
+
Note: Selenium does not support transactional fixtures; see the section
|
250
|
+
"Transactional Fixtures" below.
|
251
|
+
|
252
|
+
=== HtmlUnit
|
253
|
+
|
254
|
+
There are three different drivers, maintained as external gems, that you can
|
255
|
+
use to drive {HtmlUnit}[http://htmlunit.sourceforge.net/]:
|
256
|
+
|
257
|
+
* {Akephalos}[https://github.com/bernerdschaefer/akephalos] might be the best
|
258
|
+
HtmlUnit driver right now.
|
259
|
+
|
260
|
+
* {Celerity}[https://github.com/sobrinho/capybara-celerity] only runs on JRuby,
|
261
|
+
so you'll need to install the celerity gem under JRuby: <tt>jruby -S gem
|
262
|
+
install celerity</tt>
|
263
|
+
|
264
|
+
* {Culerity}[https://github.com/sobrinho/capybara-culerity]: Install celerity
|
265
|
+
as noted above, and make sure that JRuby is in your path. Note that Culerity
|
266
|
+
does not seem to be working under Ruby 1.9 at the moment.
|
267
|
+
|
268
|
+
Note: HtmlUnit does not support transactional fixtures; see the section
|
269
|
+
"Transactional Fixtures" below.
|
270
|
+
|
271
|
+
=== env.js
|
272
|
+
|
273
|
+
The {capybara-envjs driver}[http://github.com/smparkes/capybara-envjs]
|
274
|
+
uses the envjs gem ({GitHub}[http://github.com/smparkes/env-js],
|
275
|
+
{rubygems.org}[http://rubygems.org/gems/envjs]) to interpret
|
276
|
+
JavaScript outside the browser. The driver is installed by installing the capybara-envjs gem:
|
277
|
+
|
278
|
+
gem install capybara-envjs
|
279
|
+
|
280
|
+
More info about the driver and env.js are available through the links above. The envjs gem only supports
|
281
|
+
Ruby 1.8.7 at this time.
|
282
|
+
|
283
|
+
Note: Envjs does not support transactional fixtures; see the section
|
284
|
+
"Transactional Fixtures" below.
|
285
|
+
|
286
|
+
=== Capybara-webkit
|
287
|
+
|
288
|
+
The {capybara-webkit drive}[https://github.com/thoughtbot/capybara-webkit] is for true headless
|
289
|
+
testing. It uses WebKitQt to start a rendering engine process. It can execute JavaScript as well.
|
290
|
+
It is significantly faster than drivers like Selenium since it does not load an entire browser.
|
291
|
+
|
292
|
+
You can install it with:
|
293
|
+
|
294
|
+
gem install capybara-webkit
|
295
|
+
|
296
|
+
And you can use it by:
|
297
|
+
|
298
|
+
Capybara.javascript_driver = :webkit
|
299
|
+
|
300
|
+
|
301
|
+
== The DSL
|
302
|
+
|
303
|
+
Capybara's DSL (domain-specific language) is inspired by Webrat. While
|
304
|
+
backwards compatibility is retained in a lot of cases, there are certain
|
305
|
+
important differences. Unlike in Webrat, all searches in Capybara are *case
|
306
|
+
sensitive*. This is because Capybara heavily uses XPath, which doesn't support
|
307
|
+
case insensitivity.
|
308
|
+
|
309
|
+
=== Navigating
|
310
|
+
|
311
|
+
You can use the
|
312
|
+
<tt>{visit}[http://rubydoc.info/github/jnicklas/capybara/master/Capybara/Session#visit-instance_method]</tt>
|
313
|
+
method to navigate to other pages:
|
314
|
+
|
315
|
+
visit('/projects')
|
316
|
+
visit(post_comments_path(post))
|
317
|
+
|
318
|
+
The visit method only takes a single parameter, the request method is *always*
|
319
|
+
GET.
|
320
|
+
|
321
|
+
You can get the {current
|
322
|
+
path}[http://rubydoc.info/github/jnicklas/capybara/master/Capybara/Session#current_path-instance_method]
|
323
|
+
of the browsing session for test assertions:
|
324
|
+
|
325
|
+
current_path.should == post_comments_path(post)
|
326
|
+
|
327
|
+
=== Clicking links and buttons
|
328
|
+
|
329
|
+
<em>Full reference: {Capybara::Node::Actions}[http://rubydoc.info/github/jnicklas/capybara/master/Capybara/Node/Actions]</em>
|
330
|
+
|
331
|
+
You can interact with the webapp by following links and buttons. Capybara
|
332
|
+
automatically follows any redirects, and submits forms associated with buttons.
|
333
|
+
|
334
|
+
click_link('id-of-link')
|
335
|
+
click_link('Link Text')
|
336
|
+
click_button('Save')
|
337
|
+
click_on('Link Text') # clicks on either links or buttons
|
338
|
+
click_on('Button Value')
|
339
|
+
|
340
|
+
=== Interacting with forms
|
341
|
+
|
342
|
+
<em>Full reference: {Capybara::Node::Actions}[http://rubydoc.info/github/jnicklas/capybara/master/Capybara/Node/Actions]</em>
|
343
|
+
|
344
|
+
There are a number of tools for interacting with form elements:
|
345
|
+
|
346
|
+
fill_in('First Name', :with => 'John')
|
347
|
+
fill_in('Password', :with => 'Seekrit')
|
348
|
+
fill_in('Description', :with => 'Really Long Text...')
|
349
|
+
choose('A Radio Button')
|
350
|
+
check('A Checkbox')
|
351
|
+
uncheck('A Checkbox')
|
352
|
+
attach_file('Image', '/path/to/image.jpg')
|
353
|
+
select('Option', :from => 'Select Box')
|
354
|
+
|
355
|
+
=== Querying
|
356
|
+
|
357
|
+
<em>Full reference: {Capybara::Node::Matchers}[http://rubydoc.info/github/jnicklas/capybara/master/Capybara/Node/Matchers]</em>
|
358
|
+
|
359
|
+
Capybara has a rich set of options for querying the page for the existence of
|
360
|
+
certain elements, and working with and manipulating those elements.
|
361
|
+
|
362
|
+
page.has_selector?('table tr')
|
363
|
+
page.has_selector?(:xpath, '//table/tr')
|
364
|
+
page.has_no_selector?(:content)
|
365
|
+
|
366
|
+
page.has_xpath?('//table/tr')
|
367
|
+
page.has_css?('table tr.foo')
|
368
|
+
page.has_content?('foo')
|
369
|
+
|
370
|
+
You can use these with RSpec's magic matchers:
|
371
|
+
|
372
|
+
page.should have_selector('table tr')
|
373
|
+
page.should have_selector(:xpath, '//table/tr')
|
374
|
+
page.should have_no_selector(:content)
|
375
|
+
|
376
|
+
page.should have_xpath('//table/tr')
|
377
|
+
page.should have_css('table tr.foo')
|
378
|
+
page.should have_content('foo')
|
379
|
+
page.should have_no_content('foo')
|
380
|
+
|
381
|
+
Note that <tt>page.should have_no_xpath</tt> is preferred over
|
382
|
+
<tt>page.should_not have_xpath</tt>. Read the section on asynchronous JavaScript
|
383
|
+
for an explanation.
|
384
|
+
|
385
|
+
If all else fails, you can also use the
|
386
|
+
<tt>{page.html}[http://rubydoc.info/github/jnicklas/capybara/master/Capybara/Session#html-instance_method]</tt>
|
387
|
+
method to test against the raw HTML:
|
388
|
+
|
389
|
+
page.html.should match /<span>.../i
|
390
|
+
|
391
|
+
=== Finding
|
392
|
+
|
393
|
+
<em>Full reference: {Capybara::Node::Finders}[http://rubydoc.info/github/jnicklas/capybara/master/Capybara/Node/Finders]</em>
|
394
|
+
|
395
|
+
You can also find specific elements, in order to manipulate them:
|
396
|
+
|
397
|
+
find_field('First Name').value
|
398
|
+
find_link('Hello').visible?
|
399
|
+
find_button('Send').click
|
400
|
+
|
401
|
+
find(:xpath, "//table/tr").click
|
402
|
+
find("#overlay").find("h1").click
|
403
|
+
all('a').each { |a| a[:href] }
|
404
|
+
|
405
|
+
Note that <tt>find</tt> will wait for an element to appear on the page, as explained in the
|
406
|
+
Ajax section. If the element does not appear it will raise an error.
|
407
|
+
|
408
|
+
These elements all have all the Capybara DSL methods available, so you can restrict them
|
409
|
+
to specific parts of the page:
|
410
|
+
|
411
|
+
find('#navigation').click_link('Home')
|
412
|
+
find('#navigation').should have_button('Sign out')
|
413
|
+
|
414
|
+
=== Scoping
|
415
|
+
|
416
|
+
Capybara makes it possible to restrict certain actions, such as interacting with
|
417
|
+
forms or clicking links and buttons, to within a specific area of the page. For
|
418
|
+
this purpose you can use the generic
|
419
|
+
<tt>{within}[http://rubydoc.info/github/jnicklas/capybara/master/Capybara/Session#within-instance_method]</tt>
|
420
|
+
method. Optionally you can specify which kind of selector to use.
|
421
|
+
|
422
|
+
within("li#employee") do
|
423
|
+
fill_in 'Name', :with => 'Jimmy'
|
424
|
+
end
|
425
|
+
|
426
|
+
within(:xpath, "//li[@id='employee']") do
|
427
|
+
fill_in 'Name', :with => 'Jimmy'
|
428
|
+
end
|
429
|
+
|
430
|
+
Note that <tt>within</tt> will scope the actions to the _first_ (not _any_)
|
431
|
+
element that matches the selector.
|
432
|
+
|
433
|
+
There are special methods for restricting the scope to a specific fieldset,
|
434
|
+
identified by either an id or the text of the fieldet's legend tag, and to a
|
435
|
+
specific table, identified by either id or text of the table's caption tag.
|
436
|
+
|
437
|
+
within_fieldset('Employee') do
|
438
|
+
fill_in 'Name', :with => 'Jimmy'
|
439
|
+
end
|
440
|
+
|
441
|
+
within_table('Employee') do
|
442
|
+
fill_in 'Name', :with => 'Jimmy'
|
443
|
+
end
|
444
|
+
|
445
|
+
=== Scripting
|
446
|
+
|
447
|
+
In drivers which support it, you can easily execute JavaScript:
|
448
|
+
|
449
|
+
page.execute_script("$('body').empty()")
|
450
|
+
|
451
|
+
For simple expressions, you can return the result of the script. Note
|
452
|
+
that this may break with more complicated expressions:
|
453
|
+
|
454
|
+
result = page.evaluate_script('4 + 4');
|
455
|
+
|
456
|
+
=== Debugging
|
457
|
+
|
458
|
+
It can be useful to take a snapshot of the page as it currently is and take a
|
459
|
+
look at it:
|
460
|
+
|
461
|
+
save_and_open_page
|
462
|
+
|
463
|
+
== Transactional fixtures
|
464
|
+
|
465
|
+
Transactional fixtures only work in the default Rack::Test driver, but not for
|
466
|
+
other drivers like Selenium. Cucumber takes care of this automatically, but
|
467
|
+
with Test::Unit or RSpec, you may have to use the
|
468
|
+
{database_cleaner}[https://github.com/bmabey/database_cleaner] gem. See {this
|
469
|
+
explanation}[https://groups.google.com/d/msg/ruby-capybara/JI6JrirL9gM/R6YiXj4gi_UJ]
|
470
|
+
(and code for {solution
|
471
|
+
2}[http://opinionated-programmer.com/2011/02/capybara-and-selenium-with-rspec-and-rails-3/#comment-220]
|
472
|
+
and {solution 3}[http://pastie.org/1745020]) for details.
|
473
|
+
|
474
|
+
== Asynchronous JavaScript (Ajax and friends)
|
475
|
+
|
476
|
+
When working with asynchronous JavaScript, you might come across situations
|
477
|
+
where you are attempting to interact with an element which is not yet present
|
478
|
+
on the page. Capybara automatically deals with this by waiting for elements
|
479
|
+
to appear on the page.
|
480
|
+
|
481
|
+
When issuing instructions to the DSL such as:
|
482
|
+
|
483
|
+
click_link('foo')
|
484
|
+
click_link('bar')
|
485
|
+
page.should have_content('baz')
|
486
|
+
|
487
|
+
If clicking on the *foo* link triggers an asynchronous process, such as
|
488
|
+
an Ajax request, which, when complete will add the *bar* link to the page,
|
489
|
+
clicking on the *bar* link would be expected to fail, since that link doesn't
|
490
|
+
exist yet. However Capybara is smart enought to retry finding the link for a
|
491
|
+
brief period of time before giving up and throwing an error. The same is true of
|
492
|
+
the next line, which looks for the content *baz* on the page; it will retry
|
493
|
+
looking for that content for a brief time. You can adjust how long this period
|
494
|
+
is (the default is 2 seconds):
|
495
|
+
|
496
|
+
Capybara.default_wait_time = 5
|
497
|
+
|
498
|
+
Be aware that because of this behaviour, the following two statements are *not*
|
499
|
+
equivalent, and you should *always* use the latter!
|
500
|
+
|
501
|
+
page.should_not have_xpath('a')
|
502
|
+
page.should have_no_xpath('a')
|
503
|
+
|
504
|
+
The former would incorrectly wait for the content to appear, since the
|
505
|
+
asynchronous process has not yet removed the element from the page, it would
|
506
|
+
therefore fail, even though the code might be working correctly. The latter
|
507
|
+
correctly waits for the element to disappear from the page.
|
508
|
+
|
509
|
+
Capybara's waiting behaviour is quite advanced, and can deal with situations
|
510
|
+
such as the following line of code:
|
511
|
+
|
512
|
+
find('#sidebar').find('h1').should have_content('Something')
|
513
|
+
|
514
|
+
Even if JavaScript causes <tt>#sidebar</tt> to disappear off the page, Capybara
|
515
|
+
will automatically reload it and any elements it contains. So if an AJAX
|
516
|
+
request causes the contents of <tt>#sidebar</tt> to change, which would update
|
517
|
+
the text of the <tt>h1</tt> to "Something", and this happened, this test would
|
518
|
+
pass. If you do not want this behaviour, you can set
|
519
|
+
<tt>Capybara.automatic_reload</tt> to <tt>false</tt>.
|
520
|
+
|
521
|
+
== Using the DSL in unsupported testing frameworks
|
522
|
+
|
523
|
+
You can mix the DSL into any context by including +Capybara::DSL+:
|
524
|
+
|
525
|
+
|
526
|
+
require 'capybara'
|
527
|
+
require 'capybara/dsl'
|
528
|
+
|
529
|
+
Capybara.default_driver = :culerity
|
530
|
+
|
531
|
+
module MyModule
|
532
|
+
include Capybara::DSL
|
533
|
+
|
534
|
+
def login!
|
535
|
+
within("//form[@id='session']") do
|
536
|
+
fill_in 'Login', :with => 'user@example.com'
|
537
|
+
fill_in 'Password', :with => 'password'
|
538
|
+
end
|
539
|
+
click_link 'Sign in'
|
540
|
+
end
|
541
|
+
end
|
542
|
+
|
543
|
+
== Calling remote servers
|
544
|
+
|
545
|
+
Normally Capybara expects to be testing an in-process Rack application, but you
|
546
|
+
can also use it to talk to a web server running anywhere on the internets, by
|
547
|
+
setting app_host:
|
548
|
+
|
549
|
+
Capybara.current_driver = :selenium
|
550
|
+
Capybara.app_host = 'http://www.google.com'
|
551
|
+
...
|
552
|
+
visit('/')
|
553
|
+
|
554
|
+
Note that the default driver (<tt>:rack_test</tt>) does not support running
|
555
|
+
against a remote server. With drivers that support it, you can also visit any
|
556
|
+
URL directly:
|
557
|
+
|
558
|
+
visit('http://www.google.com')
|
559
|
+
|
560
|
+
By default Capybara will try to boot a rack application automatically. You
|
561
|
+
might want to switch off Capybara's rack server if you are running against a
|
562
|
+
remote application:
|
563
|
+
|
564
|
+
Capybara.run_server = false
|
565
|
+
|
566
|
+
== Using the sessions manually
|
567
|
+
|
568
|
+
For ultimate control, you can instantiate and use a
|
569
|
+
{Session}[http://rubydoc.info/github/jnicklas/capybara/master/Capybara/Session]
|
570
|
+
manually.
|
571
|
+
|
572
|
+
require 'capybara'
|
573
|
+
|
574
|
+
session = Capybara::Session.new(:culerity, my_rack_app)
|
575
|
+
session.within("//form[@id='session']") do
|
576
|
+
session.fill_in 'Login', :with => 'user@example.com'
|
577
|
+
session.fill_in 'Password', :with => 'password'
|
578
|
+
end
|
579
|
+
session.click_link 'Sign in'
|
580
|
+
|
581
|
+
== XPath, CSS and selectors
|
582
|
+
|
583
|
+
Capybara does not try to guess what kind of selector you are going to give it,
|
584
|
+
and will always use CSS by default. If you want to use XPath, you'll need to
|
585
|
+
do:
|
586
|
+
|
587
|
+
within(:xpath, '//ul/li') { ... }
|
588
|
+
find(:xpath, '//ul/li').text
|
589
|
+
find(:xpath, '//li[contains(.//a[@href = "#"]/text(), "foo")]').value
|
590
|
+
|
591
|
+
Alternatively you can set the default selector to XPath:
|
592
|
+
|
593
|
+
Capybara.default_selector = :xpath
|
594
|
+
find('//ul/li').text
|
595
|
+
|
596
|
+
Capybara allows you to add custom selectors, which can be very useful if you
|
597
|
+
find yourself using the same kinds of selectors very often:
|
598
|
+
|
599
|
+
Capybara.add_selector(:id) do
|
600
|
+
xpath { |id| XPath.descendant[XPath.attr(:id) == id.to_s] }
|
601
|
+
end
|
602
|
+
|
603
|
+
Capybara.add_selector(:row) do
|
604
|
+
xpath { |num| ".//tbody/tr[#{num}]" }
|
605
|
+
end
|
606
|
+
|
607
|
+
The block given to xpath must always return an XPath expression as a String, or
|
608
|
+
an XPath expression generated through the XPath gem. You can now use these
|
609
|
+
selectors like this:
|
610
|
+
|
611
|
+
find(:id, 'post_123')
|
612
|
+
find(:row, 3)
|
613
|
+
|
614
|
+
You can specify an optional match option which will automatically use the
|
615
|
+
selector if it matches the argument:
|
616
|
+
|
617
|
+
Capybara.add_selector(:id) do
|
618
|
+
xpath { |id| XPath.descendant[XPath.attr(:id) == id.to_s] }
|
619
|
+
match { |value| value.is_a?(Symbol) }
|
620
|
+
end
|
621
|
+
|
622
|
+
Now use it like this:
|
623
|
+
|
624
|
+
find(:post_123)
|
625
|
+
|
626
|
+
This :id selector is already built into Capybara by default, so you don't
|
627
|
+
need to add it yourself.
|
628
|
+
|
629
|
+
== Beware the XPath // trap
|
630
|
+
|
631
|
+
In XPath the expression // means something very specific, and it might not be what
|
632
|
+
you think. Contrary to common belief, // means "anywhere in the document" not "anywhere
|
633
|
+
in the current context". As an example:
|
634
|
+
|
635
|
+
page.find(:xpath, '//body').all(:xpath, '//script')
|
636
|
+
|
637
|
+
You might expect this to find all script tags in the body, but actually, it finds all
|
638
|
+
script tags in the entire document, not only those in the body! What you're looking
|
639
|
+
for is the .// expression which means "any descendant of the current node":
|
640
|
+
|
641
|
+
page.find(:xpath, '//body').all(:xpath, './/script')
|
642
|
+
|
643
|
+
The same thing goes for within:
|
644
|
+
|
645
|
+
within(:xpath, '//body') do
|
646
|
+
page.find(:xpath, './/script')
|
647
|
+
within(:xpath, './/table/tbody') do
|
648
|
+
...
|
649
|
+
end
|
650
|
+
end
|
651
|
+
|
652
|
+
== Configuring and adding drivers
|
653
|
+
|
654
|
+
Capybara makes it convenient to switch between different drivers. It also exposes
|
655
|
+
an API to tweak those drivers with whatever settings you want, or to add your own
|
656
|
+
drivers. This is how to switch the selenium driver to use chrome:
|
657
|
+
|
658
|
+
Capybara.register_driver :selenium do |app|
|
659
|
+
Capybara::Selenium::Driver.new(app, :browser => :chrome)
|
660
|
+
end
|
661
|
+
|
662
|
+
However, it's also possible to give this a different name, so tests can switch
|
663
|
+
between using different browsers effortlessly:
|
664
|
+
|
665
|
+
Capybara.register_driver :selenium_chrome do |app|
|
666
|
+
Capybara::Selenium::Driver.new(app, :browser => :chrome)
|
667
|
+
end
|
668
|
+
|
669
|
+
Whatever is returned from the block should conform to the API described by
|
670
|
+
Capybara::Driver::Base, it does not however have to inherit from this class.
|
671
|
+
Gems can use this API to add their own drivers to Capybara.
|
672
|
+
|
673
|
+
The {Selenium wiki}[http://code.google.com/p/selenium/wiki/RubyBindings] has
|
674
|
+
additional info about how the underlying driver can be configured.
|
675
|
+
|
676
|
+
== Gotchas:
|
677
|
+
|
678
|
+
* Access to session and request is not possible from the test, Access to
|
679
|
+
response is limited. Some drivers allow access to response headers and HTTP
|
680
|
+
status code, but this kind of functionality is not provided by some drivers,
|
681
|
+
such as Selenium.
|
682
|
+
|
683
|
+
* Access to Rails specific stuff (such as <tt>controller</tt>) is unavailable,
|
684
|
+
since we're not using Rails' integration testing.
|
685
|
+
|
686
|
+
* Freezing time: It's common practice to mock out the Time so that features
|
687
|
+
that depend on the current Date work as expected. This can be problematic,
|
688
|
+
since Capybara's Ajax timing uses the system time, resulting in Capybara
|
689
|
+
never timing out and just hanging when a failure occurs. It's still possible to
|
690
|
+
use plugins which allow you to travel in time, rather than freeze time.
|
691
|
+
One such plugin is {Timecop}[http://github.com/jtrupiano/timecop].
|
692
|
+
|
693
|
+
* When using Rack::Test, beware if attempting to visit absolute URLs. For
|
694
|
+
example, a session might not be shared between visits to <tt>posts_path</tt>
|
695
|
+
and <tt>posts_url</tt>. If testing an absolute URL in an Action Mailer email,
|
696
|
+
set <tt>default_url_options</tt> to match the Rails default of
|
697
|
+
<tt>www.example.com</tt>.
|
698
|
+
|
699
|
+
== License:
|
700
|
+
|
701
|
+
(The MIT License)
|
702
|
+
|
703
|
+
Copyright (c) 2009 Jonas Nicklas
|
704
|
+
|
705
|
+
Permission is hereby granted, free of charge, to any person obtaining
|
706
|
+
a copy of this software and associated documentation files (the
|
707
|
+
'Software'), to deal in the Software without restriction, including
|
708
|
+
without limitation the rights to use, copy, modify, merge, publish,
|
709
|
+
distribute, sublicense, and/or sell copies of the Software, and to
|
710
|
+
permit persons to whom the Software is furnished to do so, subject to
|
711
|
+
the following conditions:
|
712
|
+
|
713
|
+
The above copyright notice and this permission notice shall be
|
714
|
+
included in all copies or substantial portions of the Software.
|
715
|
+
|
716
|
+
THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
|
717
|
+
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
718
|
+
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
719
|
+
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
|
720
|
+
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
|
721
|
+
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
|
722
|
+
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|