capybara 3.12.0 → 3.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8b3b4d3a612269d9ee165e7ed94e1e62f91c6fd85bcc5c5ae614c25d0c22bd32
-  data.tar.gz: a2bdfa0c2398789bd15d791e3b2d0d03d9c3371033e4f4e4d21e302db845c93f
+  metadata.gz: da79991ce86301cce84e97c31e9c46424309edfaaef6c1f52316d78408673340
+  data.tar.gz: 0dbf02750a107ebc011c9899a60e5958099444f897cca384607919b58554dc9b
 SHA512:
-  metadata.gz: f4815632f5bc14c932e9b5181d68584ac3088f11241e8ee3c19f3ee0a27190f8ad1544b88a532f901eaf79f9ae3c2f721dfca1d2d6d20d098a40438042b9f64a
-  data.tar.gz: eb2765462cdbdda76a4ca5d100b93688029d1ca727c00579c5e9e5d77f26fc4a0fe64bbe3616bb3f89b34e730c337e242b319b2ea606b5287a780f8219ee5b08
+  metadata.gz: 3718591ef61c25cadb6de5048b73095340b2fa983d0f978e016ec3da1348ea88bcac5797e717b2c8053e2804b7b94aa27b46e3b57ce40fcdfa33cf70fca43d52
+  data.tar.gz: 5cf850913d7c0624002f969bfc3c87661a30b475b9a35decb2d607a7be82456f406f1c3490a803d30cd3f573dccdece7ad66ef8d46be36a347476af01f9ce7b8

data/History.md

@@ -1,3 +1,16 @@
+# Version 3.13.0
+Release date: 2019-01-23
+
+### Added
+
+* Session#quit added
+* #scroll_to added to allow scrolling page/elements to specified locations
+* Speed optimizations around multiple element location and path generation when using the Selenium driver
+* Support for locator type checking in custom selectors
+* Allow configuration of gumbo use - defaults to off
+* `assert_style`/`has_style`/`have_style` depreacted in favor of `assert_matches_style`/`matches_styles?`/`match_style`
+* :style filter added to selectors
+
 # Version 3.12.0
 Release date: 2018-11-28
 

data/README.md

