rails-dom-testing 2.1.0 → 2.2.0

data/lib/rails/dom/testing/assertions/selector_assertions.rb

@@ -1,5 +1,6 @@
-require_relative 'selector_assertions/count_describable'
-require_relative 'selector_assertions/html_selector'
+# frozen_string_literal: true
+
+require_relative "selector_assertions/html_selector"
 
 module Rails
   module Dom
@@ -18,257 +19,288 @@ module Rails
         # * +assert_dom_encoded+ - Assertions on HTML encoded inside XML, for example for dealing with feed item descriptions.
         # * +assert_dom_email+ - Assertions on the HTML body of an e-mail.
         module SelectorAssertions
+          # Select and return all matching elements.
+          #
+          # If called with a single argument, uses that argument as a selector.
+          # Called without an element +css_select+ selects from
+          # the element returned in +document_root_element+
+          #
+          # The default implementation of +document_root_element+ raises an exception explaining this.
+          #
+          # Returns an empty Nokogiri::XML::NodeSet if no match is found.
+          #
+          # If called with two arguments, uses the first argument as the root
+          # element and the second argument as the selector. Attempts to match the
+          # root element and any of its children.
+          # Returns an empty Nokogiri::XML::NodeSet if no match is found.
+          #
+          # The selector may be a CSS selector expression (String).
+          # css_select returns nil if called with an invalid css selector.
+          #
+          #   # Selects all div tags
+          #   divs = css_select("div")
+          #
+          #   # Selects all paragraph tags and does something interesting
+          #   pars = css_select("p")
+          #   pars.each do |par|
+          #     # Do something fun with paragraphs here...
+          #   end
+          #
+          #   # Selects all list items in unordered lists
+          #   items = css_select("ul>li")
+          #
+          #   # Selects all form tags and then all inputs inside the form
+          #   forms = css_select("form")
+          #   forms.each do |form|
+          #     inputs = css_select(form, "input")
+          #     ...
+          #   end
+          def css_select(*args)
+            raise ArgumentError, "you at least need a selector argument" if args.empty?
 
-        # Select and return all matching elements.
-        #
-        # If called with a single argument, uses that argument as a selector.
-        # Called without an element +css_select+ selects from
-        # the element returned in +document_root_element+
-        #
-        # The default implementation of +document_root_element+ raises an exception explaining this.
-        #
-        # Returns an empty Nokogiri::XML::NodeSet if no match is found.
-        #
-        # If called with two arguments, uses the first argument as the root
-        # element and the second argument as the selector. Attempts to match the
-        # root element and any of its children.
-        # Returns an empty Nokogiri::XML::NodeSet if no match is found.
-        #
-        # The selector may be a CSS selector expression (String).
-        # css_select returns nil if called with an invalid css selector.
-        #
-        #   # Selects all div tags
-        #   divs = css_select("div")
-        #
-        #   # Selects all paragraph tags and does something interesting
-        #   pars = css_select("p")
-        #   pars.each do |par|
-        #     # Do something fun with paragraphs here...
-        #   end
-        #
-        #   # Selects all list items in unordered lists
-        #   items = css_select("ul>li")
-        #
-        #   # Selects all form tags and then all inputs inside the form
-        #   forms = css_select("form")
-        #   forms.each do |form|
-        #     inputs = css_select(form, "input")
-        #     ...
-        #   end
-        def css_select(*args)
-          raise ArgumentError, "you at least need a selector argument" if args.empty?
+            root = args.size == 1 ? document_root_element : args.shift
 
-          root = args.size == 1 ? document_root_element : args.shift
+            nodeset(root).css(args.first)
+          end
 
