capybara-compose 1.0.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 037e1213be976eef937bb06defb927fc534915273d3f0b01388c78a0f9f69021
+  data.tar.gz: 64cf4560fc3a53a2333c02addb42336d768dbb7d115a41d18a26b584a0205884
+SHA512:
+  metadata.gz: d35e1c57511578085cf4b7484b933d31dbbc16238b5c931d6592e389408d3b4b0d4ceb27bfba61682c2860dc6a9f22b662dacc928993c82a65d0445e0f2b2888
+  data.tar.gz: 9a48802d63b7b580f76ccc37e458587de08d6ae3374c21a46f3f650fa238815cce1bc0f79f9d0d9073735919dda9ea3cb6a093f926d0bb7ccfd6740ce999763e

data/CHANGELOG.md

@@ -0,0 +1,27 @@
+## Capybara Compose 2.0.0 (2021-02-24) ##
+
+* Rebrand _Capybara Test Helpers_ as _Capybara Compose_, and emphasize how the advantage is in reusing modules shared by the community.
+
+## Capybara Test Helpers 1.0.4 (2020-11-26) ##
+
+* Add `have_no` alias for `have_no_selector`.
+* Add `has_no?` alias for `has_no_selector?`.
+* Remove internal method `wrap_test_helper`.
+* Allow to use locator aliases in `assert_` methods as well, for consistency.
+
+## Capybara Test Helpers 1.0.3 (2020-11-24) ##
+
+* Add `Capybara::Compose::BenchmarkHelpers`
+
+## Capybara Test Helpers 1.0.2 (2020-11-23) ##
+
+*   Add `aliases` DSL to define `SELECTORS`.
+
+## Capybara Test Helpers 1.0.1 (2020-11-19) ##
+
+*   Add `has?` alias for `has_selector?`.
+*   Delegate `have` to the RSpec collection matcher when passing an Integer.
+
+## Capybara Test Helpers 1.0.0 (2020-11-17) ##
+
+*   Initial Release.

data/README.md

