capybara 3.0.0 → 3.40.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (312) hide show
  1. checksums.yaml +4 -4
  2. data/.yardopts +1 -1
  3. data/History.md +891 -12
  4. data/License.txt +1 -1
  5. data/README.md +257 -84
  6. data/lib/capybara/config.rb +29 -10
  7. data/lib/capybara/cucumber.rb +1 -1
  8. data/lib/capybara/driver/base.rb +22 -4
  9. data/lib/capybara/driver/node.rb +38 -9
  10. data/lib/capybara/dsl.rb +9 -7
  11. data/lib/capybara/helpers.rb +57 -8
  12. data/lib/capybara/minitest/spec.rb +185 -84
  13. data/lib/capybara/minitest.rb +264 -145
  14. data/lib/capybara/node/actions.rb +248 -124
  15. data/lib/capybara/node/base.rb +35 -20
  16. data/lib/capybara/node/document.rb +14 -2
  17. data/lib/capybara/node/document_matchers.rb +13 -15
  18. data/lib/capybara/node/element.rb +350 -113
  19. data/lib/capybara/node/finders.rb +104 -82
  20. data/lib/capybara/node/matchers.rb +363 -157
  21. data/lib/capybara/node/simple.rb +54 -15
  22. data/lib/capybara/node/whitespace_normalizer.rb +81 -0
  23. data/lib/capybara/queries/active_element_query.rb +18 -0
  24. data/lib/capybara/queries/ancestor_query.rb +9 -10
  25. data/lib/capybara/queries/base_query.rb +25 -18
  26. data/lib/capybara/queries/current_path_query.rb +16 -6
  27. data/lib/capybara/queries/match_query.rb +11 -0
  28. data/lib/capybara/queries/selector_query.rb +617 -104
  29. data/lib/capybara/queries/sibling_query.rb +9 -7
  30. data/lib/capybara/queries/style_query.rb +45 -0
  31. data/lib/capybara/queries/text_query.rb +40 -22
  32. data/lib/capybara/queries/title_query.rb +2 -2
  33. data/lib/capybara/rack_test/browser.rb +106 -31
  34. data/lib/capybara/rack_test/driver.rb +16 -7
  35. data/lib/capybara/rack_test/errors.rb +6 -0
  36. data/lib/capybara/rack_test/form.rb +74 -49
  37. data/lib/capybara/rack_test/node.rb +120 -47
  38. data/lib/capybara/rails.rb +1 -1
  39. data/lib/capybara/registration_container.rb +41 -0
  40. data/lib/capybara/registrations/drivers.rb +42 -0
  41. data/lib/capybara/registrations/patches/puma_ssl.rb +29 -0
  42. data/lib/capybara/registrations/servers.rb +66 -0
  43. data/lib/capybara/result.rb +87 -53
  44. data/lib/capybara/rspec/features.rb +8 -10
  45. data/lib/capybara/rspec/matcher_proxies.rb +39 -18
  46. data/lib/capybara/rspec/matchers/base.rb +113 -0
  47. data/lib/capybara/rspec/matchers/become_closed.rb +33 -0
  48. data/lib/capybara/rspec/matchers/compound.rb +88 -0
  49. data/lib/capybara/rspec/matchers/count_sugar.rb +37 -0
  50. data/lib/capybara/rspec/matchers/have_ancestor.rb +28 -0
  51. data/lib/capybara/rspec/matchers/have_current_path.rb +29 -0
  52. data/lib/capybara/rspec/matchers/have_selector.rb +69 -0
  53. data/lib/capybara/rspec/matchers/have_sibling.rb +27 -0
  54. data/lib/capybara/rspec/matchers/have_text.rb +33 -0
  55. data/lib/capybara/rspec/matchers/have_title.rb +29 -0
  56. data/lib/capybara/rspec/matchers/match_selector.rb +27 -0
  57. data/lib/capybara/rspec/matchers/match_style.rb +43 -0
  58. data/lib/capybara/rspec/matchers/spatial_sugar.rb +39 -0
  59. data/lib/capybara/rspec/matchers.rb +142 -315
  60. data/lib/capybara/rspec.rb +3 -2
  61. data/lib/capybara/selector/builders/css_builder.rb +84 -0
  62. data/lib/capybara/selector/builders/xpath_builder.rb +71 -0
  63. data/lib/capybara/selector/css.rb +85 -8
  64. data/lib/capybara/selector/definition/button.rb +68 -0
  65. data/lib/capybara/selector/definition/checkbox.rb +26 -0
  66. data/lib/capybara/selector/definition/css.rb +10 -0
  67. data/lib/capybara/selector/definition/datalist_input.rb +35 -0
  68. data/lib/capybara/selector/definition/datalist_option.rb +25 -0
  69. data/lib/capybara/selector/definition/element.rb +28 -0
  70. data/lib/capybara/selector/definition/field.rb +40 -0
  71. data/lib/capybara/selector/definition/fieldset.rb +14 -0
  72. data/lib/capybara/selector/definition/file_field.rb +13 -0
  73. data/lib/capybara/selector/definition/fillable_field.rb +33 -0
  74. data/lib/capybara/selector/definition/frame.rb +17 -0
  75. data/lib/capybara/selector/definition/id.rb +6 -0
  76. data/lib/capybara/selector/definition/label.rb +62 -0
  77. data/lib/capybara/selector/definition/link.rb +55 -0
  78. data/lib/capybara/selector/definition/link_or_button.rb +16 -0
  79. data/lib/capybara/selector/definition/option.rb +27 -0
  80. data/lib/capybara/selector/definition/radio_button.rb +27 -0
  81. data/lib/capybara/selector/definition/select.rb +81 -0
  82. data/lib/capybara/selector/definition/table.rb +109 -0
  83. data/lib/capybara/selector/definition/table_row.rb +21 -0
  84. data/lib/capybara/selector/definition/xpath.rb +5 -0
  85. data/lib/capybara/selector/definition.rb +280 -0
  86. data/lib/capybara/selector/filter.rb +1 -0
  87. data/lib/capybara/selector/filter_set.rb +72 -28
  88. data/lib/capybara/selector/filters/base.rb +45 -2
  89. data/lib/capybara/selector/filters/expression_filter.rb +5 -6
  90. data/lib/capybara/selector/filters/locator_filter.rb +29 -0
  91. data/lib/capybara/selector/filters/node_filter.rb +18 -4
  92. data/lib/capybara/selector/regexp_disassembler.rb +211 -0
  93. data/lib/capybara/selector/selector.rb +89 -200
  94. data/lib/capybara/selector/xpath_extensions.rb +17 -0
  95. data/lib/capybara/selector.rb +474 -534
  96. data/lib/capybara/selenium/atoms/getAttribute.min.js +1 -0
  97. data/lib/capybara/selenium/atoms/isDisplayed.min.js +1 -0
  98. data/lib/capybara/selenium/atoms/src/getAttribute.js +161 -0
  99. data/lib/capybara/selenium/atoms/src/isDisplayed.js +454 -0
  100. data/lib/capybara/selenium/driver.rb +270 -245
  101. data/lib/capybara/selenium/driver_specializations/chrome_driver.rb +117 -0
  102. data/lib/capybara/selenium/driver_specializations/edge_driver.rb +128 -0
  103. data/lib/capybara/selenium/driver_specializations/firefox_driver.rb +84 -0
  104. data/lib/capybara/selenium/driver_specializations/internet_explorer_driver.rb +26 -0
  105. data/lib/capybara/selenium/driver_specializations/safari_driver.rb +24 -0
  106. data/lib/capybara/selenium/extensions/file_input_click_emulation.rb +34 -0
  107. data/lib/capybara/selenium/extensions/find.rb +110 -0
  108. data/lib/capybara/selenium/extensions/html5_drag.rb +229 -0
  109. data/lib/capybara/selenium/extensions/modifier_keys_stack.rb +28 -0
  110. data/lib/capybara/selenium/extensions/scroll.rb +76 -0
  111. data/lib/capybara/selenium/node.rb +460 -170
  112. data/lib/capybara/selenium/nodes/chrome_node.rb +125 -0
  113. data/lib/capybara/selenium/nodes/edge_node.rb +110 -0
  114. data/lib/capybara/selenium/nodes/firefox_node.rb +136 -0
  115. data/lib/capybara/selenium/nodes/ie_node.rb +22 -0
  116. data/lib/capybara/selenium/nodes/safari_node.rb +118 -0
  117. data/lib/capybara/selenium/patches/atoms.rb +18 -0
  118. data/lib/capybara/selenium/patches/is_displayed.rb +16 -0
  119. data/lib/capybara/selenium/patches/logs.rb +45 -0
  120. data/lib/capybara/selenium/patches/pause_duration_fix.rb +9 -0
  121. data/lib/capybara/selenium/patches/persistent_client.rb +20 -0
  122. data/lib/capybara/server/animation_disabler.rb +80 -0
  123. data/lib/capybara/server/checker.rb +44 -0
  124. data/lib/capybara/server/middleware.rb +71 -0
  125. data/lib/capybara/server.rb +58 -67
  126. data/lib/capybara/session/config.rb +40 -6
  127. data/lib/capybara/session/matchers.rb +26 -19
  128. data/lib/capybara/session.rb +252 -194
  129. data/lib/capybara/spec/public/jquery.js +5 -5
  130. data/lib/capybara/spec/public/offset.js +6 -0
  131. data/lib/capybara/spec/public/test.js +126 -8
  132. data/lib/capybara/spec/session/accept_alert_spec.rb +11 -11
  133. data/lib/capybara/spec/session/accept_confirm_spec.rb +3 -3
  134. data/lib/capybara/spec/session/accept_prompt_spec.rb +9 -10
  135. data/lib/capybara/spec/session/active_element_spec.rb +31 -0
  136. data/lib/capybara/spec/session/all_spec.rb +135 -44
  137. data/lib/capybara/spec/session/ancestor_spec.rb +24 -19
  138. data/lib/capybara/spec/session/assert_all_of_selectors_spec.rb +67 -38
  139. data/lib/capybara/spec/session/{assert_current_path.rb → assert_current_path_spec.rb} +20 -18
  140. data/lib/capybara/spec/session/assert_selector_spec.rb +143 -0
  141. data/lib/capybara/spec/session/assert_style_spec.rb +26 -0
  142. data/lib/capybara/spec/session/{assert_text.rb → assert_text_spec.rb} +76 -52
  143. data/lib/capybara/spec/session/{assert_title.rb → assert_title_spec.rb} +12 -12
  144. data/lib/capybara/spec/session/attach_file_spec.rb +126 -72
  145. data/lib/capybara/spec/session/body_spec.rb +11 -13
  146. data/lib/capybara/spec/session/check_spec.rb +112 -51
  147. data/lib/capybara/spec/session/choose_spec.rb +62 -30
  148. data/lib/capybara/spec/session/click_button_spec.rb +227 -161
  149. data/lib/capybara/spec/session/click_link_or_button_spec.rb +49 -30
  150. data/lib/capybara/spec/session/click_link_spec.rb +89 -55
  151. data/lib/capybara/spec/session/current_scope_spec.rb +8 -8
  152. data/lib/capybara/spec/session/current_url_spec.rb +44 -37
  153. data/lib/capybara/spec/session/dismiss_confirm_spec.rb +3 -3
  154. data/lib/capybara/spec/session/dismiss_prompt_spec.rb +2 -2
  155. data/lib/capybara/spec/session/element/{assert_match_selector.rb → assert_match_selector_spec.rb} +11 -9
  156. data/lib/capybara/spec/session/element/match_css_spec.rb +18 -10
  157. data/lib/capybara/spec/session/element/match_xpath_spec.rb +8 -6
  158. data/lib/capybara/spec/session/element/matches_selector_spec.rb +70 -56
  159. data/lib/capybara/spec/session/evaluate_async_script_spec.rb +7 -7
  160. data/lib/capybara/spec/session/evaluate_script_spec.rb +28 -8
  161. data/lib/capybara/spec/session/execute_script_spec.rb +8 -7
  162. data/lib/capybara/spec/session/fill_in_spec.rb +110 -44
  163. data/lib/capybara/spec/session/find_button_spec.rb +23 -23
  164. data/lib/capybara/spec/session/find_by_id_spec.rb +8 -8
  165. data/lib/capybara/spec/session/find_field_spec.rb +33 -31
  166. data/lib/capybara/spec/session/find_link_spec.rb +42 -14
  167. data/lib/capybara/spec/session/find_spec.rb +251 -142
  168. data/lib/capybara/spec/session/first_spec.rb +45 -44
  169. data/lib/capybara/spec/session/frame/frame_title_spec.rb +6 -6
  170. data/lib/capybara/spec/session/frame/frame_url_spec.rb +6 -6
  171. data/lib/capybara/spec/session/frame/switch_to_frame_spec.rb +32 -20
  172. data/lib/capybara/spec/session/frame/within_frame_spec.rb +46 -19
  173. data/lib/capybara/spec/session/go_back_spec.rb +1 -1
  174. data/lib/capybara/spec/session/go_forward_spec.rb +1 -1
  175. data/lib/capybara/spec/session/has_all_selectors_spec.rb +23 -23
  176. data/lib/capybara/spec/session/has_ancestor_spec.rb +46 -0
  177. data/lib/capybara/spec/session/has_any_selectors_spec.rb +29 -0
  178. data/lib/capybara/spec/session/has_button_spec.rb +98 -12
  179. data/lib/capybara/spec/session/has_css_spec.rb +271 -137
  180. data/lib/capybara/spec/session/has_current_path_spec.rb +50 -35
  181. data/lib/capybara/spec/session/has_element_spec.rb +47 -0
  182. data/lib/capybara/spec/session/has_field_spec.rb +137 -58
  183. data/lib/capybara/spec/session/has_link_spec.rb +46 -6
  184. data/lib/capybara/spec/session/has_none_selectors_spec.rb +33 -31
  185. data/lib/capybara/spec/session/has_select_spec.rb +84 -50
  186. data/lib/capybara/spec/session/has_selector_spec.rb +117 -69
  187. data/lib/capybara/spec/session/has_sibling_spec.rb +50 -0
  188. data/lib/capybara/spec/session/has_table_spec.rb +181 -4
  189. data/lib/capybara/spec/session/has_text_spec.rb +101 -53
  190. data/lib/capybara/spec/session/has_title_spec.rb +19 -14
  191. data/lib/capybara/spec/session/has_xpath_spec.rb +56 -38
  192. data/lib/capybara/spec/session/{headers.rb → headers_spec.rb} +1 -1
  193. data/lib/capybara/spec/session/html_spec.rb +13 -6
  194. data/lib/capybara/spec/session/matches_style_spec.rb +37 -0
  195. data/lib/capybara/spec/session/node_spec.rb +958 -122
  196. data/lib/capybara/spec/session/node_wrapper_spec.rb +15 -12
  197. data/lib/capybara/spec/session/refresh_spec.rb +9 -7
  198. data/lib/capybara/spec/session/reset_session_spec.rb +65 -37
  199. data/lib/capybara/spec/session/{response_code.rb → response_code_spec.rb} +1 -1
  200. data/lib/capybara/spec/session/save_and_open_page_spec.rb +2 -2
  201. data/lib/capybara/spec/session/save_and_open_screenshot_spec.rb +5 -4
  202. data/lib/capybara/spec/session/save_page_spec.rb +41 -38
  203. data/lib/capybara/spec/session/save_screenshot_spec.rb +13 -11
  204. data/lib/capybara/spec/session/screenshot_spec.rb +2 -2
  205. data/lib/capybara/spec/session/scroll_spec.rb +119 -0
  206. data/lib/capybara/spec/session/select_spec.rb +102 -76
  207. data/lib/capybara/spec/session/selectors_spec.rb +51 -18
  208. data/lib/capybara/spec/session/sibling_spec.rb +9 -9
  209. data/lib/capybara/spec/session/text_spec.rb +26 -24
  210. data/lib/capybara/spec/session/title_spec.rb +8 -6
  211. data/lib/capybara/spec/session/uncheck_spec.rb +41 -22
  212. data/lib/capybara/spec/session/unselect_spec.rb +37 -37
  213. data/lib/capybara/spec/session/visit_spec.rb +79 -53
  214. data/lib/capybara/spec/session/window/become_closed_spec.rb +22 -19
  215. data/lib/capybara/spec/session/window/current_window_spec.rb +4 -3
  216. data/lib/capybara/spec/session/window/open_new_window_spec.rb +4 -3
  217. data/lib/capybara/spec/session/window/switch_to_window_spec.rb +25 -21
  218. data/lib/capybara/spec/session/window/window_opened_by_spec.rb +10 -5
  219. data/lib/capybara/spec/session/window/window_spec.rb +88 -54
  220. data/lib/capybara/spec/session/window/windows_spec.rb +11 -8
  221. data/lib/capybara/spec/session/window/within_window_spec.rb +17 -16
  222. data/lib/capybara/spec/session/within_spec.rb +82 -44
  223. data/lib/capybara/spec/spec_helper.rb +46 -52
  224. data/lib/capybara/spec/test_app.rb +148 -41
  225. data/lib/capybara/spec/views/animated.erb +49 -0
  226. data/lib/capybara/spec/views/form.erb +156 -42
  227. data/lib/capybara/spec/views/frame_child.erb +4 -3
  228. data/lib/capybara/spec/views/frame_one.erb +2 -1
  229. data/lib/capybara/spec/views/frame_parent.erb +1 -1
  230. data/lib/capybara/spec/views/frame_two.erb +1 -1
  231. data/lib/capybara/spec/views/initial_alert.erb +2 -1
  232. data/lib/capybara/spec/views/layout.erb +10 -0
  233. data/lib/capybara/spec/views/obscured.erb +47 -0
  234. data/lib/capybara/spec/views/offset.erb +33 -0
  235. data/lib/capybara/spec/views/path.erb +2 -2
  236. data/lib/capybara/spec/views/popup_one.erb +1 -1
  237. data/lib/capybara/spec/views/popup_two.erb +1 -1
  238. data/lib/capybara/spec/views/react.erb +45 -0
  239. data/lib/capybara/spec/views/scroll.erb +21 -0
  240. data/lib/capybara/spec/views/spatial.erb +31 -0
  241. data/lib/capybara/spec/views/tables.erb +68 -1
  242. data/lib/capybara/spec/views/with_animation.erb +81 -0
  243. data/lib/capybara/spec/views/with_base_tag.erb +2 -2
  244. data/lib/capybara/spec/views/with_dragula.erb +24 -0
  245. data/lib/capybara/spec/views/with_fixed_header_footer.erb +2 -1
  246. data/lib/capybara/spec/views/with_hover.erb +3 -2
  247. data/lib/capybara/spec/views/with_hover1.erb +10 -0
  248. data/lib/capybara/spec/views/with_html.erb +46 -11
  249. data/lib/capybara/spec/views/with_html5_svg.erb +20 -0
  250. data/lib/capybara/spec/views/with_jquery_animation.erb +24 -0
  251. data/lib/capybara/spec/views/with_js.erb +30 -5
  252. data/lib/capybara/spec/views/with_jstree.erb +26 -0
  253. data/lib/capybara/spec/views/with_namespace.erb +21 -0
  254. data/lib/capybara/spec/views/with_scope.erb +2 -2
  255. data/lib/capybara/spec/views/with_scope_other.erb +6 -0
  256. data/lib/capybara/spec/views/with_shadow.erb +31 -0
  257. data/lib/capybara/spec/views/with_slow_unload.erb +2 -1
  258. data/lib/capybara/spec/views/with_sortable_js.erb +21 -0
  259. data/lib/capybara/spec/views/with_unload_alert.erb +1 -0
  260. data/lib/capybara/spec/views/with_windows.erb +1 -1
  261. data/lib/capybara/spec/views/within_frames.erb +1 -1
  262. data/lib/capybara/version.rb +1 -1
  263. data/lib/capybara/window.rb +32 -26
  264. data/lib/capybara.rb +128 -104
  265. data/spec/basic_node_spec.rb +59 -34
  266. data/spec/capybara_spec.rb +65 -51
  267. data/spec/counter_spec.rb +35 -0
  268. data/spec/css_builder_spec.rb +101 -0
  269. data/spec/css_splitter_spec.rb +38 -0
  270. data/spec/dsl_spec.rb +84 -55
  271. data/spec/filter_set_spec.rb +24 -7
  272. data/spec/fixtures/certificate.pem +25 -0
  273. data/spec/fixtures/key.pem +27 -0
  274. data/spec/fixtures/selenium_driver_rspec_failure.rb +5 -5
  275. data/spec/fixtures/selenium_driver_rspec_success.rb +5 -5
  276. data/spec/minitest_spec.rb +49 -5
  277. data/spec/minitest_spec_spec.rb +92 -62
  278. data/spec/per_session_config_spec.rb +6 -6
  279. data/spec/rack_test_spec.rb +183 -115
  280. data/spec/regexp_dissassembler_spec.rb +250 -0
  281. data/spec/result_spec.rb +99 -39
  282. data/spec/rspec/features_spec.rb +28 -25
  283. data/spec/rspec/scenarios_spec.rb +10 -6
  284. data/spec/rspec/shared_spec_matchers.rb +418 -364
  285. data/spec/rspec/views_spec.rb +4 -3
  286. data/spec/rspec_matchers_spec.rb +35 -10
  287. data/spec/rspec_spec.rb +109 -85
  288. data/spec/sauce_spec_chrome.rb +43 -0
  289. data/spec/selector_spec.rb +392 -62
  290. data/spec/selenium_spec_chrome.rb +183 -41
  291. data/spec/selenium_spec_chrome_remote.rb +96 -0
  292. data/spec/selenium_spec_edge.rb +41 -8
  293. data/spec/selenium_spec_firefox.rb +228 -0
  294. data/spec/selenium_spec_firefox_remote.rb +94 -0
  295. data/spec/selenium_spec_ie.rb +129 -11
  296. data/spec/selenium_spec_safari.rb +162 -0
  297. data/spec/server_spec.rb +192 -81
  298. data/spec/session_spec.rb +52 -16
  299. data/spec/shared_selenium_node.rb +79 -0
  300. data/spec/shared_selenium_session.rb +460 -123
  301. data/spec/spec_helper.rb +124 -2
  302. data/spec/whitespace_normalizer_spec.rb +54 -0
  303. data/spec/xpath_builder_spec.rb +93 -0
  304. metadata +344 -45
  305. data/.yard/templates_custom/default/class/html/selectors.erb +0 -38
  306. data/.yard/templates_custom/default/class/html/setup.rb +0 -17
  307. data/.yard/yard_extensions.rb +0 -78
  308. data/lib/capybara/rspec/compound.rb +0 -90
  309. data/lib/capybara/spec/session/assert_selector.rb +0 -149
  310. data/lib/capybara/spec/session/source_spec.rb +0 -0
  311. data/lib/capybara/spec/views/with_title.erb +0 -5
  312. data/spec/selenium_spec_marionette.rb +0 -143
