dommy-rails 0.9.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 62f4ed9c4e72fad6e37235d7831a24fed0f941d5832be21a9469972f04cc40d8
+  data.tar.gz: dc94f1a8349a01b22819c66602d38a9795670f917e5b55aeba313eddaafea918
+SHA512:
+  metadata.gz: 2ed06d6d5570260669b7cb7626566aeeaed03f1771a4afc0f0c99377079e68a15f0283068f6b00f749a62a5cf92d16adbaa6849f424f9af22a08ee07f88084ec
+  data.tar.gz: 01e9d6f47a22a8a60dac0a88efe08835b5be3d0fb0c2fdc28fd0d30c387aaab6fdfa3f3489e20c35ce7b4875c6aed531c314a3771cf4fa731a01d33bb426e717

data/README.md

@@ -0,0 +1,129 @@
+# dommy-rails
+
+Rails integration for [Dommy](https://github.com/takahashim/dommy) —
+provides Rails-specific DOM testing helpers for request specs, view specs,
+component specs, and mailer specs.
+
+## Features
+
+- **Form helper understanding**: Detect Rails forms, `_method` override, CSRF tokens
+- **Turbo Stream support**: Parse and assert Turbo Stream responses
+- **Turbo Frame support**: Assert `<turbo-frame>` presence and contents
+- **Stimulus checking**: Verify `data-controller`, `data-action`, `data-target`, `data-*-value`
+- **Mailer assertions**: Check HTML and plain text mail bodies
+- **HTML quality linting**: Find duplicate IDs, invalid ARIA references, missing form labels, empty links, and nested interactive elements
+- **URL normalization**: Compare URLs accounting for host differences, query param ordering, HTML entities
+
+## Installation
+
+```ruby
+gem "dommy-rails"
+```
+
+## Usage
+
+### Minitest (ActionDispatch::IntegrationTest)
+
+```ruby
+require "dommy/rails/minitest"
+
+class ArticlesControllerTest < ActionDispatch::IntegrationTest
+  include Dommy::Rails::Minitest::Integration
+
+  def test_index
+    get articles_path
+    
+    assert_dom_has_css dom, "h1", text: "Articles"
+    assert_dom_has_link dom, "New article", href: new_article_path
+    assert_dom_has_form dom, action: articles_path, method: :post
+    assert_dom_has_title dom, "Articles"
+    assert_dom_has_csrf_meta_tags dom
+    assert_dom_has_stimulus_controller dom, "articles"
+    assert_dom_has_turbo_frame dom, "articles"
+    assert_dom_no_duplicate_ids dom
+    assert_dom_no_empty_links dom
+  end
+
+  def test_turbo_stream
+    post articles_path, params: { article: { title: "Hello" } }, as: :turbo_stream
+    
+    assert_dom_appends_turbo_stream response, "articles" do |fragment|
+      assert_dom_has_css fragment, ".article", text: "Hello"
+    end
+  end
+end
+```
+
+### RSpec
+
+```ruby
+require "dommy/rails/rspec"
+
+RSpec.configure do |config|
+  config.include Dommy::Rails::RSpec::Integration, type: :request
+  config.include Dommy::Rails::RSpec::Integration, type: :view
+  config.include Dommy::Rails::RSpec::Integration, type: :component
+  config.include Dommy::Rails::RSpec::Integration, type: :mailer
+end
+```
+
+```ruby
+RSpec.describe "Articles", type: :request do
+  it "renders the index" do
+    get articles_path
+
+    expect(dom).to have_css("h1", text: "Articles")
+    expect(dom).to have_link("New article", href: new_article_path)
+    expect(dom).to have_form(action: articles_path, method: :post)
+    expect(dom).to have_title("Articles")
+    expect(dom).to have_csrf_meta_tags
+    expect(dom).to have_stimulus_controller("articles")
+    expect(dom).to have_no_duplicate_ids
+    expect(dom).to have_no_empty_links
+  end
+
+  it "renders a Turbo Stream response" do
+    post articles_path, params: { article: { title: "Hello" } }, as: :turbo_stream
+
+    expect(response).to append_turbo_stream("articles") { |fragment|
+      expect(fragment).to have_css(".article", text: "Hello")
+    }
+  end
+end
+```
+
+Turbo Frames can be checked directly:
+
+```ruby
+expect(dom).to have_turbo_frame("articles") { |frame|
+  expect(frame).to have_css(".article", text: "Hello")
+}
+```
+
+Mailer specs can check mail objects directly:
+
+```ruby
+expect(mail).to have_html_link("Confirm your account", href: confirmation_url(user))
+expect(mail).to have_html_text("Confirm your account")
+expect(mail).to have_plain_text("Welcome")
+```
+
+## URL normalization
+
+`have_link(href:)`, `have_form(action:)`, and their Minitest counterparts
+absorb the representational differences between Rails URL helpers and
+rendered HTML. Before comparison, both sides are normalized:
+
+- scheme and host are dropped (`http://www.example.com/articles` ≡ `/articles`)
+- query parameters are sorted (`?b=2&a=1` ≡ `?a=1&b=2`)
+- HTML entities are unescaped (`&amp;` ≡ `&`)
+- trailing slashes are removed (`/articles/` ≡ `/articles`)
+
+This is deliberately lenient: because the host is ignored, an absolute
+URL to an external site with the same path matches a relative `href:`.
+Strict external-host matching is out of scope for now; pass a `Regexp`
+as `href:` when you need to pin the host.
+
+## License
+
+MIT

data/lib/dommy/rails/aria_snapshot_matching.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Dommy
+  module Rails
+    # Compares a Playwright-compatible ARIA snapshot against an expected
+    # template using Playwright's `toMatchAriaSnapshot` semantics: a SUBSET
+    # match. Every node listed in `expected` must appear in `actual`, in order,
+    # at the same nesting — but `actual` may contain extra nodes. A node matches
+    # when role + (optional) name + (subset of) flags agree. An expected name
+    # written as `/pattern/` is matched as a regular expression; an omitted name
+    # is a wildcard.
+    module AriaSnapshotMatching
+      Node = Struct.new(:role, :name, :name_regex, :flags, :children, keyword_init: true)
+
+      module_function
+
+      def matches?(actual_text, expected_text)
+        children_match?(parse(expected_text).children, parse(actual_text).children)
+      end
+
+      # --- comparison ---
+
+      def node_match?(expected, actual)
+        return false unless expected.role == actual.role
+        return false unless name_match?(expected, actual)
+        return false unless (expected.flags - actual.flags).empty?
+
+        children_match?(expected.children, actual.children)
+      end
+
+      def name_match?(expected, actual)
+        return actual.name.to_s.match?(expected.name_regex) if expected.name_regex
+        return true if expected.name.nil?
+
+        expected.name == actual.name
+      end
+
+      # Greedy ordered-subsequence match: each expected child must match a later
+      # actual child, allowing extra actual children in between.
+      def children_match?(expected_children, actual_children)
+        cursor = 0
+        expected_children.each do |expected|
+          cursor += 1 until cursor >= actual_children.size || node_match?(expected, actual_children[cursor])
+          return false if cursor >= actual_children.size
+
+          cursor += 1
+        end
+        true
+      end
+
+      # --- parsing (indentation outline -> Node tree) ---
+
+      def parse(text)
+        root = Node.new(role: nil, flags: [], children: [])
+        stack = [[-1, root]]
+        text.to_s.each_line do |line|
+          stripped = line.strip
+          next if stripped.empty? || !stripped.start_with?("- ")
+
+          indent = line[/\A */].length
+          node = parse_line(stripped[2..])
+          stack.pop while stack.size > 1 && stack.last[0] >= indent
+          stack.last[1].children << node
+          stack.push([indent, node])
+        end
+        root
+      end
+
+      def parse_line(body)
+        body = body.sub(/:\s*\z/, "")
+        return Node.new(role: "text", name: unquote(body.sub(/\Atext:\s*/, "")), flags: [], children: []) \
+          if body.start_with?("text:")
+
+        role, rest = body.split(/\s+/, 2)
+        name, name_regex, rest = scan_name(rest)
+        flags = rest.to_s.scan(/\[([^\]]*)\]/).flatten
+        Node.new(role: role, name: name, name_regex: name_regex, flags: flags, children: [])
+      end
+
+      def scan_name(rest)
+        return [nil, nil, rest] if rest.nil?
+
+        if rest.start_with?('"') && (md = rest.match(/\A"((?:\\.|[^"\\])*)"/))
+          [unescape(md[1]), nil, rest[md.end(0)..].to_s.strip]
+        elsif rest.start_with?("/") && (md = rest.match(%r{\A/((?:\\.|[^/\\])*)/}))
+          [nil, Regexp.new(md[1]), rest[md.end(0)..].to_s.strip]
+        else
+          [nil, nil, rest]
+        end
+      end
+
+      def unquote(text)
+        md = text.to_s.strip.match(/\A"((?:\\.|[^"\\])*)"\z/)
+        md ? unescape(md[1]) : text.to_s.strip
+      end
+
+      def unescape(text) = text.gsub(/\\(.)/, '\1')
+    end
+  end
+end