-          nodeset(root).css(args.first)
-        end
+          # An assertion that selects elements and makes one or more equality tests.
+          #
+          # If the first argument is an element, selects all matching elements
+          # starting from (and including) that element and all its children in
+          # depth-first order.
+          #
+          # If no element is specified +assert_dom+ selects from
+          # the element returned in +document_root_element+
+          # unless +assert_dom+ is called from within an +assert_dom+ block.
+          # Override +document_root_element+ to tell +assert_dom+ what to select from.
+          # The default implementation raises an exception explaining this.
+          #
+          # When called with a block +assert_dom+ passes an array of selected elements
+          # to the block. Calling +assert_dom+ from the block, with no element specified,
+          # runs the assertion on the complete set of elements selected by the enclosing assertion.
+          # Alternatively the array may be iterated through so that +assert_dom+ can be called
+          # separately for each element.
+          #
+          #
+          # ==== Example
+          # If the response contains two ordered lists, each with four list elements then:
+          #   assert_dom "ol" do |elements|
+          #     elements.each do |element|
+          #       assert_dom element, "li", 4
+          #     end
+          #   end
+          #
+          # will pass, as will:
+          #   assert_dom "ol" do
+          #     assert_dom "li", 8
+          #   end
+          #
+          # The selector may be a CSS selector expression (String, Symbol, or Numeric) or an expression
+          # with substitution values (Array).
+          # Substitution uses a custom pseudo class match. Pass in whatever attribute you want to match (enclosed in quotes) and a ? for the substitution.
+          # assert_dom returns nil if called with an invalid css selector.
+          #
+          # assert_dom "div:match('id', ?)", "id_string"
+          # assert_dom "div:match('id', ?)", :id_string
+          # assert_dom "div:match('id', ?)", 1
+          # assert_dom "div:match('id', ?)", /\d+/
+          #
+          # === Equality Tests
+          #
+          # The equality test may be one of the following:
+          # * <tt>true</tt> - Assertion is true if at least one element selected.
+          # * <tt>false</tt> - Assertion is true if no element selected.
+          # * <tt>String/Regexp</tt> - Assertion is true if the text value of at least
+          #   one element matches the string or regular expression.
+          # * <tt>Integer</tt> - Assertion is true if exactly that number of
+          #   elements are selected.
+          # * <tt>Range</tt> - Assertion is true if the number of selected
+          #   elements fit the range.
+          # If no equality test specified, the assertion is true if at least one
+          # element selected.
+          #
+          # To perform more than one equality tests, use a hash with the following keys:
+          # * <tt>:text</tt> - Narrow the selection to elements that have this text
+          #   value (string or regexp).
+          # * <tt>:html</tt> - Narrow the selection to elements that have this HTML
+          #   content (string or regexp).
+          # * <tt>:count</tt> - Assertion is true if the number of selected elements
+          #   is equal to this value.
+          # * <tt>:minimum</tt> - Assertion is true if the number of selected
+          #   elements is at least this value.
+          # * <tt>:maximum</tt> - Assertion is true if the number of selected
+          #   elements is at most this value.
+          #
+          # If the method is called with a block, once all equality tests are
+          # evaluated the block is called with an array of all matched elements.
+          #
+          #   # At least one form element
+          #   assert_dom "form"
+          #
+          #   # Form element includes four input fields
+          #   assert_dom "form input", 4
+          #
+          #   # Page title is "Welcome"
+          #   assert_dom "title", "Welcome"
+          #
+          #   # Page title is "Welcome" and there is only one title element
+          #   assert_dom "title", {count: 1, text: "Welcome"},
+          #       "Wrong title or more than one title element"
+          #
+          #   # Page contains no forms
+          #   assert_dom "form", false, "This page must contain no forms"
+          #
+          #   # Test the content and style
+          #   assert_dom "body div.header ul.menu"
+          #
+          #   # Use substitution values
+          #   assert_dom "ol>li:match('id', ?)", /item-\d+/
+          #
+          #   # All input fields in the form have a name
+          #   assert_dom "form input" do
+          #     assert_dom ":match('name', ?)", /.+/  # Not empty
+          #   end
+          def assert_dom(*args, &block)
+            @selected ||= nil
 
