with_form 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a9e706ed3dfe301d30053e531b040f1588ae35ca430f4c1de408bd01bd777e8e
-  data.tar.gz: dfbc4ba02b11b52f69a852e1b66b226ce10ef86a7e6bf075264b70ed4e808cbb
+  metadata.gz: 7a78f39980ba03659bd61b33c94e65e8987dc590647ba8870271141a879eafca
+  data.tar.gz: ad43310ff4fd4a42ddb3f154af5c9e799f1a25c82dafdd46c9d18a6f41f48304
 SHA512:
-  metadata.gz: 2fc1f5efb683e554791d22d0ec68ef467fffb768a9b9c1c96100545bd882715147757f91715d534be2eb9fa9dbc18ad3c8f9fe8785cd891e722d5a80450d3a91
-  data.tar.gz: 21d93934220c9b60dfa9aa1814b8f72121001f2e11f43b236634fd722e8c967cc03214f7208458244897b81845362b68bf8fe02823f9c19a48e7390b65174b40
+  metadata.gz: 2a300ce3b20953400496bc7b7cf09e0bb9206870526c8d63cfb6987db7537ffe702788cd1543ad9eb28f83b99ac44bb39063b628be3677eac73069874a0bdbd6
+  data.tar.gz: b596e4300be6ac53de36e9e81e85514722d1763f3c877ed82aa1b5b38a04adb8d02995d625d89eb800a07938f42343a76d565aa62c0523e338e16845aa675e95

data/README.md

@@ -7,6 +7,8 @@ Your System Test's counterpart to `form_with`
 Leverage Rails-generated `<label>` values to submit `<form>` elements in System
 Tests.
 
+### The `with_form` test helper
+
 To add coverage to a form's fields that are generated by ActionView's
 `form_with` helper, fill them using `with_form`:
 
@@ -60,6 +62,29 @@ The `with_form` helper method accepts two styles of options:
 
 * `scope:` - the internationalization scope key to use when translating Capybara's
   locator values
+
+  When submitting a `<form>` through a call to `form.click_button`, you can pass
+  an `action` as the translation scope. A `with_form(scope:)` call will default
+  to the `submit` key when one is not specified. For instance:
+
+  ```ruby
+  form_with(scope: :post) do |form|
+    form.click_button
+  end
+  ```
+
+  This call will search for an `<input type="text">` or `<button>` whose `value`
+  or text content is the String translated by the `helpers.submit.post.submit`
+  key.
+
+  That action can be overridden:
+
+  ```ruby
+  form_with(scope: :post) do |form|
+    form.click_button :create
+  end
+  ```
+
 * `model:` - an instance of an `ActiveModel::Model` or `ActiveRecord::Base` to
   be used to translate Capybara's locator values, and to populate the fields
   with an attribute's value.
@@ -97,9 +122,65 @@ The `with_form` helper method accepts two styles of options:
   `"New Title"`) will take precedence over the `post.title` attribute's value
   (in this case, `"Old Title"`).
 