data/lib/dommy/rails/browser_spec.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Dommy
+  module Rails
+    # Test-integration helper that runs application JavaScript against the real
+    # Rails app, bridging request-style specs to the lightweight test browser.
+    # Include it in a Minitest test or RSpec example group to get a `browser`
+    # (a `javascript: true` Dommy::Rack::Session bound to the Rails Rack app):
+    #
+    #   browser.visit todos_path
+    #   browser.click "li.todo"
+    #   assert browser.has_css?("li.todo.is-completed")
+    #
+    # External `<script>`s and `fetch` resolve through the Rails app itself
+    # (Propshaft / Sprockets / controllers), sharing the session cookie jar.
+    # The browser is disposed at teardown, and any uncaught JS error / unhandled
+    # rejection fails the test (strict by default) unless wrapped in
+    # `allow_js_errors`.
+    module BrowserSpec
+      # Auto-wire teardown: RSpec example groups get an `after` hook (the
+      # example is passed so we can save artifacts on failure); Minitest tests
+      # use `after_teardown` (defined below).
+      def self.included(base)
+        if base.respond_to?(:after)
+          base.after do |example|
+            dommy_browser_after(failed: example.exception ? true : false,
+              label: example.full_description, exception: example.exception)
+          end
+        end
+      end
+
+      # Minitest teardown hook (no-op outside Minitest).
+      def after_teardown
+        failures = respond_to?(:failures) ? self.failures : []
+        dommy_browser_after(failed: !failures.empty?, label: (name if respond_to?(:name)),
+          exception: failures.first)
+      ensure
+        super if defined?(super)
+      end
+
+      # On a failed example, write debugging artifacts (page HTML + trace +
+      # visible text) before disposing, then run the normal teardown. Shared by
+      # the RSpec and Minitest hooks.
+      def dommy_browser_after(failed:, label: nil, exception: nil)
+        dommy_save_failure_artifacts(label, exception: exception) if failed && browser_started?
+        dommy_browser_teardown
+      end
+
+      # The Rack app the browser drives. Defaults to the Rails application;
+      # override `dommy_browser_app` to point elsewhere.
+      def dommy_browser_app
+        return ::Rails.application if defined?(::Rails) && ::Rails.respond_to?(:application)
+
+        raise "Dommy::Rails::BrowserSpec needs a Rack app: define #dommy_browser_app " \
+              "(Rails.application was not available)."
+      end
+
+      # Memoized JS-enabled session bound to the app. Lazily requires the
+      # dommy-rack + QuickJS integration so the dependency is only needed when a
+      # browser spec actually runs.
+      def browser
+        @dommy_browser ||= begin
+          require "dommy/js/quickjs/rack"
+          ::Dommy::Rack::Session.new(dommy_browser_app, javascript: true, trace: true, trace_dom: true,
+            trace_snapshots: true)
+        end
+      end
+
+      # Directory failure artifacts are written under (override per host).
+      def dommy_failures_dir = ::File.join("tmp", "dommy", "failures")
+
+      def browser_started? = !@dommy_browser.nil?
+
+      # Suppress strict JS-error failure for errors raised inside the block (they
+      # stay in `browser.js_errors`). For specs that intentionally trigger one.
+      def allow_js_errors
+        @dommy_allow_js_errors = true
+        yield
+      ensure
+        dommy_browser_ack_js_errors
+      end
+
+      # Dispose the browser and fail if uncaught JS errors were collected. Call
+      # from a Minitest #teardown / RSpec after hook (the integration modules
+      # wire this automatically).
+      def dommy_browser_teardown
+        return unless browser_started?
+
+        pending = browser.js_errors[(@dommy_browser_acked || 0)..] || []
+        browser.dispose_js
+        @dommy_browser = nil
+        return if @dommy_allow_js_errors || pending.empty?
+
+        raise dommy_browser_js_error(pending)
+      end
+
+      private
+
+      # Write current.html / trace.txt / visible-text.txt plus a self-contained
+      # NDJSON trace bundle for a failed example into a per-example directory, so
+      # a CI run can surface what the browser saw. Best-effort: a browser without
+      # a trace (or any IO error) is skipped silently rather than masking the
+      # real failure.
+      def dommy_save_failure_artifacts(label, exception: nil)
+        return unless browser.respond_to?(:trace) && browser.trace
+
+        # Append the failing expectation to the trace so the viewer shows where
+        # (and how) the test failed, in line with the events that led there.
+        if exception
+          browser.trace.record_error(message: exception.message.to_s.lines.first&.strip,
+            exception_class: exception.class.name)
+        end
+
+        dir = ::File.join(dommy_failures_dir, dommy_artifact_slug(label))
+        ::FileUtils.mkdir_p(dir)
+        ::File.write(::File.join(dir, "current.html"), browser.html.to_s)
+        ::File.write(::File.join(dir, "trace.txt"), browser.trace.to_text)
+        ::File.write(::File.join(dir, "visible-text.txt"), browser.text.to_s)
+        # A self-contained NDJSON bundle (trace.ndjson + artifacts/) for the
+        # standalone `dommy-trace` viewer — the machine-readable trace format.
+        browser.trace.save(dir, status: "failed", metadata: {"example" => label.to_s})
+        if browser.respond_to?(:debug)
+          ::File.write(::File.join(dir, "dom-summary.txt"), browser.debug.dom_summary)
+          ::File.write(::File.join(dir, "aria-snapshot.txt"), browser.debug.aria_snapshot)
+        end
+        dir
+      rescue StandardError
+        nil
+      end
+
+      def dommy_artifact_slug(label)
+        slug = label.to_s.strip.downcase.gsub(/[^a-z0-9]+/, "-").gsub(/\A-+|-+\z/, "")
+        slug.empty? ? "example" : slug[0, 100]
+      end
+
+      def dommy_browser_ack_js_errors
+        @dommy_browser_acked = browser_started? ? browser.js_errors.length : 0
+      end
+
+      def dommy_browser_js_error(errors)
+        lines = errors.map { |e| "  #{e.class}: #{e.message}" }
+        RuntimeError.new("#{errors.length} uncaught JS error(s) during the spec:\n#{lines.join("\n")}")
+      end
+    end
+  end
+end