@@ -5,50 +5,75 @@ module Capybara
5
5
  module Finders
6
6
  ##
7
7
  #
8
- # Find an {Capybara::Node::Element} based on the given arguments. +find+ will raise an error if the element
8
+ # Find an {Capybara::Node::Element} based on the given arguments. {#find} will raise an error if the element
9
9
  # is not found.
10
10
  #
11
- # @!macro waiting_behavior
12
- # If the driver is capable of executing JavaScript, +$0+ will wait for a set amount of time
13
- # and continuously retry finding the element until either the element is found or the time
14
- # expires. The length of time +find+ will wait is controlled through {Capybara.default_max_wait_time}
15
- # and defaults to 2 seconds.
16
- # @option options [false, Numeric] wait (Capybara.default_max_wait_time) Maximum time to wait for matching element to appear.
17
- #
18
- # +find+ takes the same options as +all+.
19
- #
20
11
  # page.find('#foo').find('.bar')
21
12
  # page.find(:xpath, './/div[contains(., "bar")]')
22
13
  # page.find('li', text: 'Quox').click_link('Delete')
23
14
  #
24
- # @param (see Capybara::Node::Finders#all)
15
+ # @param (see #all)
16
+ #
17
+ # @macro waiting_behavior
25
18
  #
26
- # @option options [Boolean] match The matching strategy to use.
19
+ # @!macro system_filters
20
+ # @option options [String, Regexp] text Only find elements which contain this text or match this regexp
21
+ # @option options [String, Regexp, String] exact_text
22
+ # When String the elements contained text must match exactly, when Boolean controls whether the `text` option must match exactly.
23
+ # Defaults to {Capybara.configure exact_text}.
24
+ # @option options [Boolean] normalize_ws
25
+ # Whether the `text`/`exact_text` options are compared against element text with whitespace normalized or as returned by the driver.
26
+ # Defaults to {Capybara.configure default_normalize_ws}.
27
+ # @option options [Boolean, Symbol] visible
28
+ # Only find elements with the specified visibility. Defaults to behavior indicated by {Capybara.configure ignore_hidden_elements}.
29
+ # * true - only finds visible elements.
30
+ # * false - finds invisible _and_ visible elements.
31
+ # * :all - same as false; finds visible and invisible elements.
32
+ # * :hidden - only finds invisible elements.
33
+ # * :visible - same as true; only finds visible elements.
34
+ # @option options [Boolean] obscured Only find elements with the specified obscured state:
35
+ # * true - only find elements whose centerpoint is not in the viewport or is obscured by another non-descendant element.
36
+ # * false - only find elements whose centerpoint is in the viewport and is not obscured by other non-descendant elements.
37
+ # @option options [String, Regexp] id Only find elements with an id that matches the value passed
38
+ # @option options [String, Array<String>, Regexp] class Only find elements with matching class/classes.
39
+ # * Absence of a class can be checked by prefixing the class name with `!`
40
+ # * If you need to check for existence of a class name that starts with `!` then prefix with `!!`
41
+ #
42
+ # class:['a', '!b', '!!!c'] # limit to elements with class 'a' and '!c' but not class 'b'
43
+ #
44
+ # @option options [String, Regexp, Hash] style Only find elements with matching style. String and Regexp will be checked against text of the elements `style` attribute, while a Hash will be compared against the elements full style
45
+ # @option options [Boolean] exact Control whether `is` expressions in the given XPath match exactly or partially. Defaults to {Capybara.configure exact}.
46
+ # @option options [Symbol] match The matching strategy to use. Defaults to {Capybara.configure match}.
27
47
  #