+  When submitting a `<form>` through a call to `form.click_button`, you can pass
+  an `action` as the translation scope. A `with_form(model:)` call will
+  determine the translation key based on [the `model`
+  argument's persistence state][persisted].
+
+  When a `model` instance is a new record, the key will use `create`. For
+  instance:
+
+  ```ruby
+  post = Post.new
+
+  form_with(model: post) do |form|
+    form.click_button
+  end
+  ```
+
+  This call will search for an `<input type="text">` or `<button>` whose `value`
+  or text content is the String translated by the `helpers.submit.post.create`
+  key.
+
+  That action can be overridden:
+
+  ```ruby
+  post = Post.new
+
+  form_with(model: post) do |form|
+    form.click_button :submit
+  end
+  ```
+
+  When a `model` instance is an existing persisted record, the key will use
+  `update`. For instance:
+
+  ```ruby
+  post = Post.last
+
+  form_with(model: post) do |form|
+    form.click_button
+  end
+  ```
+
+  This call will search for an `<input type="text">` or `<button>` whose `value`
+  or text content is the String translated by the `helpers.submit.post.update`
+  key.
+
+  That action can be overridden:
+
+  ```ruby
+  post = Post.last
+
+  form_with(model: post) do |form|
+    form.click_button :submit
+  end
+  ```
+
 [label]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/label
 [input]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input
 [textarea]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/textarea
+[persisted]: https://api.rubyonrails.org/classes/ActiveModel/Model.html#method-i-persisted-3F
 
 With the exception of `#click_link` and `#click_link_or_button`, the argument
 yielded to `with_form` supports [all helper methods made available by
@@ -118,6 +199,117 @@ Those include:
 
 [actions]: https://www.rubydoc.info/github/jnicklas/capybara/master/Capybara/Node/Actions
 
+#### ActionText `rich_text_area` support
+
+When [`ActionText`][actiontext] is available, `with_form` provides a
+`#fill_in_rich_text_area` helper method.
+
+The current implementation is inspired by
+`ActionText::SystemTestHelper#fill_in_rich_text_area` that is currently declared
+on  the current [`rails@master` branch][fill_in_rich_text_area].
+
+```ruby
+class UserInteractsWithRichTextAreasTest < ApplicationSystemTestCase
+  include WithForm::TestHelpers
+
+  test "makes a post with a scope: argument" do
+    visit new_post_path
+    with_form(scope: :post) do |form|
+      form.fill_in_rich_text_area :body, with: "My First Post"
+      form.click_button
+    end
+
+    assert_text "My First Post"
+  end
+
+  test "user makes a post with a model: argument" do
+    post = Post.new(body: "My First Post")
+
+    visit new_post_path
+    with_form(model: post) do |form|
+      form.fill_in_rich_text_area :body
+      form.click_button
+    end
+
+    assert_text "My First Post"
+  end
+end
+```
+
+There is a current limitation in how the [`rails@master`-inspired
+`#fill_in_rich_text_area` implementation][fill_in_rich_text_area] resolves the
+`locator` argument. Since the underlying `<trix-editor>` element is not a
+default field provided by the browser, focussing on its corresponding `<label>`
+element won't focus the `<trix-editor>`. To resolve that shortcoming, the
+`#fill_in_rich_text_area` uses the `<trix-editor aria-label="...">` attribute as
+the label text.
+
+This is a helpful, but incomplete solution to the problem. This requires that
+instead of declaring a `<label for="my_rich_text_field">` element
+referencing the `<trix-editor id="my_rich_text_field">` element, the `<label>`
+element's text (or rather, the text that _would be_ in the `<label>` element)
+must be passed to the `<trix-editor aria-label="...">` attribute.
+
+For example:
+
+```html+erb
+<%= form_with(model: Post.new) do |form %>
+  <%= form.label :my_rich_text_field %>
+  <%= form.rich_text_area :my_rich_text_field, "aria-label": translate(:my_rich_text_field, scope: "helpers.label.post") %>
+<% end %>
+```
+
+[actiontext]: https://edgeguides.rubyonrails.org/action_text_overview.html#examples
+[fill_in_rich_text_area]: https://github.com/rails/rails/blob/339be65d669c83fd4c64541a9e82086dc5e64682/actiontext/lib/action_text/system_test_helper.rb
+
+### The `label` and `submit` test helpers
+
+While `with_form` can simplify `<form>` element interactions with multiple
+steps, there are times when a single line of instructions is more convenient.
+
+Behind the scenes, `with_form` utilize the `#label` and `#submit` helper
+methods to translate `<label>` and `<button>` text, along with `<input
+type="submit">` values.
+
+To put the same helpers to use within your test, include the
+`WithForm::TranslationHelpers` module and invoke either:
+
+* `label(model_name, attribute)`
+
+* `submit(model_name, action = :submit)`
+
+For example when clicking an `<input type="checkbox">` labelled by a translation
+declared at `helpers.label.session.ready`:
+
+```ruby
+class UserInteractsWithFormsTest < ApplicationSystemTestCase
+  include WithForm::TranslationHelpers
+
+  test "user ticks a box" do
+    visit new_session_path
+    check label(:session, :ready)
+
+    assert_text "We're glad you're ready, user@example.com."
+  end
+end
+```
+
+Or, to destroy a Post by clicking a button labelled by a translation declared at
+`helpers.submit.post.destroy`:
+
+```ruby
+class UserInteractsWithFormsTest < ApplicationSystemTestCase
+  include WithForm::TranslationHelpers
+
+  test "user deletes a post" do
+    visit new_post_path
+    click_on submit(:post, :destroy)
+
+    assert_text "Deleted Post."
+  end
+end
+```
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -186,6 +378,10 @@ I've used the [`formulaic` gem][formulaic] before. How is this gem different?
 [form_with]: https://guides.rubyonrails.org/form_helpers.html#dealing-with-basic-forms
 [rails-i18n]: https://api.rubyonrails.org/classes/ActionView/Helpers/FormBuilder.html#method-i-label
 
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/db/migrate/20200310042146_create_widget_records.rb

@@ -1,4 +1,4 @@
-class CreateWidgetRecords < ActiveRecord::Migration[6.0]
+class CreateWidgetRecords < ActiveRecord::Migration[Rails.version.to_f]
   def change
     create_table :widget_records do |t|
       t.text :text_field

data/lib/with_form/engine.rb

@@ -1,4 +1,22 @@
 module WithForm
   class Engine < ::Rails::Engine
+    ActiveSupport.on_load :action_dispatch_system_test_case do
+      Capybara.add_selector :rich_text_area do
+        label "rich-text area"
+        xpath do |locator|
+          if locator.nil?
+            XPath.descendant(:"trix-editor")
+          else
+            input_located_by_name = XPath.anywhere(:input).where(XPath.attr(:name) == locator).attr(:id)
+
+            XPath.descendant(:"trix-editor").where \
+              XPath.attr(:id).equals(locator) |
+              XPath.attr(:placeholder).equals(locator) |
+              XPath.attr(:"aria-label").equals(locator) |
+              XPath.attr(:input).equals(input_located_by_name)
+          end
+        end
+      end
+    end
   end
 end

data/lib/with_form/model_form.rb

@@ -15,6 +15,14 @@ module WithForm
       )
     end
 
+    def fill_in_rich_text_area(attribute, with: nil, **options)
+      scope_form.fill_in_rich_text_area(
+        attribute,
+        with: with || @model.public_send(attribute),
+        **options,
+      )
+    end
+
     def attach_file(attribute, path = nil, **options)
       scope_form.attach_file(
         attribute,

data/lib/with_form/scope_form.rb

@@ -1,18 +1,54 @@
+require "with_form/translation_helpers"
+
 module WithForm
   class ScopeForm
     include ActionView::Helpers::TranslationHelper
+    include WithForm::TranslationHelpers
 
-    delegate :check, :uncheck, :choose, to: :@page
+    delegate :choose, to: :@page
 
     def initialize(scope:, page:)
       @page = page
       @scope = scope
     end
 
+    def check(attribute, **options)
+      case attribute
+      when Symbol
+        value = label(attribute)
+      else
+        value = attribute
+      end
+
+      @page.check value, **options
+    end
+
+    def uncheck(attribute, **options)
+      case attribute
+      when Symbol
+        value = label(attribute)
+      else
+        value = attribute
+      end
+
+      @page.uncheck value, **options
+    end
+
     def fill_in(attribute, with:, **options)
       @page.fill_in label(attribute), with: with, **options
     end
 
+    def fill_in_rich_text_area(locator = nil, with:)
+      fill_in_script = <<~JS
+        this.editor.loadHTML(arguments[0])
+      JS
+
+      @page.find(:rich_text_area, label(locator)).execute_script(
+        fill_in_script,
+        with.to_s,
+      )
+    end
+
     def select(value, from:, **options)
       @page.select value, from: label(from), **options
     end
@@ -30,11 +66,11 @@ module WithForm
     end
 
     def submit(action = nil)
-      translate(action || :submit, scope: [:helpers, :submit, @scope])
+      super(@scope, action || :submit)
     end
 
     def label(attribute)
-      translate(attribute, scope: [:helpers, :label, @scope])
+      super(@scope, attribute)
     end
   end
 end

data/lib/with_form/translation_helpers.rb

@@ -0,0 +1,11 @@
+module WithForm
+  module TranslationHelpers
+    def submit(model_name, action = :submit)
+      translate(action, scope: [:helpers, :submit, model_name])
+    end
+
+    def label(model_name, attribute)
+      translate(attribute, scope: [:helpers, :label, model_name])
+    end
+  end
+end

data/lib/with_form/version.rb

@@ -1,3 +1,3 @@
 module WithForm
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end

metadata

@@ -1,35 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: with_form
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Sean Doyle
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-03-10 00:00:00.000000000 Z
+date: 2020-04-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: rails
+  name: railties
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 6.0.2
     - - ">="
       - !ruby/object:Gem::Version
-        version: 6.0.2.1
+        version: 5.2.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 6.0.2
     - - ">="
       - !ruby/object:Gem::Version
-        version: 6.0.2.1
+        version: 5.2.0
 - !ruby/object:Gem::Dependency
   name: capybara
   requirement: !ruby/object:Gem::Requirement
@@ -58,6 +52,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.2.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.2.0
 - !ruby/object:Gem::Dependency
   name: selenium-webdriver
   requirement: !ruby/object:Gem::Requirement
@@ -104,6 +112,7 @@ files:
 - lib/with_form/model_form.rb
 - lib/with_form/scope_form.rb
 - lib/with_form/test_helpers.rb
+- lib/with_form/translation_helpers.rb
 - lib/with_form/version.rb
 homepage: https://github.com/seanpdoyle/with_form
 licenses: