capybara-compose 1.0.4

data/lib/capybara/compose/benchmark_helpers.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+require 'active_support/core_ext/numeric/time'
+require 'rainbow'
+
+# rubocop:disable Style/ClassVars
+
+# Public: Keeps track of the running time for user-defined helpers, useful as a
+# way to keep track of the executed methods, and to easily spot slow operations.
+module Capybara::Compose::BenchmarkHelpers
+  extend ActiveSupport::Concern
+
+  included do
+    @@indentation_level = 0
+    @@indented_logs = []
+  end
+
+protected
+
+  # Internal: Helper to benchmark an operation, outputs the method name, its
+  # arguments, and the ellapsed time in milliseconds.
+  def benchmark_method(method_name, args, kwargs)
+    @@indented_logs.push(log = +'') # Push it in order, set the content later.
+    @@indentation_level += 1
+    before = Time.now
+    yield
+  ensure
+    diff_in_millis = (Time.now - before).in_milliseconds.round
+    @@indentation_level -= 1
+
+    # Set the queued message with the method call and the ellapsed time.
+    log.sub!('', _benchmark_str(method_name: method_name, args: args, kwargs: kwargs, time: diff_in_millis))
+
+    # Print the messages once we outdent all, and clear the queue.
+    @@indented_logs.each { |inner_log| Kernel.puts(inner_log) }.clear if @@indentation_level.zero?
+  end
+
+private
+
+  # Internal: Indents nested method calls, and adds color to make it readable.
+  def _benchmark_str(method_name:, args:, kwargs:, time:)
+    args += [kwargs] unless kwargs.empty?
+    args_str = args.map(&:inspect)
+    [
+      '  ' * @@indentation_level,
+      Rainbow(self.class.name.chomp('TestHelper') + '#').slategray.rjust(40),
+      Rainbow(method_name.to_s).cyan,
+      Rainbow("(#{ args_str.join(', ') })").slategray,
+      '  ',
+      Rainbow("#{ time } ms").send(time > 1000 && :red || time > 100 && :yellow || :green),
+    ].join('')
+  end
+
+  module ClassMethods
+    # Hook: Benchmarks all methods in the class once it's loaded.
+    def on_test_helper_load
+      super
+      benchmark_all
+    end
+
+    # Debug: Wraps all instance methods of the test helper class to log them.
+    def benchmark_all
+      return if defined?(@benchmarked_all)
+
+      benchmark(instance_methods - superclass.instance_methods - [:lazy_for])
+      @benchmarked_all = true
+    end
+
+    # Debug: Wraps a method to output its parameters and ellapsed time.
+    #
+    # Usage:
+    #   benchmark :input_for
+    #   benchmark def input_for(...)
+    def benchmark(method_names)
+      prepend(Module.new {
+        Array.wrap(method_names).each do |method_name|
+          define_method(method_name) { |*args, **kwargs, &block|
+            benchmark_method(method_name, args, kwargs) { super(*args, **kwargs, &block) }
+          }
+        end
+      })
+      method_names
+    end
+  end
+end
+# rubocop:enable Style/ClassVars

data/lib/capybara/compose/cucumber.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'capybara/compose'
+
+World(Capybara::Compose::DependencyInjection)
+
+# Public: Use outside of the steps to make it available on all steps.
+def use_test_helpers(*names)
+  names.each do |name|
+    define_method(name) { get_test_helper(name) }
+  end
+end

data/lib/capybara/compose/dependency_injection.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+# Internal: Provides dependency injection for RSpec and Cucumber, by using the
+# test helper name and a convention for naming and organizing helpers.
+module Capybara::Compose::DependencyInjection
+  # Public: Returns an instance of a test helper that inherits BaseTestHelper.
+  #
+  # NOTE: Memoizes the test helper instances, keeping one per test helper class.
+  # Test helpers are not mutable, they return a new instance every time an
+  # operation is performed, so it's safe to apply this optimization.
+  def get_test_helper(helper_name)
+    ivar_name = "@#{ helper_name }_capybara_test_helper"
+    instance_variable_get(ivar_name) ||
+      instance_variable_set(ivar_name, get_test_helper_class(helper_name).new(self))
+  end
+
+  # Internal: Requires a test helper file and memoizes the class for all tests.
+  #
+  # Returns a Class that subclasses BaseTestHelper.
+  def get_test_helper_class(name)
+    file_name = "#{ name }_test_helper"
+    ivar_name = "@#{ file_name }_test_helper_class"
+    instance_variable_get(ivar_name) || begin
+      require_test_helper(file_name)
+      test_helper_class = file_name.camelize.constantize
+      test_helper_class.on_test_helper_load
+      instance_variable_set(ivar_name, test_helper_class)
+    end
+  end
+
+  # Internal: Requires a test helper file.
+  def require_test_helper(name)
+    Capybara::Compose.config.helpers_paths.each do |path|
+      require Pathname.new(File.expand_path(path)).join("#{ name }.rb").to_s
+      return true # Don't check on the result, it could have been required earlier.
+    rescue LoadError
+      false
+    end
+    raise LoadError, "No '#{ name }.rb' file found in #{ Capybara::Compose.config.helpers_paths.inspect }. "\
+      'Check for typos, or make sure the dirs in `Capybara::Compose.config.helpers_paths` are in the load path.'
+  end
+end
+
+Capybara.extend(Capybara::Compose::DependencyInjection)