28
48
  # @return [Capybara::Node::Element] The found element
29
49
  # @raise [Capybara::ElementNotFound] If the element can't be found before time expires
30
50
  #
31
51
  def find(*args, **options, &optional_filter_block)
32
52
  options[:session_options] = session_options
33
- synced_resolve Capybara::Queries::SelectorQuery.new(*args, options, &optional_filter_block)
53
+ count_options = options.slice(*Capybara::Queries::BaseQuery::COUNT_KEYS)
54
+ unless count_options.empty?
55
+ Capybara::Helpers.warn(
56
+ "'find' does not support count options (#{count_options}) ignoring. " \
57
+ "Called from: #{Capybara::Helpers.filter_backtrace(caller)}"
58
+ )
59
+ end
60
+ synced_resolve Capybara::Queries::SelectorQuery.new(*args, **options, &optional_filter_block)
34
61
  end
35
62
 
36
63
  ##
37
64
  #
38
- # Find an {Capybara::Node::Element} based on the given arguments that is also an ancestor of the element called on. +ancestor+ will raise an error if the element
39
- # is not found.
65
+ # Find an {Capybara::Node::Element} based on the given arguments that is also an ancestor of the element called on.
66
+ # {#ancestor} will raise an error if the element is not found.
40
67
  #
41
- # +ancestor+ takes the same options as +find+.
68
+ # {#ancestor} takes the same options as {#find}.
42
69
  #
43
70
  # element.ancestor('#foo').find('.bar')
44
71
  # element.ancestor(:xpath, './/div[contains(., "bar")]')
45
72
  # element.ancestor('ul', text: 'Quox').click_link('Delete')
46
73
  #
47
- # @param (see Capybara::Node::Finders#find)
74
+ # @param (see #find)
48
75
  #
49
- # @!macro waiting_behavior
50
- #
51
- # @option options [Boolean] match The matching strategy to use.
76
+ # @macro waiting_behavior
52
77
  #
53
78
  # @return [Capybara::Node::Element] The found element
54
79
  # @raise [Capybara::ElementNotFound] If the element can't be found before time expires
@@ -60,22 +85,19 @@ module Capybara
60
85
 
61
86
  ##
62
87
  #
63
- # Find an {Capybara::Node::Element} based on the given arguments that is also a sibling of the element called on. +sibling+ will raise an error if the element
64
- # is not found.
88
+ # Find an {Capybara::Node::Element} based on the given arguments that is also a sibling of the element called on.
89
+ # {#sibling} will raise an error if the element is not found.
65
90
  #
66
- #
67
- # +sibling+ takes the same options as +find+.
91
+ # {#sibling} takes the same options as {#find}.
68
92
  #
69
93
  # element.sibling('#foo').find('.bar')
