capybara-select 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9dfbc64a457c2deff5829d629d5b36d76bc171272708cf986b6c11cc7e248c5e
+  data.tar.gz: 674a66dc213e0df0721c907d28a4537b47c2e19959b623354ff6644e4318e1cf
+SHA512:
+  metadata.gz: 8a8ef90e15eafee60a35af1b3b5c0c53bf8061a2b6168010882ed98cdaa1647a5fdb8fc1b3c5ea49bf251249aba92c13c2ff31663b8f52ff04aed2c905f7217a
+  data.tar.gz: fb63296bfcf654617b6922852202a1928bd77ce108e11376760a799dee4375da80d56340070f4de492bc1a720c063e5eddd1c43fa499ceda55c14f12d691a45c

data/Changes.md

@@ -0,0 +1,34 @@
+# capybara-select Changes
+
+1.0.0
+---------
+
+First release of this fork under its own name, `capybara-select`; `capybara-select2` on rubygems.org is the
+original (1.0.1, 2015). Keep `require 'capybara-select2'` and `Capybara::Select2`.
+
+- A click that does not open the dropdown is retried (3 clicks), so a field that re-renders under the click, or a
+  dropdown that closes straight away, still gets its option picked.
+- A dropdown that closes before the option is listed (a lookup re-rendering the form) is opened again.
+- A field re-rendered under the click (`StaleElementReferenceError`) is found again with the same locator.
+- A field that never opens fails fast with `select2 dropdown did not open after 3 clicks on …`, instead of waiting
+  `default_max_wait_time` several times and reporting missing 3.x `li.select2-result-selectable` options. The
+  select2 version is read from the field, not from the dropdown.
+- `search: true` and the "Searching…" wait no longer spend a full `default_max_wait_time` when nothing is loading,
+  and every wait is bounded.
+- Fix: `from:` with select2 3.x matched both the label and select2's off-screen copy of it.
+- Fix: `Capybara::Ambiguous` reported the number of listed options, not of matches.
+- `search: true` works with select2 3.x.
+- Private helpers are prefixed with `select2_` (`select2_find_and_open`, `select2_fetch_options`, …). They are mixed
+  into every example, so a spec helper with 1.0.4's names (`find_select2_and_open`, `open_select2`,
+  `find_select2_container`, `fetch_options`) used to replace them. Call `select2` instead of those helpers.
+- `css:` and `xpath:` may point at an element wrapping the select2 container, such as a form field.
+- Removed `lib/capybara/select2.rb`, which could not be loaded.
+- Specs against select2 4.0.13 and 3.5.4 in headless Chrome. Requires Ruby >= 3.2, Capybara 3 and
+  selenium-webdriver 4. Packages only files committed to git. Release tasks in `rakelib/release.rake`.
+
+1.0.4 (fork, never published)
+---------
+
+- `mode:` (`:exact_text`, `:insensitive`, `:case_insensitive`), `await_option:`, `max_retries:` and retries while
+  select2 shows "Searching…".
+- `wait:` to sleep before reading options (was `sleep:`).

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2012 William Yeung
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,70 @@
+# capybara-select
+
+[![CI](https://github.com/moskvin/capybara-select2/actions/workflows/ci.yml/badge.svg)](https://github.com/moskvin/capybara-select2/actions/workflows/ci.yml)
+
+Capybara helpers to pick an option in a [select2](https://select2.org) field (4.x and 3.x), for RSpec feature specs
+run with Selenium.
+
+A fork of [capybara-select2](https://github.com/goodwill/capybara-select2), released as `capybara-select` because the
+original name is taken on rubygems.org. It keeps the original's `require` name and `Capybara::Select2` module, and
+adds what flaky browser specs need:
+
+- a click that does not open the dropdown is retried, and a dropdown that closes before its option is listed (a form
+  re-rendering under the click) is opened again;
+- a field re-rendered under the click is found again with the same locator;
+- a field that never opens fails fast with `select2 dropdown did not open after 3 clicks on …`;
+- results that load slowly are waited for ("Searching…"), within `Capybara.default_max_wait_time`.
+
+## Installation
+
+```ruby
+group :test do
+  gem 'capybara-select', require: 'capybara-select2'
+end
+```
+
+The gem includes its helpers into every RSpec example. Outside RSpec (for example Cucumber), add
+`include Capybara::Select2` to your support file.
+
+## Usage
+
+Locate the field by its label, the `for` of its label, CSS or XPath of the select2 container:
+
+```ruby
+select2('Banana', from: 'Fruit')
+select2('Banana', field: 'fruit')
+select2('Banana', css: '#question_12 .select2-container')
+select2('Banana', xpath: container.path)
+```
+
+Options:
+
+| Option | Default | |
+|---|---|---|
+| `mode:` | `:exact_text` | `:insensitive` matches part of the text (or a Regexp), `:case_insensitive` ignores case |
+| `search: true` | | types the value into the search box first, for fields with a minimum input length |
+| `await_option: true` | | polls for the option before reading the list (`max_retries:`, default 5) |
+| `wait:` | | sleeps this many seconds before reading the list |
+
+`select2_filter('an', from: 'Fruit', search: true)` returns the listed options without picking one.
+
+For a field with [tags](https://select2.github.io/select2/#tags):
+
+```ruby
+select2_tag('value', from: 'Label of input')
+```
+
+## Development
+
+    bundle install
+    bundle exec rake          # RuboCop and the specs (headless Chrome, select2 4.0.13 and 3.5.4)
+
+## Releasing
+
+    rake "release:bump[minor]"   # bump version.rb, add a Changes.md section
+    rake release:dry_run         # checks, lint, specs, package inspection; pushes nothing
+    rake release                 # the same checks, then tag vX.Y.Z and push to rubygems.org
+
+## License
+
+MIT, see [LICENSE.txt](LICENSE.txt). Original author: William Yeung.

data/capybara-select2.gemspec

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative 'lib/capybara-select2/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'capybara-select'
+  spec.version = Capybara::Select2::VERSION
+  spec.authors = ['William Yeung', 'Nikolay Moskvin']
+  spec.email = ['william@tofugear.com']
+
+  spec.summary = 'Capybara helpers to pick options in select2 (3.x and 4.x) fields'
+  spec.description = 'select2 and select2_filter for Capybara/RSpec, with retries for dropdowns that close or ' \
+                     're-render under the click and for results that load slowly. A fork of capybara-select2.'
+  spec.homepage = 'https://github.com/moskvin/capybara-select2'
+  spec.license = 'MIT'
+
+  # Only files committed to git, so a local scratch file can never be published.
+  spec.files = IO.popen(%w[git ls-files -z], chdir: __dir__, &:read).split("\x0").select do |f|
+    f.start_with?('lib/') || %w[Changes.md LICENSE.txt README.md capybara-select2.gemspec].include?(f)
+  end
+
+  spec.require_paths = ['lib']
+  spec.required_ruby_version = '>= 3.2.0'
+
+  spec.metadata = {
+    'homepage_uri' => 'https://github.com/moskvin/capybara-select2',
+    'bug_tracker_uri' => 'https://github.com/moskvin/capybara-select2/issues',
+    'changelog_uri' => 'https://github.com/moskvin/capybara-select2/blob/master/Changes.md',
+    'source_code_uri' => 'https://github.com/moskvin/capybara-select2',
+    'rubygems_mfa_required' => 'true'
+  }
+
+  spec.add_dependency 'capybara', '>= 3.0', '< 4'
+  spec.add_dependency 'rspec-core', '>= 3.0', '< 4'
+  spec.add_dependency 'rspec-expectations', '>= 3.0', '< 4'
+  spec.add_dependency 'selenium-webdriver', '>= 4.0', '< 5'
+end

data/lib/capybara/selectors/tag_selector.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Capybara
+  module Selectors
+    module TagSelector
+      def select2_tag(value, options = {})
+        if options[:from]
+          find(:fillable_field, options[:from]).set(value)
+        else
+          find('input.select2-input').set(value)
+        end
+
+        find('.select2-drop li', text: value).click
+      end
+    end
+  end
+end

data/lib/capybara-select2/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Capybara
+  module Select2
+    VERSION = '1.0.0'
+  end
+end

data/lib/capybara-select2.rb

@@ -0,0 +1,243 @@
+# frozen_string_literal: true
+
+require 'capybara-select2/version'
+require 'capybara/selectors/tag_selector'
+require 'rspec/core'
+require 'selenium/webdriver'
+
+module Capybara
+  module Select2
+    # Clicks used to open a dropdown. A click can be lost when the field re-renders under it, or the dropdown can
+    # close straight away; each attempt waits default_max_wait_time / OPEN_ATTEMPTS for it to open.
+    OPEN_ATTEMPTS = 3
+
+    # Markup per select2 major version. The version is read from the field itself, never from an open dropdown,
+    # so a dropdown that failed to open is reported as such instead of as missing 3.x options.
+    MARKUP = {
+      4 => {
+        trigger: '.select2-selection',
+        open: '.select2-container--open',
+        dropdown: '.select2-container--open .select2-dropdown',
+        option: 'li.select2-results__option',
+        search: '.select2-container--open input.select2-search__field',
+        loading: '.loading-results'
+      }.freeze,
+      3 => {
+        trigger: '.select2-choice, .select2-choices',
+        open: '.select2-dropdown-open',
+        dropdown: '.select2-drop-active',
+        option: 'li.select2-result-selectable',
+        search: '.select2-drop-active input.select2-input',
+        loading: '.select2-searching'
+      }.freeze
+    }.freeze
+
+    # Fill in a select2 filter and return the options.
+    # @return [Array] the filtered options
+    def select2_filter(value, **args)
+      markup = select2_find_and_open(value, **args)
+      select2_fetch_options(value, markup:, **args).find_all(select2_option_selector(markup))
+    end
+
+    # Fill in a select2 field and select the value.
+    # @param value [String, Regexp]
+    # @param args
+    #   - xpath, css, from or field [String] - locates the select2 container
+    #   - mode [Symbol] - :exact_text (default), :insensitive or :case_insensitive
+    #   - search [Boolean] - type the value into the search box first
+    #   - wait [Float] - sleep this long before reading the options
+    #   - await_option [Boolean] - poll for the option before reading the options
+    #   - max_retries [Integer] - polls for await_option (default 5)
+    # @raise [Capybara::ElementNotFound]
+    # @raise [Capybara::Ambiguous]
+    # @raise [Capybara::ExpectationNotMet] when the dropdown does not open
+    def select2(value, **args)
+      text = select2_match_text(value, args[:mode])
+      exact_text = select2_exact_text?(args[:mode])
+      option = exact_text ? { exact_text: text } : { text:, count: 1 }
+      markup = select2_open_with_option(value, text, option, **args)
+      expect(select2_body).to have_css(select2_option_selector(markup), wait: 0, **option)
+
+      select2_pick_option(value, text, exact_text, markup)
+    end
+
+    private
+
+    # Private helpers are prefixed with select2_: they are mixed into every example, so a spec helper with the same
+    # name would otherwise replace them.
+
+    def select2_pick_option(value, text, exact_text, markup)
+      matches = select2_body.find_all(select2_option_selector(markup)).select do |result|
+        exact_text ? result.text == text : result.text.match?(text)
+      end
+
+      case matches.size
+      when 0
+        raise Capybara::ElementNotFound, "Unable to find a matching option for #{value}"
+      when 1
+        matches.first.click
+      else
+        raise Capybara::Ambiguous, "Ambiguous match, found #{matches.size} options for #{value}"
+      end
+    end
+
+    def select2_monotonic_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def select2_match_text(value, mode)
+      case mode
+      when :insensitive
+        value.is_a?(Regexp) ? value : /#{Regexp.escape(value)}/
+      when :case_insensitive
+        /#{Regexp.escape(value)}/i
+      else
+        value
+      end
+    end
+
+    def select2_exact_text?(mode)
+      mode.nil? || mode == :exact_text
+    end
+
+    # Opens the dropdown and waits for the option. A dropdown that closes before the option is listed (the field
+    # re-rendered, as a lookup updating a form does) is opened again; one that stays open without it is left to
+    # select2's expectation to report.
+    def select2_open_with_option(value, text, option, **args)
+      OPEN_ATTEMPTS.times do
+        markup = select2_find_and_open(value, **args)
+        select2_fetch_options(text, markup:, **args)
+        return markup if select2_option_listed_or_open?(markup, option)
+      end
+      raise Capybara::ExpectationNotMet, "select2 dropdown closed before listing #{value} #{OPEN_ATTEMPTS} times"
+    end
+
+    # true once the option is listed, or when default_max_wait_time passes with the dropdown still open;
+    # false as soon as the dropdown closes.
+    def select2_option_listed_or_open?(markup, option)
+      deadline = select2_monotonic_now + Capybara.default_max_wait_time
+      body = select2_body
+      loop do
+        return true if body.has_css?(select2_option_selector(markup), wait: 0, **option)
+        return false unless body.has_selector?(markup[:dropdown], wait: 0)
+        return true if select2_monotonic_now >= deadline
+
+        sleep(0.05)
+      end
+    end
+
+    def select2_option_selector(markup)
+      "#{markup[:dropdown]} #{markup[:option]}"
+    end
+
+    def select2_body
+      find(:xpath, '//body')
+    end
+
+    def select2_fetch_options(text, markup:, **args)
+      sleep(args[:wait]) unless args[:wait].nil?
+      if args[:await_option]
+        select2_await_option(text, markup:, max_retries: args[:max_retries] || 5, mode: args[:mode])
+      end
+      select2_await_loaded(markup)
+      select2_body
+    end
+
+    # Polls with a growing wait until the option is listed; select2 then fails with Capybara's own message.
+    def select2_await_option(text, markup:, mode:, max_retries:)
+      options = select2_exact_text?(mode) ? { exact_text: text } : { text:, count: 1 }
+      (max_retries + 1).times do |attempt|
+        break if select2_body.has_css?(select2_option_selector(markup), wait: attempt / 10.0, **options)
+
+        sleep(0.3)
+        select2_logger.warn("Retry to find a matching option for #{text}, mode: #{mode}, " \
+                            "attempt: #{attempt + 1}/#{max_retries}")
+      end
+    end
+
+    # Waits, up to default_max_wait_time, while the dropdown shows "Searching…".
+    def select2_await_loaded(markup)
+      deadline = select2_monotonic_now + Capybara.default_max_wait_time
+      loading = "#{markup[:dropdown]} #{markup[:loading]}"
+      sleep(0.05) while select2_body.has_selector?(loading, wait: 0) && select2_monotonic_now < deadline
+    end
+
+    def select2_find_container(**args)
+      if args[:xpath]
+        select2_container_in(find(:xpath, args[:xpath]))
+      elsif args[:css]
+        select2_container_in(find(:css, args[:css]))
+      else
+        select2_container_next_to(select2_find_label(**args))
+      end
+    end
+
+    def select2_find_label(**args)
+      if args[:field]
+        find(%(label[for="#{args[:field]}"]))
+      elsif args[:from]
+        # select2 3.x copies the label into its container as an off-screen label
+        find('label:not(.select2-offscreen)', text: args[:from])
+      else
+        raise ArgumentError, 'None of xpath, css, field, nor from given'
+      end
+    end
+
+    def select2_container_next_to(label)
+      label.find(:xpath, '..').find('.select2-container')
+    end
+
+    # xpath: and css: may point at the select2 container or at an element wrapping it (such as a form field).
+    def select2_container_in(element)
+      return element if element.matches_css?('.select2-container', wait: 0)
+
+      element.find('.select2-container', match: :first)
+    end
+
+    def select2_version(container)
+      return 4 if container.has_selector?(MARKUP[4][:trigger], wait: 0)
+      return 3 if container.has_selector?(MARKUP[3][:trigger], wait: 0)
+
+      # Not rendered yet: wait once for either version.
+      container.has_selector?("#{MARKUP[4][:trigger]}, #{MARKUP[3][:trigger]}")
+      container.has_selector?(MARKUP[4][:trigger], wait: 0) ? 4 : 3
+    end
+
+    # Clicks the field until its dropdown opens. A field re-rendered under the click is found again.
+    def select2_open(container, markup, **args)
+      wait = Capybara.default_max_wait_time.to_f / OPEN_ATTEMPTS
+      OPEN_ATTEMPTS.times do
+        return if container.matches_css?(markup[:open], wait: 0)
+
+        container.find(markup[:trigger], match: :first).click
+        return if container.matches_css?(markup[:open], wait:)
+      rescue Selenium::WebDriver::Error::StaleElementReferenceError
+        container = select2_find_container(**args)
+      end
+      raise Capybara::ExpectationNotMet,
+            "select2 dropdown did not open after #{OPEN_ATTEMPTS} clicks on #{markup[:trigger]}"
+    end
+
+    # Opens the field (typing the value into the search box with `search: true`) and returns its MARKUP.
+    def select2_find_and_open(value, **args)
+      container = select2_find_container(**args)
+      markup = MARKUP.fetch(select2_version(container))
+      select2_open(container, markup, **args)
+
+      if args[:search]
+        select2_body.find(markup[:search]).send_keys(value)
+        select2_await_loaded(markup)
+      end
+      markup
+    end
+
+    def select2_logger
+      ::Selenium::WebDriver.logger
+    end
+  end
+end
+
+RSpec.configure do |config|
+  config.include Capybara::Select2
+  config.include Capybara::Selectors::TagSelector
+end

metadata

@@ -0,0 +1,135 @@
+--- !ruby/object:Gem::Specification
+name: capybara-select
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- William Yeung
+- Nikolay Moskvin
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: capybara
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+- !ruby/object:Gem::Dependency
+  name: rspec-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+- !ruby/object:Gem::Dependency
+  name: rspec-expectations
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+- !ruby/object:Gem::Dependency
+  name: selenium-webdriver
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5'
+description: select2 and select2_filter for Capybara/RSpec, with retries for dropdowns
+  that close or re-render under the click and for results that load slowly. A fork
+  of capybara-select2.
+email:
+- william@tofugear.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Changes.md
+- LICENSE.txt
+- README.md
+- capybara-select2.gemspec
+- lib/capybara-select2.rb
+- lib/capybara-select2/version.rb
+- lib/capybara/selectors/tag_selector.rb
+homepage: https://github.com/moskvin/capybara-select2
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/moskvin/capybara-select2
+  bug_tracker_uri: https://github.com/moskvin/capybara-select2/issues
+  changelog_uri: https://github.com/moskvin/capybara-select2/blob/master/Changes.md
+  source_code_uri: https://github.com/moskvin/capybara-select2
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Capybara helpers to pick options in select2 (3.x and 4.x) fields
+test_files: []