capybara_test_helpers 1.0.0

data/lib/capybara_test_helpers/selectors.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require 'capybara/rspec'
+require 'active_support/core_ext/array/wrap'
+
+# Internal: Avoid warnings in assert_valid_keys for passing the `test_helper` option.
+Capybara::Queries::BaseQuery.prepend(Module.new {
+  attr_reader :test_helper
+
+  def initialize(options)
+    @test_helper = options.delete(:test_helper)
+  end
+})
+
+# Internal: Handle locator aliases provided in the test helper to finders,
+# matchers, assertions, and actions.
+Capybara::Queries::SelectorQuery.prepend(Module.new {
+  def initialize(*args, **options, &filter_block)
+    # Resolve any locator aliases defined in the test helper where this query
+    # originated from (through a finder, assertion, or matcher).
+    if test_helper = options[:test_helper]
+      args, options, filter_block = test_helper.resolve_alias_for_selector_query(args, options, filter_block)
+    end
+
+    # Unwrap any test helpers that were provided to the :label selector, since
+    # it's making an explicit check by class.
+    options[:for] = options[:for].to_capybara_node if options[:for].is_a?(CapybaraTestHelpers::TestHelper)
+
+    super(*args, **options, &filter_block)
+  end
+})
+
+# Public: Adds aliasing for element selectors to make it easier to encapsulate
+# how to find a particular kind of element in the UI.
+module CapybaraTestHelpers::Selectors
+  SELECTOR_SEPARATOR = ','
+
+  def self.included(base)
+    base.extend(ClassMethods)
+  end
+
+  module ClassMethods
+    # Public: Returns the available selectors for the test helper, or an empty
+    # Hash if selectors are not defined.
+    def selectors
+      unless defined?(@selectors)
+        parent_selectors = superclass.respond_to?(:selectors) ? superclass.selectors : {}
+        child_selectors = (defined?(self::SELECTORS) && self::SELECTORS || {})
+          .tap { |new_selectors| validate_selectors(new_selectors) }
+        @selectors = parent_selectors.merge(child_selectors).transform_values(&:freeze).freeze
+      end
+      @selectors
+    end
+
+    # Internal: Allows to "call" selectors, as a shortcut for find.
+    #
+    # Example: table.header == table.find(:header)
+    def define_getters_for_selectors
+      selectors.each_key do |selector_name|
+        define_method(selector_name) { |*args, **kwargs, &block|
+          find(selector_name, *args, **kwargs, &block)
+        }
+      end
+    end
+
+    # Internal: Validates that all the selectors defined in the class won't
+    # cause confusion or misbehavior.
+    def validate_selectors(selectors)
+      selectors.each_key do |name|
+        if Capybara::Selector.all.key?(name)
+          raise "A selector with the name #{ name.inspect } is already registered in Capybara," \
+          " consider renaming the #{ name.inspect } alias in #{ self.class.name } to avoid confusion."
+        end
+        if CapybaraTestHelpers::RESERVED_METHODS.include?(name)
+          raise "A method with the name #{ name.inspect } is part of the Capybara DSL," \
+          " consider renaming the #{ name.inspect } alias in #{ self.class.name } to avoid confusion."
+        end
+      end
+    end
+  end
+
+  # Public: Returns the available selectors for the test helper, or an empty
+  # Hash if selectors are not defined.
+  def selectors
+    self.class.selectors
+  end
+
+  # Internal: Inspects the arguments for a SelectorQuery, and resolves a
+  # selector alias if provided.
+  #
+  # Returns a pair of arguments and keywords to initialize a SelectorQuery.
+  def resolve_alias_for_selector_query(args, kwargs, filter_block)
+    # Extract the explicitly provided selector, if any. Example: `find_button`.
+    explicit_type = args.shift if selectors.key?(args[1])
+
+    if selectors.key?(args[0])
+      args, kwargs = locator_for(*args, **kwargs)
+
+      # Remove the type provided by the alias, and add back the explicit one.
+      if explicit_type
+        args.shift if args[0].is_a?(Symbol)
+        args.unshift(explicit_type)
+      end
+    end
+
+    [args, kwargs, wrap_filter(filter_block)]
+  end
+
+private
+
+  # Internal: Checks if there's a Capybara selector defined by that name.
+  def registered_selector?(name)
+    Capybara::Selector.all.key?(name)
+  end
+
+  # Internal: Returns the query locator defined under the specified alias.
+  #
+  # NOTE: In most cases, the query locator is a simple CSS selector, but it also
+  # supports any of the built-in Capybara selectors.
+  #
+  # Returns an Array with the Capybara locator arguments, and options if any.
+  def locator_for(*args, **kwargs)
+    if args.size == 1
+      args = [*Array.wrap(resolve_locator_alias(args.first))]
+      kwargs = args.pop.deep_merge(kwargs) if args.last.is_a?(Hash)
+    end
+    [args, kwargs]
+  rescue KeyError => error
+    raise NotImplementedError, "A selector in #{ self.class.name } is not defined, #{ error.message }"
+  end
+
+  # Internal: Resolves one of the segments of a locator alias.
+  def resolve_locator_alias(fragment)
+    return fragment unless fragment.is_a?(Symbol) && (selectors.key?(fragment) || !registered_selector?(fragment))
+
+    locator = selectors.fetch(fragment)
+
+    locator.is_a?(Array) ? combine_locator_fragments(locator) : locator
+  end
+
+  # Internal: Resolves a complex locator alias, which might reference other
+  # locator aliases as well.
+  def combine_locator_fragments(fragments)
+    return fragments unless fragments.any? { |fragment| fragment.is_a?(Symbol) }
+
+    fragments = fragments.map { |fragment| resolve_locator_alias(fragment) }
+    flat_fragments = fragments.flatten(1)
+    type = flat_fragments.shift if flat_fragments.first.is_a?(Symbol)
+
+    # Only flatten fragments if it's CSS or XPath
+    if type.nil? || type == :css || type == :xpath
+      fragments = flat_fragments
+    else
+      type = nil
+    end
+
+    options = fragments.pop if fragments.last.is_a?(Hash)
+
+    [type, *combine_css_selectors(fragments), options].compact
+  end
+
+  # Internal: Combines parent and child classes to preserve the order.
+  def combine_css_selectors(selectors)
+    return selectors unless selectors.size > 1 && selectors.all? { |selector| selector.is_a?(String) }
+
+    selectors.reduce { |parent_selectors, children_selectors|
+      parent_selectors.split(SELECTOR_SEPARATOR).flat_map { |parent_selector|
+        children_selectors.split(SELECTOR_SEPARATOR).map { |children_selector|
+          "#{ parent_selector }#{ children_selector }"
+        }
+      }.join(SELECTOR_SEPARATOR)
+    }
+  end
+end

data/lib/capybara_test_helpers/synchronization.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# Internal: Provides helper functions to perform asynchronous assertions.
+module CapybaraTestHelpers::Synchronization
+  # Internal: Necessary because the RSpec exception is not a StandardError and
+  # thus capybara does not rescue it, so it wouldn't attempt to retry it.
+  class ExpectationError < StandardError; end
+
+  # Internal: Errors that will be retried in a `synchronize_expectation` block.
+  EXPECTATION_ERRORS = [
+    ExpectationError,
+    Capybara::ElementNotFound,
+    (Selenium::WebDriver::Error::StaleElementReferenceError if defined?(Selenium::WebDriver::Error::StaleElementReferenceError)),
+  ].compact.freeze
+
+protected
+
+  # Public: Can be used to make an asynchronous expectation, that will be
+  # retried until the max wait time configured in Capybara.
+  def synchronize_expectation(retry_on_errors: [], **options)
+    synchronize(errors: EXPECTATION_ERRORS + retry_on_errors, **options) {
+      begin
+        yield
+      rescue RSpec::Expectations::ExpectationNotMetError => error
+        # NOTE: Rethrow as ExpectationError because the RSpec exception is not
+        # a StandardError so capybara wouldn't rescue it inside synchronize.
+        raise ExpectationError, error
+      end
+    }
+  rescue ExpectationError => error
+    raise error.cause # Unwrap this internal error and raise the original error.
+  end
+
+  # Public: Used to implement more specific synchronization helpers.
+  #
+  # By default Capybara's methods like `find` and `have_css` already use
+  # synchronize to achieve asynchronicity, so it's not necessary to use this.
+  def synchronize(wait: Capybara.default_max_wait_time == 0 ? Capybara.default_max_wait_time : 3, **options, &block)
+    (current_element? ? current_context : page.document).synchronize(wait, **options, &block)
+  end
+end

data/lib/capybara_test_helpers/test_helper.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require 'capybara/rspec'
+
+require 'active_support/core_ext/module/delegation'
+require 'active_support/core_ext/string/inflections'
+require 'active_support/core_ext/object/blank'
+
+require 'capybara_test_helpers/selectors'
+require 'capybara_test_helpers/synchronization'
+require 'capybara_test_helpers/finders'
+require 'capybara_test_helpers/actions'
+require 'capybara_test_helpers/assertions'
+require 'capybara_test_helpers/matchers'
+
+# Public: Base class to create test helpers that have full access to the
+# Capybara DSL, while easily defining custom assertions, getters, and actions.
+#
+# It also supports locator aliases to prevent duplication and keep tests easier
+# to understand and to maintain.
+class CapybaraTestHelpers::TestHelper
+  include RSpec::Matchers
+  include RSpec::Mocks::ExampleMethods
+  include Capybara::DSL
+  include CapybaraTestHelpers::Selectors
+  include CapybaraTestHelpers::Synchronization
+  include CapybaraTestHelpers::Finders
+  include CapybaraTestHelpers::Actions
+  include CapybaraTestHelpers::Assertions
+  include CapybaraTestHelpers::Matchers
+
+  undef_method(*CapybaraTestHelpers::SKIPPED_DSL_METHODS)
+
+  attr_reader :query_context, :test_context
+
+  def initialize(query_context, test_context: query_context, negated: nil)
+    @query_context, @test_context, @negated = query_context, test_context, negated
+  end
+
+  # Public: To make the benchmark log less verbose.
+  def inspect
+    %(#<#{ self.class.name } #{ current_element? ? %(tag="#{ base.tag_name }") : object_id }>)
+  rescue *page.driver.invalid_element_errors
+    %(#<#{ self.class.name } #{ object_id }>)
+  end
+
+  # Public: Makes it easier to inspect the current element.
+  def inspect_node
+    to_capybara_node.inspect
+  end
+
+  # Public: Casts the current context as a Capybara::Node::Element.
+  #
+  # NOTE: Uses the :el convention, which means actions can be performed directly
+  # on the test helper if an :el selector is defined.
+  def to_capybara_node
+    return current_context if current_element?
+    return find_element(:el) if selectors.key?(:el)
+
+    raise_missing_element_error
+  end
+
+  # Public: Wraps a Capybara::Node::Element with a test helper object.
+  def wrap_element(capybara_node)
+    if capybara_node.is_a?(Enumerable)
+      capybara_node.map { |node| wrap_element(node) }
+    else
+      self.class.new(capybara_node, test_context: test_context)
+    end
+  end
+
+  # Public: Wraps a CapybaraTestHelper with a different test helper object.
+  def wrap_test_helper(test_helper)
+    self.class.new(test_helper.query_context, test_context: test_context) if test_helper.query_context
+  end
+
+  # Public: Scopes the Capybara queries in the block to be inside the specified
+  # selector.
+  def within_element(*args, **kwargs, &block)
+    locator = args.empty? ? [self] : args
+    kwargs[:test_helper] = self
+    page.within(*locator, **kwargs, &block)
+  end
+
+  # Public: Scopes the Capybara queries in the block to be inside the specified
+  # selector.
+  def within(*args, **kwargs, &block)
+    return be_within(*args, **kwargs) unless block_given? # RSpec matcher.
+
+    within_element(*args, **kwargs, &block)
+  end
+
+  # Public: Unscopes the inner block from any previous `within` calls.
+  def within_document
+    page.instance_exec { scopes << nil }
+    yield wrap_element(page.document)
+  ensure
+    page.instance_exec { scopes.pop }
+  end
+
+  # Internal: Returns the name of the class without the suffix.
+  #
+  # Example: 'current_page' for CurrentPageTestHelper.
+  def friendly_name
+    self.class.name.chomp('TestHelper').underscore
+  end
+
+protected
+
+  # Internal: Used to perform assertions and others.
+  def current_context
+    query_context.respond_to?(:to_capybara_node) ? query_context : page
+  end
+
+  # Internal: Returns true if the current context is an element.
+  def current_element?
+    current_context.is_a?(Capybara::Node::Element)
+  end
+
+private
+
+  # Internal: Wraps the optional filter block to ensure we pass it a test helper
+  # instead of a raw Capybara::Node::Element.
+  def wrap_filter(filter)
+    proc { |capybara_node_element| filter.call(wrap_element(capybara_node_element)) } if filter
+  end
+
+  # Internal: Helper to provide more information on the error.
+  def raise_missing_element_error
+    method_caller = caller.select { |x| x['test_helpers'] }[1]
+    method_caller_name = method_caller&.match(/in `(\w+)'/)
+    method_caller_name = method_caller_name ? method_caller_name[1] : method_caller
+    raise ArgumentError, "You are calling the `#{ method_caller_name }' method on the test helper but :el is not defined nor there's a current element.\n"\
+    'Define :el, or find an element before performing the action.'
+  end
+
+  class << self
+    # Public: Make methods in the test context available in the helpers.
+    def delegate_to_test_context(*method_names)
+      delegate(*method_names, to: :test_context)
+    end
+
+    # Public: Allows to define dependencies on other matchers.
+    #
+    # NOTE: When you call a helper the "negated" state is preserved for assertions.
+    #
+    # NOTE: You can also pass an element to a test helper to "wrap" a specified
+    # element with the specified test helper class.
+    #
+    # Example:
+    #   dropdown(element).toggle_menu
+    def use_test_helpers(*helper_names)
+      helper_names.each do |helper_name|
+        private define_method(helper_name) { |element = nil|
+          test_helper = test_context.get_test_helper(helper_name)
+          if element
+            raise ArgumentError, "#{ element.inspect } must be a test helper or element." unless element.respond_to?(:to_capybara_node)
+
+            test_helper = test_helper.wrap_element(element.to_capybara_node)
+          end
+          @negated.nil? ? test_helper : test_helper.should(@negated)
+        }
+      end
+    end
+
+    # Internal: Allows to perform certain actions just before a test helper will
+    # be loaded for the first time.
+    def on_test_helper_load
+      define_getters_for_selectors
+    end
+
+    # Internal: Fail early if a reserved method is redefined.
+    def method_added(method_name)
+      return unless CapybaraTestHelpers::RESERVED_METHODS.include?(method_name)
+
+      raise "A method with the name #{ method_name.inspect } is part of the Capybara DSL," \
+        ' overriding it could cause unexpected issues that could be very hard to debug.'
+    end
+  end
+end
+
+Capybara::TestHelper = CapybaraTestHelpers::TestHelper unless defined?(Capybara::TestHelper)

data/lib/capybara_test_helpers/to_or_expectation_handler.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'capybara/rspec'
+
+# Internal: Used heavily in the RSpec matchers, makes it very easy to create
+# a dual assertion (can be used as positive or negative).
+#
+# See https://maximomussini.com/posts/cucumber-to_or_not_to/
+module CapybaraTestHelpers::ToOrExpectationHandler
+  # Public: Allows a more convenient definition of should/should not Gherkin steps.
+  #
+  # Example:
+  #
+  #   Then(/^I should (not )?see "(.*)"$/) do |not_to, text|
+  #     expect(page).to_or not_to, have_content(text)
+  #   end
+  #
+  def to_or(not_to, matcher, message = nil, &block)
+    if not_to
+      not_to(matcher, message, &block)
+    else
+      to(matcher, message, &block)
+    end
+  end
+end
+
+RSpec::Expectations::ExpectationTarget.include(CapybaraTestHelpers::ToOrExpectationHandler)

data/lib/capybara_test_helpers/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Easily write fluent Page Objects for Capybara in Ruby.
+module CapybaraTestHelpers
+  VERSION = '1.0.0'
+end

data/lib/generators/test_helper/test_helper_generator.rb

@@ -0,0 +1,26 @@
+require 'capybara_test_helpers'
+require 'rails/generators/named_base'
+
+# Internal: Generates a new test helper file in the appropriate directory.
+class TestHelperGenerator < Rails::Generators::NamedBase
+  def create_helper_file
+    create_file("#{ CapybaraTestHelpers.config.helpers_paths.first }/#{ file_name }_test_helper.rb") {
+      <<~CAPYBARA_TEST_HELPER
+        # frozen_string_literal: true
+
+        class #{ file_name.camelize }TestHelper < #{ file_name.to_s == 'base' ? 'Capybara::TestHelper' : 'BaseTestHelper' }
+        # Selectors: Semantic aliases for elements, a useful abstraction.
+          SELECTORS = {}
+
+        # Getters: A convenient way to get related data or nested elements.
+
+        # Actions: Encapsulate complex actions to provide a cleaner interface.
+
+        # Assertions: Check on element properties, used with `should` and `should_not`.
+
+        # Background: Helpers to add/modify/delete data in the database or session.
+        end
+      CAPYBARA_TEST_HELPER
+    }
+  end
+end