capybara 2.5.0 → 2.18.0

data/lib/capybara/minitest.rb

@@ -0,0 +1,278 @@
+# frozen_string_literal: true
+require 'minitest'
+require 'capybara/dsl'
+
+module Capybara
+  module Minitest
+    module Assertions
+      ## Assert text exists
+      #
+      # @!method assert_text
+      #  see {Capybara::Node::Matchers#assert_text}
+
+      ## Assert text does not exist
+      #
+      # @!method assert_no_text
+      #  see {Capybara::Node::Matchers#assert_no_text}
+
+      ##
+      # Assertion that page title does match
+      #
+      # @!method assert_title
+      #   see {Capybara::Node::DocumentMatchers#assert_title}
+
+      ##
+      # Assertion that page title does not match
+      #
+      # @!method refute_title
+      # @!method assert_no_title
+      #   see {Capybara::Node::DocumentMatchers#assert_no_title}
+
+      ##
+      # Assertion that current path matches
+      #
+      # @!method assert_current_path
+      #   see {Capybara::SessionMatchers#assert_current_path}
+
+      ##
+      # Assertion that current page does not match
+      #
+      # @!method refute_current_path
+      # @!method assert_no_current_path
+      #   see {Capybara::SessionMatchers#assert_no_current_path}
+
+
+      %w(assert_text assert_no_text assert_title assert_no_title assert_current_path assert_no_current_path).each do |assertion_name|
+        self.class_eval <<-EOM, __FILE__, __LINE__ + 1
+          def #{assertion_name} *args
+            self.assertions +=1
+            subject, *args = determine_subject(args)
+            subject.#{assertion_name}(*args)
+          rescue Capybara::ExpectationNotMet => e
+            raise ::Minitest::Assertion, e.message
+          end
+        EOM
+      end
+
+      alias_method :refute_title, :assert_no_title
+      alias_method :refute_text, :assert_no_text
+      alias_method :refute_content, :refute_text
+      alias_method :refute_current_path, :assert_no_current_path
+      alias_method :assert_content, :assert_text
+      alias_method :assert_no_content, :refute_text
+
+      ## Assert selector exists on page
+      #
+      # @!method assert_selector
+      #   see {Capybara::Node::Matchers#assert_selector}
+
+      ## Assert selector does not exist on page
+      #
+      # @!method assert_no_selector
+      #   see {Capybara::Node::Matchers#assert_no_selector}
+
+      ## Assert element matches selector
+      #
+      # @!method assert_matches_selector
+      #   see {Capybara::Node::Matchers#assert_matches_selector}
+
+      ## Assert element does not match selector
+      #
+      # @!method assert_xpath
+      #   see {Capybara::Node::Matchers#assert_not_matches_selector}
+
+      %w(assert_selector assert_no_selector
+         assert_all_of_selectors assert_none_of_selectors
+         assert_matches_selector assert_not_matches_selector).each do |assertion_name|
+        self.class_eval <<-EOM, __FILE__, __LINE__ + 1
+          def #{assertion_name} *args, &optional_filter_block
+            self.assertions +=1
+            subject, *args = determine_subject(args)
+            subject.#{assertion_name}(*args, &optional_filter_block)
+          rescue Capybara::ExpectationNotMet => e
+            raise ::Minitest::Assertion, e.message
+          end
+        EOM
+      end
+
+      alias_method :refute_selector, :assert_no_selector
+      alias_method :refute_matches_selector, :assert_not_matches_selector
+
+      %w(xpath css link button field select table).each do |selector_type|
+        define_method "assert_#{selector_type}" do |*args, &optional_filter_block|
+          subject, *args = determine_subject(args)
+          locator, options = extract_locator(args)
+          assert_selector(subject, selector_type.to_sym, locator, options, &optional_filter_block)
+        end
+
+        define_method "assert_no_#{selector_type}" do |*args, &optional_filter_block|
+          subject, *args = determine_subject(args)
+          locator, options = extract_locator(args)
+          assert_no_selector(subject, selector_type.to_sym, locator, options, &optional_filter_block)
+        end
+        alias_method "refute_#{selector_type}", "assert_no_#{selector_type}"
+      end
+
+      %w(checked unchecked).each do |field_type|
+        define_method "assert_#{field_type}_field" do |*args, &optional_filter_block|
+          subject, *args = determine_subject(args)
+          locator, options = extract_locator(args)
+          assert_selector(subject, :field, locator, options.merge(field_type.to_sym => true), &optional_filter_block)
+        end
+
+        define_method "assert_no_#{field_type}_field" do |*args, &optional_filter_block|
+          subject, *args = determine_subject(args)
+          locator, options = extract_locator(args)
+          assert_no_selector(subject, :field, locator, options.merge(field_type.to_sym => true), &optional_filter_block)
+        end
+        alias_method "refute_#{field_type}_field", "assert_no_#{field_type}_field"
+      end
+
+      %w(xpath css).each do |selector_type|
+        define_method "assert_matches_#{selector_type}" do |*args, &optional_filter_block|
+          subject, *args = determine_subject(args)
+          assert_matches_selector(subject, selector_type.to_sym, *args, &optional_filter_block)
+        end
+
+        define_method "assert_not_matches_#{selector_type}" do |*args, &optional_filter_block|
+          subject, *args = determine_subject(args)
+          assert_not_matches_selector(subject, selector_type.to_sym, *args, &optional_filter_block)
+        end
+        alias_method "refute_matches_#{selector_type}", "assert_not_matches_#{selector_type}"
+      end
+
+
+      ##
+      # Assertion that there is xpath
+      #
+      # @!method assert_xpath
+      #   see Capybara::Node::Matchers#has_xpath?
+
+      ##
+      # Assertion that there is no xpath
+      #
+      # @!method refute_xpath
+      # @!method assert_no_xpath
+      #   see Capybara::Node::Matchers#has_no_xpath?
+
+      ##
+      # Assertion that there is css
+      #
+      # @!method assert_css
+      #   see Capybara::Node::Matchers#has_css?
+
+      ##
+      # Assertion that there is no css
+      #
+      # @!method refute_css
+      # @!method assert_no_css
+      #   see Capybara::Node::Matchers#has_no_css?
+
+      ##
+      # Assertion that there is link
+      #
+      # @!method assert_link
+      #   see {Capybara::Node::Matchers#has_link?}
+
+      ##
+      # Assertion that there is no link
+      #
+      # @!method assert_no_link
+      # @!method refute_link
+      # see {Capybara::Node::Matchers#has_no_link?}
+
+      ##
+      # Assertion that there is button
+      #
+      # @!method assert_button
+      #   see {Capybara::Node::Matchers#has_button?}
+
+      ##
+      # Assertion that there is no button
+      #
+      # @!method refute_button
+      # @!method assert_no_button
+      #   see {Capybara::Node::Matchers#has_no_button?}
+
+      ##
+      # Assertion that there is field
+      #
+      # @!method assert_field
+      #   see {Capybara::Node::Matchers#has_field?}
+
+      ##
+      # Assertion that there is no field
+      #
+      # @!method refute_field
+      # @!method assert_no_field
+      #   see {Capybara::Node::Matchers#has_no_field?}
+
+      ##
+      # Assertion that there is checked_field
+      #
+      # @!method assert_checked_field
+      #   see {Capybara::Node::Matchers#has_checked_field?}
+
+      ##
+      # Assertion that there is no checked_field
+      #
+      # @!method assert_no_checked_field
+      # @!method refute_checked_field
+
+      ##
+      # Assertion that there is unchecked_field
+      #
+      # @!method assert_unchecked_field
+      #   see {Capybara::Node::Matchers#has_unchecked_field?}
+
+      ##
+      # Assertion that there is no unchecked_field
+      #
+      # @!method assert_no_unchecked_field
+      # @!method refute_unchecked_field
+
+      ##
+      # Assertion that there is select
+      #
+      # @!method assert_select
+      #   see {Capybara::Node::Matchers#has_select?}
+
+      ##
+      # Assertion that there is no select
+      #
+      # @!method refute_select
+      # @!method assert_no_select
+      #   see {Capybara::Node::Matchers#has_no_select?}
+
+      ##
+      # Assertion that there is table
+      #
+      # @!method assert_table
+      #   see {Capybara::Node::Matchers#has_table?}
+
+      ##
+      # Assertion that there is no table
+      #
+      # @!method refute_table
+      # @!method assert_no_table
+      #   see {Capybara::Node::Matchers#has_no_table?}
+
+      private
+
+      def determine_subject(args)
+        case args.first
+        when Capybara::Session, Capybara::Node::Base, Capybara::Node::Simple
+          args
+        else
+          [page, *args]
+        end
+      end
+
+      def extract_locator(args)
+        locator, options = *args, {}
+        locator, options = nil, locator if locator.is_a? Hash
+        [locator, options]
+      end
+    end
+  end
+end

