capybara-compose 1.0.4

data/lib/capybara/compose/synchronization.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# Internal: Provides helper functions to perform asynchronous assertions.
+module Capybara::Compose::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, **options, &block)
+    (current_element? ? current_context : page.document).synchronize(wait, **options, &block)
+  end
+end

data/lib/capybara/compose/test_helper.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+# NOTE: Optional dependencies.
+require 'capybara/rspec' rescue nil
+require 'capybara/minitest' rescue nil
+
+require 'active_support/core_ext/module/delegation'
+require 'active_support/core_ext/string/inflections'
+require 'active_support/core_ext/object/blank'
+
+# 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 Capybara::Compose::TestHelper
+  include RSpec::Matchers rescue nil
+  include RSpec::Mocks::ExampleMethods rescue nil
+  include Capybara::Minitest::Assertions rescue nil
+
+  include Capybara::DSL
+  include Capybara::Compose::Selectors
+  include Capybara::Compose::Synchronization
+  include Capybara::Compose::Finders
+  include Capybara::Compose::Actions
+  include Capybara::Compose::Assertions
+  include Capybara::Compose::Matchers
+
+  undef_method(*Capybara::Compose::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 or test helper with a test helper
+  # object of this class.
+  def wrap_element(element)
+    if element.is_a?(Enumerable)
+      element.map { |node| wrap_element(node) }
+    else
+      raise ArgumentError, "#{ element.inspect } must be a test helper or element." unless element.respond_to?(:to_capybara_node)
+
+      self.class.new(element.to_capybara_node, test_context: test_context)
+    end
+  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 make other test helpers available.
+    #
+    # 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)
+          test_helper = test_helper.wrap_element(element) if element
+          @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 Capybara::Compose::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

data/lib/capybara/compose/to_or_expectation_handler.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# 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 Capybara::Compose::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

data/lib/capybara/compose/version.rb

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

data/lib/generators/test_helper/test_helper_generator.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'capybara/compose'
+require 'rails/generators/named_base'
+
+# Internal: Generates a new test helper file in the appropriate directory.
+class TestHelperGenerator < Rails::Generators::NamedBase
+  def base_helper?
+    file_name.to_s == 'base'
+  end
+
+  def create_helper_file
+    create_file("#{ Capybara::Compose.config.helpers_paths.first }/#{ file_name }_test_helper.rb") {
+      <<~CAPYBARA_TEST_HELPER
+        # frozen_string_literal: true
+
+        class #{ file_name.camelize }TestHelper < #{ base_helper? ? 'Capybara::TestHelper' : 'BaseTestHelper' }
+        # Aliases: Semantic aliases for locators, can be used in most DSL methods.
+          aliases(
+            #{ base_helper? ? '# Avoid defining :el here since it will be inherited by all helpers.' : "# el: '.#{ file_name.tr('_', '-') }'," }
+          )
+
+        # Finders: 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

metadata

@@ -0,0 +1,106 @@
+--- !ruby/object:Gem::Specification
+name: capybara-compose
+version: !ruby/object:Gem::Version
+  version: 1.0.4
+platform: ruby
+authors:
+- Maximo Mussini
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2021-02-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: capybara
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Write tests that everyone can understand, and leverage your Ruby skills
+  to keep them easy to read and easy to change.
+email:
+- maximomussini@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- README.md
+- lib/capybara/compose.rb
+- lib/capybara/compose/actions.rb
+- lib/capybara/compose/assertions.rb
+- lib/capybara/compose/benchmark_helpers.rb
+- lib/capybara/compose/cucumber.rb
+- lib/capybara/compose/dependency_injection.rb
+- lib/capybara/compose/finders.rb
+- lib/capybara/compose/matchers.rb
+- lib/capybara/compose/rspec.rb
+- lib/capybara/compose/selectors.rb
+- lib/capybara/compose/synchronization.rb
+- lib/capybara/compose/test_helper.rb
+- lib/capybara/compose/to_or_expectation_handler.rb
+- lib/capybara/compose/version.rb
+- lib/generators/test_helper/test_helper_generator.rb
+homepage: https://github.com/ElMassimo/capybara-compose
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/ElMassimo/capybara-compose
+  source_code_uri: https://github.com/ElMassimo/capybara-compose
+  changelog_uri: https://github.com/ElMassimo/capybara-compose/blob/master/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.3
+signing_key:
+specification_version: 4
+summary: Easily write fluent Page Objects for Capybara in Ruby.
+test_files: []