rails-dom-testing 2.1.1 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dc48c3a21ae3839cf5bbde901d06210fe2a4d1d58e6aae4048a26c19a6baf577
-  data.tar.gz: b082464768d961ef20cc41ec1da545691bd7e0caac93a16b8668128818855885
+  metadata.gz: 92842b3fcd4006daf9f8047da3d90a171ead6f39900c2d4f491d3c3ac0658845
+  data.tar.gz: 67b13526065e8c54acc109945f9566947f1976c601e44bb2295eaab79d7fcfe4
 SHA512:
-  metadata.gz: 51f291660cac9014e810adbf636c5dfbf7da80db478c062191eecedebe5b77b4f795a12259b1b427fd04b548e0a9b1b524d550e514b8e8b561ae566c36471182
-  data.tar.gz: d5ac742ae523c62d565627f9c95553780286de17ba7a43f32972a5dcf2458d316b79c80edcfd3f4361b2d77a4dcfa541976f14cbb09b249bf681bfabf2c5696e
+  metadata.gz: d16235fedf30e46ccc6f0fc4463f567917d12084d6d8a0b67cfce316ae7cdd5100b78d84f314e856ff56904e4ffa628628e0c2b5fee11cf1b287ddffdb04431c
+  data.tar.gz: 93e996ac52d49ead86b8a04ae43299303c3c02231adc0911158142e7defb49e5afc3b4584f66bb437e9983d910fc70f8bacdddfb79f648c8f1f27cd003532b87

data/README.md

@@ -5,26 +5,6 @@ Doms are compared via `assert_dom_equal` and `assert_dom_not_equal`.
 Elements are asserted via `assert_dom`, `assert_dom_encoded`, `assert_dom_email` and a subset of the dom can be selected with `css_select`.
 The gem is developed for Rails 4.2 and above, and will not work on previous versions.
 