70
94
  # element.sibling(:xpath, './/div[contains(., "bar")]')
71
95
  # element.sibling('ul', text: 'Quox').click_link('Delete')
72
96
  #
73
- # @param (see Capybara::Node::Finders#find)
97
+ # @param (see #find)
74
98
  #
75
99
  # @macro waiting_behavior
76
100
  #
77
- # @option options [Boolean] match The matching strategy to use.
78
- #
79
101
  # @return [Capybara::Node::Element] The found element
80
102
  # @raise [Capybara::ElementNotFound] If the element can't be found before time expires
81
103
  #
@@ -88,8 +110,8 @@ module Capybara
88
110
  #
89
111
  # Find a form field on the page. The field can be found by its name, id or label text.
90
112
  #
91
- # @overload find_field([locator], options={})
92
- # @param [String] locator name, id, placeholder or text of associated label element
113
+ # @overload find_field([locator], **options)
114
+ # @param [String] locator name, id, {Capybara.configure test_id} attribute, placeholder or text of associated label element
93
115
  #
94
116
  # @macro waiting_behavior
95
117
  #
@@ -104,48 +126,47 @@ module Capybara
104
126
  # @option options [String, Regexp] with Value of field to match on
105
127
  # @option options [String] type Type of field to match on
106
128
  # @option options [Boolean] multiple Match fields that can have multiple values?
