capybara_test_helpers 1.0.0

data/lib/capybara_test_helpers/assertions.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require 'capybara_test_helpers/to_or_expectation_handler'
+
+# Internal: Wraps RSpec matchers to allow using them after calling `should` or
+# `should_not` to perform the assertion.
+module CapybaraTestHelpers::Assertions
+  # Public: Allows writing custom on-demand matchers, as well as chaining
+  # several assertions.
+  def should(negated = false)
+    negated = !!negated # Coerce to boolean.
+    return self if negated == @negated
+
+    clone.tap { |test_helper| test_helper.instance_variable_set('@negated', negated) }
+  end
+  [:should_still, :should_now, :and, :and_instead, :and_also, :and_still].each { |should_alias| alias_method should_alias, :should }
+
+  # Public: Allows writing custom on-demand matchers, as well as chaining
+  # several assertions.
+  def should_not
+    @negated ? self : should(true)
+  end
+  [:should_still_not, :should_no_longer, :nor, :and_not].each { |should_alias| alias_method should_alias, :should_not }
+
+  # Public: Makes it more readable when in used in combination with to_or.
+  def not_to
+    raise(ArgumentError, 'You must call `should` or `should_not` before calling this method') if @negated.nil?
+
+    @negated
+  end
+  alias or_should_not not_to
+
+  # Public: Allows to write complex nested assertions.
+  def invert_expectation
+    should(!not_to)
+  end
+
+  %i[
+    have_selector
+    have_no_selector
+    have_css
+    have_no_css
+    have_xpath
+    have_no_xpath
+    have_link
+    have_no_link
+    have_button
+    have_no_button
+    have_field
+    have_no_field
+    have_select
+    have_no_select
+    have_table
+    have_no_table
+    have_checked_field
+    have_no_checked_field
+    have_unchecked_field
+    have_no_unchecked_field
+    have_all_of_selectors
+    have_none_of_selectors
+    have_any_of_selectors
+    have_title
+    have_no_title
+  ].each do |method_name|
+    CapybaraTestHelpers.define_helper_method(self, method_name, assertion: true)
+  end
+
+  %i[
+    have_ancestor
+    have_no_ancestor
+    have_sibling
+    have_no_sibling
+    match_selector
+    not_match_selector
+    match_css
+    not_match_css
+    match_xpath
+    not_match_xpath
+    have_text
+    have_no_text
+    have_content
+    have_no_content
+    match_style
+    have_style
+  ].each do |method_name|
+    CapybaraTestHelpers.define_helper_method(self, method_name, target: :to_capybara_node, assertion: true)
+  end
+
+  %i[
+    have_current_path
+    have_no_current_path
+  ].each do |method_name|
+    CapybaraTestHelpers.define_helper_method(self, method_name, target: :page, assertion: true, inject_test_helper: false)
+  end
+
+  alias have have_selector
+
+  # Public: Allows to check on any input value asynchronously.
+  def have_value(expected_value, **options)
+    synchronize_expectation(**options) { expect(value).to_or not_to, eq(expected_value) }
+    self
+  end
+
+private
+
+  # Internal: Override the method_missing defined in RSpec::Matchers to avoid
+  # accidentally calling a predicate or has matcher instead of an assertion.
+  def method_missing(method, *args, **kwargs, &block)
+    case method.to_s
+    when CapybaraTestHelpers::TestHelper::DYNAMIC_MATCHER_REGEX
+      raise NoMethodError, "undefined method `#{ method }' for #{ inspect }.\nUse `delegate_to_test_context(:#{ method })` in the test helper class if you plan to use it often, or `test_context.#{ method }` as needed in the instance."
+    else
+      super
+    end
+  end
+
+  # Internal: Override the method_missing defined in RSpec::Matchers to avoid
+  # accidentally calling a predicate or has matcher instead of an assertion.
+  def respond_to_missing?(method, *)
+    return false if method =~ CapybaraTestHelpers::TestHelper::DYNAMIC_MATCHER_REGEX
+
+    super
+  end
+end