-## Nokogiri::CSS::SyntaxError exceptions when upgrading to Rails 4.2:
-
-Nokogiri is slightly stricter about the format of CSS selectors than the previous implementation.
-
-Check the 4.2 release notes [section on `assert_select`](http://edgeguides.rubyonrails.org/4_2_release_notes.html#assert-select) for help.
-
-## Installation
-
-Add this line to your application's Gemfile:
-
-    gem 'rails-dom-testing'
-
-And then execute:
-
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install rails-dom-testing
-
 ## Usage
 
 ### Dom Assertions
@@ -44,6 +24,9 @@ css_select '.hello' # => Nokogiri::XML::NodeSet of elements with hello class
 # select from a supplied node. assert_dom asserts elements exist.
 assert_dom document_root_element.at('.hello'), '.goodbye'
 
+# select from a supplied node. assert_not_dom asserts elements do not exist.
+assert_not_dom document_root_element.at('.hello'), '.goodbye'
+
 # elements in CDATA encoded sections can also be selected
 assert_dom_encoded '#out-of-your-element'
 
@@ -53,6 +36,44 @@ assert_dom_email '#you-got-mail'
 
 The documentation in [selector_assertions.rb](https://github.com/rails/rails-dom-testing/blob/master/lib/rails/dom/testing/assertions/selector_assertions.rb) goes into a lot more detail of how selector assertions can be used.
 
+### HTML versions
+
+By default, assertions will use Nokogiri's HTML4 parser.
+
+If `Rails::Dom::Testing.default_html_version` is set to `:html5`, then the assertions will use
+Nokogiri's HTML5 parser. (If the HTML5 parser is not available on your platform, then a
+`NotImplementedError` will be raised.)
+
+When testing in a Rails application, the parser default can also be set by setting
+`Rails.application.config.dom_testing_default_html_version`.
+
+Some assertions support an `html_version:` keyword argument which can override the default for that
+assertion. For example:
+
+``` ruby
+# compare DOMs built with the HTML5 parser
+assert_dom_equal(expected, actual, html_version: :html5)
+
+# compare DOMs built with the HTML4 parser
+assert_dom_not_equal(expected, actual, html_version: :html4)
+```
+
+Please see documentation for individual assertions for more details.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'rails-dom-testing'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install rails-dom-testing
+
 ## Read more
 
 Under the hood the doms are parsed with Nokogiri, and you'll generally be working with these two classes:

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Rails
   module Dom
     module Testing
@@ -6,9 +8,32 @@ module Rails
           # \Test two HTML strings for equivalency (e.g., equal even when attributes are in another order)
           #
           #   # assert that the referenced method generates the appropriate HTML string
-          #   assert_dom_equal '<a href="http://www.example.com">Apples</a>', link_to("Apples", "http://www.example.com")
-          def assert_dom_equal(expected, actual, message = nil, strict: false)
-            expected_dom, actual_dom = fragment(expected), fragment(actual)
+          #   assert_dom_equal(
+          #     '<a href="http://www.example.com">Apples</a>',
+          #     link_to("Apples", "http://www.example.com"),
+          #   )
+          #
+          # By default, the matcher will not pay attention to whitespace in text nodes (e.g., spaces
+          # and newlines). If you want stricter matching with exact matching for whitespace, pass
+          # <tt>strict: true</tt>:
+          #
+          #   # these assertions will both pass
+          #   assert_dom_equal     "<div>\nfoo\n\</div>", "<div>foo</div>", strict: false
+          #   assert_dom_not_equal "<div>\nfoo\n\</div>", "<div>foo</div>", strict: true
+          #
+          # The DOMs are 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_equal expected, actual, html_version: :html5
+          #
+          def assert_dom_equal(expected, actual, message = nil, strict: false, html_version: nil)
+            expected_dom, actual_dom = fragment(expected, html_version: html_version), fragment(actual, html_version: html_version)
             message ||= "Expected: #{expected}\nActual: #{actual}"
             assert compare_doms(expected_dom, actual_dom, strict), message
           end
@@ -16,15 +41,38 @@ module Rails
           # The negated form of +assert_dom_equal+.
           #
           #   # assert that the referenced method does not generate the specified HTML string
-          #   assert_dom_not_equal '<a href="http://www.example.com">Apples</a>', link_to("Oranges", "http://www.example.com")
-          def assert_dom_not_equal(expected, actual, message = nil, strict: false)
-            expected_dom, actual_dom = fragment(expected), fragment(actual)
+          #   assert_dom_not_equal(
+          #     '<a href="http://www.example.com">Apples</a>',
+          #     link_to("Oranges", "http://www.example.com"),
+          #   )
+          #
+          # By default, the matcher will not pay attention to whitespace in text nodes (e.g., spaces
+          # and newlines). If you want stricter matching with exact matching for whitespace, pass
+          # <tt>strict: true</tt>:
+          #
+          #   # these assertions will both pass
+          #   assert_dom_equal     "<div>\nfoo\n\</div>", "<div>foo</div>", strict: false
+          #   assert_dom_not_equal "<div>\nfoo\n\</div>", "<div>foo</div>", strict: true
+          #
+          # The DOMs are 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_not_equal expected, actual, html_version: :html5
+          #
+          def assert_dom_not_equal(expected, actual, message = nil, strict: false, html_version: nil)
+            expected_dom, actual_dom = fragment(expected, html_version: html_version), fragment(actual, html_version: html_version)
             message ||= "Expected: #{expected}\nActual: #{actual}"
             assert_not compare_doms(expected_dom, actual_dom, strict), message
           end
+          alias_method :refute_dom_equal, :assert_dom_not_equal
 
           protected
-
             def compare_doms(expected, actual, strict)
               expected_children = extract_children(expected, strict)
               actual_children   = extract_children(actual, strict)
@@ -41,7 +89,7 @@ module Rails
               if strict
                 node.children
               else
-                node.children.reject{|n| n.text? && n.text.blank?}
+                node.children.reject { |n| n.text? && n.text.blank? }
               end
             end
 
@@ -83,9 +131,8 @@ module Rails
             end
 
           private
-
-            def fragment(text)
-              Nokogiri::HTML::DocumentFragment.parse(text)
+            def fragment(text, html_version: nil)
+              Rails::Dom::Testing.html_document_fragment(html_version: html_version).parse(text)
             end
         end
       end

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

@@ -1,122 +1,154 @@
-require 'minitest'
-require 'active_support'
-require 'active_support/core_ext/module/attribute_accessors'
-require_relative 'substitution_context'
-
-class HTMLSelector #:nodoc:
-  attr_reader :css_selector, :tests, :message
-
-  include Minitest::Assertions
-
-  def initialize(values, previous_selection = nil, &root_fallback)
-    @values = values
-    @root = extract_root(previous_selection, root_fallback)
-    extract_selectors
-    @tests = extract_equality_tests
-    @message = @values.shift
-
-    if @message.is_a?(Hash)
-      raise ArgumentError, "Last argument was a Hash, which would be used for the assertion message. You probably want this to be a String, or you have the wrong type of arguments."
-    end
-
-    if @values.shift
-      raise ArgumentError, "Not expecting that last argument, you either have too many arguments, or they're the wrong type"
-    end
-  end
-
-  def selecting_no_body? #:nodoc:
-    # Nokogiri gives the document a body element. Which means we can't
-    # run an assertion expecting there to not be a body.
-    @selector == 'body' && @tests[:count] == 0
-  end
-
-  def select
-    filter @root.css(@selector, context)
-  end
-
-  private
-
-  NO_STRIP = %w{pre script style textarea}
-
-  mattr_reader(:context) { SubstitutionContext.new }
-
-  def filter(matches)
-    match_with = tests[:text] || tests[:html]
-    return matches if matches.empty? || !match_with
-
-    content_mismatch = nil
-    text_matches = tests.has_key?(:text)
-    regex_matching = match_with.is_a?(Regexp)
-
-    remaining = matches.reject do |match|
-      # Preserve markup with to_s for html elements
-      content = text_matches ? match.text : match.children.to_s
-
-      content.strip! unless NO_STRIP.include?(match.name)
-      content.sub!(/\A\n/, '') if text_matches && match.name == "textarea"
-
-      next if regex_matching ? (content =~ match_with) : (content == match_with)
-      content_mismatch ||= diff(match_with, content)
-      true
-    end
-
-    @message ||= content_mismatch if remaining.empty?
-    Nokogiri::XML::NodeSet.new(matches.document, remaining)
-  end
-
-  def extract_root(previous_selection, root_fallback)
-    possible_root = @values.first
-
-    if possible_root == nil
-      raise ArgumentError, 'First argument is either selector or element ' \
-        'to select, but nil found. Perhaps you called assert_dom with ' \
-        'an element that does not exist?'
-    elsif possible_root.respond_to?(:css)
-      @values.shift # remove the root, so selector is the first argument
-      possible_root
-    elsif previous_selection
-      previous_selection
-    else
-      root_fallback.call
-    end
-  end
-
-  def extract_selectors
-    selector = @values.shift
-
-    unless selector.is_a? String
-      raise ArgumentError, "Expecting a selector as the first argument"
-    end
-
-    @css_selector = context.substitute!(selector, @values.dup, true)
-    @selector     = context.substitute!(selector, @values)
-  end
-
-  def extract_equality_tests
-    comparisons = {}
-    case comparator = @values.shift
-    when Hash
-      comparisons = comparator
-    when String, Regexp
-      comparisons[:text] = comparator
-    when Integer
-      comparisons[:count] = comparator
-    when Range
-      comparisons[:minimum] = comparator.begin
-      comparisons[:maximum] = comparator.end
-    when FalseClass
-      comparisons[:count] = 0
-    when NilClass, TrueClass
-      comparisons[:minimum] = 1
-    else raise ArgumentError, "I don't understand what you're trying to match"
-    end
-
-    # By default we're looking for at least one match.
-    if comparisons[:count]
-      comparisons[:minimum] = comparisons[:maximum] = comparisons[:count]
-    else
-      comparisons[:minimum] ||= 1
+# frozen_string_literal: true
+
+require "minitest"
+
+require_relative "substitution_context"
+
+module Rails
+  module Dom
+    module Testing
+      module Assertions
+        module SelectorAssertions
+          class HTMLSelector # :nodoc:
+            attr_reader :css_selector, :tests, :message
+
+            include Minitest::Assertions
+
+            def initialize(values, previous_selection = nil, refute: false, &root_fallback)
+              @values = values
+              @root = extract_root(previous_selection, root_fallback)
+              extract_selectors
+              @tests = extract_equality_tests(refute)
+              @message = @values.shift
+
+              if @message.is_a?(Hash)
+                raise ArgumentError, "Last argument was a Hash, which would be used for the assertion message. You probably want this to be a String, or you have the wrong type of arguments."
+              end
+
+              if @values.shift
+                raise ArgumentError, "Not expecting that last argument, you either have too many arguments, or they're the wrong type"
+              end
+            end
+
+            def selecting_no_body? # :nodoc:
+              # Nokogiri gives the document a body element. Which means we can't
+              # run an assertion expecting there to not be a body.
+              @selector == "body" && @tests[:count] == 0
+            end
+
+            def select
+              filter @root.css(@selector, context)
+            end
+
+            private
+              NO_STRIP = %w{pre script style textarea}
+
+              mattr_reader(:context) { SubstitutionContext.new }
+
+              def filter(matches)
+                match_with = tests[:text] || tests[:html]
+                return matches if matches.empty? || !match_with
+
+                content_mismatch = nil
+                text_matches = tests.has_key?(:text)
+                html_matches = tests.has_key?(:html)
+                regex_matching = match_with.is_a?(Regexp)
+
+                remaining = matches.reject do |match|
+                  # Preserve markup with to_s for html elements
+                  content = text_matches ? match.text : match.inner_html
+
+                  content.strip! unless NO_STRIP.include?(match.name)
+                  content.delete_prefix!("\n") if text_matches && match.name == "textarea"
+                  collapse_html_whitespace!(content) unless NO_STRIP.include?(match.name) || html_matches
+
+                  next if regex_matching ? (content =~ match_with) : (content == match_with)
+                  content_mismatch ||= diff(match_with, content)
+                  true
+                end
+
+                @message ||= content_mismatch if remaining.empty?
+                Nokogiri::XML::NodeSet.new(matches.document, remaining)
+              end
+
+              def extract_root(previous_selection, root_fallback)
+                possible_root = @values.first
+
+                if possible_root == nil
+                  raise ArgumentError, "First argument is either selector or element " \
+                    "to select, but nil found. Perhaps you called assert_dom with " \
+                    "an element that does not exist?"
+                elsif possible_root.respond_to?(:css)
+                  @values.shift # remove the root, so selector is the first argument
+                  possible_root
+                elsif previous_selection
+                  previous_selection
+                else
+                  root_fallback.call
+                end
+              end
+
+              def extract_selectors
+                selector = @values.shift
+
+                unless selector.is_a? String
+                  raise ArgumentError, "Expecting a selector as the first argument"
+                end
+
+                @css_selector = context.substitute!(selector, @values.dup, true)
+                @selector     = context.substitute!(selector, @values)
+              end
+
+              def extract_equality_tests(refute)
+                comparisons = {}
+                case comparator = @values.shift
+                when Hash
+                  comparisons = comparator
+                when String, Regexp
+                  comparisons[:text] = comparator
+                when Integer
+                  comparisons[:count] = comparator
+                when Range
+                  comparisons[:minimum] = comparator.begin
+                  comparisons[:maximum] = comparator.end
+                when FalseClass
+                  comparisons[:count] = 0
+                when NilClass, TrueClass
+                  comparisons[:minimum] = 1
+                else
+                  raise ArgumentError, "I don't understand what you're trying to match"
+                end
+
+                if refute
+                  if comparisons[:count] || (comparisons[:minimum] && !comparator.nil?) || comparisons[:maximum]
+                    raise ArgumentError, "Cannot use true, false, Integer, Range, :count, :minimum and :maximum when asserting that a selector does not match"
+                  end
+
+                  comparisons[:count] = 0
+                end
+
+                # By default we're looking for at least one match.
+                if comparisons[:count]
+                  comparisons[:minimum] = comparisons[:maximum] = comparisons[:count]
+                else
+                  comparisons[:minimum] ||= 1
+                end
+
+                if comparisons[:minimum] && comparisons[:maximum] && comparisons[:minimum] > comparisons[:maximum]
+                  raise ArgumentError, "Range begin or :minimum cannot be greater than Range end or :maximum"
+                end
+
+                @strict = comparisons[:strict]
+
+                comparisons
+              end
+
+              def collapse_html_whitespace!(text)
+                text.gsub!(/\s+/, " ")
+              end
+          end
+        end
+      end
     end
-    comparisons
   end
 end

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

@@ -1,30 +1,44 @@
-class SubstitutionContext
-  def initialize
-    @substitute = '?'
-  end
+# frozen_string_literal: true
 
-  def substitute!(selector, values, format_for_presentation = false)
-    selector.gsub @substitute do |match|
-      next match[0] if values.empty? || !substitutable?(values.first)
-      matcher_for(values.shift, format_for_presentation)
-    end
-  end
+module Rails
+  module Dom
+    module Testing
+      module Assertions
+        module SelectorAssertions
+          class SubstitutionContext # :nodoc:
+            def initialize
+              @substitute = "?"
+            end
 
-  def match(matches, attribute, matcher)
-    matches.find_all { |node| node[attribute] =~ Regexp.new(matcher) }
-  end
+            def substitute!(selector, values, format_for_presentation = false)
+              selector.gsub @substitute do |match|
+                next match[0] if values.empty? || !substitutable?(values.first)
+                matcher_for(values.shift, format_for_presentation)
+              end
+            end
 
-  private
-    def matcher_for(value, format_for_presentation)
-      # Nokogiri doesn't like arbitrary values without quotes, hence inspect.
-      if format_for_presentation
-        value.inspect # Avoid to_s so Regexps aren't put in quotes.
-      else
-        "\"#{value}\""
-      end
-    end
+            def match(matches, attribute, matcher)
+              matches.find_all { |node| node[attribute] =~ Regexp.new(matcher) }
+            end
+
+            private
+              def matcher_for(value, format_for_presentation)
+                # Nokogiri doesn't like arbitrary values without quotes, hence inspect.
+                if format_for_presentation
+                  value.inspect # Avoid to_s so Regexps aren't put in quotes.
+                elsif value.is_a?(Regexp)
+                  "\"#{value}\""
+                else
+                  value.to_s.inspect
+                end
+              end
 
-    def substitutable?(value)
-      [ Symbol, Numeric, String, Regexp ].any? { |type| value.is_a? type }
+              def substitutable?(value)
+                [ Symbol, Numeric, String, Regexp ].any? { |type| value.is_a? type }
+              end
+          end
+        end
+      end
     end
+  end
 end