data/lib/capybara/node/actions.rb

@@ -1,15 +1,27 @@
+# frozen_string_literal: true
 module Capybara
   module Node
     module Actions
 
       ##
       #
-      # Finds a button or link by id, text or value and clicks it. Also looks at image
-      # alt text inside the link.
+      # Finds a button or link and clicks it.  See {Capybara::Node::Actions#click_button} and
+      # {Capybara::Node::Actions#click_link} for what locator will match against for each type of element
+      # @!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}
+      #
+      #   @option options [false, Numeric] wait (Capybara.default_max_wait_time) Maximum time to wait for matching element to appear.
+      #
+      # @overload click_link_or_button([locator], options)
+      #
+      #   @param [String] locator      See {Capybara::Node::Actions#click_button} and {Capybara::Node::Actions#click_link}
       #
-      # @param [String] locator      Text, id or value of link or button
+      # @return [Capybara::Node::Element]  The element clicked
       #
-      def click_link_or_button(locator, options={})
+      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
@@ -19,10 +31,15 @@ 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
       #
-      def click_link(locator, options={})
+      # @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}
+      #
+      # @return [Capybara::Node::Element]  The element clicked
+      def click_link(locator=nil, options={})
+        locator, options = nil, locator if locator.is_a? Hash
         find(:link, locator, options).click
       end
 