data/lib/capybara_test_helpers/benchmark_helpers.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+require 'active_support/core_ext/numeric/time'
+require 'rainbow'
+
+begin
+  require 'amazing_print'
+rescue LoadError
+end
+
+# 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 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_str = args.map(&:inspect)
+    unless kwargs.empty?
+      args_str.push kwargs.respond_to?(:awesome_inspect) ? kwargs.awesome_inspect(multiline: false, ruby19_syntax: true)[2..-3] : kwargs.inspect
+    end
+    [
+      '  ' * @@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_test_helpers/config.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require 'capybara/rspec'
+
+# Internal: Configuration for Provides the basic functionality to create simple test helpers.
+module CapybaraTestHelpers
+  DEFAULTS = {
+    helpers_paths: ['test_helpers'].freeze,
+  }.freeze
+
+  # Internal: Reserved methods for Capybara::TestHelper.
+  test_helper_methods = [
+    :page,
+    :find_element,
+    :should,
+    :should_not,
+    :not_to,
+  ].freeze
+
+  # Internal: Methods that are in the Capybara DSL but are so common that we
+  # don't want to issue a warning if they are used as selectors.
+  SKIPPED_DSL_METHODS = [
+    :title,
+    :body,
+    :html,
+  ].freeze
+
+  # Internal: Methods that should not be overiden or used as locator aliases to
+  # avoid confusion while working on test helpers.
+  RESERVED_METHODS = (Capybara::Session::DSL_METHODS - SKIPPED_DSL_METHODS + test_helper_methods).to_set.freeze
+
+  # Internal: Ruby 2.7 swallows keyword arguments, so for methods that take a
+  # Hash as the first argument as well as keyword arguments, we need to manually
+  # detect and move them to args if empty.
+  METHODS_EXPECTING_A_HASH = %i[matches_style? has_style? match_style have_style].to_set.freeze
+
+  # Public: Returns the current configuration for the test helpers.
+  def self.config
+    @config ||= OpenStruct.new(DEFAULTS)
+    yield @config if block_given?
+    @config
+  end
+
+  # Internal: Allows to define methods that are a part of the Capybara DSL, as
+  # well as RSpec matchers.
+  def self.define_helper_method(klass, method_name, wrap: false, assertion: false, target: 'current_context', return_self: assertion, inject_test_helper: true)
+    klass.class_eval <<~HELPER, __FILE__, __LINE__ + 1
+      def #{ method_name }(*args, **kwargs, &filter)
+        #{ 'args.push(kwargs) && (kwargs = {}) if args.empty?' if METHODS_EXPECTING_A_HASH.include?(method_name) }
+        #{ 'kwargs[:test_helper] = self' if inject_test_helper }
+        #{ 'wrap_element ' if wrap }#{ assertion ? "expect(#{ target }).to_or not_to, test_context" : target }.#{ method_name }(*args, **kwargs, &filter)
+        #{ 'self' if return_self }
+      end
+    HELPER
+  end
+end

data/lib/capybara_test_helpers/cucumber.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'capybara_test_helpers'
+
+World(CapybaraTestHelpers::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_test_helpers/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 CapybaraTestHelpers::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)
+    CapybaraTestHelpers.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 #{ CapybaraTestHelpers.config.helpers_paths.inspect }. "\
+      'Check for typos, or make sure the dirs in `CapybaraTestHelpers.config.helpers_paths` are in the load path.'
+  end
+end
+
+Capybara.extend(CapybaraTestHelpers::DependencyInjection)

data/lib/capybara_test_helpers/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 CapybaraTestHelpers::Finders
+  %i[
+    find
+    find_all
+    find_field
+    find_link
+    find_button
+    find_by_id
+    first
+    ancestor
+    sibling
+  ].each do |method_name|
+    CapybaraTestHelpers.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_test_helpers/matchers.rb

@@ -0,0 +1,55 @@
+# 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 CapybaraTestHelpers::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|
+    CapybaraTestHelpers.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|
+    CapybaraTestHelpers.define_helper_method(self, method_name, target: :to_capybara_node)
+  end
+end

data/lib/capybara_test_helpers/rspec.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'capybara_test_helpers'
+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_test_helpers 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.
+  %i[feature system view].each do |type|
+    config.include(CapybaraTestHelpers::DependencyInjection, type: type)
+    config.before(:each, type: type, &inject_test_helpers)
+  end
+end