data/lib/dommy/rails/dom_source.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "mail_part"
+
+module Dommy
+  module Rails
+    # Shared implementation of the `dom` helper for the Minitest and
+    # RSpec integration modules: locates the HTML source on the test
+    # context (response / rendered / mail) and memoizes the parsed
+    # document per source string.
+    module DomSource
+      def dom
+        source = dom_html_source.to_s
+        return @dommy_rails_dom if defined?(@dommy_rails_dom_source) && @dommy_rails_dom_source == source
+
+        @dommy_rails_dom_source = source
+        @dommy_rails_dom = Dommy.parse(source).document
+      end
+
+      private
+
+      def dom_html_source
+        if respond_to?(:response) && response.respond_to?(:body) && response.body
+          response.body
+        elsif respond_to?(:rendered) && rendered
+          rendered
+        elsif respond_to?(:message) && (html = MailPart.html_body(message))
+          html
+        else
+          raise "Dommy::Rails could not find HTML for `dom`. Expected response.body, rendered, or message.html_part."
+        end
+      end
+    end
+  end
+end

data/lib/dommy/rails/form_inspector.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "dommy/internal/element_matching"
+require_relative "url_matcher"
+
+module Dommy
+  module Rails
+    module FormInspector
+      module_function
+
+      def matches?(document, action: nil, method: nil, model: nil)
+        forms = Internal::ElementMatching.find_forms(document, action: action && UrlMatcher.new(action), method: method)
+        forms = forms.select { |form| form_has_model?(form, model_name_for(model)) } if model
+        forms.any?
+      end
+
+      def method_override(form)
+        hidden = form.query_selector("input[type='hidden'][name='_method']")
+        hidden ? hidden.get_attribute("value") : nil
+      end
+
+      def authenticity_token(form)
+        input = form.query_selector("input[type='hidden'][name='authenticity_token']")
+        input ? input.get_attribute("value") : nil
+      end
+
+      def model_name_for(model)
+        if model.respond_to?(:model_name)
+          model.model_name.param_key
+        elsif model.respond_to?(:to_model)
+          model.to_model.model_name.param_key
+        else
+          # No ActiveSupport fallback: dommy-rails depends only on dommy,
+          # and Rails form helpers require these methods too.
+          raise ArgumentError,
+            "model: expects an object responding to #model_name or #to_model, got #{model.class}"
+        end
+      end
+
+      # A Rails model form scopes its field names under the model's
+      # param key (e.g. name="article[title]").
+      def form_has_model?(form, model_name)
+        prefix = "#{model_name}["
+        form.query_selector_all("input, textarea, select").to_a.any? do |field|
+          field.get_attribute("name").to_s.start_with?(prefix)
+        end
+      end
+
+      private_class_method :model_name_for, :form_has_model?
+    end
+  end
+end