@@ -0,0 +1,124 @@
+[docs]: https://capybara-test-helpers.netlify.app/
+[guide]: https://capybara-test-helpers.netlify.app/guide/
+[api]: https://capybara-test-helpers.netlify.app/api/
+[design patterns]: https://capybara-test-helpers.netlify.app/guide/advanced/design-patterns
+[installation]: https://capybara-test-helpers.netlify.app/installation
+[capybara]: https://github.com/teamcapybara/capybara
+[cucumber]: https://github.com/cucumber/cucumber-ruby
+[current context]: https://capybara-test-helpers.netlify.app/guide/essentials/current-context
+[rspec]: https://github.com/rspec/rspec
+[aliases]: https://capybara-test-helpers.netlify.app/guide/essentials/aliases
+[assertions]: https://capybara-test-helpers.netlify.app/guide/essentials/assertions
+[synchronization]: https://capybara-test-helpers.netlify.app/guide/advanced/synchronization
+
+<h1 align="center">
+  Capybara Test Helpers
+  <p align="center">
+    <a href="https://github.com/ElMassimo/capybara-compose/actions">
+      <img alt="Build Status" src="https://github.com/ElMassimo/capybara-compose/workflows/build/badge.svg"/>
+    </a>
+    <a href="https://codeclimate.com/github/ElMassimo/capybara-compose">
+      <img alt="Maintainability" src="https://codeclimate.com/github/ElMassimo/capybara-compose/badges/gpa.svg"/>
+    </a>
+    <a href="https://codeclimate.com/github/ElMassimo/capybara-compose">
+      <img alt="Test Coverage" src="https://codeclimate.com/github/ElMassimo/capybara-compose/badges/coverage.svg"/>
+    </a>
+    <a href="https://rubygems.org/gems/capybara-compose">
+      <img alt="Gem Version" src="https://img.shields.io/gem/v/capybara-compose.svg?colorB=e9573f"/>
+    </a>
+    <a href="https://github.com/ElMassimo/capybara-compose/blob/main/LICENSE.txt">
+      <img alt="License" src="https://img.shields.io/badge/license-MIT-428F7E.svg"/>
+    </a>
+  </p>
+</h1>
+
+[__Capybara Test Helpers__](https://github.com/ElMassimo/capybara-compose) allows you to easily encapsulate logic in your integration tests.
+
+Write tests that everyone can understand, and leverage your Ruby skills to keep them __easy to read and easy to change__.
+
+## Features ⚡️
+
+[Locator Aliases][aliases] work with every [Capybara] method, allowing you to encapsulate CSS selectors and labels, and avoid coupling tests with the implementation.
+
+The [entire Capybara DSL is available][api], and element results are [wrapped automatically][current context] so that you can chain your own assertions and actions fluently.
+
+A [powerful syntax for assertions][assertions] and convenient primitives for [synchronization] enable you to write async-aware expectations: say goodbye to flaky tests.
+
+## Documentation 📖
+
+Visit the [documentation website][docs] to check out the [guides][guide], searchable [__API reference__][api], and examples.
+
+## Installation 💿
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'capybara/compose'
+```
+
+To use with [RSpec], add the following to your `spec_helper.rb`:
+
+```ruby
+require 'capybara/compose/rspec'
+```
+
+To use with [Cucumber], add the following to your `support/env.rb`:
+
+```ruby
+require 'capybara/compose/cucumber'
+```
+
+Additional installation instructions are available in the [documentation website][installation].
+
+## Quick Tour 🛣
+
+Let's say we have a list of cities, and we want to test the _Edit_ functionality using [Capybara].
+
+```ruby
+scenario 'editing a city' do
+  visit('/cities')
+
+  within('.cities') {
+    find(:table_row, { 'Name' => 'NYC' }).click_on('Edit')
+  }
+  fill_in 'Name', with: 'New York City'
+  click_on('Update City')
+
+  within('.cities') {
+    expect(page).not_to have_selector(:table_row, { 'Name' => 'NYC' })
+    expect(page).to have_selector(:table_row, { 'Name' => 'New York City' })
+  }
+end
+```
+
+Even though it gets the job done, it takes a while to understand what the test is trying to do.
+
+Without discipline these tests can become __hard to manage__ and require __frequent updating__.
+
+### Using Test Helpers
+
+We can avoid the duplication and keep the [focus on the test][design patterns] instead of its
+implementation by using [__test helpers__][docs].
+
+```ruby
+scenario 'editing a city', test_helpers: [:cities] do
+  cities.visit_page
+
+  cities.edit('NYC', with: { name: 'New York City' })
+
+  cities.should_no_longer.have_city('NYC')
+  cities.should_now.have_city('New York City')
+end
+```
+
+Learn more about it in the [documentation website][docs].
+
+## Special Thanks 🙏
+
+This library wouldn't be the same without early validation from my colleagues, and numerous improvements and bugfixes they contributed to it. Thanks for the support 😃
+
+- [capybara]: Excellent library to write integration tests in Ruby.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/capybara/compose.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'capybara'
+
+require 'zeitwerk'
+loader = Zeitwerk::Loader.for_gem
+loader.tag = 'capybara-compose'
+loader.ignore(
+  File.expand_path("#{ __dir__ }/compose/rspec.rb"),
+  File.expand_path("#{ __dir__ }/compose/cucumber.rb"),
+  File.expand_path("#{ __dir__ }/compose/minitest.rb"),
+)
+loader.push_dir(__dir__, namespace: Capybara)
+loader.setup
+
+# Internal: Global configuration for the library.
+module Capybara::Compose
+  DEFAULT_CONFIGURATION = {
+    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
+
+  # Internal: Struct for configuration.
+  Config = Struct.new(*DEFAULT_CONFIGURATION.keys)
+
+  # Public: Returns the current configuration for the test helpers.
+  def self.config
+    @config ||= Config.new(*DEFAULT_CONFIGURATION.values)
+    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
+
+# NOTE: Simplify migration from Capybara Test Helpers.
+CapybaraTestHelpers = Capybara::Compose unless defined?(CapybaraTestHelpers)
+Capybara::TestHelper = Capybara::Compose::TestHelper unless defined?(Capybara::TestHelper)

data/lib/capybara/compose/actions.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+# Internal: Allows to pass test helpers as arguments to `evaluate_script`.
+Capybara::Session.prepend(Module.new {
+private
+
+  # Override: To ensure test helpers are sent to the driver as native elements.
+  def driver_args(args)
+    super(args.map { |arg| arg.is_a?(Capybara::Compose::TestHelper) ? arg.to_capybara_node : arg })
+  end
+})
+
+# Internal: Allows to pass a test helper to `scroll_to`.
+Capybara::Node::Element.prepend(Module.new {
+  # Override: Unwrap capybara test helpers into a node.
+  def scroll_to(pos_or_x_or_el, *args, **kwargs)
+    pos_or_x_or_el = pos_or_x_or_el.to_capybara_node if pos_or_x_or_el.is_a?(Capybara::Compose::TestHelper)
+    super
+  end
+})
+
+# Internal: Wraps Capybara actions 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::Actions
+  delegate(
+    :==,  # Allows to make comparisons more transparent.
+    :===, # Allows to ensure case statements inside Capybara work as expected.
+    to: :to_capybara_node,
+  )
+
+  delegate(
+    :[],
+    :all_text,
+    :checked?,
+    :disabled?,
+    :multiple?,
+    :obscured?,
+    :readonly?,
+    :selected?,
+    :base,
+    :native,
+    :path,
+    :rect,
+    :style,
+    :tag_name,
+    :text,
+    :value,
+    :visible?,
+    :visible_text,
+    to: :to_capybara_node,
+  )
+
+  delegate(
+    :evaluate_script,
+    :evaluate_async_script,
+    to: :current_context,
+  )
+
+  %i[
+    execute_script
+    scroll_to
+  ].each do |method_name|
+    Capybara::Compose.define_helper_method(self, method_name, return_self: true, inject_test_helper: false)
+  end
+
+  %i[
+    click
+    double_click
+    drag_to
+    drop
+    flash
+    hover
+    reload
+    right_click
+    select_option
+    send_keys
+    set
+    trigger
+    unselect_option
+  ].each do |method_name|
+    Capybara::Compose.define_helper_method(self, method_name, target: :to_capybara_node, return_self: true, inject_test_helper: false)
+  end
+
+  %i[
+    click_on
+    click_link_or_button
+    click_button
+    click_link
+    choose
+    check
+    uncheck
+    fill_in
+    attach_file
+    select
+    unselect
+  ].each do |method_name|
+    Capybara::Compose.define_helper_method(self, method_name, wrap: true)
+  end
+
+  # Public: Sets the value for the input, or presses the specified keys, one at a time.
+  def type_in(*text, typing: text.size > 1 || text.first.is_a?(Symbol) || text.first.is_a?(Array), **options)
+    typing ? send_keys(*text) : set(text.first, **options)
+  end
+
+  # Public: Useful to natively give focus to an element.
+  def focus
+    to_capybara_node.execute_script('this.focus()')
+    self
+  end
+
+  # Public: Useful to natively blur an element.
+  def blur
+    to_capybara_node.execute_script('this.blur()')
+    self
+  end
+end

data/lib/capybara/compose/assertions.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+# NOTE: Optional dependency to enable `to_or`.
+begin
+  require 'rspec/expectations'
+  RSpec::Expectations::ExpectationTarget.include(Capybara::Compose::ToOrExpectationHandler)
+rescue LoadError
+end
+
+# Internal: Wraps RSpec matchers to allow using them after calling `should` or
+# `should_not` to perform the assertion.
+module Capybara::Compose::Assertions
+  # Public: Returns a test helper with a positive assertion state.
+  # Any assertions called after it will execute as `expect(...).to ...`.
+  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: Returns a test helper with a negative assertion state.
+  # Any assertions called after it will execute as `expect(...).not_to ...`.
+  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|
+    Capybara::Compose.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|
+    Capybara::Compose.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|
+    Capybara::Compose.define_helper_method(self, method_name, target: :page, assertion: true, inject_test_helper: false)
+  end
+
+  # Public: Allows to call have_selector with a shorter syntax.
+  def have(*args, **kwargs, &filter)
+    if args.first.is_a?(Integer)
+      ::RSpec::CollectionMatchers::Have.new(*args, **kwargs)
+    else
+      have_selector(*args, **kwargs, &filter)
+    end
+  end
+
+  alias have_no have_no_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
+
+  BE_PREDICATE_REGEX = /^(?:be_(?:an?_)?)(.*)/
+  HAS_REGEX = /^(?:have_)(.*)/
+  DYNAMIC_MATCHER_REGEX = Regexp.union(BE_PREDICATE_REGEX, HAS_REGEX)
+
+  # 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 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 =~ DYNAMIC_MATCHER_REGEX
+
+    super
+  end
+end