dommy 0.5.0

data/lib/dommy/rspec/capy_style_matchers.rb

@@ -0,0 +1,356 @@
+# frozen_string_literal: true
+
+require_relative "../internal/dom_matching"
+require_relative "../internal/scope_resolution"
+
+module Dommy
+  module RSpec
+    # Capybara-style RSpec matchers backed by Dommy.
+    #
+    # These mirror Capybara's matcher names (`have_selector`, `have_content`,
+    # `have_link`, etc.) so existing Capybara test suites can be migrated
+    # to a pure-Ruby DOM stack with minimal code changes.
+    #
+    # Because the names collide with Capybara::RSpecMatchers, this module
+    # should be included into specs that DO NOT also include Capybara —
+    # typically view / component / request specs, with feature specs
+    # left to Capybara. See the README for a `type:` split example.
+    #
+    # @example
+    #   require "dommy/rspec/capy_style_matchers"
+    #
+    #   RSpec.configure do |c|
+    #     c.include Dommy::TestHelpers,                type: :view
+    #     c.include Dommy::RSpec::CapyStyleMatchers,   type: :view
+    #   end
+    #
+    #   expect(dom).to have_selector("button.primary")
+    #   expect(dom).to have_content("Welcome")
+    #   expect(dom).to have_link("Sign up", href: "/signup")
+    module CapyStyleMatchers
+      def have_selector(selector, **opts)
+        HaveSelector.new(selector, **opts)
+      end
+
+      alias_method :have_css, :have_selector
+
+      def have_no_selector(selector, **opts)
+        HaveNoSelector.new(selector, **opts)
+      end
+
+      alias_method :have_no_css, :have_no_selector
+
+      def have_content(text, **opts)
+        HaveContent.new(text, **opts)
+      end
+
+      alias_method :have_text, :have_content
+
+      def have_no_content(text, **opts)
+        HaveNoContent.new(text, **opts)
+      end
+
+      alias_method :have_no_text, :have_no_content
+
+      def have_link(text = nil, **opts)
+        HaveLink.new(text, **opts)
+      end
+
+      def have_no_link(text = nil, **opts)
+        HaveNoLink.new(text, **opts)
+      end
+
+      def have_button(text = nil, **opts)
+        HaveButton.new(text, **opts)
+      end
+
+      def have_no_button(text = nil, **opts)
+        HaveNoButton.new(text, **opts)
+      end
+
+      def have_field(name_or_label = nil, **opts)
+        HaveField.new(name_or_label, **opts)
+      end
+
+      def have_no_field(name_or_label = nil, **opts)
+        HaveNoField.new(name_or_label, **opts)
+      end
+
+      # ----- Base behavior shared across element-finding matchers -----
+
+      # @api private
+      class Base
+        def initialize(selector, **opts)
+          @selector = selector
+          @text = opts[:text] || opts[:content]
+          @count = opts[:count]
+          @exact = opts[:exact] || opts[:exact_text]
+          @visible = opts.fetch(:visible, :visible)
+          # :wait is accepted for Capybara compatibility but ignored
+          # (Dommy is synchronous).
+        end
+
+        def matches?(scope)
+          @scope = Internal::ScopeResolution.resolve(scope)
+          @matched = find_matches(@scope)
+          count_ok?(@matched.size)
+        end
+
+        def does_not_match?(scope)
+          @scope = Internal::ScopeResolution.resolve(scope)
+          @matched = find_matches(@scope)
+          if @count
+            !count_ok?(@matched.size)
+          else
+            @matched.empty?
+          end
+        end
+
+        def description
+          "have #{describe_target}"
+        end
+
+        def failure_message
+          "expected to find #{describe_target}, found #{@matched.size}"
+        end
+
+        def failure_message_when_negated
+          "expected NOT to find #{describe_target}, found #{@matched.size}"
+        end
+
+        private
+
+        def find_matches(scope)
+          elements = scope.query_selector_all(query_selector).to_a
+          elements = filter_by_text(elements) if @text
+          Internal::DomMatching.filter_by_visibility(elements, @visible)
+        end
+
+        def filter_by_text(elements)
+          elements.select { |el| Internal::DomMatching.text_matches?(el.text_content, @text, exact: @exact) }
+        end
+
+        def query_selector
+          @selector
+        end
+
+        def count_ok?(actual)
+          Internal::DomMatching.count_matches?(actual, @count)
+        end
+
+        def describe_target
+          parts = [describe_what]
+          parts << "with text #{@text.inspect}" if @text
+          parts << "(count: #{@count.inspect})" if @count
+          parts.join(" ")
+        end
+
+        def describe_what
+          "elements matching #{@selector.inspect}"
+        end
+      end
+
+      # @api private
+      # Mixin that flips matches? / does_not_match? for the "no_*" matchers,
+      # so each negative matcher reads identically to its positive twin
+      # but with inverted assertions.
+      module Negated
+        def matches?(scope)
+          !super
+        end
+
+        def does_not_match?(scope)
+          !matches?(scope)
+        end
+
+        def failure_message
+          "expected NOT to find #{describe_target}, found #{@matched.size}"
+        end
+
+        def failure_message_when_negated
+          "expected to find #{describe_target}, found #{@matched.size}"
+        end
+      end
+
+      class HaveSelector < Base
+      end
+
+      class HaveNoSelector < HaveSelector
+        include Negated
+      end
+
+      # @api private
+      class HaveContent
+        def initialize(text, **opts)
+          @text = text
+          @exact = opts[:exact] || opts[:exact_text]
+        end
+
+        def matches?(scope)
+          @scope = Internal::ScopeResolution.resolve(scope)
+          @actual = Internal::DomMatching.text_of(@scope)
+          Internal::DomMatching.text_matches?(@actual, @text, exact: @exact)
+        end
+
+        def does_not_match?(scope)
+          !matches?(scope)
+        end
+
+        def description
+          "have content #{@text.inspect}"
+        end
+
+        def failure_message
+          "expected text to include #{@text.inspect}, got #{@actual.inspect}"
+        end
+
+        def failure_message_when_negated
+          "expected text NOT to include #{@text.inspect}, got #{@actual.inspect}"
+        end
+      end
+
+      # @api private
+      class HaveNoContent < HaveContent
+        def matches?(scope)
+          !super
+        end
+
+        def does_not_match?(scope)
+          !matches?(scope)
+        end
+
+        def failure_message
+          "expected text NOT to include #{@text.inspect}, got #{@actual.inspect}"
+        end
+
+        def failure_message_when_negated
+          "expected text to include #{@text.inspect}, got #{@actual.inspect}"
+        end
+      end
+
+      # @api private
+      class HaveLink < Base
+        def initialize(text, **opts)
+          super("a[href]", text: text, **opts.reject { |k, _| k == :href })
+          @href = opts[:href]
+        end
+
+        private
+
+        def find_matches(scope)
+          elements = super
+          return elements unless @href
+
+          elements.select do |a|
+            href = a.get_attribute("href").to_s
+            case @href
+            when Regexp
+              href.match?(@href)
+            else
+              href == @href.to_s
+            end
+          end
+        end
+
+        def describe_what
+          @href ? "link to #{@href.inspect}" : "link"
+        end
+      end
+
+      class HaveNoLink < HaveLink
+        include Negated
+      end
+
+      # @api private
+      class HaveButton < Base
+        def initialize(text, **opts)
+          # Buttons are <button> elements OR <input type="submit|button|reset">.
+          super("button, input[type='submit'], input[type='button'], input[type='reset']", text: text, **opts)
+          @type_filter = opts[:type]
+        end
+
+        private
+
+        def find_matches(scope)
+          elements = super
+          return elements unless @type_filter
+
+          elements.select { |el| el.get_attribute("type") == @type_filter.to_s }
+        end
+
+        # Override Base's text filter so <input type=submit> matches by
+        # its `value` attribute rather than text content.
+        def filter_by_text(elements)
+          elements.select do |el|
+            label = el.tag_name.downcase == "input" ? el.get_attribute("value").to_s : el.text_content.to_s
+            Internal::DomMatching.text_matches?(label, @text, exact: @exact)
+          end
+        end
+
+        def describe_what
+          "button"
+        end
+      end
+
+      class HaveNoButton < HaveButton
+        include Negated
+      end
+
+      # @api private
+      # have_field locates form fields by name attribute, id, or label text.
+      class HaveField < Base
+        def initialize(name_or_label, **opts)
+          super("input, textarea, select", text: nil, **opts.reject { |k, _| %i[with type].include?(k) })
+          @locator = name_or_label
+          @with_value = opts[:with]
+          @type_filter = opts[:type]
+        end
+
+        private
+
+        def find_matches(scope)
+          elements = scope.query_selector_all(query_selector).to_a
+          elements = elements.select { |el| matches_locator?(el, @locator) } if @locator
+          elements = elements.select { |el| el.get_attribute("type") == @type_filter.to_s } if @type_filter
+          elements = elements.select { |el| matches_value?(el, @with_value) } unless @with_value.nil?
+          Internal::DomMatching.filter_by_visibility(elements, @visible)
+        end
+
+        def matches_locator?(el, locator)
+          locator_str = locator.to_s
+          return true if el.get_attribute("name") == locator_str
+          return true if el.get_attribute("id") == locator_str
+          return true if matches_label?(el, locator_str)
+
+          false
+        end
+
+        # Find a <label> with matching text whose `for=` points to this element,
+        # or that wraps this element.
+        def matches_label?(el, label_text)
+          @scope.query_selector_all("label").any? do |label|
+            next false unless label.text_content.to_s.strip.include?(label_text)
+
+            for_attr = label.get_attribute("for")
+            next true if for_attr && el.get_attribute("id") == for_attr
+
+            label.contains?(el)
+          end
+        end
+
+        def matches_value?(el, expected_value)
+          actual = el.respond_to?(:value) ? el.value.to_s : el.get_attribute("value").to_s
+          actual == expected_value.to_s
+        end
+
+        def describe_what
+          @locator ? "field #{@locator.inspect}" : "field"
+        end
+      end
+
+      class HaveNoField < HaveField
+        include Negated
+      end
+    end
+  end
+end