@@ -33,9 +50,14 @@ 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}
+      # @return [Capybara::Node::Element]  The element clicked
+      def click_button(locator=nil, options={})
+        locator, options = nil, locator if locator.is_a? Hash
         find(:button, locator, options).click
       end
 
@@ -44,20 +66,35 @@ module Capybara
       # Locate a text field or text area and fill it in with the given text
       # The field can be found via its name, id or label text.
       #
-      #     page.fill_in 'Name', :with => 'Bob'
+      #     page.fill_in 'Name', with: 'Bob'
       #
-      # @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
       #
+      # @overload fill_in([locator], options={})
+      #   @param [String] locator                 Which field to fill in
+      #   @param [Hash] options
+      #   @macro waiting_behavior
+      #   @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] :currently_with The current value property of the field to fill in
+      #   @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
+      #   @option options [String, Array<String>] :class    Match fields that match the class(es) provided
+      #
+      # @return [Capybara::Node::Element]  The element filled_in
       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)
+        options[:with] = options.delete(:currently_with) if options.has_key?(:currently_with)
         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
@@ -65,10 +102,19 @@ 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
+      #   @option options [String, Array<String>] :class    Match fields that match the class(es) provided
+      #   @macro waiting_behavior
+      #   @macro label_click
+      #
+      # @return [Capybara::Node::Element]  The element chosen or the label clicked
       def choose(locator, options={})
-        find(:radio_button, locator, options).set(true)
+        _check_with_label(:radio_button, true, locator, options)
       end
 
       ##
@@ -78,10 +124,20 @@ 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
+      #   @option options [String, Array<String>] :class    Match fields that match the class(es) provided
+      #   @macro label_click
+      #   @macro waiting_behavior
+      #
+      # @return [Capybara::Node::Element]  The element checked or the label clicked
       def check(locator, options={})
-        find(:checkbox, locator, options).set(true)
+        _check_with_label(:checkbox, true, locator, options)
       end
 
       ##
@@ -91,10 +147,20 @@ 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
+      #   @option options [String, Array<String>] :class    Match fields that match the class(es) provided
+      #   @macro label_click
+      #   @macro waiting_behavior
+      #
+      # @return [Capybara::Node::Element]  The element unchecked or the label clicked
       def uncheck(locator, options={})
-        find(:checkbox, locator, options).set(false)
+        _check_with_label(:checkbox, false, locator, options)
       end
 
       ##
@@ -106,11 +172,14 @@ module Capybara
       # one option.
       # The select box can be found via its name, id or label text. The option can be found by its text.
       #
-      #     page.select 'March', :from => 'Month'
+      #     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
       #
+      # @return [Capybara::Node::Element]  The option element selected
       def select(value, options={})
         if options.has_key?(:from)
           from = options.delete(:from)
@@ -126,11 +195,14 @@ module Capybara
       # box is a multiple select, +unselect+ can be called multiple times to unselect more than
       # one option. The select box can be found via its name, id or label text.
       #
-      #     page.unselect 'March', :from => 'Month'
+      #     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
       #
+      # @return [Capybara::Node::Element]  The option element unselected
       def unselect(value, options={})
         if options.has_key?(:from)
           from = options.delete(:from)