data/lib/dommy/rails/lint.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "dommy/internal/element_matching"
+
+module Dommy
+  module Rails
+    module Lint
+      # Inputs whose accessible name comes from elsewhere (value
+      # attribute) or that are not user-visible, so a <label> is not
+      # expected.
+      NON_LABELABLE_INPUT_TYPES = %w[hidden submit button reset image].freeze
+
+      module_function
+
+      def duplicate_ids(document)
+        all_elements = document.query_selector_all("*[id]").to_a
+        ids = all_elements.map { |el| el.get_attribute("id") }
+        ids.select { |id| ids.count(id) > 1 }.uniq
+      end
+
+      def invalid_aria_references(document)
+        issues = []
+        document.query_selector_all("*").each do |el|
+          %w[aria-labelledby aria-describedby].each do |attr|
+            next unless el.has_attribute?(attr)
+
+            el.get_attribute(attr).to_s.split.each do |id|
+              issues << { element: el, attribute: attr, id: id } unless document.get_element_by_id(id)
+            end
+          end
+        end
+        issues
+      end
+
+      # Lenient policy: aria-label / aria-labelledby / placeholder are
+      # all accepted as label substitutes, even though a placeholder is
+      # not a sufficient accessible name under WCAG.
+      def missing_form_labels(document)
+        issues = []
+        document.query_selector_all("input, textarea, select").each do |field|
+          next if field.tag_name == "INPUT" &&
+            NON_LABELABLE_INPUT_TYPES.include?(field.get_attribute("type").to_s.downcase)
+          next if field.has_attribute?("aria-label")
+          next if field.has_attribute?("aria-labelledby")
+          next if field.has_attribute?("placeholder")
+          next if Dommy::Internal::ElementMatching.field_labels(field).any?
+
+          issues << { element: field, name: field.get_attribute("name") }
+        end
+        issues
+      end
+
+      def empty_links(document)
+        document.query_selector_all("a[href]").to_a.select do |link|
+          accessible_link_text(link).empty?
+        end
+      end
+
+      def nested_interactive_elements(document)
+        issues = []
+        interactive_elements(document).each do |element|
+          parent = element.parent_node
+          while parent
+            if interactive_element?(parent)
+              issues << { element: element, ancestor: parent }
+              break
+            end
+            parent = parent.respond_to?(:parent_node) ? parent.parent_node : nil
+          end
+        end
+        issues
+      end
+
+      def interactive_elements(document)
+        document.query_selector_all("a[href], button, input, select, textarea, summary").to_a.reject do |element|
+          element.tag_name == "INPUT" && element.get_attribute("type").to_s.downcase == "hidden"
+        end
+      end
+
+      def interactive_element?(element)
+        return false unless element.respond_to?(:tag_name)
+
+        case element.tag_name
+        when "A"
+          element.has_attribute?("href")
+        when "BUTTON", "SELECT", "TEXTAREA", "SUMMARY"
+          true
+        when "INPUT"
+          element.get_attribute("type").to_s.downcase != "hidden"
+        else
+          false
+        end
+      end
+
+      def accessible_link_text(link)
+        [
+          link.text_content,
+          link.get_attribute("aria-label"),
+          link.get_attribute("title"),
+          image_alt_text(link)
+        ].compact.join.strip
+      end
+
+      def image_alt_text(link)
+        link.query_selector_all("img").to_a.map { |image| image.get_attribute("alt").to_s }.join
+      end
+    end
+  end
+end