data/lib/dommy/rspec/matchers.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+require_relative "../internal/dom_matching"
+require_relative "../internal/scope_resolution"
+
+module Dommy
+  module RSpec
+    # Custom RSpec matchers for asserting against Dommy DOM objects.
+    #
+    # @example RSpec config
+    #   require "dommy/rspec"
+    #   RSpec.configure do |c|
+    #     c.include Dommy::RSpec::Matchers
+    #   end
+    #
+    # @example Usage
+    #   expect(root).to contain_dom("button.primary")
+    #   expect(root).to contain_dom("li", count: 3)
+    #   expect(root).to contain_dom("h1", text: "Welcome")
+    #   expect(root).to contain_dom_text("Submit")
+    #   expect(button).to have_dom_attribute("type", "button")
+    #   expect(button).to have_dom_class("primary")
+    #   expect(root).to match_dom_html("<h1>Hello</h1>")
+    module Matchers
+      def contain_dom(selector, text: nil, count: nil)
+        ContainDom.new(selector, text: text, count: count)
+      end
+
+      def contain_dom_text(text)
+        ContainDomText.new(text)
+      end
+
+      def have_dom_attribute(name, value = UNSET)
+        HaveDomAttribute.new(name, value)
+      end
+
+      def have_dom_class(class_name)
+        HaveDomClass.new(class_name)
+      end
+
+      def match_dom_html(expected_html)
+        MatchDomHtml.new(expected_html)
+      end
+
+      # Sentinel for "value was not passed" — distinguishes
+      # `have_dom_attribute("disabled")` (existence only) from
+      # `have_dom_attribute("disabled", "true")` (value match).
+      UNSET = Object.new.freeze
+      private_constant :UNSET
+
+      # @api private
+      class ContainDom
+        def initialize(selector, text: nil, count: nil)
+          @selector = selector
+          @text = text
+          @count = count
+        end
+
+        def matches?(scope)
+          @scope = Internal::ScopeResolution.resolve(scope)
+          @matched = Internal::DomMatching.filter(@scope, @selector, text: @text)
+          Internal::DomMatching.count_matches?(@matched.size, @count)
+        end
+
+        def does_not_match?(scope)
+          !matches?(scope)
+        end
+
+        def description
+          parts = ["contain DOM matching #{@selector.inspect}"]
+          parts << "with text #{@text.inspect}" if @text
+          parts << "(count: #{@count.inspect})" if @count
+          parts.join(" ")
+        end
+
+        def failure_message
+          "expected #{describe_scope} to #{description} (found #{@matched.size})"
+        end
+
+        def failure_message_when_negated
+          "expected #{describe_scope} not to #{description} (found #{@matched.size})"
+        end
+
+        private
+
+        def describe_scope
+          @scope.respond_to?(:tag_name) ? "<#{@scope.tag_name.downcase}>" : @scope.class.name
+        end
+      end
+
+      # @api private
+      class ContainDomText
+        def initialize(text)
+          @text = text
+        end
+
+        def matches?(scope)
+          @scope = Internal::ScopeResolution.resolve(scope)
+          @actual_text = Internal::DomMatching.text_of(@scope)
+          Internal::DomMatching.text_matches?(@actual_text, @text)
+        end
+
+        def does_not_match?(scope)
+          !matches?(scope)
+        end
+
+        def description
+          "contain text #{@text.inspect}"
+        end
+
+        def failure_message
+          "expected text to include #{@text.inspect}, got #{@actual_text.inspect}"
+        end
+
+        def failure_message_when_negated
+          "expected text not to include #{@text.inspect}, got #{@actual_text.inspect}"
+        end
+      end
+
+      # @api private
+      class HaveDomAttribute
+        def initialize(name, value)
+          @name = name.to_s
+          @value = value
+        end
+
+        def matches?(element)
+          @element = element
+          return false unless element.has_attribute?(@name)
+
+          @actual = element.get_attribute(@name)
+          unset?(@value) ? true : @actual.to_s == @value.to_s
+        end
+
+        def does_not_match?(element)
+          !matches?(element)
+        end
+
+        def description
+          if unset?(@value)
+            "have DOM attribute #{@name.inspect}"
+          else
+            "have DOM attribute #{@name.inspect} = #{@value.inspect}"
+          end
+        end
+
+        def failure_message
+          if unset?(@value)
+            "expected element to have attribute #{@name.inspect}, but it was missing"
+          else
+            "expected attribute #{@name.inspect} to equal #{@value.inspect}, got #{@actual.inspect}"
+          end
+        end
+
+        def failure_message_when_negated
+          if unset?(@value)
+            "expected element NOT to have attribute #{@name.inspect}, but it was present (#{@actual.inspect})"
+          else
+            "expected attribute #{@name.inspect} not to equal #{@value.inspect}"
+          end
+        end
+
+        private
+
+        def unset?(value)
+          value.equal?(UNSET)
+        end
+      end
+
+      # @api private
+      class HaveDomClass
+        def initialize(class_name)
+          @class_name = class_name.to_s
+        end
+
+        def matches?(element)
+          @element = element
+          @actual_classes = element.class_list.value.to_s.split(/\s+/)
+          @actual_classes.include?(@class_name)
+        end
+
+        def does_not_match?(element)
+          !matches?(element)
+        end
+
+        def description
+          "have DOM class #{@class_name.inspect}"
+        end
+
+        def failure_message
+          "expected element to have class #{@class_name.inspect}, got #{@actual_classes.inspect}"
+        end
+
+        def failure_message_when_negated
+          "expected element NOT to have class #{@class_name.inspect}, got #{@actual_classes.inspect}"
+        end
+      end
+
+      # @api private
+      class MatchDomHtml
+        def initialize(expected_html)
+          @expected_html = expected_html
+        end
+
+        def matches?(scope)
+          @scope = Internal::ScopeResolution.resolve(scope)
+          @actual_normalized = Internal::DomMatching.normalize_html(Internal::DomMatching.html_of(@scope))
+          @expected_normalized = Internal::DomMatching.normalize_html(@expected_html)
+          @actual_normalized == @expected_normalized
+        end
+
+        def does_not_match?(scope)
+          !matches?(scope)
+        end
+
+        def description
+          "match DOM HTML #{@expected_html.inspect}"
+        end
+
+        def failure_message
+          "expected DOM HTML to match.\nExpected: #{@expected_normalized}\nActual:   #{@actual_normalized}"
+        end
+
+        def failure_message_when_negated
+          "expected DOM HTML NOT to match #{@expected_normalized}"
+        end
+      end
+    end
+  end
+end

data/lib/dommy/rspec.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# Entry point for using Dommy from RSpec test suites.
+# Loads the test helpers and DOM matcher modules so users can
+# `include` them into their RSpec config.
+#
+# @example
+#   require "dommy/rspec"
+#
+#   RSpec.configure do |c|
+#     c.include Dommy::TestHelpers
+#     c.include Dommy::RSpec::Matchers
+#   end
+
+require "dommy"
+require "dommy/test_helpers"
+require "dommy/rspec/matchers"
+require "dommy/rspec/capy_style_matchers"