-        # An assertion that selects elements and makes one or more equality tests.
-        #
-        # If the first argument is an element, selects all matching elements
-        # starting from (and including) that element and all its children in
-        # depth-first order.
-        #
-        # If no element is specified +assert_dom+ selects from
-        # the element returned in +document_root_element+
-        # unless +assert_dom+ is called from within an +assert_dom+ block.
-        # Override +document_root_element+ to tell +assert_dom+ what to select from.
-        # The default implementation raises an exception explaining this.
-        #
-        # When called with a block +assert_dom+ passes an array of selected elements
-        # to the block. Calling +assert_dom+ from the block, with no element specified,
-        # runs the assertion on the complete set of elements selected by the enclosing assertion.
-        # Alternatively the array may be iterated through so that +assert_dom+ can be called
-        # separately for each element.
-        #
-        #
-        # ==== Example
-        # If the response contains two ordered lists, each with four list elements then:
-        #   assert_dom "ol" do |elements|
-        #     elements.each do |element|
-        #       assert_dom element, "li", 4
-        #     end
-        #   end
-        #
-        # will pass, as will:
-        #   assert_dom "ol" do
-        #     assert_dom "li", 8
-        #   end
-        #
-        # The selector may be a CSS selector expression (String, Symbol, or Numeric) or an expression
-        # with substitution values (Array).
-        # Substitution uses a custom pseudo class match. Pass in whatever attribute you want to match (enclosed in quotes) and a ? for the substitution.
-        # assert_dom returns nil if called with an invalid css selector.
-        #
-        # assert_dom "div:match('id', ?)", "id_string"
-        # assert_dom "div:match('id', ?)", :id_string
-        # assert_dom "div:match('id', ?)", 1
-        # assert_dom "div:match('id', ?)", /\d+/
-        #
-        # === Equality Tests
-        #
-        # The equality test may be one of the following:
-        # * <tt>true</tt> - Assertion is true if at least one element selected.
-        # * <tt>false</tt> - Assertion is true if no element selected.
-        # * <tt>String/Regexp</tt> - Assertion is true if the text value of at least
-        #   one element matches the string or regular expression.
-        # * <tt>Integer</tt> - Assertion is true if exactly that number of
-        #   elements are selected.
-        # * <tt>Range</tt> - Assertion is true if the number of selected
-        #   elements fit the range.
-        # If no equality test specified, the assertion is true if at least one
-        # element selected.
-        #
-        # To perform more than one equality tests, use a hash with the following keys:
-        # * <tt>:text</tt> - Narrow the selection to elements that have this text
-        #   value (string or regexp).
-        # * <tt>:html</tt> - Narrow the selection to elements that have this HTML
-        #   content (string or regexp).
-        # * <tt>:count</tt> - Assertion is true if the number of selected elements
-        #   is equal to this value.
-        # * <tt>:minimum</tt> - Assertion is true if the number of selected
-        #   elements is at least this value.
-        # * <tt>:maximum</tt> - Assertion is true if the number of selected
-        #   elements is at most this value.
-        #
-        # If the method is called with a block, once all equality tests are
-        # evaluated the block is called with an array of all matched elements.
-        #
-        #   # At least one form element
-        #   assert_dom "form"
-        #
-        #   # Form element includes four input fields
-        #   assert_dom "form input", 4
-        #
-        #   # Page title is "Welcome"
-        #   assert_dom "title", "Welcome"
-        #
-        #   # Page title is "Welcome" and there is only one title element
-        #   assert_dom "title", {count: 1, text: "Welcome"},
-        #       "Wrong title or more than one title element"
-        #
-        #   # Page contains no forms
-        #   assert_dom "form", false, "This page must contain no forms"
-        #
-        #   # Test the content and style
-        #   assert_dom "body div.header ul.menu"
-        #
-        #   # Use substitution values
-        #   assert_dom "ol>li:match('id', ?)", /item-\d+/
-        #
-        #   # All input fields in the form have a name
-        #   assert_dom "form input" do
-        #     assert_dom ":match('name', ?)", /.+/  # Not empty
-        #   end
-        def assert_dom(*args, &block)
-          @selected ||= nil
-
-          selector = HTMLSelector.new(args, @selected) { nodeset document_root_element }
+            selector = HTMLSelector.new(args, @selected) { nodeset document_root_element }
 
