capybara 2.7.1 → 2.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 85d6a1e7f742859bc5336d455e804e941efbaffe
-  data.tar.gz: 9235385a6473080bb3ac0cae536857a054d323fc
+  metadata.gz: 0cbea94168c582ba31d25ccf5f24312005b47616
+  data.tar.gz: 7b779b6363ffb09be883cfe71ac2fde7cd616851
 SHA512:
-  metadata.gz: 301575ccd96eb6a4239441886571377806d911f0de5868fc3891f052518199fef15424eba03429e8bf7e7ba5d1abba62e6953ba7a171a66ba2e3a325824806a8
-  data.tar.gz: 3339a52f863d7417eaedae85e8e556d5359f40a04f4c628dc883ddadd517a04d62c0f40b3a0d2d6cf2600842a6f3f1bb011d1df5fe88a977278273ae7055a417
+  metadata.gz: 132688050a792bda11f9d4054aa5bac76e6f4070668f72c10bce230060d622e306e9eeb1b2bb079de66d428ca24f2814d07102083619db4e8f53075c473727a6
+  data.tar.gz: dbd2d43752dad9b40b2281ca1281cd3751e774ba6b785024f98c3c7c845637cdb76c36521343d16f338af34c21439cab00a76f837b32c4a1a88115f52a99e674

data/History.md

@@ -1,3 +1,25 @@
+# Version 2.8.0
+Release date: 2016-08-16
+
+### Fixed
+* Issue with modals present when closing the page using selenium - Issue #1696 [Jonas Nicklas, Thomas Walpole]
+* Server errors raised in test code have the cause set to an explanatory exception
+  in rubies that support Exception#cause rather than a confusing ExpectationNotMet - Issue #1719 [Thomas Walpole]
+* background/given/given! RSoec aliases will work if RSpec config.shared_context_metadata_behavior == :apply_to_host_groups [Thomas Walpole]
+* Fixed setting of unexpectedAlertError now that Selenium will be freezing the Capabilities::DEFAULTS [Thomas Walpole]
+
+### Added
+* 'check', 'uncheck', and 'choose' can now optionally click the associated label if the checkbox/radio button is not visible [Thomas Walpole]
+* Raise error if Capybara.app_host/default_host are specified incorrectly [Thomas Walpole]
+* Capybara::Selector::FilterSet allows for sharing filter definitions between selectors [Thomas Walpole]
+* Remove need to pass nil locator in most node actions when locator is not needed [Thomas Walpole]
+* New frames API for drivers - Issue #1365 [Thomas Walpole]
+* Deprecated Element#parent in favor of Element#query_scope to better indicate what it is [Thomas Walpole]
+* Improved error messages for have_text matcher [Alex Chaffee, Thomas Walpole]
+* The `:with` option for the field selector now accepts a regular expression for matching the field value [Uwe Kubosch]
+* Support matching on aria-label attribute when finding fields/links/buttons - Issue #1528 [Thomas Walpole]
+* Optimize Capybara::Result to only apply fields as necessary in common use-case of `.all[idx]` [Thomas Walpole]
+
 #Version 2.7.1
 Release date: 2016-05-01
 

data/README.md

@@ -3,6 +3,7 @@
 [![Build Status](https://secure.travis-ci.org/jnicklas/capybara.svg)](https://travis-ci.org/jnicklas/capybara)
 [![Dependency Status](https://gemnasium.com/jnicklas/capybara.svg)](https://gemnasium.com/jnicklas/capybara)
 [![Code Climate](https://codeclimate.com/github/jnicklas/capybara.svg)](https://codeclimate.com/github/jnicklas/capybara)
+[![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/jnicklas/capybara?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 
 Capybara helps you test web applications by simulating how a real user would
 interact with your app. It is agnostic about the driver running your tests and
@@ -12,6 +13,8 @@ through an external gem.
 **Need help?** Ask on the mailing list (please do not open an issue on
 GitHub): http://groups.google.com/group/ruby-capybara
 
+**Note: Firefox 48** If you're using Firefox with selenium-webdrvier, stay on Firefox 47.0.1 and selenium-webdriver 2.53.4.  Firefox 48 requires geckodriver and is not supported without selenium-webdriver 3 which currently has multiple issues and is feature incomplete
+
 ## Table of contents
 
 - [Key benefits](#key-benefits)
@@ -44,7 +47,7 @@ GitHub): http://groups.google.com/group/ruby-capybara
 - [Asynchronous JavaScript (Ajax and friends)](#asynchronous-javascript-ajax-and-friends)
 - [Using the DSL elsewhere](#using-the-dsl-elsewhere)
 - [Calling remote servers](#calling-remote-servers)
-- [Using the sessions manually](#using-the-sessions-manually)
+- [Using sessions](#using-sessions)
 - [XPath, CSS and selectors](#xpath-css-and-selectors)
 - [Beware the XPath // trap](#beware-the-xpath--trap)
 - [Configuring and adding drivers](#configuring-and-adding-drivers)
@@ -69,7 +72,7 @@ Capybara requires Ruby 1.9.3 or later. To install, add this line to your
 gem 'capybara'
 ```
 
-**Note:** If using Ruby < 2.0 you will also need to limit the version of mime-types to < 3.0
+**Note:** If using Ruby < 2.0 you will also need to limit the version of mime-types to < 3.0 and the version of rack to < 2.0
 
 If the application that you are testing is a Rails app, add this line to your test helper file:
 
@@ -818,7 +821,28 @@ remote application:
 Capybara.run_server = false
 ```
 
-## <a name="using-the-sessions-manually"></a>Using the sessions manually
+## <a name="using-sessions"></a>Using sessions
+
+Capybara manages named sessions (:default if not specified) allowing multiple sessions using the same driver and test app instance to be interacted with.
+A new session will be created using the current driver if a session with the given name using the current driver and test app instance is not found.
+
+### Named sessions
+To perform operations in a different session and then revert to the previous session
+
+```ruby
+Capybara.using_session("Bob's session") do
+   #do something in Bob's browser session
+end
+ #reverts to previous session
+```
+
+To permanently switch the current session to a different session
+
+```ruby
+Capybara.session_name = "some other session"
+````
+
+### <a name="using-sessions-manually"></a>Using sessions manually
 
 For ultimate control, you can instantiate and use a
 [Session](http://rubydoc.info/github/jnicklas/capybara/master/Capybara/Session)

data/lib/capybara.rb

@@ -20,10 +20,11 @@ module Capybara
   class ReadOnlyElementError < CapybaraError; end
 
   class << self
-    attr_accessor :asset_host, :app_host, :run_server, :default_host, :always_include_port
-    attr_accessor :server_port, :exact, :match, :exact_options, :visible_text_only
+    attr_reader :app_host, :default_host
+    attr_accessor :asset_host, :run_server, :always_include_port
+    attr_accessor :server_port, :exact, :match, :exact_options, :visible_text_only, :enable_aria_label
     attr_accessor :default_selector, :default_max_wait_time, :ignore_hidden_elements
-    attr_accessor :save_path, :wait_on_first_by_default, :automatic_reload
+    attr_accessor :save_path, :wait_on_first_by_default, :automatic_label_click, :automatic_reload
     attr_accessor :reuse_server, :raise_server_errors, :server_errors
     attr_writer :default_driver, :current_driver, :javascript_driver, :session_name, :server_host
     attr_reader :save_and_open_page_path
@@ -40,7 +41,7 @@ module Capybara
     #
     # === Configurable options
     #
-    # [app_host = String]                 The default host to use when giving a relative URL to visit
+    # [app_host = String/nil]             The default host to use when giving a relative URL to visit, must be a valid URL e.g. http://www.example.com
     # [always_include_port = Boolean]     Whether the Rack server's port should automatically be inserted into every visited URL (Default: false)
     # [asset_host = String]               Where dynamic assets are hosted - will be prepended to relative asset locations if present (Default: nil)
     # [run_server = Boolean]              Whether to start a Rack server for the given Rack app (Default: true)
@@ -52,6 +53,8 @@ module Capybara
     # [automatic_reload = Boolean]        Whether to automatically reload elements as Capybara is waiting (Default: true)
     # [save_path = String]  Where to put pages saved through save_(page|screenshot), save_and_open_(page|screenshot) (Default: Dir.pwd)
     # [wait_on_first_by_default = Boolean]   Whether Node#first defaults to Capybara waiting behavior for at least 1 element to match (Default: false)
+    # [automatic_label_click = Boolean]   Whether Node#choose, Node#check, Node#uncheck will attempt to click the associated label element if the checkbox/radio button are non-visible (Default: false)
+    # [enable_aria_label = Boolean]  Whether fields, links, and buttons will match against aria-label attribute (Default: false)
     # [reuse_server = Boolean]  Reuse the server thread between multiple sessions using the same app object (Default: true)
     # === DSL Options
     #
@@ -387,6 +390,16 @@ module Capybara
       @save_and_open_page_path = path
     end
 
+    def app_host=(url)
+      raise ArgumentError.new("Capybara.app_host should be set to a url (http://www.example.com)") unless url.nil? || (url =~ URI::regexp)
+      @app_host = url
+    end
+
+    def default_host=(url)
+      raise ArgumentError.new("Capybara.default_host should be set to a url (http://www.example.com)") unless url.nil? || (url =~ URI::regexp)
+      @default_host = url
+    end
+
     def included(base)
       base.send(:include, Capybara::DSL)
       warn "`include Capybara` is deprecated. Please use `include Capybara::DSL` instead."
@@ -487,6 +500,8 @@ Capybara.configure do |config|
   config.server_errors = [StandardError]
   config.visible_text_only = false
   config.wait_on_first_by_default = false
+  config.automatic_label_click = false
+  config.enable_aria_label = false
   config.reuse_server = true
 end
 

data/lib/capybara/driver/base.rb

@@ -48,8 +48,12 @@ class Capybara::Driver::Base
     raise Capybara::NotSupportedByDriverError, 'Capybara::Driver::Base#status_code'
   end
 
-  def within_frame(frame_handle)
-    raise Capybara::NotSupportedByDriverError, 'Capybara::Driver::Base#within_frame'
+  ##
+  #
+  # @param frame [Capybara::Node::Element, :parent, :top]  The iframe element to switch to
+  #
+  def switch_to_frame(frame)
+    raise Capybara::NotSupportedByDriverError, 'Capybara::Driver::Base#switch_to_frame'
   end
 
   def current_window_handle

data/lib/capybara/driver/node.rb

@@ -42,23 +42,23 @@ module Capybara
       def click
         raise NotImplementedError
       end
-      
+
       def right_click
         raise NotImplementedError
       end
-      
+
       def double_click
         raise NotImplementedError
       end
-      
+
       def send_keys(*args)
         raise NotImplementedError
       end
-      
+
       def hover
         raise NotImplementedError
       end
-      
+
       def drag_to(element)
         raise NotImplementedError
       end
@@ -83,6 +83,14 @@ module Capybara
         raise NotImplementedError
       end
 
+      def readonly?
+        !!self[:readonly]
+      end
+
+      def multiple?
+        !!self[:multiple]
+      end
+
       def path
         raise NotSupportedByDriverError, 'Capybara::Driver::Node#path'
       end

data/lib/capybara/helpers.rb

@@ -28,8 +28,8 @@ module Capybara
     # @param [String] text Text to escape
     # @return [String]     Escaped text
     #
-    def to_regexp(text)
-      text.is_a?(Regexp) ? text : Regexp.new(Regexp.escape(normalize_whitespace(text)))
+    def to_regexp(text, options=nil)
+      text.is_a?(Regexp) ? text : Regexp.new(Regexp.escape(normalize_whitespace(text)), options)
     end
 
     ##

data/lib/capybara/node/actions.rb

@@ -7,10 +7,19 @@ module Capybara
       #
       # Finds a button or link by id, text or value and clicks it. Also looks at image
       # alt text inside the link.
+      # @!macro waiting_behavior
+      #   If the driver is capable of executing JavaScript, +$0+ will wait for a set amount of time
+      #   and continuously retry finding the element until either the element is found or the time
+      #   expires. The length of time +find+ will wait is controlled through {Capybara.default_max_wait_time}
       #
-      # @param [String] locator      Text, id or value of link or button
+      #   @option options [false, Numeric] wait (Capybara.default_max_wait_time) Maximum time to wait for matching element to appear.
       #
-      def click_link_or_button(locator, options={})
+      # @overload click_link_or_button([locator], options)
+      #
+      #   @param [String] locator      Text, id or value of link or button
+      #
+      def click_link_or_button(locator=nil, options={})
+        locator, options = nil, locator if locator.is_a? Hash
         find(:link_or_button, locator, options).click
       end
       alias_method :click_on, :click_link_or_button
@@ -20,10 +29,14 @@ module Capybara
       # Finds a link by id, text or title and clicks it. Also looks at image
       # alt text inside the link.
       #
-      # @param [String] locator         text, id, title or nested image's alt attribute
-      # @param options                  See {Capybara::Node::Finders#find_link}
+      # @macro waiting_behavior
+      #
+      # @overload click_link([locator], options)
+      #   @param [String] locator         text, id, title or nested image's alt attribute
+      #   @param options                  See {Capybara::Node::Finders#find_link}
       #
-      def click_link(locator, options={})
+      def click_link(locator=nil, options={})
+        locator, options = nil, locator if locator.is_a? Hash
         find(:link, locator, options).click
       end
 
@@ -34,9 +47,13 @@ module Capybara
       # \<button> element. All buttons can be found by their id, value, or title. \<button> elements can also be found
       # by their text content, and image \<input> elements by their alt attribute
       #
-      # @param [String] locator      Which button to find
-      # @param options     See {Capybara::Node::Finders#find_button}
-      def click_button(locator, options={})
+      # @macro waiting_behavior
+      #
+      # @overload click_button([locator], options)
+      #   @param [String] locator      Which button to find
+      #   @param options     See {Capybara::Node::Finders#find_button}
+      def click_button(locator=nil, options={})
+        locator, options = nil, locator if locator.is_a? Hash
         find(:button, locator, options).click
       end
 
@@ -47,18 +64,28 @@ module Capybara
       #
       #     page.fill_in 'Name', :with => 'Bob'
       #
+      # @macro waiting_behavior
+      #
       # @param [String] locator                 Which field to fill in
       # @param [Hash] options
-      # @option options [String] :with     The value to fill in - required
-      # @option options [Hash] :fill_options Driver specific options regarding how to fill fields
+      # @option options [String] :with          The value to fill in - required
+      # @option options [Hash] :fill_options    Driver specific options regarding how to fill fields
+      # @option options [Boolean] :multiple      Match fields that can have multiple values?
+      # @option options [String] id             Match fields that match the id attribute
+      # @option options [String] name           Match fields that match the name attribute
+      # @option options [String] placeholder    Match fields that match the placeholder attribute
       #
       def fill_in(locator, options={})
+        locator, options = nil, locator if locator.is_a? Hash
         raise "Must pass a hash containing 'with'" if not options.is_a?(Hash) or not options.has_key?(:with)
         with = options.delete(:with)
         fill_options = options.delete(:fill_options)
         find(:fillable_field, locator, options).set(with, fill_options)
       end
 
+      # @!macro label_click
+      #   @option options [Boolean] :allow_label_click (Capybara.automatic_label_click) Attempt to click the label to toggle state if element is non-visible.
+
       ##
       #
       # Find a radio button and mark it as checked. The radio button can be found
@@ -66,10 +93,30 @@ module Capybara
       #
       #     page.choose('Male')
       #
-      # @param [String] locator           Which radio button to choose
+      # @overload choose([locator], options)
+      #   @param [String] locator           Which radio button to choose
       #
+      #   @option options [String] :option  Value of the radio_button to choose
+      #   @option options [String] id             Match fields that match the id attribute
+      #   @option options [String] name           Match fields that match the name attribute
+      #   @macro waiting_behavior
+      #   @macro label_click
       def choose(locator, options={})
-        find(:radio_button, locator, options).set(true)
+        locator, options = nil, locator if locator.is_a? Hash
+        allow_label_click = options.delete(:allow_label_click) { Capybara.automatic_label_click }
+
+        begin
+          find(:radio_button, locator, options).set(true)
+        rescue Capybara::ElementNotFound => e
+          raise unless allow_label_click
+          begin
+            radio = find(:radio_button, locator, options.merge({wait: 0, visible: :hidden}))
+            label = find(:label, for: radio, wait: 0, visible: true)
+            label.click unless radio.checked?
+          rescue
+            raise e
+          end
+        end
       end
 
       ##
@@ -79,10 +126,32 @@ module Capybara
       #
       #     page.check('German')
       #
-      # @param [String] locator           Which check box to check
+      #
+      # @overload check([locator], options)
+      #   @param [String] locator           Which check box to check
+      #
+      #   @option options [String] :option  Value of the checkbox to select
+      #   @option options [String] id       Match fields that match the id attribute
+      #   @option options [String] name     Match fields that match the name attribute
+      #   @macro label_click
+      #   @macro waiting_behavior
       #
       def check(locator, options={})
-        find(:checkbox, locator, options).set(true)
+        locator, options = nil, locator if locator.is_a? Hash
+        allow_label_click = options.delete(:allow_label_click) { Capybara.automatic_label_click }
+
+        begin
+          find(:checkbox, locator, options).set(true)
+        rescue Capybara::ElementNotFound => e
+          raise unless allow_label_click
+          begin
+            cbox = find(:checkbox, locator, options.merge({wait: 0, visible: :hidden}))
+            label = find(:label, for: cbox, wait: 0, visible: true)
+            label.click unless cbox.checked?
+          rescue
+            raise e
+          end
+        end
       end
 
       ##
@@ -92,10 +161,32 @@ module Capybara
       #
       #     page.uncheck('German')
       #
-      # @param [String] locator           Which check box to uncheck
+      #
+      # @overload uncheck([locator], options)
+      #   @param [String] locator           Which check box to uncheck
+      #
+      #   @option options [String] :option  Value of the checkbox to deselect
+      #   @option options [String] id       Match fields that match the id attribute
+      #   @option options [String] name     Match fields that match the name attribute
+      #   @macro label_click
+      #   @macro waiting_behavior
       #
       def uncheck(locator, options={})
-        find(:checkbox, locator, options).set(false)
+        locator, options = nil, locator if locator.is_a? Hash
+        allow_label_click = options.delete(:allow_label_click) { Capybara.automatic_label_click }
+
+        begin
+          find(:checkbox, locator, options).set(false)
+        rescue Capybara::ElementNotFound => e
+          raise unless allow_label_click
+          begin
+            cbox = find(:checkbox, locator, options.merge({wait: 0, visible: :hidden}))
+            label = find(:label, for: cbox, wait: 0, visible: true)
+            label.click if cbox.checked?
+          rescue
+            raise e
+          end
+        end
       end
 
       ##
@@ -109,6 +200,8 @@ module Capybara
       #
       #     page.select 'March', :from => 'Month'
       #
+      # @macro waiting_behavior
+      #
       # @param [String] value                   Which option to select
       # @option options [String] :from  The id, name or label of the select box
       #
@@ -129,6 +222,8 @@ module Capybara
       #
       #     page.unselect 'March', :from => 'Month'
       #
+      # @macro waiting_behavior
+      #
       # @param [String] value                   Which option to unselect
       # @param [Hash{:from => String}] options  The id, name or label of the select box
       #
@@ -148,15 +243,19 @@ module Capybara
       #
       #     page.attach_file(locator, '/path/to/file.png')
       #
+      # @macro waiting_behavior
+      #
       # @param [String] locator       Which field to attach the file to
       # @param [String] path          The path of the file that will be attached, or an array of paths
       #
       # @option options [Symbol] match (Capybara.match)     The matching strategy to use (:one, :first, :prefer_exact, :smart).
       # @option options [Boolean] exact (Capybara.exact)    Match the exact label name/contents or accept a partial match.
-      # @option options [Fixnum] wait (Capybara.default_max_wait_time)      If using a Javascript driver, maximum number of seconds during which the element will be searched for.
       # @option options [Boolean] multiple Match field which allows multiple file selection
+      # @option options [String] id             Match fields that match the id attribute
+      # @option options [String] name           Match fields that match the name attribute
       #
       def attach_file(locator, path, options={})
+        locator, path, options = nil, locator, path if path.is_a? Hash
         Array(path).each do |p|
           raise Capybara::FileNotFound, "cannot attach file, #{p} does not exist" unless File.exist?(p.to_s)
         end