page_ez 0.1.0

data/README.md

@@ -0,0 +1,575 @@
+# PageEz
+
+[![Coverage Status](https://coveralls.io/repos/github/joshuaclayton/page_ez/badge.svg?branch=main)](https://coveralls.io/github/joshuaclayton/page_ez?branch=main)
+
+PageEz is a tool to define page objects with [Capybara].
+
+[Capybara]: https://github.com/teamcapybara/capybara
+
+## Installation
+
+Add the gem to your `Gemfile`:
+
+```
+gem "page_ez"
+```
+
+## Usage
+
+Define a page object:
+
+```rb
+class TodosIndex < PageEz::Page
+  has_one :active_list, "section.active ul" do
+    has_many :items do
+      has_one :name, "span[data-role=todo-name]"
+      has_one :checkbox, "input[type=checkbox]"
+
+      def mark_complete
+        checkbox.click
+      end
+    end
+  end
+
+  def active_todo_names
+    items.map { _1.name.text }
+  end
+
+  has_one :completed_list, "section.complete ul" do
+    has_many :items do
+      has_one :name, "span[data-role=todo-name]"
+      has_one :checkbox, "input[type=checkbox]"
+
+      def mark_incomplete
+        checkbox.click
+      end
+    end
+  end
+end
+```
+
+Use your page object:
+
+```rb
+it "manages todos state when completing" do
+  user = create(:user)
+  create(:todo, name: "Buy milk", user:)
+  create(:todo, name: "Buy eggs", user:)
+
+  sign_in_as user
+
+  todos_index = TodosIndex.new
+
+  expect(todos_index.active_todo_names).to eq(["Buy milk", "Buy eggs"])
+  todos_index.active_list.item_matching(text: "Buy milk").mark_complete
+  expect(todos_index.active_todo_names).to eq(["Buy eggs"])
+  todos_index.active_list.item_matching(text: "Buy eggs").mark_complete
+
+  expect(todos_index.active_todo_names).to be_empty
+
+  todos_index.completed_list.item_matching(text: "Buy milk").mark_incomplete
+  expect(todos_index.active_todo_names).to eq(["Buy milk"])
+  todos_index.completed_list.item_matching(text: "Buy eggs").mark_incomplete
+  expect(todos_index.active_todo_names).to eq(["Buy milk", "Buy eggs"])
+end
+```
+
+### `has_one`
+
+You can define accessors to individual elements (matched with Capybara's `find`):
+
+```rb
+class BlogPost < PageEz::Page
+  has_one :post_title, "header h2"
+  has_one :body, "section[data-role=post-body]"
+  has_one :published_date, "time[data-role=published-date]"
+end
+
+# generates the following methods:
+
+blog_post = BlogPost.new
+
+blog_post.post_title             # => find("header h2")
+blog_post.has_post_title?        # => has_css?("header h2")
+blog_post.has_no_post_title?     # => has_no_css?("header h2")
+
+blog_post.body                   # => find("section[data-role=post-body]")
+blog_post.has_body?              # => has_css?("section[data-role=post-body]")
+blog_post.has_no_body?           # => has_no_css?("section[data-role=post-body]")
+
+blog_post.published_date         # => find("time[data-role=published-date]")
+blog_post.has_published_date?    # => has_css?("time[data-role=published-date]")
+blog_post.has_no_published_date? # => has_no_css?("time[data-role=published-date]")
+
+blog_post.post_title(text: "Writing Ruby is Fun!")           # => find("header h2", text: "Writing Ruby is Fun!")
+blog_post.has_post_title?(text: "Writing Ruby is Fun!")      # => has_css?("header h2", text: "Writing Ruby is Fun!")
+blog_post.has_no_post_title?(text: "Writing Ruby is Boring") # => has_no_css?("header h2", text: "Writing Ruby is Boring")
+```
+
+The methods defined by PageEz can be passed additional options from Capybara. Refer to documentation for the following methods:
+
+* [`Capybara::Node::Finders#find`]
+* [`Capybara::Node::Matchers#has_css?`]
+
+### `has_many`
+
+You can define accessors to multiple elements (matched with Capybara's `all`):
+
+```rb
+class TodosIndex < PageEz::Page
+  has_many :todos, "ul li span[data-role=todo-name]"
+end
+
+# generates the following methods:
+
+todos_index = TodosIndex.new
+
+todos_index.todos                                   # => all("ul li span[data-role=todo-name]")
+todos_index.has_todos?                              # => has_css?("ul li span[data-role=todo-name]")
+todos_index.has_no_todos?                           # => has_no_css?("ul li span[data-role=todo-name]")
+
+todos_index.todo_matching(text: "Buy milk")         # => find("ul li span[data-role=todo-name]", text: "Buy milk")
+todos_index.has_todo_matching?(text: "Buy milk")    # => has_css?("ul li span[data-role=todo-name]", text: "Buy milk")
+todos_index.has_no_todo_matching?(text: "Buy milk") # => has_no_css?("ul li span[data-role=todo-name]", text: "Buy milk")
+
+todos_index.todos.has_count_of?(number)             # => has_css?("ul li span[data-role=todo-name]", count: number)
+todos_index.has_todos_count?(number)                # => has_css?("ul li span[data-role=todo-name]", count: number)
+
+todos_index.todos.has_any_elements?                 # => has_css?("ul li span[data-role=todo-name]")
+todos_index.todos.has_no_elements?                  # => has_no_css?("ul li span[data-role=todo-name]")
+```
+
+The methods defined by PageEz can be passed additional options from Capybara. Refer to documentation for the following methods:
+
+* [`Capybara::Node::Finders#all`]
+* [`Capybara::Node::Matchers#has_css?`]
+
+### `has_many_ordered`
+
+This mirrors the `has_many` macro but adds additional methods for accessing
+elements at a specific index.
+
+```rb
+class TodosIndex < PageEz::Page
+  has_many_ordered :todos, "ul[data-role=todo-list] li"
+end
+
+# generates the base has_many methods (see above)
+
+# in addition, it generates the ability to access at an index. The index passed
+# to Ruby will be translated to the appropriate `:nth-of-child` (which is a
+# 1-based index rather than 0-based)
+
+todos_index.todo_at(0)                   # => find("ul[data-role=todo-list] li:nth-of-type(1)")
+todos_index.has_todo_at?(0)              # => has_css?("ul[data-role=todo-list] li:nth-of-type(1)")
+todos_index.has_no_todo_at?(0)           # => has_no_css?("ul[data-role=todo-list] li:nth-of-type(1)")
+
+todos_index.todo_at(0, text: "Buy milk") # => find("ul[data-role=todo-list] li:nth-of-type(1)", text: "Buy milk")
+```
+
+The methods defined by PageEz can be passed additional options from Capybara. Refer to documentation for the following methods:
+
+* [`Capybara::Node::Finders#find`]
+* [`Capybara::Node::Matchers#has_css?`]
+
+### `contains`
+
+This provides a shorthand for delegating methods from one page object to
+another, flattening the hierarchy of page objects and making it easier to
+interact with application-level componentry.
+
+```rb
+class SidebarModal < PageEz::Page
+  base_selector "div[data-role=sidebar]"
+
+  has_one :sidebar_heading, "h2"
+  has_one :sidebar_contents, "section[data-role=contents]"
+end
+
+class PeopleIndex < PageEz::Page
+  contains SidebarModal
+
+  has_many :people_rows, "ul[data-role=people-list] li" do
+    has_one :name, "span[data-role=person-name]"
+    has_one :edit_link, "a", text: "Edit"
+  end
+
+  def change_person_name(from:, to:)
+    people_row_matching(text: from).edit_link.click
+
+    within sidebar_contents do
+      fill_in "Name", with: to
+      click_on "Save Person"
+    end
+  end
+end
+```
+
+By default, this delegates all methods to an instance of the page object. If
+you prefer to delegate a subset of the methods, you can do so with the `only`
+option:
+
+```rb
+class SidebarModal < PageEz::Page
+  base_selector "div[data-role=sidebar]"
+
+  has_one :sidebar_heading, "h2"
+  has_one :sidebar_contents, "section[data-role=contents]"
+end
+
+class PeopleIndex < PageEz::Page
+  contains SidebarModal, only: %i[sidebar_contents]
+end
+```
+
+The equivalent functionality could be achieved with:
+
+```rb
+class SidebarModal < PageEz::Page
+  base_selector "div[data-role=sidebar]"
+
+  has_one :sidebar_heading, "h2"
+  has_one :sidebar_contents, "section[data-role=contents]"
+end
+
+class PeopleIndex < PageEz::Page
+  has_one :sidebar_modal, SidebarModal
+  delegate :sidebar_contents, to: :sidebar_modal
+end
+```
+
+### Using Methods as Dynamic Selectors
+
+In the examples above, the CSS selectors are static.
+
+However, there are a few different ways to define `has_one`, `has_many`, and
+`has_many_ordered` elements as dynamic.
+
+```rb
+class TodosIndex < PageEz::Page
+  has_one :todo_by_id
+
+  def todo_by_id(id:)
+    "[data-model=todo][data-model-id=#{id}]"
+  end
+end
+
+# generates the same methods as has_one (see above) but with a required `id:` keyword argument
+
+todos_index = TodosIndex.new
+todos_index.todo_by_id(id: 5)         # => find("[data-model=todo][data-model-id=5]")
+todos_index.has_todo_by_id?(id: 5)    # => has_css?("[data-model=todo][data-model-id=5]")
+todos_index.has_no_todo_by_id?(id: 5) # => has_no_css?("[data-model=todo][data-model-id=5]")
+```
+
+The first mechanism declares the `has_one :todo_by_id` at the top of the file,
+and the definition for the selector later on. This allows for grouping multiple
+`has_one`s together for readability.
+
+The second approach syntactically mirrors Ruby's `private_class_method`:
+
+```rb
+class TodosIndex < PageEz::Page
+  has_one def todo_by_id(id:)
+    "[data-model=todo][data-model-id=#{id}]"
+  end
+
+  # or
+
+  def todo_by_id(id:)
+    "[data-model=todo][data-model-id=#{id}]"
+  end
+  has_one :todo_by_id
+end
+```
+
+In either case, the method needs to return a CSS string. PageEz will generate
+the corresponding predicate methods as expected, as well (in the example above,
+`#has_todo_by_id?(id:)` and `#has_no_todo_by_id?(id:)`
+
+For the additional methods generated with the `has_many_ordered` macro (e.g.
+for `has_many_ordered :items`, the methods `#item_at` and `#has_item_at?`), the
+first argument is the index of the element, and all other args will be passed
+through.
+
+```rb
+class TodosList < PageEz::Page
+  has_many_ordered :items do
+    has_one :name, "[data-role='title']"
+    has_one :checkbox, "input[type='checkbox']"
+  end
+
+  def items(state:)
+    "li[data-state='#{state}']"
+  end
+end
+```
+
+This would enable usage as follows:
+
+```rb
+todos = TodosList.new
+
+expect(todos.items(state: "complete")).to have_count_of(1)
+expect(todos.items(state: "incomplete")).to have_count_of(2)
+
+expect(todos).to have_item_at(0, state: "complete")
+expect(todos).not_to have_item_at(1, state: "complete")
+expect(todos).to have_item_at(0, state: "incomplete")
+expect(todos).to have_item_at(1, state: "incomplete")
+expect(todos).not_to have_item_at(2, state: "incomplete")
+```
+
+One key aspect of PageEz is that page hierarchy can be codified and scoped for interaction.
+
+```rb
+class TodosList
+  has_many_ordered :items, "li" do
+    has_one :name, "span[data-role=name]"
+    has_one :complete_button, "input[type=checkbox][data-action=toggle-complete]"
+  end
+end
+
+# generates the following method chains
+
+todos_list = TodosList.new
+
+todos_list.items.first.name                             # => all("li").first.find("span[data-role=name]")
+todos_list.items.first.has_name?                        # => all("li").first.has_css?("span[data-role=name]")
+todos_list.items.first.has_no_name?(text: "Buy yogurt") # => all("li").first.has_no_css?("span[data-role=name]", text: "Buy yogurt")
+todos_list.items.first.complete_button.click            # => all("li").first.find("input[type=checkbox][data-action=toggle-complete]").click
+
+# and, because we're using has_many_ordered:
+
+todos_list.item_at(0).name                              # => find("li:nth-of-type(1)").find("span[data-role=name]")
+todos_list.item_at(0).has_name?                         # => find("li:nth-of-type(1)").has_css?("span[data-role=name]")
+todos_list.item_at(0).has_no_name?(text: "Buy yogurt")  # => find("li:nth-of-type(1)").has_no_css?("span[data-role=name]", text: "Buy yogurt")
+todos_list.item_at(0).complete_button.click             # => find("li:nth-of-type(1)").find("input[type=checkbox][data-action=toggle-complete]").click
+```
+
+[`Capybara::Node::Finders#all`]: https://rubydoc.info/github/teamcapybara/capybara/Capybara/Node/Finders#all-instance_method
+[`Capybara::Node::Finders#find`]: https://rubydoc.info/github/teamcapybara/capybara/Capybara/Node/Finders#find-instance_method
+[`Capybara::Node::Matchers#has_css?`]: https://rubydoc.info/github/teamcapybara/capybara/Capybara/Node/Matchers#has_css%3F-instance_method
+
+## Base Selectors
+
+Certain components may exist across multiple pages but have a base selector
+from which all interactions should be scoped.
+
+This can be configured on a per-object basis:
+
+```rb
+class ApplicationHeader < PageEz::Page
+  base_selector "header[data-role=primary]"
+
+  has_one :application_title, "h1"
+end
+```
+
+## Page Object Composition
+
+Because page objects can encompass as much or as little of the DOM as desired,
+it's possible to compose multiple page objects.
+
+### Composition via DSL
+
+```rb
+class Card < PageEz::Page
+  has_one :header, "h3"
+end
+
+class PrimaryNav < PageEz::Page
+  has_one :home_link, "a[data-role='home-link']"
+end
+
+class Dashboard < PageEz::Page
+  has_many_ordered :metrics, "ul.metrics li" do
+    has_one :card, Card
+  end
+
+  has_one :primary_nav, PrimaryNav, base_selector: "nav.primary"
+end
+```
+
+### Manual Composition
+
+```rb
+class Card < PageEz::Page
+  has_one :header, "h3"
+end
+
+class PrimaryNav < PageEz::Page
+  has_one :home_link, "a[data-role='home-link']"
+end
+
+class Dashboard < PageEz::Page
+  has_many_ordered :metrics, "ul.metrics li" do
+    def card
+      # passing `self` is required to scope the query for the specific card
+      # within the metric when nested inside `has_one`, `has_many`, and
+      # `has_many_ordered`
+      Card.new(self)
+    end
+  end
+
+  def primary_nav
+    # pass the element `Capybara::Node::Element` to scope page interaction when
+    # composing at the top-level PageEz::Page class
+    PrimaryNav.new(find("nav.primary"))
+  end
+end
+```
+
+With the following markup:
+
+```html
+<nav class="primary">
+  <ul>
+    <li><a data-role="home-link" href="/">Home</a></li>
+  </ul>
+</nav>
+
+<ul class="metrics">
+  <li><h3>Metric 0</h3></li>
+  <li><h3>Metric 1</h3></li>
+  <li><h3>Metric 2</h3></li>
+</ul>
+
+<ul class="stats">
+  <li><h3>Stat 1</h3></li>
+  <li><h3>Stat 2</h3></li>
+  <li><h3>Stat 3</h3></li>
+</ul>
+```
+
+One could then interact with the card as such:
+
+```rb
+# within a spec file
+
+visit "/"
+
+dashboard = Dashboard.new
+
+expect(dashboard.primary_nav).to have_home_link
+expect(dashboard.metric_at(0).card.header).to have_text("Metric 0")
+```
+
+Review page object composition within the [composition specs].
+
+[composition specs]: ./spec/features/composition_spec.rb
+
+## Configuration
+
+### Logger
+
+Configure PageEz's logger to capture debugging information about
+which page objects and methods are defined.
+
+
+```rb
+PageEz.configure do |config|
+  config.logger = Logger.new($stdout)
+end
+```
+
+### Pluralization Warnings
+
+Use of the different macros imply singular or plural values, e.g.
+
+* `has_one :todos_list, "ul"`
+* `has_many :cards, "li[data-role=card]"`
+
+By default, PageEz allows for any pluralization usage regardless of macro. You
+can configure PageEz to either warn (via its logger) or raise an exception if
+pluralization doesn't look to align. Behind the scenes, PageEz uses
+ActiveSupport's pluralization mechanisms.
+
+```rb
+PageEz.configure do |config|
+  config.on_pluralization_mismatch = :warn # or :raise, nil is the default
+end
+```
+
+### Collisions with Capybara's RSpec Matchers
+
+Capybara ships with a set of RSpec matchers, including:
+
+* `have_title`
+* `have_link`
+* `have_button`
+* `have_field`
+* `have_select`
+* `have_table`
+* `have_text`
+
+By default, if any elements are declared in PageEz that would overlap
+with these matchers (e.g. `has_one :title, "h3"`), PageEz will raise an
+exception in order to prevent confusing errors when asserting via predicate
+matchers (since PageEz will define corresponding `has_title?` and
+`has_no_title?` methods).
+
+You can configure the behavior to warn (or do nothing):
+
+```rb
+PageEz.configure do |config|
+  config.on_matcher_collision = :warn # or nil, :raise is the default
+end
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run
+`rake spec` to run the tests. You can also run `bin/console` for an interactive
+prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To
+release a new version, update the version number in `version.rb`, and then run
+`bundle exec rake release`, which will create a git tag for the version, push
+git commits and the created tag, and push the `.gem` file to
+[rubygems.org](https://rubygems.org).
+
+## Feature Tests
+
+This uses a test harness for Rack app generation called `AppGenerator`, which
+handles mounting HTML responses to endpoints accessible via `GET`. In tests,
+call `build_page` with the markup you'd like and it will mount that response to
+the root of the application.
+
+```ruby
+page = build_page(<<-HTML)
+  <form>
+    <input name="name" type="text" />
+    <input name="email" type="text" />
+  </form>
+HTML
+```
+
+To drive interactions with a headless browser, add the RSpec metadata `:js` to
+either individual `it`s or `describe`s.
+
+## Roadmap
+
+* [x] Verify page object interactions work within `within`
+* [ ] Define `form` syntax
+* [ ] Define `define` syntax (FactoryBot style)
+* [x] Nested/reference-able page objects (from `define` syntax, by symbol, or by class name)
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/joshuaclayton/page_ez. This project is intended to be a
+safe, welcoming space for collaboration, and contributors are expected to
+adhere to the [code of
+conduct](https://github.com/joshuaclayton/page_ez/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT
+License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the PageEz project's codebases, issue trackers, chat
+rooms and mailing lists is expected to follow the [code of
+conduct](https://github.com/joshuaclayton/page_ez/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "standard/rake"
+
+task default: %i[spec standard]

data/lib/page_ez/configuration.rb

@@ -0,0 +1,33 @@
+module PageEz
+  class Configuration
+    VALID_MISMATCH_BEHAVIORS = [:warn, :raise, nil].freeze
+    attr_accessor :logger
+    attr_reader :on_pluralization_mismatch, :on_matcher_collision
+
+    def initialize
+      reset
+    end
+
+    def on_pluralization_mismatch=(value)
+      if !VALID_MISMATCH_BEHAVIORS.include?(value)
+        raise ArgumentError, "#{value.inspect} must be one of #{VALID_MISMATCH_BEHAVIORS}"
+      end
+
+      @on_pluralization_mismatch = value
+    end
+
+    def on_matcher_collision=(value)
+      if !VALID_MISMATCH_BEHAVIORS.include?(value)
+        raise ArgumentError, "#{value.inspect} must be one of #{VALID_MISMATCH_BEHAVIORS}"
+      end
+
+      @on_matcher_collision = value
+    end
+
+    def reset
+      self.logger = NullLogger.new
+      self.on_pluralization_mismatch = nil
+      self.on_matcher_collision = :raise
+    end
+  end
+end

data/lib/page_ez/delegates_to.rb

@@ -0,0 +1,25 @@
+module PageEz
+  module DelegatesTo
+    def self.[](name)
+      Module.new do
+        define_singleton_method(:included) do |base|
+          base.include(Module.new.tap do |mod|
+            mod.class_eval %{
+              def method_missing(*args, **kwargs, &block)
+                if #{name}.respond_to?(args[0])
+                  #{name}.send(*args, **kwargs, &block)
+                else
+                  super(*args, **kwargs, &block)
+                end
+              end
+
+              def respond_to_missing?(method_name, include_private = false)
+                #{name}.respond_to?(method_name, include_private) || super(method_name, include_private)
+              end
+            }, __FILE__, __LINE__ - 12
+          end)
+        end
+      end
+    end
+  end
+end

data/lib/page_ez/errors.rb

@@ -0,0 +1,17 @@
+module PageEz
+  class Error < StandardError; end
+
+  class PluralizationMismatchError < StandardError; end
+
+  class MatcherCollisionError < StandardError; end
+
+  class DuplicateElementDeclarationError < StandardError; end
+
+  class InvalidSelectorError < StandardError; end
+
+  def self.reraise_selector_error(selector)
+    yield
+  rescue Nokogiri::CSS::SyntaxError => e
+    raise InvalidSelectorError, "Invalid selector '#{selector}':\n#{e.message}"
+  end
+end

data/lib/page_ez/has_many_result.rb

@@ -0,0 +1,35 @@
+module PageEz
+  class HasManyResult
+    include DelegatesTo[:@result]
+
+    def initialize(container:, selector:, options:, constructor:)
+      @container = container
+      @selector = selector
+      @options = options
+      @result = container.all(
+        selector,
+        **options
+      ).map do |element|
+        constructor.call(element)
+      end
+    end
+
+    def has_count_of?(count)
+      @container.has_css?(
+        @selector,
+        **@options.merge(count: count)
+      )
+    end
+
+    def has_any_elements?
+      @container.has_css?(
+        @selector,
+        **@options
+      )
+    end
+
+    def has_no_elements?
+      @container.has_no_css?(@selector, **@options)
+    end
+  end
+end