-          if selector.selecting_no_body?
-            assert true
-            return
-          end
+            if selector.selecting_no_body?
+              assert true
+              return
+            end
 
-          selector.select.tap do |matches|
-            assert_size_match!(matches.size, selector.tests,
-              selector.css_selector, selector.message)
+            selector.select.tap do |matches|
+              assert_size_match!(matches.size, selector.tests,
+                selector.css_selector, selector.message)
 
-            nest_selection(matches, &block) if block_given? && !matches.empty?
+              nest_selection(matches, &block) if block_given? && !matches.empty?
+            end
           end
-        end
-        alias_method :assert_select, :assert_dom
+          alias_method :assert_select, :assert_dom
 
-        # Extracts the content of an element, treats it as encoded HTML and runs
-        # nested assertion on it.
-        #
-        # You typically call this method within another assertion to operate on
-        # all currently selected elements. You can also pass an element or array
-        # of elements.
-        #
-        # The content of each element is un-encoded, and wrapped in the root
-        # element +encoded+. It then calls the block with all un-encoded elements.
-        #
-        #   # Selects all bold tags from within the title of an Atom feed's entries (perhaps to nab a section name prefix)
-        #   assert_dom "feed[xmlns='http://www.w3.org/2005/Atom']" do
-        #     # Select each entry item and then the title item
-        #     assert_dom "entry>title" do
-        #       # Run assertions on the encoded title elements
-        #       assert_dom_encoded do
-        #         assert_dom "b"
-        #       end
-        #     end
-        #   end
-        #
-        #
-        #   # Selects all paragraph tags from within the description of an RSS feed
-        #   assert_dom "rss[version=2.0]" do
-        #     # Select description element of each feed item.
-        #     assert_dom "channel>item>description" do
-        #       # Run assertions on the encoded elements.
-        #       assert_dom_encoded do
-        #         assert_dom "p"
-        #       end
-        #     end
-        #   end
-        def assert_dom_encoded(element = nil, &block)
-          if !element && !@selected
-            raise ArgumentError, "Element is required when called from a nonnested assert_dom"
-          end
+          # Extracts the content of an element, treats it as encoded HTML and runs
+          # nested assertion on it.
+          #
+          # You typically call this method within another assertion to operate on
+          # all currently selected elements. You can also pass an element or array
+          # of elements.
+          #
+          # The content of each element is un-encoded, and wrapped in the root
+          # element +encoded+. It then calls the block with all un-encoded elements.
+          #
+          #   # Selects all bold tags from within the title of an Atom feed's entries (perhaps to nab a section name prefix)
+          #   assert_dom "feed[xmlns='http://www.w3.org/2005/Atom']" do
+          #     # Select each entry item and then the title item
+          #     assert_dom "entry>title" do
+          #       # Run assertions on the encoded title elements
+          #       assert_dom_encoded do
+          #         assert_dom "b"
+          #       end
+          #     end
+          #   end
+          #
+          #
+          #   # Selects all paragraph tags from within the description of an RSS feed
+          #   assert_dom "rss[version=2.0]" do
+          #     # Select description element of each feed item.
+          #     assert_dom "channel>item>description" do
+          #       # Run assertions on the encoded elements.
+          #       assert_dom_encoded do
+          #         assert_dom "p"
+          #       end
+          #     end
+          #   end
+          #
+          # The DOM is created using an HTML parser specified by
+          # Rails::Dom::Testing.default_html_version (either :html4 or :html5).
+          #
+          # When testing in a Rails application, the parser default can also be set by setting
+          # +Rails.application.config.dom_testing_default_html_version+.
+          #
+          # If you want to specify the HTML parser just for a particular assertion, pass
+          # <tt>html_version: :html4</tt> or <tt>html_version: :html5</tt> keyword arguments:
+          #
+          #   assert_dom "feed[xmlns='http://www.w3.org/2005/Atom']" do
+          #     assert_dom "entry>title" do
+          #       assert_dom_encoded(html_version: :html5) do
+          #         assert_dom "b"
+          #       end
+          #     end
+          #   end
+          #
+          def assert_dom_encoded(element = nil, html_version: nil, &block)
+            if !element && !@selected
+              raise ArgumentError, "Element is required when called from a nonnested assert_dom"
+            end
 
-          content = nodeset(element || @selected).map do |elem|
-            elem.children.select do |child|
-              child.cdata? || (child.text? && !child.blank?)
-            end.map(&:content)
-          end.join
+            content = nodeset(element || @selected).map do |elem|
+              elem.children.select do |child|
+                child.cdata? || (child.text? && !child.blank?)
+              end.map(&:content)
+            end.join
 
-          selected = Nokogiri::HTML::DocumentFragment.parse(content)
-          nest_selection(selected) do
-            if content.empty?
-              yield selected
-            else
-              assert_dom ":root", &block
+            selected = Rails::Dom::Testing.html_document_fragment(html_version: html_version).parse(content)
+            nest_selection(selected) do
+              if content.empty?
+                yield selected
+              else
+                assert_dom ":root", &block
+              end
             end
           end
-        end
-        alias_method :assert_select_encoded, :assert_dom_encoded
+          alias_method :assert_select_encoded, :assert_dom_encoded
 
-        # Extracts the body of an email and runs nested assertions on it.
-        #
-        # You must enable deliveries for this assertion to work, use:
-        #   ActionMailer::Base.perform_deliveries = true
-        #
-        #  assert_dom_email do
-        #    assert_dom "h1", "Email alert"
-        #  end
-        #
-        #  assert_dom_email do
-        #    items = assert_dom "ol>li"
-        #    items.each do
-        #       # Work with items here...
-        #    end
-        #  end
-        def assert_dom_email(&block)
-          deliveries = ActionMailer::Base.deliveries
-          assert !deliveries.empty?, "No e-mail in delivery list"
+          # Extracts the body of an email and runs nested assertions on it.
+          #
+          # You must enable deliveries for this assertion to work, use:
+          #   ActionMailer::Base.perform_deliveries = true
+          #
+          # Example usage:
+          #
+          #   assert_dom_email do
+          #     assert_dom "h1", "Email alert"
+          #   end
+          #
+          #   assert_dom_email do
+          #     items = assert_dom "ol>li"
+          #     items.each do
+          #        # Work with items here...
+          #     end
+          #   end
+          #
+          # The DOM is created using an HTML parser specified by
+          # Rails::Dom::Testing.default_html_version (either :html4 or :html5).
+          #
+          # When testing in a Rails application, the parser default can also be set by setting
+          # +Rails.application.config.dom_testing_default_html_version+.
+          #
+          # If you want to specify the HTML parser just for a particular assertion, pass
+          # <tt>html_version: :html4</tt> or <tt>html_version: :html5</tt> keyword arguments:
+          #
+          #   assert_dom_email(html_version: :html5) do
+          #     assert_dom "h1", "Email alert"
+          #   end
+          #
+          def assert_dom_email(html_version: nil, &block)
+            deliveries = ActionMailer::Base.deliveries
+            assert !deliveries.empty?, "No e-mail in delivery list"
 
-          deliveries.each do |delivery|
-            (delivery.parts.empty? ? [delivery] : delivery.parts).each do |part|
-              if part["Content-Type"].to_s =~ /^text\/html\W/
-                root = Nokogiri::HTML::DocumentFragment.parse(part.body.to_s)
-                assert_dom root, ":root", &block
+            deliveries.each do |delivery|
+              (delivery.parts.empty? ? [delivery] : delivery.parts).each do |part|
+                if /^text\/html\W/.match?(part["Content-Type"].to_s)
+                  root = Rails::Dom::Testing.html_document_fragment(html_version: html_version).parse(part.body.to_s)
+                  assert_dom root, ":root", &block
+                end
               end
             end
           end
-        end
-        alias_method :assert_select_email, :assert_dom_email
+          alias_method :assert_select_email, :assert_dom_email
 
         private