@@ -147,15 +219,99 @@ 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 [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
+      # @option options [String, Array<String>] :class    Match fields that match the class(es) provided
+      # @option options [true, Hash] make_visible   A Hash of CSS styles to change before attempting to attach the file, if `true` { opacity: 1, display: 'block', visibility: 'visible' } is used (may not be supported by all drivers)
+      #
+      # @return [Capybara::Node::Element]  The file field element
       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
-        find(:file_field, locator, options).set(path)
+        # Allow user to update the CSS style of the file input since they are so often hidden on a page
+        if style = options.delete(:make_visible)
+          style = { opacity: 1, display: 'block', visibility: 'visible' } if style == true
+          ff = find(:file_field, locator, options.merge({visible: :all}))
+          _update_style(ff, style)
+          if ff.visible?
+            begin
+              ff.set(path)
+            ensure
+              _reset_style(ff)
+            end
+          else
+            raise ExpectationNotMet, "The style changes in :make_visible did not make the file input visible"
+          end
+        else
+          find(:file_field, locator, options).set(path)
+        end
+      end
+
+    private
+      def _update_style(element, style)
+        script = <<-JS
+          var el = arguments[0];
+          el.capybara_style_cache = el.style.cssText;
+          var css = arguments[1];
+          for (var prop in css){
+            if (css.hasOwnProperty(prop)) {
+              el.style[prop] = css[prop]
+            }
+          }
+        JS
+        begin
+          session.execute_script(script, element, style)
+        rescue Capybara::NotSupportedByDriverError
+          warn "The :make_visible option is not supported by the current driver - ignoring"
+        end
       end
+
+      def _reset_style(element)
+        script = <<-JS
+          var el = arguments[0];
+          if (el.hasOwnProperty('capybara_style_cache')) {
+            el.style.cssText = el.capybara_style_cache;
+            delete el.capybara_style_cache;
+          }
+        JS
+        begin
+          session.execute_script(script, element)
+        rescue
+        end
+      end
+
+
+      def _check_with_label(selector, checked, locator, options)
+        locator, options = nil, locator if locator.is_a? Hash
+        allow_label_click = options.delete(:allow_label_click) { session_options.automatic_label_click }
+
+        synchronize(Capybara::Queries::BaseQuery.wait(options, session_options.default_max_wait_time)) do
+          begin
+            el = find(selector, locator, options)
+            el.set(checked)
+          rescue => e
+            raise unless allow_label_click && catch_error?(e)
+            begin
+              el ||= find(selector, locator, options.merge(visible: :all))
+              label = find(:label, for: el, visible: true)
+              label.click unless (el.checked? == checked)
+            rescue
+              raise e
+            end
+          end
+        end
+      end
+
     end
   end
 end

data/lib/capybara/node/base.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module Capybara
   module Node
 
@@ -16,13 +17,13 @@ module Capybara
     #
     #     session = Capybara::Session.new(:rack_test, my_app)
     #     session.visit('/')
-    #     session.fill_in('Foo', :with => 'Bar')    # from Capybara::Node::Actions
+    #     session.fill_in('Foo', with: 'Bar')    # from Capybara::Node::Actions
     #     bar = session.find('#bar')                # from Capybara::Node::Finders
-    #     bar.select('Baz', :from => 'Quox')        # from Capybara::Node::Actions
+    #     bar.select('Baz', from: 'Quox')        # from Capybara::Node::Actions
     #     session.has_css?('#foobar')               # from Capybara::Node::Matchers
     #
     class Base
-      attr_reader :session, :base, :parent
+      attr_reader :session, :base, :query_scope
 
       include Capybara::Node::Finders
       include Capybara::Node::Actions
@@ -73,7 +74,7 @@ module Capybara
       # @return [Object]                  The result of the given block
       # @raise  [Capybara::FrozenInTime]  If the return value of `Time.now` appears stuck
       #
-      def synchronize(seconds=Capybara.default_max_wait_time, options = {})
+      def synchronize(seconds=session_options.default_max_wait_time, options = {})
         start_time = Capybara::Helpers.monotonic_time
 
         if session.synchronized
@@ -89,7 +90,7 @@ module Capybara
             raise e if (Capybara::Helpers.monotonic_time - start_time) >= seconds
             sleep(0.05)
             raise Capybara::FrozenInTime, "time appears to be frozen, Capybara does not work with libraries which freeze time, consider using time travelling instead" if Capybara::Helpers.monotonic_time == start_time
-            reload if Capybara.automatic_reload
+            reload if session_options.automatic_reload
             retry
           ensure
             session.synchronized = false
@@ -107,6 +108,17 @@ module Capybara
         base.find_xpath(xpath)
       end
 
+      # @deprecated Use query_scope instead
+      def parent
+        warn "DEPRECATED: #parent is deprecated in favor of #query_scope - Note: #parent was not the elements parent in the document so it's most likely not what you wanted anyway"
+        query_scope
+      end
+
+      # @api private
+      def session_options
+        session.config
+      end
+
     protected
 
       def catch_error?(error, errors = nil)

data/lib/capybara/node/document.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module Capybara
   module Node
 
@@ -23,6 +24,10 @@ module Capybara
         find(:xpath, '/html').text(type)
       end
 
+      ##
+      #
+      # @return [String]    The title of the document
+      #
       def title
         session.driver.title
       end