107
- # @option options [String] id Match fields that match the id attribute
129
+ # @option options [String, Regexp] id Match fields that match the id attribute
108
130
  # @option options [String] name Match fields that match the name attribute
109
131
  # @option options [String] placeholder Match fields that match the placeholder attribute
110
- # @option options [String, Array<String>] Match fields that match the class(es) passed
132
+ # @option options [String, Array<String>, Regexp] class Match fields that match the class(es) passed
111
133
  # @return [Capybara::Node::Element] The found element
112
134
  #
113
-
114
135
  def find_field(locator = nil, **options, &optional_filter_block)
115
- find(:field, locator, options, &optional_filter_block)
136
+ find(:field, locator, **options, &optional_filter_block)
116
137
  end
117
138
 
118
139
  ##
119
140
  #
120
141
  # Find a link on the page. The link can be found by its id or text.
121
142
  #
122
- # @overload find_link([locator], options={})
123
- # @param [String] locator id, title, text, or alt of enclosed img element
143
+ # @overload find_link([locator], **options)
144
+ # @param [String] locator id, {Capybara.configure test_id} attribute, title, text, or alt of enclosed img element
124
145
  #
125
146
  # @macro waiting_behavior
126
147
  #
127
- # @option options [String,Regexp,nil] href Value to match against the links href, if nil finds link placeholders (<a> elements with no href attribute)
128
- # @option options [String] id Match links with the id provided
148
+ # @option options [String,Regexp,nil] href Value to match against the links href, if `nil` finds link placeholders (`<a>` elements with no href attribute), if `false` ignores the href
149
+ # @option options [String, Regexp] id Match links with the id provided
129
150
  # @option options [String] title Match links with the title provided
