feat: some assertions allow setting the HTML parser version

via an `html_version` kwarg:

- assert_dom_equal and assert_dom_not_equal
- assert_dom_encoded
- assert_dom_email

The remaining assertions all rely on `document_root_element` to return
the DOM (meaning we'll have to make changes to Rails).

Author: flavorjones

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../parser_selection"
+
 module Rails
   module Dom
     module Testing
@@ -9,8 +11,8 @@ module DomAssertions
           #
           #   # 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)
+          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
@@ -19,8 +21,8 @@ def assert_dom_equal(expected, actual, message = nil, strict: false)
           #
           #   # 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)
+          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
@@ -84,8 +86,8 @@ def equal_attribute?(attr, other_attr)
             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

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

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "../parser_selection"
 require_relative "selector_assertions/count_describable"
 require_relative "selector_assertions/html_selector"
 
@@ -212,7 +213,7 @@ def assert_dom(*args, &block)
           #       end
           #     end
           #   end
-          def assert_dom_encoded(element = nil, &block)
+          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
@@ -223,7 +224,7 @@ def assert_dom_encoded(element = nil, &block)
               end.map(&:content)
             end.join
 
-            selected = Nokogiri::HTML::DocumentFragment.parse(content)
+            selected = Rails::Dom::Testing.html_document_fragment(html_version: html_version).parse(content)
             nest_selection(selected) do
               if content.empty?
                 yield selected
@@ -249,14 +250,14 @@ def assert_dom_encoded(element = nil, &block)
           #       # Work with items here...
           #    end
           #  end
-          def assert_dom_email(&block)
+          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 /^text\/html\W/.match?(part["Content-Type"].to_s)
-                  root = Nokogiri::HTML::DocumentFragment.parse(part.body.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

test/dom_assertions_test.rb

@@ -125,3 +125,90 @@ def test_dom_not_equal_with_interior_whitespace
     assert_dom_not_equal(with_space, without_space)
   end
 end
+
+class DomAssertionsHtmlParserSelectionTest < ActiveSupport::TestCase
+  include DomTestingHelpers
+  include Rails::Dom::Testing::Assertions::DomAssertions
+
+  def setup
+    super
+
+    # https://html.spec.whatwg.org/multipage/parsing.html#an-introduction-to-error-handling-and-strange-cases-in-the-parser
+    # we use these results to assert that we're invoking the expected parser.
+    @input = "<p>1<b>2<i>3</b>4</i>5</p>"
+    @html4_result = jruby? ? "<p>1<b>2<i>3</i></b><i>4</i>5</p>" : "<p>1<b>2<i>3</i></b>45</p>"
+    @html5_result = jruby? ? nil                                 : "<p>1<b>2<i>3</i></b><i>4</i>5</p>"
+  end
+
+  test "default value is html4" do
+    assert_equal(:html4, Rails::Dom::Testing.default_html_version)
+  end
+
+  test "default html4, no version specified" do
+    with_default_html_version(:html4) do
+      assert_dom_equal(@html4_result, @input)
+      assert_dom_not_equal(@html5_result, @input)
+    end
+  end
+
+  test "default html4, html4 specified" do
+    with_default_html_version(:html4) do
+      assert_dom_equal(@html4_result, @input, html_version: :html4)
+      assert_dom_not_equal(@html5_result, @input, html_version: :html4)
+    end
+  end
+
+  test "default html4, html5 specified" do
+    skip("html5 is not supported") unless Rails::Dom::Testing.html5_support?
+
+    with_default_html_version(:html4) do
+      assert_dom_equal(@html5_result, @input, html_version: :html5)
+      assert_dom_not_equal(@html4_result, @input, html_version: :html5)
+    end
+  end
+
+  test "default html5, no version specified" do
+    skip("html5 is not supported") unless Rails::Dom::Testing.html5_support?
+
+    with_default_html_version(:html5) do
+      assert_dom_equal(@html5_result, @input)
+      assert_dom_not_equal(@html4_result, @input)
+    end
+  end
+
+  test "default html5, html4 specified" do
+    with_default_html_version(:html5) do
+      assert_dom_equal(@html4_result, @input, html_version: :html4)
+      assert_dom_not_equal(@html5_result, @input, html_version: :html4)
+    end
+  end
+
+  test "default html5, html5 specified" do
+    skip("html5 is not supported") unless Rails::Dom::Testing.html5_support?
+
+    with_default_html_version(:html5) do
+      assert_dom_equal(@html5_result, @input, html_version: :html5)
+      assert_dom_not_equal(@html4_result, @input, html_version: :html5)
+    end
+  end
+
+  test "raise NotImplementedError html5 when not supported" do
+    Rails::Dom::Testing.stub(:html5_support?, false) do
+      with_default_html_version(:html5) do
+        assert_raises(NotImplementedError) { assert_dom_equal("a", "b") }
+        assert_raises(NotImplementedError) { assert_dom_equal("a", "b", html_version: :html5) }
+        assert_nothing_raised { assert_dom_equal(@html4_result, @input, html_version: :html4) }
+      end
+    end
+  end
+
+  test "default set to invalid" do
+    with_default_html_version(:html9) do
+      assert_raises(ArgumentError) { assert_dom_equal("a", "b") }
+    end
+  end
+
+  test "invalid version specified" do
+    assert_raises(ArgumentError) { assert_dom_equal("a", "b", html_version: :html9) }
+  end
+end

test/selector_assertions_test.rb

@@ -7,6 +7,7 @@
 class AssertSelectTest < ActiveSupport::TestCase
   Assertion = Minitest::Assertion
 
+  include DomTestingHelpers
   include Rails::Dom::Testing::Assertions::SelectorAssertions
 
   def assert_failure(message, &block)
@@ -302,6 +303,52 @@ def test_feed_item_encoded
     end
   end
 
+  def test_feed_item_encoded_with_html_version
+    # https://html.spec.whatwg.org/multipage/parsing.html#an-introduction-to-error-handling-and-strange-cases-in-the-parser
+    # we use these results to assert that we're invoking the expected parser.
+    input = CGI.escapeHTML("<p>1<b>2<i>3</b>4</i>5</p>")
+    html4_result = jruby? ? "<p>1<b>2<i>3</i></b><i>4</i>5</p>" : "<p>1<b>2<i>3</i></b>45</p>"
+    html5_result = jruby? ? nil                                 : "<p>1<b>2<i>3</i></b><i>4</i>5</p>"
+
+    render_xml(<<~XML)
+      <root>
+        <contents>#{input}</contents>
+      </root>
+    XML
+
+    with_default_html_version(:html4) do
+      assert_select "root contents" do
+        assert_select_encoded do |contents|
+          assert_equal(html4_result, contents.to_html)
+        end
+
+        assert_select_encoded(html_version: :html4) do |contents|
+          assert_equal(html4_result, contents.to_html)
+        end
+
+        assert_select_encoded(html_version: :html5) do |contents|
+          assert_equal(html5_result, contents.to_html)
+        end if Rails::Dom::Testing.html5_support?
+      end
+    end
+
+    with_default_html_version(:html5) do
+      assert_select "root contents" do
+        assert_select_encoded do |contents|
+          assert_equal(html5_result, contents.to_html)
+        end if Rails::Dom::Testing.html5_support?
+
+        assert_select_encoded(html_version: :html4) do |contents|
+          assert_equal(html4_result, contents.to_html)
+        end
+
+        assert_select_encoded(html_version: :html5) do |contents|
+          assert_equal(html5_result, contents.to_html)
+        end if Rails::Dom::Testing.html5_support?
+      end
+    end
+  end
+
   def test_body_not_present_in_empty_document
     render_html "<div></div>"
     assert_select "body", 0
@@ -348,7 +395,7 @@ def fake_render(content_type, content)
       @html_document = if content_type == :xml
         Nokogiri::XML::Document.parse(content)
       else
-        Nokogiri::HTML::Document.parse(content)
+        Rails::Dom::Testing.html_document.parse(content)
       end
     end
 

test/test_helper.rb

@@ -8,6 +8,10 @@
 ActiveSupport::TestCase.test_order = :random
 
 module DomTestingHelpers
+  def jruby?
+    !! Nokogiri.jruby?
+  end
+
   def with_default_html_version(version)
     old_version = Rails::Dom::Testing.default_html_version
     begin