with_form 0.1.0

checksums.yaml

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

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2020 Sean Doyle
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,191 @@
+# WithForm
+
+Your System Test's counterpart to `form_with`
+
+## Usage
+
+Leverage Rails-generated `<label>` values to submit `<form>` elements in System
+Tests.
+
+To add coverage to a form's fields that are generated by ActionView's
+`form_with` helper, fill them using `with_form`:
+
+```ruby
+class UserInteractsWithFormsTest < ApplicationSystemTestCase
+  include WithForm::TestHelpers
+
+  test "user signs in" do
+    visit new_session_path
+    with_form(scope: :session) do |form|
+      form.fill_in :email, with: "user@example.com"
+      form.fill_in :password, with: "secr3t"
+      form.check :remember_me
+      form.click_button
+    end
+
+    assert_text "Welcome back, user@example.com."
+  end
+
+  test "user makes a post" do
+    post = Post.new(title: "My First Post", tags: ["ruby", "testing"])
+
+    visit new_post_path
+    with_form(model: post) do |form|
+      form.fill_in :title
+      form.check :tags
+      form.click_button
+    end
+
+    assert_text "Created Post: My First Post."
+  end
+
+  test "user updates their profile" do
+    profile = Profile.create!
+
+    visit profile_path
+    with_form(model: profile) do |form|
+      form.fill_in :email, with: "updated.user@example.com"
+      form.select "NY", from: :state
+      form.click_button :update
+    end
+
+    assert_text "Your profile has been updated."
+  end
+end
+```
+
+### `with_form` Options
+
+The `with_form` helper method accepts two styles of options:
+
+* `scope:` - the internationalization scope key to use when translating Capybara's
+  locator values
+* `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.
+
+  For example, assuming that a `Post` record has a `title` attribute:
+
+  ```ruby
+  post = Post.new(title: "The Title")
+
+  form_with(model: post) do |form|
+    form.fill_in :title
+  end
+  ```
+
+  The call to `form.fill_in` will search for an [`<input>` element][input] or a
+  [`<textarea>` element][textarea] that is labelled by a
+  [`<label>` element][label] whose value is translated from the
+  `helpers.label.post.title` internationalization key. If that element exists,
+  set its value to the value of `post.title` (in this case, `"The Title"`).
+
+  An attribute's value can be overridden by providing
+  a different value. For instance, assuming that a `Post` record has a `title`
+  attribute:
+
+  ```ruby
+  post = Post.create!(title: "Old Title")
+
+  form_with(model: post) do |form|
+    form.fill_in :title, with: "New Title"
+  end
+  ```
+
+  The call to `form.fill_in` will work much like the example above, with the
+  exception that the provided `with:` option's value (in this case,
+  `"New Title"`) will take precedence over the `post.title` attribute's value
+  (in this case, `"Old Title"`).
+
+[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
+
+With the exception of `#click_link` and `#click_link_or_button`, the argument
+yielded to `with_form` supports [all helper methods made available by
+`Capybara::Node::Actions`][actions].
+
+Those include:
+
+* `attach_file(locator = nil, paths, make_visible: nil, **options)`
+* `check(locator, **options)`
+* `choose(locator, **options)`
+* `click_button(locator, nil, **options)`
+* `fill_in(locator, with: nil, **options)`
+* `select(value = nil, from: nil, **options)`
+* `uncheck(locator, **options)`
+* `unselect(value = nil, from: nil, **options)`
+
+[actions]: https://www.rubydoc.info/github/jnicklas/capybara/master/Capybara/Node/Actions
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'with_form'
+```
+
+And then execute:
+
+```bash
+$ bundle
+```
+
+Then, include the `WithForm::TestHelpers` into your project testing framework.
+
+### MiniTest
+
+```ruby
+# test/application_system_test_case.rb
+class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
+  include WithForm::TestHelpers
+end
+```
+
+### RSpec
+
+```ruby
+# spec/support/with_form.rb
+RSpec.configure do |config|
+  config.include(WithForm::TestHelpers, type: :system)
+end
+```
+
+## FAQ
+
+I want to call a Capybara helper with that input's [`id` attribute][mdn-id]
+or [`name` attribute][mdn-name]. How can I do that?
+
+* You can mix the object that you invoke the helper methods on within the
+  `with_form` block. For instance:
+
+  ```ruby
+  with_form(scope: :post) do |form|
+    form.fill_in :title, with: "The Post's Title"
+    fill_in "another-field-id", with: "Another Value"
+    fill_in "post[special-field]", with: "Special Value"
+  end
+  ```
+
+I've used the [`formulaic` gem][formulaic] before. How is this gem different?
+
+* Formulaic's `fill_form` and `fill_form_and_submit` are very useful
+  abstractions over [`simple_form`-generated `<form>` elements][simple_form].
+  This gem's focus is at a different layer of abstraction. Instead of translating
+  a Hash of attribute-value pairs into `<form>` element interactions, this gem's
+  interface focussed on enhancing the experience of filling in
+  [`form_with`-generated `<form>` elements][form_with] that are labelled by the
+  [`ActionView`-provided internationalization tooling][rails-i18n].
+
+
+[mdn-id]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id
+[mdn-name]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Input#attr-name
+[formulaic]: https://github.com/thoughtbot/formulaic
+[simple_form]: https://github.com/heartcombo/simple_form
+[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
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,32 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'WithForm'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.md')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load 'rails/tasks/engine.rake'
+
+load 'rails/tasks/statistics.rake'
+
+require 'bundler/gem_tasks'
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+task default: :test

data/db/migrate/20200310042146_create_widget_records.rb

@@ -0,0 +1,7 @@
+class CreateWidgetRecords < ActiveRecord::Migration[6.0]
+  def change
+    create_table :widget_records do |t|
+      t.text :text_field
+    end
+  end
+end

data/lib/tasks/with_form_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :with_form do
+#   # Task goes here
+# end

data/lib/with_form.rb

@@ -0,0 +1,6 @@
+require "with_form/engine"
+require "with_form/test_helpers"
+
+module WithForm
+  # Your code goes here...
+end

data/lib/with_form/engine.rb

@@ -0,0 +1,4 @@
+module WithForm
+  class Engine < ::Rails::Engine
+  end
+end

data/lib/with_form/model_form.rb

@@ -0,0 +1,98 @@
+module WithForm
+  class ModelForm
+    include ActionView::Helpers::TranslationHelper
+
+    def initialize(model:, page:)
+      @page = page
+      @model = model
+    end
+
+    def fill_in(attribute, with: nil, **options)
+      scope_form.fill_in(
+        attribute,
+        with: with || @model.public_send(attribute),
+        **options,
+      )
+    end
+
+    def attach_file(attribute, path = nil, **options)
+      scope_form.attach_file(
+        attribute,
+        path || @model.public_send(attribute),
+        **options,
+      )
+    end
+
+    def choose(attribute, **options)
+      case attribute
+      when Symbol
+        value = @model.public_send(attribute)
+      else
+        value = attribute
+      end
+
+      scope_form.choose value, **options
+    end
+
+    def check(attribute, **options)
+      case attribute
+      when Symbol
+        values = Array(@model.public_send(attribute))
+      else
+        values = Array(attribute)
+      end
+
+      values.each { |value| scope_form.check(value, **options) }
+    end
+
+    def uncheck(attribute, **options)
+      case attribute
+      when Symbol
+        values = Array(@model.public_send(attribute))
+      else
+        values = Array(attribute)
+      end
+
+      values.each { |value| scope_form.uncheck(value, **options) }
+    end
+
+    def select(attribute, from: nil, **options)
+      case attribute
+      when Symbol
+        value = @model.public_send(attribute)
+      else
+        value = attribute
+      end
+
+      scope_form.select value, from: from || attribute, **options
+    end
+
+    def unselect(attribute, from: nil, **options)
+      case attribute
+      when Symbol
+        value = @model.public_send(attribute)
+      else
+        value = attribute
+      end
+
+      scope_form.unselect value, from: from || attribute, **options
+    end
+
+    def click_button(action = nil, **options)
+      if action.present?
+      elsif @model.persisted?
+        action = :update
+      else
+        action = :create
+      end
+
+      scope_form.click_button action, **options
+    end
+
+    private
+
+    def scope_form
+      WithForm::ScopeForm.new(scope: @model.model_name.i18n_key, page: @page)
+    end
+  end
+end

data/lib/with_form/scope_form.rb

@@ -0,0 +1,40 @@
+module WithForm
+  class ScopeForm
+    include ActionView::Helpers::TranslationHelper
+
+    delegate :check, :uncheck, :choose, to: :@page
+
+    def initialize(scope:, page:)
+      @page = page
+      @scope = scope
+    end
+
+    def fill_in(attribute, with:, **options)
+      @page.fill_in label(attribute), with: with, **options
+    end
+
+    def select(value, from:, **options)
+      @page.select value, from: label(from), **options
+    end
+
+    def unselect(value, from:, **options)
+      @page.unselect value, from: label(from), **options
+    end
+
+    def attach_file(attribute, path, **options)
+      @page.attach_file label(attribute), path, **options
+    end
+
+    def click_button(action = nil, **options)
+      @page.click_button submit(action), **options
+    end
+
+    def submit(action = nil)
+      translate(action || :submit, scope: [:helpers, :submit, @scope])
+    end
+
+    def label(attribute)
+      translate(attribute, scope: [:helpers, :label, @scope])
+    end
+  end
+end

data/lib/with_form/test_helpers.rb

@@ -0,0 +1,16 @@
+require "with_form/model_form"
+require "with_form/scope_form"
+
+module WithForm
+  module TestHelpers
+    def with_form(scope: nil, model: nil, &block)
+      if model.present?
+        WithForm::ModelForm.new(model: model, page: page).yield_self(&block)
+      elsif scope.present?
+        WithForm::ScopeForm.new(scope: scope, page: page).yield_self(&block)
+      else
+        raise "with_form must be invoked with either a scope: or model: option"
+      end
+    end
+  end
+end

data/lib/with_form/version.rb

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

metadata

@@ -0,0 +1,131 @@
+--- !ruby/object:Gem::Specification
+name: with_form
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Sean Doyle
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2020-03-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 6.0.2
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.0.2.1
+  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
+- !ruby/object:Gem::Dependency
+  name: capybara
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.15'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.15'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: selenium-webdriver
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: webdrivers
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Leverage Rails-generated <label> values to submit <form> elements in
+  System Tests
+email:
+- sean.p.doyle24@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- db/migrate/20200310042146_create_widget_records.rb
+- lib/tasks/with_form_tasks.rake
+- lib/with_form.rb
+- lib/with_form/engine.rb
+- lib/with_form/model_form.rb
+- lib/with_form/scope_form.rb
+- lib/with_form/test_helpers.rb
+- lib/with_form/version.rb
+homepage: https://github.com/seanpdoyle/with_form
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: Your System Test's counterpart to `form_with`
+test_files: []