130
151
  # @option options [String] alt Match links with a contained img element whose alt matches
131
- # @option options [String, Array<String>] class Match links that match the class(es) provided
152
+ # @option options [String, Boolean] download Match links with the download provided
153
+ # @option options [String] target Match links with the target provided
154
+ # @option options [String, Array<String>, Regexp] class Match links that match the class(es) provided
132
155
  # @return [Capybara::Node::Element] The found element
133
156
  #
134
157
  def find_link(locator = nil, **options, &optional_filter_block)
135
- find(:link, locator, options, &optional_filter_block)
158
+ find(:link, locator, **options, &optional_filter_block)
136
159
  end
137
160
 
138
161
  ##
139
162
  #
140
163
  # Find a button on the page.
141
- # This can be any \<input> element of type submit, reset, image, button or it can be a
142
- # \<button> element. All buttons can be found by their id, value, or title. \<button> elements can also be found
143
- # by their text content, and image \<input> elements by their alt attribute
144
- #
145
- # @overload find_button([locator], options={})
146
- # @param [String] locator id, value, title, text content, alt of image
164
+ # This can be any `<input>` element of type submit, reset, image, button or it can be a
165
+ # `<button>` element. All buttons can be found by their id, name, {Capybara.configure test_id} attribute, value, or title.
166
+ # `<button>` elements can also be found by their text content, and image `<input>` elements by their alt attribute.
147
167
  #
148
- # @overload find_button(options={})
168
+ # @overload find_button([locator], **options)
169
+ # @param [String] locator id, name, {Capybara.configure test_id} attribute, value, title, text content, alt of image
149
170
  #
150
171
  # @macro waiting_behavior
151
172
  #
@@ -153,14 +174,15 @@ module Capybara
153
174
  # * true - only finds a disabled button
154
175
  # * false - only finds an enabled button
155
176
  # * :all - finds either an enabled or disabled button
156
- # @option options [String] id Match buttons with the id provided
157
- # @option options [String] title Match buttons with the title provided
158
- # @option options [String] value Match buttons with the value provided
159
- # @option options [String, Array<String>] class Match buttons that match the class(es) provided
177
+ # @option options [String, Regexp] id Match buttons with the id provided
178
+ # @option options [String] name Match buttons with the name provided
179
+ # @option options [String] title Match buttons with the title provided
180
+ # @option options [String] value Match buttons with the value provided
181
+ # @option options [String, Array<String>, Regexp] class Match buttons that match the class(es) provided
160
182
  # @return [Capybara::Node::Element] The found element
161
183
  #
162
184
  def find_button(locator = nil, **options, &optional_filter_block)
163
- find(:button, locator, options, &optional_filter_block)
185
+ find(:button, locator, **options, &optional_filter_block)
164
186
  end
165
187
 
166
188
  ##
@@ -174,11 +196,11 @@ module Capybara
174
196
  # @return [Capybara::Node::Element] The found element
175
197
  #
176
198
  def find_by_id(id, **options, &optional_filter_block)
177
- find(:id, id, options, &optional_filter_block)
199
+ find(:id, id, **options, &optional_filter_block)
178
200
  end
179
201
 
180
202
  ##
181
- # @!method all([kind = Capybara.default_selector], locator = nil, options = {})
203
+ # @!method all([kind = Capybara.default_selector], locator = nil, **options)
182
204
  #
183
205
  # Find all elements on the page matching the given selector
184
206
  # and options.
@@ -190,9 +212,8 @@ module Capybara
190
212
  # page.all(:css, 'a#person_123')
191
213
  # page.all(:xpath, './/a[@id="person_123"]')
192
214
  #
193
- #
194
215
  # If the type of selector is left out, Capybara uses
195
- # {Capybara.default_selector}. It's set to :css by default.
216
+ # {Capybara.configure default_selector}. It's set to `:css` by default.
196
217
  #
197
218
  # page.all("a#person_123")
198
219
  #
@@ -205,56 +226,51 @@ module Capybara
205
226
  # page.all('a', text: 'Home')
206
227
  # page.all('#menu li', visible: true)
207
228
  #
208
- # By default Capybara's waiting behavior will wait up to `Capybara.default_max_wait_time`
229
+ # By default Capybara's waiting behavior will wait up to {Capybara.configure default_max_wait_time}
209
230
  # seconds for matching elements to be available and then return an empty result if none
210
231
  # are available. It is possible to set expectations on the number of results located and
211
232
  # Capybara will raise an exception if the number of elements located don't satisfy the
212
- # specified conditions. The expectations can be set using
233
+ # specified conditions. The expectations can be set using:
213
234
  #
214
235
  # page.assert_selector('p#foo', count: 4)
215
236
  # page.assert_selector('p#foo', maximum: 10)
216
237
  # page.assert_selector('p#foo', minimum: 1)
217
238
  # page.assert_selector('p#foo', between: 1..10)
218
239
  #
219
- # See {Capybara::Helpers#matches_count?} for additional information about
220
- # count matching.
221
- #
222
- # @param [Symbol] kind Optional selector type (:css, :xpath, :field, etc.) - Defaults to Capybara.default_selector
240
+ # @param [Symbol] kind Optional selector type (:css, :xpath, :field, etc.). Defaults to {Capybara.configure default_selector}.
223
241
  # @param [String] locator The locator for the specified selector
224
- # @option options [String, Regexp] text Only find elements which contain this text or match this regexp
225
- # @option options [String, Boolean] exact_text (Capybara.exact_text) When String the elements contained text must match exactly, when Boolean controls whether the :text option must match exactly
226
- # @option options [Boolean, Symbol] visible Only find elements with the specified visibility:
227
- # * true - only finds visible elements.
228
- # * false - finds invisible _and_ visible elements.
229
- # * :all - same as false; finds visible and invisible elements.
230
- # * :hidden - only finds invisible elements.
231
- # * :visible - same as true; only finds visible elements.
242
+ # @macro system_filters
243
+ # @macro waiting_behavior
232
244
  # @option options [Integer] count Exact number of matches that are expected to be found
233
245
  # @option options [Integer] maximum Maximum number of matches that are expected to be found
234
246
  # @option options [Integer] minimum Minimum number of matches that are expected to be found
235
247
  # @option options [Range] between Number of matches found must be within the given range
236
- # @option options [Boolean] exact Control whether `is` expressions in the given XPath match exactly or partially
237
- # @option options [Integer, false] wait (Capybara.default_max_wait_time) The time to wait for matching elements to become available
238
- # @overload all([kind = Capybara.default_selector], locator = nil, options = {})
239
- # @overload all([kind = Capybara.default_selector], locator = nil, options = {}, &filter_block)
248
+ # @option options [Boolean] allow_reload Beta feature - May be removed in any version.
249
+ # When `true` allows elements to be reloaded if they become stale. This is an advanced behavior and should only be used
250
+ # if you fully understand the potential ramifications. The results can be confusing on dynamic pages. Defaults to `false`
251
+ # @overload all([kind = Capybara.default_selector], locator = nil, **options)
252
+ # @overload all([kind = Capybara.default_selector], locator = nil, **options, &filter_block)
240
253
  # @yieldparam element [Capybara::Node::Element] The element being considered for inclusion in the results
241
254
  # @yieldreturn [Boolean] Should the element be considered in the results?
242
255
  # @return [Capybara::Result] A collection of found elements
243
256
  # @raise [Capybara::ExpectationNotMet] The number of elements found doesn't match the specified conditions
244
- def all(*args, **options, &optional_filter_block)
257
+ def all(*args, allow_reload: false, **options, &optional_filter_block)
245
258
  minimum_specified = options_include_minimum?(options)
246
259
  options = { minimum: 1 }.merge(options) unless minimum_specified
247
260
  options[:session_options] = session_options
248
- query = Capybara::Queries::SelectorQuery.new(*args.push(options), &optional_filter_block)
261
+ query = Capybara::Queries::SelectorQuery.new(*args, **options, &optional_filter_block)
249
262
  result = nil
250
263
  begin
251
264
  synchronize(query.wait) do
252
265
  result = query.resolve_for(self)
266
+ result.allow_reload! if allow_reload
253
267
  raise Capybara::ExpectationNotMet, result.failure_message unless result.matches_count?
268
+
254
269
  result
255
270
  end
256
271
  rescue Capybara::ExpectationNotMet
257
272
  raise if minimum_specified || (result.compare_count == 1)
273
+
258
274
  Result.new([], nil)
259
275
  end
260
276
  end
@@ -263,12 +279,12 @@ module Capybara
263
279
  ##
264
280
  #
265
281
  # Find the first element on the page matching the given selector
266
- # and options. By default `first` will wait up to `Capybara.default_max_wait_time`
282
+ # and options. By default {#first} will wait up to {Capybara.configure default_max_wait_time}
267
283
  # seconds for matching elements to appear and then raise an error if no matching
268
284
  # element is found, or `nil` if the provided count options allow for empty results.
269
285
  #
270
286
  # @overload first([kind], locator, options)
271
- # @param [:css, :xpath] kind The type of selector
287
+ # @param [Symbol] kind The type of selector
272
288
  # @param [String] locator The selector
273
289
  # @param [Hash] options Additional options; see {#all}
274
290
  # @return [Capybara::Node::Element] The found element or nil
@@ -290,23 +306,29 @@ module Capybara
290
306
  result = query.resolve_for(self)
291
307
  end
292
308
 
293
- raise Capybara::Ambiguous, "Ambiguous match, found #{result.size} elements matching #{query.description}" if ambiguous?(query, result)
294
- raise Capybara::ElementNotFound, "Unable to find #{query.description}" if result.empty?
309
+ if ambiguous?(query, result)
310
+ raise Capybara::Ambiguous, "Ambiguous match, found #{result.size} elements matching #{query.applied_description}"
311
+ end
312
+ raise Capybara::ElementNotFound, "Unable to find #{query.applied_description}" if result.empty?
295
313
 
296
314
  result.first
297
315
  end.tap(&:allow_reload!)
298
316
  end
299
317
 
300
318
  def ambiguous?(query, result)
301
- query.match == :one or query.match == :smart and result.size > 1
319
+ %i[one smart].include?(query.match) && (result.size > 1)
302
320
  end
303
321
 
304
322
  def prefer_exact?(query)
305
- query.match == :smart or query.match == :prefer_exact
323
+ %i[smart prefer_exact].include?(query.match)
306
324
  end
307
325
 
308
326
  def options_include_minimum?(opts)
309
- %i[count minimum between].any? { |k| opts.key?(k) }
327
+ %i[count minimum between].any? { |key| opts.key?(key) }
328
+ end
329
+
330
+ def parent
331
+ first(:xpath, './parent::*', minimum: 0)
310
332
  end
311
333
  end
312
334
  end