@@ -6,7 +6,7 @@
 [![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)
 [![SemVer](https://api.dependabot.com/badges/compatibility_score?dependency-name=capybara&package-manager=bundler&version-scheme=semver)](https://dependabot.com/compatibility-score.html?dependency-name=capybara&package-manager=bundler&version-scheme=semver)
 
-**Note** You are viewing the README for the 3.12.x version of Capybara.
+**Note** You are viewing the README for the version 3.13.x of Capybara.
 
 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
@@ -35,6 +35,7 @@ GitHub): http://groups.google.com/group/ruby-capybara
     - [Selecting the Driver](#selecting-the-driver)
     - [RackTest](#racktest)
     - [Selenium](#selenium)
+    - [Apparition](#apparition)
     - [Capybara-webkit](#capybara-webkit)
     - [Poltergeist](#poltergeist)
 - [The DSL](#the-dsl)
@@ -217,7 +218,7 @@ feature "Signing in" do
 end
 ```
 
-`feature` is in fact just an alias for `describe ..., type:> :feature`,
+`feature` is in fact just an alias for `describe ..., type: :feature`,
 `background` is an alias for `before`, `scenario` for `it`, and
 `given`/`given!` aliases for `let`/`let!`, respectively.
 
@@ -406,6 +407,15 @@ to the browsers.  See the section on adding and configuring drivers.
 same transaction as your tests, causing data not to be shared between your test
 and test server, see [Transactions and database setup](#transactions-and-database-setup) below.
 
+### <a name="apparition"></a>Apparition
+
+The [apparition driver](https://github.com/twalpole/apparition) in a new driver thatallows you to run tests using Chrome in a headless
+or headed configuration. It attempts to provide backwards compatibility with the [Poltergeist driver API](https://github.com/teampoltergeist/poltergeist)
+while allowing for the use of modern JS/CSS. It uses CDP to communicate with Chrome, thereby obviating the need for chromedriver.
+A compatibility layer for capybara-webkit is planned, although has not yet been started. This driver is being developed by the
+maintainer of Capybara and will attempt to keep up to date with new Capybara releases. It will probably be moved into the
+teamcapybara repo once completely stable.
+
 ### <a name="capybara-webkit"></a>Capybara-webkit
 
 Note: `capybara-webkit` depends on QtWebkit which went EOL quite some time ago. There has been an attempt to revive the project but `capybara-webkit` is not yet (AFAIK) compatible with the revived version of QtWebKit (could be a good OSS project for someone) and as such is still limited to an old version of QtWebKit.  This means its support for modern JS and CSS is severely limited.
@@ -428,7 +438,7 @@ Capybara.javascript_driver = :webkit
 
 ### <a name="poltergeist"></a>Poltergeist
 
-Note: `poltergeist` depends on PhantomJS for which active development ended quite some time ago (2.1.1). As such it is roughly equivalent to a 6-7 year old version of Safari, meaning lack of support for modern JS And CSS. If any effort to update PhantomJS succeeds in the future this situation could change.
+Note: `poltergeist` depends on PhantomJS for which active development ended quite some time ago (2.1.1). As such it is roughly equivalent to a 6-7 year old version of Safari, meaning lack of support for modern JS and CSS. If any effort to update PhantomJS succeeds in the future this situation could change.
 
 [Poltergeist](https://github.com/teampoltergeist/poltergeist) is another
 headless driver which integrates Capybara with

data/lib/capybara.rb

@@ -38,6 +38,8 @@ module Capybara
     #   See {Capybara.configure}
     # @!method javascript_driver
     #   See {Capybara.configure}
+    # @!method allow_gumbo
+    #   See {Capybara.configure}
     Config::OPTIONS.each do |method|
       def_delegators :config, method, "#{method}="
     end
@@ -86,6 +88,7 @@ module Capybara
     # [test_id = Symbol/String/nil] Optional attribute to match locator aginst with builtin selectors along with id (Default: nil)
     # [predicates_wait = Boolean]  Whether Capybaras predicate matchers use waiting behavior by default (Default: true)
     # [default_normalize_ws = Boolean] Whether text predicates and matchers use normalize whitespace behaviour (Default: false)
+    # [allow_gumbo = Boolean] When `nokogumbo` is available, whether it will be used to parse HTML strings (Default: false)
     #
     # === DSL Options
     #
@@ -162,8 +165,8 @@ module Capybara
     # @param [Symbol] name    The name of the selector to add
     # @yield                  A block executed in the context of the new {Capybara::Selector}
     #
-    def add_selector(name, &block)
-      Capybara::Selector.add(name, &block)
+    def add_selector(name, **options, &block)
+      Capybara::Selector.add(name, **options, &block)
     end
 
     ##
@@ -173,7 +176,7 @@ module Capybara
     # button style (a class) might look like this
     #
     #     Capybara.modify_selector(:button) do
-    #       filter (:style, valid_values: [:primary, :secondary]) { |node, style| node[:class].split.include? "btn-#{style}" }
+    #       filter (:btn_style, valid_values: [:primary, :secondary]) { |node, style| node[:class].split.include? "btn-#{style}" }
     #     end
     #
     #
@@ -366,7 +369,7 @@ module Capybara
     # @return [Nokogiri::HTML::Document]      HTML document
     #
     def HTML(html) # rubocop:disable Naming/MethodName
-      if Nokogiri.respond_to?(:HTML5) # Nokogumbo installed
+      if Nokogiri.respond_to?(:HTML5) && Capybara.allow_gumbo # Nokogumbo installed and allowed for use
         Nokogiri::HTML5(html).tap do |document|
           document.xpath('//textarea').each do |textarea|
             # The Nokogumbo HTML5 parser already returns spec compliant contents
@@ -522,6 +525,7 @@ Capybara.configure do |config|
   config.test_id = nil
   config.predicates_wait = true
   config.default_normalize_ws = false
+  config.allow_gumbo = false
 end
 
 Capybara.register_driver :rack_test do |app|

data/lib/capybara/config.rb

@@ -7,12 +7,14 @@ module Capybara
   class Config
     extend Forwardable
 
-    OPTIONS = %i[app reuse_server threadsafe default_wait_time server default_driver javascript_driver].freeze
+    OPTIONS = %i[app reuse_server threadsafe default_wait_time server
+                 default_driver javascript_driver allow_gumbo].freeze
 
     attr_accessor :app
     attr_reader :reuse_server, :threadsafe
     attr_reader :session_options
     attr_writer :default_driver, :javascript_driver
+    attr_accessor :allow_gumbo
 
     SessionConfig::OPTIONS.each do |method|
       def_delegators :session_options, method, "#{method}="

data/lib/capybara/driver/base.rb

@@ -15,11 +15,11 @@ class Capybara::Driver::Base
     raise NotImplementedError
   end
 
-  def find_xpath(query)
+  def find_xpath(query, **options)
     raise NotImplementedError
   end
 
-  def find_css(query)
+  def find_css(query, **options)
     raise NotImplementedError
   end
 

data/lib/capybara/driver/node.rb

@@ -3,11 +3,12 @@
 module Capybara
   module Driver
     class Node
-      attr_reader :driver, :native
+      attr_reader :driver, :native, :initial_cache
 
-      def initialize(driver, native)
+      def initialize(driver, native, initial_cache = {})
         @driver = driver
         @native = native
+        @initial_cache = initial_cache
       end
 
       def all_text
@@ -68,6 +69,14 @@ module Capybara
         raise NotImplementedError
       end
 
+      def scroll_by(x, y)
+        raise NotImplementedError
+      end
+
+      def scroll_to(element, alignment, position = nil)
+        raise NotImplementedError
+      end
+
       def tag_name
         raise NotImplementedError
       end

data/lib/capybara/minitest.rb

@@ -83,10 +83,10 @@ module Capybara
 
       ## Assert element has the provided CSS styles
       #
-      # @!method assert_style
-      #   see {Capybara::Node::Matchers#assert_style}
+      # @!method assert_matches_style
+      #   see {Capybara::Node::Matchers#assert_matches_style}
 
-      %w[selector no_selector style
+      %w[selector no_selector matches_style
          all_of_selectors none_of_selectors any_of_selectors
          matches_selector not_matches_selector].each do |assertion_name|
         class_eval <<-ASSERTION, __FILE__, __LINE__ + 1

data/lib/capybara/minitest/spec.rb

@@ -17,7 +17,7 @@ module Capybara
       end + [%w[assert_all_of_selectors must_have_all_of_selectors],
              %w[assert_none_of_selectors must_have_none_of_selectors],
              %w[assert_any_of_selectors must_have_any_of_selectors],
-             %w[assert_style must_have_style]] +
+             %w[assert_matches_style must_match_style]] +
       %w[selector xpath css].flat_map do |assertion|
         [%W[assert_matches_#{assertion} must_match_#{assertion}],
          %W[refute_matches_#{assertion} wont_match_#{assertion}]]
@@ -36,6 +36,13 @@ module Capybara
       end
       # rubocop:enable Style/MultilineBlockChain
 
+      ##
+      # @deprecated
+      def must_have_style(*args, &block)
+        warn 'must_have_style is deprecated, please use must_match_style'
+        must_match_style(*args, &block)
+      end
+
       ##
       # Expectation that there is xpath
       #
@@ -169,8 +176,8 @@ module Capybara
       ##
       # Expectation that element has style
       #
-      # @!method must_have_style
-      #   see {Capybara::Node::Matchers#assert_style}
+      # @!method must_match_style
+      #   see {Capybara::Node::Matchers#assert_matches_style}
     end
   end
 end

data/lib/capybara/node/actions.rb

@@ -195,6 +195,8 @@ module Capybara
       #
       # @return [Capybara::Node::Element]  The option element selected
       def select(value = nil, from: nil, **options)
+        raise ArgumentError, 'The :from option does not take an element' if from.is_a? Capybara::Node::Element
+
         el = from ? find_select_or_datalist_input(from, options) : self
 
         if el.respond_to?(:tag_name) && (el.tag_name == 'input')
@@ -221,6 +223,8 @@ module Capybara
       #
       # @return [Capybara::Node::Element]  The option element unselected
       def unselect(value = nil, from: nil, **options)
+        raise ArgumentError, 'The :from option does not take an element' if from.is_a? Capybara::Node::Element
+
         scope = from ? find(:select, from, options) : self
         scope.find(:option, value, options).unselect_option
       end

data/lib/capybara/node/base.rb

@@ -86,7 +86,7 @@ module Capybara
           raise err unless driver.wait? && catch_error?(err, errors)
           raise err if timer.expired?
 
-          sleep(0.05)
+          sleep(0.01)
           reload if session_options.automatic_reload
           retry
         ensure
@@ -95,13 +95,21 @@ module Capybara
       end
 
       # @api private
-      def find_css(css)
-        base.find_css(css)
+      def find_css(css, **options)
+        if base.method(:find_css).arity != 1
+          base.find_css(css, **options)
+        else
+          base.find_css(css)
+        end
       end
 
       # @api private
-      def find_xpath(xpath)
-        base.find_xpath(xpath)
+      def find_xpath(xpath, **options)
+        if base.method(:find_xpath).arity != 1
+          base.find_xpath(xpath, **options)
+        else
+          base.find_xpath(xpath)
+        end
       end
 
       # @api private

data/lib/capybara/node/document.rb

@@ -31,6 +31,18 @@ module Capybara
       def title
         session.driver.title
       end
+
+      def execute_script(*args)
+        find(:xpath, '/html').execute_script(*args)
+      end
+
+      def evaluate_script(*args)
+        find(:xpath, '/html').evaluate_script(*args)
+      end
+
+      def scroll_to(*args)
+        find(:xpath, '//body').scroll_to(*args)
+      end
     end
   end
 end

data/lib/capybara/node/element.rb

@@ -381,6 +381,38 @@ module Capybara
         self
       end
 
+      ##
+      #
+      # Scroll the page or element
+      #
+      # Scroll the page or element to its top, bottom or middle
+      # @overload scroll_to(position, offset: [0,0])
+      #   @param [:top, :bottom, :center, :current] position
+      #   @param :offset
+      #
+      # Scroll the page or current element until the given element is aligned at the top, bottom, or center of it
+      # @overload scroll_to(element, align: :top)
+      #   @param [Capybara::Node::Element] element   The element to be scrolled into view
+      #   @param [:top, :bottom, :center] :align Where to align the element being scrolled into view with relation to the current page/element if possible
+      #
+      # @overload scroll_to(x,y)
+      #   @param [Integer] x    Horizontal scroll offset
+      #   @param [Integer] y    Vertical scroll offset
+      #
+      # @return [Capybara::Node::Element]  The element
+      def scroll_to(pos_or_el_or_x, y = nil, align: :top, offset: nil)
+        case pos_or_el_or_x
+        when Symbol
+          synchronize { base.scroll_to(nil, pos_or_el_or_x) } unless pos_or_el_or_x == :current
+        when Capybara::Node::Element
+          synchronize { base.scroll_to(pos_or_el_or_x.base, align) }
+        else
+          synchronize { base.scroll_to(nil, nil, [pos_or_el_or_x, y]) }
+        end
+        synchronize { base.scroll_by(*offset) } unless offset.nil?
+        self
+      end
+
       ##
       #
       # Execute the given JS in the context of the element not returning a result. This is useful for scripts that return
@@ -454,6 +486,11 @@ module Capybara
         %(Obsolete #<Capybara::Node::Element>)
       end
 
+      # @api private
+      def initial_cache
+        base.respond_to?(:initial_cache) ? base.initial_cache : {}
+      end
+
       STYLE_SCRIPT = <<~JS
         (function(){
           var s = window.getComputedStyle(this);

data/lib/capybara/node/finders.rb

@@ -36,6 +36,7 @@ module Capybara
       #                                            + Absence of a class can be checked by prefixing the class name with !
       #                                            + If you need to check for existence of a class name that starts with ! then prefix with !!
       #                                            + ```class:['a', '!b', '!!!c'] # limit to elements with class 'a' and '!c' but not class 'b'```
+      #   @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
       #   @option options [Boolean] exact            Control whether `is` expressions in the given XPath match exactly or partially
       # @option options [Symbol] match        The matching strategy to use.
       #

data/lib/capybara/node/matchers.rb

@@ -56,13 +56,21 @@ module Capybara
       #
       # Checks if a an element has the specified CSS styles
       #
-      #     element.has_style?( 'color' => 'rgb(0,0,255)', 'font-size' => /px/ )
+      #     element.matches_style?( 'color' => 'rgb(0,0,255)', 'font-size' => /px/ )
       #
       # @param styles [Hash]
       # @return [Boolean]                       If the styles match
       #
+      def matches_style?(styles, **options)
+        make_predicate(options) { assert_matches_style(styles, options) }
+      end
+
+      ##
+      # @deprecated
+      #
       def has_style?(styles, **options)
-        make_predicate(options) { assert_style(styles, options) }
+        warn 'DEPRECATED: has_style? is deprecated, please use matches_style?'
+        matches_style?(styles, **options)
       end
 
       ##
@@ -108,12 +116,12 @@ module Capybara
       #
       # Asserts that an element has the specified CSS styles
       #
-      #     element.assert_style( 'color' => 'rgb(0,0,255)', 'font-size' => /px/ )
+      #     element.assert_matches_style( 'color' => 'rgb(0,0,255)', 'font-size' => /px/ )
       #
       # @param styles [Hash]
       # @raise [Capybara::ExpectationNotMet]    If the element doesn't have the specified styles
       #
-      def assert_style(styles, **options)
+      def assert_matches_style(styles, **options)
         query_args = _set_query_session_options(styles, options)
         query = Capybara::Queries::StyleQuery.new(*query_args)
         synchronize(query.wait) do
@@ -122,6 +130,13 @@ module Capybara
         true
       end
 
+      ##
+      # @deprecated
+      def assert_style(styles, **options)
+        warn 'assert_style is deprecated, please use assert_matches_style instead'
+        assert_matches_style(styles, **options)
+      end
+
       # Asserts that all of the provided selectors are present on the given page
       # or descendants of the current node.  If options are provided, the assertion
       # will check that each locator is present with those options as well (other than :wait).

data/lib/capybara/node/simple.rb

@@ -164,12 +164,12 @@ module Capybara
       end
 
       # @api private
-      def find_css(css)
+      def find_css(css, **_options)
         native.css(css)
       end
 
       # @api private
-      def find_xpath(xpath)
+      def find_xpath(xpath, **_options)
         native.xpath(xpath)
       end
 
@@ -178,6 +178,11 @@ module Capybara
         Capybara.session_options
       end
 
+      # @api private
+      def initial_cache
+        {}
+      end
+
     private
 
       def option_value(option)