capybara_test_helpers 1.0.1 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9e4f6226edd7ecb46f2d8376f129d26e8ee0156ed0df1fd1083881a224489da8
-  data.tar.gz: da483ed245cd972f66b291e31c5345bf9b451c8f26c866284d7f35892043a4b6
+  metadata.gz: b44cf8eaed214e39d9bd3078cf7d5144d8664df13619b95686dcfe77c9c44fa1
+  data.tar.gz: eba61f25b74ffd67e04e45504d7479ff10910b6a155428f94d7ed13aa70456d0
 SHA512:
-  metadata.gz: 66ee90ceda7582b79b2ffc905f875422ad7122a3a9a29c589b9df2bd63417ee81c94f6fa66c2d26568ff8cb01e835c8dcc30e4e7970e6ece174376941f07ac39
-  data.tar.gz: c75546cc4a3ea671b22ccf685fba84a2767f3d0ac2e652b214f144eb28ea0a284b8f38198596b03c487f81d49bea0e447ea608b0deeaf42bf2f19d46a3fcae5a
+  metadata.gz: d01e4d56cb7cf5fa40ab2f383ff902b6d343c02741fc4be0ac2217d12b22c0a882dc665f291f6988e9b1abd3fdd663f842aa57be250778c6140f65235527fb96
+  data.tar.gz: fc19367420ea452a08aaf2505cd85b74830823902a0de8696f77f6aec0a6cb9a77ea897ee11522b754f777f1c7e4590f3b3134b0094159801429472e562ef73e

data/CHANGELOG.md

@@ -1,4 +1,8 @@
-## Upcoming Changes
+## 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.

data/README.md

@@ -1,21 +1,6 @@
-<h1 align="center">
-Capybara Test Helpers
-<p align="center">
-<a href="https://github.com/ElMassimo/capybara_test_helpers/actions"><img alt="Build Status" src="https://github.com/ElMassimo/capybara_test_helpers/workflows/build/badge.svg"/></a>
-<a href="https://codeclimate.com/github/ElMassimo/capybara_test_helpers"><img alt="Maintainability" src="https://codeclimate.com/github/ElMassimo/capybara_test_helpers/badges/gpa.svg"/></a>
-<a href="https://codeclimate.com/github/ElMassimo/capybara_test_helpers"><img alt="Test Coverage" src="https://codeclimate.com/github/ElMassimo/capybara_test_helpers/badges/coverage.svg"/></a>
-<a href="https://rubygems.org/gems/capybara_test_helpers"><img alt="Gem Version" src="https://img.shields.io/gem/v/capybara_test_helpers.svg?colorB=e9573f"/></a>
-<a href="https://github.com/ElMassimo/capybara_test_helpers/blob/master/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_test_helpers) is
-an opinionated library built on top of [capybara], that encourages good testing
-practices based on encapsulation and reuse.
-
-Write tests that everyone can understand, and leverage your Ruby skills to keep them __easy to read and easy to change__.
-
 [docs]: https://capybara-test-helpers.netlify.app/