-          include CountDescribable
-
           def document_root_element
-            raise NotImplementedError, 'Implementing document_root_element makes ' \
-              'assert_dom work without needing to specify an element to select from.'
+            raise NotImplementedError, "Implementing document_root_element makes " \
+              "assert_dom work without needing to specify an element to select from."
           end
 
           # +equals+ must contain :minimum, :maximum and :count keys
@@ -284,6 +316,22 @@ module Rails
             end
           end
 
+          def count_description(min, max, count)
+            if min && max && (max != min)
+              "between #{min} and #{max} elements"
+            elsif min && max && max == min && count
+              "exactly #{count} #{pluralize_element(min)}"
+            elsif min && !(min == 1 && max == 1)
+              "at least #{min} #{pluralize_element(min)}"
+            elsif max
+              "at most #{max} #{pluralize_element(max)}"
+            end
+          end
+
+          def pluralize_element(quantity)
+            quantity == 1 ? "element" : "elements"
+          end
+
           def nest_selection(selection)
             # Set @selected to allow nested assert_dom.
             # Can be nested several levels deep.

data/lib/rails/dom/testing/assertions.rb

@@ -1,6 +1,7 @@
-require 'nokogiri'
-require 'rails/dom/testing/assertions/dom_assertions'
-require 'rails/dom/testing/assertions/selector_assertions'
+# frozen_string_literal: true
+
+require_relative "assertions/dom_assertions"
+require_relative "assertions/selector_assertions"
 
 module Rails
   module Dom

data/lib/rails/dom/testing/railtie.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Rails
+  module Dom
+    module Testing
+      class Railtie < Rails::Railtie # :nodoc:
+        config.after_initialize do |app|
+          version = app.config.try(:dom_testing_default_html_version) # Rails 7.1+
+          Rails::Dom::Testing.default_html_version = version if version
+        end
+      end
+    end
+  end
+end

data/lib/rails/dom/testing/version.rb

@@ -1,7 +1,9 @@
+# frozen_string_literal: true
+
 module Rails
   module Dom
     module Testing
-      VERSION = "2.1.0"
+      VERSION = "2.2.0"
     end
   end
 end

data/lib/rails/dom/testing.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+require "active_support"
+require "active_support/core_ext/module/attribute_accessors"
+
+require "rails/dom/testing/assertions"
+
+module Rails
+  module Dom
+    module Testing
+      mattr_accessor :default_html_version, default: :html4
+
+      class << self
+        def html5_support?
+          defined?(Nokogiri::HTML5)
+        end
+
+        def html_document(html_version: nil)
+          parser_classes = { html4: Nokogiri::HTML4::Document }
+          parser_classes[:html5] = Nokogiri::HTML5::Document if html5_support?
+
+          choose_html_parser(parser_classes, html_version: html_version)
+        end
+
+        def html_document_fragment(html_version: nil)
+          parser_classes = { html4: Nokogiri::HTML4::DocumentFragment }
+          parser_classes[:html5] = Nokogiri::HTML5::DocumentFragment if html5_support?
+
+          choose_html_parser(parser_classes, html_version: html_version)
+        end
+
+        private
+          def choose_html_parser(parser_classes, html_version: nil)
+            html_version ||= Rails::Dom::Testing.default_html_version
+
+            case html_version
+            when :html4
+              parser_classes[:html4]
+            when :html5
+              unless Rails::Dom::Testing.html5_support?
+                raise NotImplementedError, "html5 parser is not supported on this platform"
+              end
+              parser_classes[:html5]
+            else
+              raise ArgumentError, "html_version must be :html4 or :html5, received #{html_version.inspect}"
+            end
+          end
+      end
+    end
+  end
+end

data/lib/rails-dom-testing.rb

@@ -1 +1,4 @@
-require 'rails/dom/testing/assertions'
+# frozen_string_literal: true
+
+require "rails/dom/testing"
+require "rails/dom/testing/railtie" if defined?(Rails::Railtie)