data/lib/capybara/compose/finders.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# Internal: Wraps Capybara finders to be aware of the selector aliases, and to
+# auto-wrap the returned elements with test helpers.
+module Capybara::Compose::Finders
+  %i[
+    find
+    find_all
+    find_field
+    find_link
+    find_button
+    find_by_id
+    first
+    ancestor
+    sibling
+  ].each do |method_name|
+    Capybara::Compose.define_helper_method(self, method_name, wrap: true)
+  end
+
+  # Public: Returns all the Capybara nodes that match the specified selector.
+  #
+  # Returns an Array of Capybara::Element that match the query.
+  def all(*args, **kwargs, &filter)
+    if defined?(::RSpec::Matchers::BuiltIn::All) && args.first.respond_to?(:matches?)
+      ::RSpec::Matchers::BuiltIn::All.new(*args, **kwargs)
+    else
+      find_all(*args, **kwargs, &filter)
+    end
+  end
+
+private
+
+  # Internal: Finds an element that matches the specified locator and options.
+  #
+  # Returns a Capybara::Node::Element that matches the conditions, or fails.
+  def find_element(*args, **kwargs, &filter)
+    kwargs[:test_helper] = self
+    current_context.find(*args, **kwargs, &filter)
+  end
+end

data/lib/capybara/compose/matchers.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+# Internal: Wraps Capybara matchers to enable locator aliases, and to wrap the
+# result with a test helper so that methods can be chained in a fluent style.
+module Capybara::Compose::Matchers
+  %i[
+    has_selector?
+    has_no_selector?
+    has_css?
+    has_no_css?
+    has_xpath?
+    has_no_xpath?
+    has_link?
+    has_no_link?
+    has_button?
+    has_no_button?
+    has_field?
+    has_no_field?
+    has_select?
+    has_no_select?
+    has_table?
+    has_no_table?
+    has_checked_field?
+    has_no_checked_field?
+    has_unchecked_field?
+    has_no_unchecked_field?
+    has_title?
+    has_no_title?
+    has_title?
+    has_no_title?
+  ].each do |method_name|
+    Capybara::Compose.define_helper_method(self, method_name)
+  end
+
+  %i[
+    has_ancestor?
+    has_no_ancestor?
+    has_sibling?
+    has_no_sibling?
+    matches_selector?
+    not_matches_selector?
+    matches_css?
+    not_matches_css?
+    matches_xpath?
+    not_matches_xpath?
+    has_text?
+    has_no_text?
+    has_content?
+    has_no_content?
+    matches_style?
+    has_style?
+  ].each do |method_name|
+    Capybara::Compose.define_helper_method(self, method_name, target: :to_capybara_node)
+  end
+
+  %i[
+    assert_selector
+    assert_all_of_selectors
+    assert_none_of_selectors
+    assert_any_of_selectors
+    assert_no_selector
+  ].each do |method_name|
+    Capybara::Compose.define_helper_method(self, method_name)
+  end
+
+  %i[
+    assert_matches_selector
+    assert_not_matches_selector
+    assert_ancestor
+    assert_no_ancestor
+    assert_sibling
+    assert_no_sibling
+  ].each do |method_name|
+    Capybara::Compose.define_helper_method(self, method_name, target: :to_capybara_node)
+  end
+
+  alias has? has_selector?
+  alias has_no? has_no_selector?
+end

data/lib/capybara/compose/rspec.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'capybara/compose'
+require 'capybara/rspec'
+
+# Public: Use in an RSpec describe block or in an included module to make
+# helpers available on all specs.
+def use_test_helpers(*names)
+  names.each do |name|
+    let(name) { get_test_helper(name) }
+  end
+end
+
+RSpec.configure do |config|
+  # Make it available only in certain types of tests.
+  types = %i[feature system view]
+
+  # Options that will register a test helper for the test to use.
+  keys = %i[capybara/compose test_helpers helpers]
+
+  # Inject test helpers by using a :helpers or :test_helpers option.
+  inject_test_helpers = proc { |example|
+    keys.flat_map { |key| example.metadata[key] }.compact.each do |name|
+      example.example_group_instance.define_singleton_method(name) { get_test_helper(name) }
+    end
+  }
+
+  # Allow injecting test helpers in a feature or scenario.
+  types.each do |type|
+    config.include(Capybara::Compose::DependencyInjection, type: type)
+    config.before(:each, type: type, &inject_test_helpers)
+  end
+end

data/lib/capybara/compose/selectors.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+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?(Capybara::Compose::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 Capybara::Compose::Selectors
+  SELECTOR_SEPARATOR = ','
+
+  def self.included(base)
+    base.extend(ClassMethods)
+  end
+
+  module ClassMethods
+    # Public: Light wrapper as syntax sugar for defining SELECTORS.
+    def aliases(selectors = {})
+      const_set('SELECTORS', selectors)
+    end
+
+    # 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 Capybara::Compose::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