data/lib/dommy/rails/mail_part.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Dommy
+  module Rails
+    # Extracts HTML / plain-text bodies from Mail-like objects
+    # (multipart or single-part).
+    module MailPart
+      module_function
+
+      def html_body(mail)
+        if mail.respond_to?(:html_part) && mail.html_part
+          mail.html_part.body.to_s
+        elsif mail.respond_to?(:body)
+          mail.body.to_s
+        end
+      end
+
+      def plain_body(mail)
+        if mail.respond_to?(:text_part) && mail.text_part
+          mail.text_part.body.to_s
+        elsif mail.respond_to?(:body)
+          mail.body.to_s
+        end
+      end
+
+      def html_document(mail)
+        body = html_body(mail)
+        body ? Dommy.parse(body).document : nil
+      end
+    end
+  end
+end

data/lib/dommy/rails/match_target.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Dommy
+  module Rails
+    # Resolves the objects assertions/matchers accept (response-like,
+    # raw HTML string, or an already-parsed Dommy document/element)
+    # into a document or body string.
+    module MatchTarget
+      module_function
+
+      def document(actual)
+        return actual.document if actual.respond_to?(:document)
+        return actual if actual.respond_to?(:query_selector_all)
+
+        Dommy.parse(body(actual)).document
+      end
+
+      def body(actual)
+        actual.respond_to?(:body) ? actual.body.to_s : actual.to_s
+      end
+    end
+  end
+end