+[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
 [capybara dsl]: https://github.com/teamcapybara/capybara#the-dsl
 [capybara querying]: https://github.com/teamcapybara/capybara#querying
@@ -37,38 +22,36 @@ Write tests that everyone can understand, and leverage your Ruby skills to keep
 [rails_integration]: https://github.com/ElMassimo/capybara_test_helpers/commit/c512e39987215e30227dad45e775480bc1348325
 [cucumber_integration]: https://github.com/ElMassimo/capybara_test_helpers/commit/68e20cb40ba409c50f88f8b745eb908fb067a0aa
 
-Check out the [documentation site][docs] for more information.
-
-## Why? 🤔
-
-[`capybara`][capybara] is a great library for integration tests in Ruby,
-commonly used in combination with [RSpec] or [cucumber].
-
-Although [cucumber] encourages good practices such as writing steps at a high
-level, thinking in terms of the user rather than the interactions required, it
-__doesn't scale well__ in a large project. Steps are available for all tests,
-and there's no way to partition or isolate them.
-
-At the same time, Gherkin is very limited as a language, it can be very awkward
-to use when steps require parameters, and it's hard to find and detect duplicate
-steps, and very __time consuming__ to refactor them.
+<h1 align="center">
+  Capybara Test Helpers
+  <p align="center">
+    <a href="https://github.com/ElMassimo/capybara_test_helpers/actions">
+      <img alt="Build Status" src="https://github.com/ElMassimo/capybara_test_helpers/workflows/build/badge.svg"/>
+    </a>
+    <a href="https://codeclimate.com/github/ElMassimo/capybara_test_helpers">
+      <img alt="Maintainability" src="https://codeclimate.com/github/ElMassimo/capybara_test_helpers/badges/gpa.svg"/>
+    </a>
+    <a href="https://codeclimate.com/github/ElMassimo/capybara_test_helpers">
+      <img alt="Test Coverage" src="https://codeclimate.com/github/ElMassimo/capybara_test_helpers/badges/coverage.svg"/>
+    </a>
+    <a href="https://rubygems.org/gems/capybara_test_helpers">
+      <img alt="Gem Version" src="https://img.shields.io/gem/v/capybara_test_helpers.svg?colorB=e9573f"/>
+    </a>
+    <a href="https://github.com/ElMassimo/capybara_test_helpers/blob/master/LICENSE.txt">
+      <img alt="License" src="https://img.shields.io/badge/license-MIT-428F7E.svg"/>
+    </a>
+  </p>
+</h1>
 
-In contrast, writing tests in [RSpec] has a very low barrier since Ruby is a joy
-to work with, but you are on your own to encapsulate code to avoid coupling
-tests to the current UI. Small changes to the UI should not require rewriting
-dozens of tests, but __without clear guidelines__ it's hard to achieve good tests.
+[__Capybara Test Helpers__](https://github.com/ElMassimo/capybara_test_helpers) is
+an opinionated library built on top of [capybara], that encourages good testing
+practices based on encapsulation and reuse.
 
-This library provides __a solid foundation__ of simple and repeatable patterns
-that can be used to write better tests.
+Write tests that everyone can understand, and leverage your Ruby skills to keep them __easy to read and easy to change__.
 
-## Features ⚡️
+## Documentation 📖
 
-- Leverage your __Ruby__ skills for keeping tests in good shape
-- Powerful syntax for __assertions__ (without monkey patching)
-- __Aliases__ for element locators to avoid repetition
-- __Composability__: define interactions with your UI once, and [focus on the tests][testing robots] many times
-- Dependency injection to make tests __predictable and robust__
-- Full access to the __[Capybara DSL]__
+[Visit the documentation website][docs] to check out the guides, API reference, and examples.
 
 ## Installation 💿
 
@@ -78,325 +61,66 @@ Add this line to your application's Gemfile:
 gem 'capybara_test_helpers'
 ```
 
-And then run:
-
-    $ bundle install
-
-### RSpec
-
-To use with [RSpec], require the following in `spec_helper.rb`:
+To use with [RSpec], add the following to your `spec_helper.rb`:
 
 ```ruby
 require 'capybara_test_helpers/rspec'
 ```
 
-#### In Rails
-
-If using Rails, make sure you [follow the setup in `rspec-rails`][rspec-rails] first.
-
-You can run `rails g test_helper base` to create a base test helper and require
-it as well so that other test helpers can extend it without manually requiring.
-
-```ruby
-# spec/rails_helper.rb
-require 'capybara_test_helpers/rspec'
-require Rails.root.join('test_helpers/base_test_helper')
-```
-
-[Check this example][rails_integration] to see how you can get started.
-
-### Cucumber
-
-To use with [Cucumber], require the following in `env.rb`:
+To use with [Cucumber], add the following to your `support/env.rb`:
 
 ```ruby
 require 'capybara_test_helpers/cucumber'
-require Rails.root.join('test_helpers/base_test_helper')
 ```
 
-Have in mind that RSpec is a much better fit, as Gherkin is very limited.
-
-That said, test helpers do provide [a nice way to share code](https://github.com/ElMassimo/capybara_test_helpers/blob/master/examples/rails_app/features/step_definitions/city_steps.rb) if you are migrating
-from Cucumber to RSpec.
-
-[Check this example][cucumber_integration] to see how you can get started.
+Additional installation instructions are available in the [documentation website][installation].
 
-## Usage 🚀
+## Quick Tour ⚡️
 
-You can define a test helper by subclassing `Capybara::TestHelper`, which has
-full access to the Capybara DSL.
+Let's say we have a list of cities, and we want to test the _Edit_ functionality using [Capybara].
 
 ```ruby
-class CitiesTestHelper < Capybara::TestHelper
-  use_test_helpers(:form, :table)
+scenario 'editing a city' do
+  visit('/cities')
 
-# Selectors: Semantic aliases for elements, a useful abstraction.
-  SELECTORS = {
-    el: 'table.cities',
+  within('.cities') {
+    find(:table_row, { 'Name' => 'NYC' }).click_on('Edit')
   }
+  fill_in 'Name', with: 'New York City'
+  click_on('Update City')
 
-# Getters: A convenient way to get related data or nested elements.
-  def row_for(city)
-    within { table.row_for(city.name) }
-  end
-
-# Actions: Encapsulate complex actions to provide a cleaner interface.
-  def add(**args)
-    click_on('New City')
-    save_city(**args)
-    yield(form) if block_given?
-  end
-
-  def edit(city, with:)
-    row_for(city).click_on('Edit')
-    save_city(**with)
-  end
-
-  def delete(city)
-    accept_confirm { row_for(city).click_on('Destroy') }
-  end
-
-  private \
-  def save_city(name:)
-    form.within {
-      fill_in 'Name', with: name
-      form.save
-    }
-  end
-
-# Assertions: Check on element properties, used with `should` and `should_not`.
-  def have_city(name)
-    within { have(:table_row, { 'Name' => name }) }
-  end
-
-# Background: Helpers to add/modify/delete data in the database or session.
-  def given_there_is_a_city(name)
-    City.create!(name: name)
-  end
-end
-```
-
-When using Rails, you can generate a test helper by running:
-
-    $ rails g test_helper users
-
-### Writing a Test with Helpers ✅
-
-You can find [this working example](https://github.com/ElMassimo/capybara_test_helpers/blob/master/examples/rails_app/spec/system/cities_spec.rb) and more in the [example app] and the [Capybara tests][capybara_test_helpers_tests].
-
-```ruby
-require 'rails_helper'
-
-RSpec.describe 'Cities', test_helpers: [:cities] do
-  let!(:nyc) { cities.given_there_is_a_city('NYC') }
-
-  before { cities.visit_page }
-
-  scenario 'valid inputs' do
-    cities.add(name: 'Minneapolis')
-    cities.should.have_city('Minneapolis')
-  end
-
-  scenario 'invalid inputs' do
-    cities.add(name: '') { |form|
-      form.should.have_error("Name can't be blank")
-    }
-  end
-
-  scenario 'editing a city' do
-    cities.edit(nyc, with: { name: 'New York City' })
-    cities.should_no_longer.have_city('NYC')
-    cities.should_now.have_city('New York City')
-  end
-
-  scenario 'deleting a city', screen_size: :phone do
-    cities.delete(nyc)
-    cities.should_no_longer.have_city('NYC')
-  end
-end
-```
-
-To make the test helper available you can use the [`test_helpers` option][rspec_injection]
-in a `describe`, `context` or `scenario` as seen above.
-
-When using Cucumber, you may call [`use_test_helpers`][cucumber_injection] in the step definitions.
-
-Finally, for test helpers that you expect to use very often, you can [`use_test_helpers`][rspec_global_injection] in an RSpec helper module to make them available globally.
-
-## DSL 🛠
-
-A [documentation website][docs] with the full API and examples is [now available][docs] :shipit:
-
-Every single method in the [Capybara DSL] is available inside test helpers, as
-well as the [built-in RSpec matchers][rspec matchers].
-
-### Selectors 🔍
-
-You can encapsulate locators for commonly used elements to avoid hardcoding them
-in different tests.
-
-As a result, if the UI changes there are less places that need to be updated in
-the tests 😃
-
-```ruby
-class FormTestHelper < BaseTestHelper
-  SELECTORS = {
-    el: '.form',
-    error_summary: ['#error_explanation', visible: true],
-    name_input: [:fillable_field, 'Name'],
-    save_button: [:button, type: 'submit'],
+  within('.cities') {
+    expect(page).not_to have_selector(:table_row, { 'Name' => 'NYC' })
+    expect(page).to have_selector(:table_row, { 'Name' => 'New York City' })
   }
+end
 ```
 
-You can then leverage these aliases on any Capybara method:
-
-```ruby
-# Finding an element
-form.find(:save_button, visible: false)
-
-# Interacting with an element
-form.fill_in(:name_input, with: 'Jane')
-
-# Making an assertion
-form.has_selector?(:error_summary, text: "Can't be blank")
-```
-
-#### Syntax Sugar
-
-To avoid repetition, getters are available for every selector alias:
-
-```ruby
-form.find(:name_input)
-# same as
-form.name_input
-
-form.find(:error_summary, text: "Can't be blank")
-# same as
-form.error_summary(text: "Can't be blank")
-```
-
-#### `:el` convention
-
-By convention, `:el` is the top-level element of the component or page the test
-helper is encapsulating, which will be used automatically when calling a
-Capybara operation that requires a node, such as `click` or `value`.
-
-```ruby
-form.within { save_button.click }
-# same as
-form.within(:el) { save_button.click }
-# same as
-form.el.within { save_button.click }
-```
-
-### Assertions ☑️
-
-You can use any of the [RSpec matchers provided by Capybara][capybara querying],
-but the way to use them in test helpers is slightly different.
-
-Before using an assertion, you must call [`should`][should] or [`should_not`][should_not], and then
-chain the RSpec matcher or your own custom assertion.
-
-```ruby
-users.find(:table)
-  .should.have_selector(:table_row, ['Jane', 'Doe']
-  .should_not.have_selector(:table_row, ['John', 'Doe'])
-```
-
-#### Custom Assertions 🎩
+Even though it gets the job done, it takes a while to understand what the test is trying to do.
 
-The example above becomes a lot nicer if we define a more semantic assertion,
-which can be easily done by leveraging an existing assertion:
-
-```ruby
-class UsersTestHelper < BaseTestHelper
-  SELECTORS = {
-    list: 'table.users',
-  }
+Without discipline these tests can become __hard to manage__ and require __frequent updating__.
 
-# Assertions: Check on element properties, used with `should` and `should_not`.
-  def have_user(*names)
-    have(:table_row, names)
-  end
-```
+### Using Test Helpers
 
-and then use it as:
+We can avoid the duplication and keep the [focus on the test][design patterns] instead of its
+implementation by using [__test helpers__][docs].
 
 ```ruby
-users.list
-  .should.have_user('Jane', 'Doe')
-  .should_not.have_user('John', 'Doe')
-```
-
-Notice that you don't need to define both the [positive and negative assertions],
-they are both available because we are using an existing assertion.
-
-#### Advanced Assertions ⚙️
+scenario 'editing a city', test_helpers: [:cities] do
+  cities.visit_page
 
-Sometimes built-in assertions are not enough, and you need to use an expectation
-directly. Test helpers provide [`to_or` and `not_to` methods][positive and negative assertions] that you
-can use to implement an assertion that you can use with `should` or `should_not`.
+  cities.edit('NYC', with: { name: 'New York City' })
 
-```ruby
-class CurrentPageTestHelper < BaseTestHelper
-# Getters: A convenient way to get related data or nested elements.
-  def fullscreen?
-    evaluate_script('!!(document.mozFullScreenElement || document.webkitFullscreenElement)')
-  end
-
-# Assertions: Allow to check on element properties while keeping it DRY.
-  def be_fullscreen
-    expect(fullscreen?).to_or not_to, eq(true)
-  end
+  cities.should_no_longer.have_city('NYC')
+  cities.should_now.have_city('New York City')
 end
-
-current_page.should.be_fullscreen
-current_page.should_not.be_fullscreen
-```
-
-You can make the assertion retry automatically until the Capybara timeout by
-using `synchronize_expectation`:
-
-```ruby
-  def be_fullscreen
-    synchronize_expectation {
-      expect(fullscreen?).to_or not_to, eq(true)
-    }
-  end
-```
-
-## Design 📐
-
-This library is loosely based on the concepts of [Page Objects][page_objects] and [Testing Robots][testing_robots], with a healthy dose of [dependency injection](https://martinfowler.com/articles/injection.html).
-
-Capybara has a great DSL, so the focus of this library is to build upon it, by
-allowing you to create your own actions and assertions and call them just as
-fluidly as you would call `find` or `has_content?`.
-
-This library works best when encapsulating common UI patterns in separate helpers,
-such as a `FormTestHelper` or a `DropdownTestHelper`, and then reusing them in
-page-specific test helpers to make the test read more semantically.
-
-## Formatting 📏
-
-Regarding selectors, I highly recommend writing one attribute per line, sorting
-them alphabetically (most editors can do it for you), and
-[always using a trailing comma][trailing_commas].
-
-```ruby
-class DropdownTestHelper < BaseTestHelper
-# Selectors: Semantic aliases for elements, a useful abstraction.
-  SELECTORS = {
-    el: '.dropdown',
-    toggle: '.dropdown-toggle',
-  }
 ```
 
-It will minimize the amount of git conflicts, and keep the history a lot cleaner and more meaningful when using `git blame`.
+Learn more about it in the [documentation website][docs].
 
 ## Special Thanks 🙏
 
-This library wouldn't be the same without the early validation from my colleagues, and numerous improvements and bugfixes they contributed to it. Thanks for the support 😃
+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]: Solid library to write integration tests in Ruby.
 

data/lib/capybara_test_helpers/selectors.rb

@@ -40,6 +40,11 @@ module CapybaraTestHelpers::Selectors
   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

data/lib/capybara_test_helpers/version.rb

@@ -2,5 +2,5 @@
 
 # Easily write fluent Page Objects for Capybara in Ruby.
 module CapybaraTestHelpers
-  VERSION = '1.0.1'
+  VERSION = '1.0.2'
 end

data/lib/generators/test_helper/test_helper_generator.rb

@@ -5,16 +5,22 @@ 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("#{ 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 = {}
+        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('_', '-') }'," }
+          )
 
-        # Getters: A convenient way to get related data or nested elements.
+        # Finders: A convenient way to get related data or nested elements.
 
         # Actions: Encapsulate complex actions to provide a cleaner interface.
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: capybara_test_helpers
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.2
 platform: ruby
 authors:
 - Maximo Mussini
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-11-19 00:00:00.000000000 Z
+date: 2020-11-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport