rspec-tag_matchers 0.1.0

data/lib/rspec/tag_matchers/has_tag.rb

@@ -0,0 +1,221 @@
+require 'nokogiri'
+
+module RSpec::TagMatchers
+  # Matches HTML tags by name.
+  #
+  # @modifier with_attribute
+  #   Adds a criteria that an element must match the given attributes.
+  #
+  # @modifier with_criteria
+  #   Adds an arbitrary criteria.
+  #
+  # @example Matching anchor tags
+  #   it { should have_tag(:a) }
+  #
+  # @example Matching anchor tags that link to "/"
+  #   it { should have_tag(:a).with_attribute(:href => "/") }
+  #
+  # @example Matching anchor tags with an even +id+ attribute
+  #   it { should have_tag(:a).with_criteria { |elem| elem[:id].to_i.even? } }
+  #
+  # @return [HasTag]
+  #
+  # @see HasTag#with_attribute
+  # @see HasTag#with_criteria
+  def have_tag(name)
+    HasTag.new(name)
+  end
+
+  # The base class for all tag matchers. HasTag is intended to provide facilities that are useful to
+  # subclasses. The subclasses of HasTag should define more expressive tag matchers. For example, to
+  # match a checkbox using HasTag directly, one would have to type:
+  #
+  #   it { has_tag(:input).with_attribute(:type => :checkbox) }
+  #
+  # That can all be encapsulated into a subclass that provides a more expressive matcher:
+  #
+  #   it { has_checkbox }
+  #
+  # == Element Matching
+  #
+  # The way tag matchers work is by counting how many elements match a set of filters. It starts by
+  # finding element that match the given tag name, e.g., +a+, +div+, or +input+, and then filters
+  # the list of matching elements according to a list of criteria. In the end, the matcher is left
+  # with a set of elements that match *all* criteria. The matcher is said to match the input string
+  # if the set of elements that match all its criteria contains at least one element. The matched
+  # elements need not be the top-level element.
+  #
+  # === Example
+  #
+  # In this example, the matcher looks for +div+ elements with and +id+ of "foo" and a class of
+  # "bar". An element must match all three of those criteria in order for the matcher to consider it
+  # a successful match:
+  #
+  #   matcher = HasTag.new(:div).with_attribute(:id => :foo, :class => :bar)
+  #   matcher.matches?('<div id="foo" class="bar"></div>')  # => true
+  #   matcher.matches?('<div id="foo"></div>')              # => false
+  #
+  # However, the all criteria must be matched by <strong>the same</strong> element. If one element
+  # matches half of the criteria and another element matches the other half of the criteria, it is
+  # not considered a successful match:
+  #
+  #   matcher = HasTag.new(:div).with_attribute(:id => :foo, :class => :bar)
+  #   matcher.matches?('<div id="foo"></div><div class="bar"></div>')   # => false
+  #
+  # == Subclassing HasTag
+  #
+  # In the most basic case, a subclass of HasTag will simply override the constructor to provide a
+  # default tag name that must be matched. For example, a matcher to match +object+ tags might look
+  # like this:
+  #
+  #   class HasObject < HasTag
+  #     def initialize
+  #       super(:object)
+  #     end
+  #   end
+  #
+  # Also, one should provide a helper method to construct the matcher inside of a spec. For the
+  # above example, the helper method would look like this:
+  #
+  #   def have_object
+  #     HasObject.new
+  #   end
+  #
+  # This allows the user to construct a HasObject matcher by calling +have_object+ in his spec,
+  # which provides for a more readable spec:
+  #
+  #   it { should have_object }
+  #
+  # In some cases it might make sense to add additional criteria from within the constructor or to
+  # provide additional methods that can be chained from the matcher to provide tag-specific
+  # criteria. See {HasTag#with_criteria} for how to add custom criteria to a matcher.
+  class HasTag
+
+    # Constructs a matcher that matches HTML tags by +name+.
+    #
+    # @param [String, Symbol] name  The type of tag to match.
+    def initialize(name)
+      @name       = name.to_s
+      @attributes = {}
+      @criteria   = []
+    end
+
+    # Answers whether or not the matcher matches any elements within +rendered+.
+    #
+    # @param [String] rendered    A string of HTML or an Object whose +to_s+ method returns HTML.
+    #                             (That includes Nokogiri classes.)
+    #
+    # @return [Boolean]
+    def matches?(rendered)
+      Nokogiri::HTML::Document.parse(rendered.to_s).css(@name).select do |element|
+        matches_attributes?(element) && matches_criteria?(element)
+      end.length > 0
+    end
+
+    # Adds a constraint that the matched elements must match certain attributes.  The +attributes+
+    # hash contains a set of key/value pairs. Each key is used for the attribute name (not case
+    # sensitive) and the value is used to determine if an attribute matches according to the rules
+    # in the following table:
+    #
+    # [Attribute Matching Values]
+    #   String::  The attribute's value must match exactly.
+    #   Symbol::  The attribute's value must match, but it is not case sensitive.
+    #   Regexp::  The attribute's value must match the regular expression.
+    #   true::    The attribute must exist. The attribute's value does not matter.
+    #   false::   The attribute must *not* exist.
+    #
+    # @param [Hash]  attributes  A hash of attribute key/value pairs. The keys are the attribute
+    #                             names.
+    #
+    # @return [self]
+    def with_attribute(attributes)
+      @attributes.merge!(attributes)
+      self
+    end
+    alias :with_attributes :with_attribute
+
+    # Adds an arbitrary criteria to the matched elements. The criteria can be a method name or a
+    # block. The method or block should accept a single Nokogiri::XML::Node object as its argument
+    # and return whether or not the element passed as an argument matches the criteria.
+    #
+    # @example
+    #   have_div.with_criteria { |element| element[:id].to_i % 2 == 0 }
+    #
+    # @param  [Symbol]  method  The name of the method to be called.
+    # @param  [Proc]    block   A block to be calle => d.
+    #
+    # @return [self]
+    def with_criteria(method = nil, &block)
+      @criteria << method   unless method.nil?
+      @criteria << block    if block_given?
+      self
+    end
+
+    protected
+
+    # Tests with +attribute+ matches +expected+ according the the attribute matching rules described
+    # in {#with_attribute}. This can be useful for testing attributes in subclasses.
+    #
+    # @note
+    #   The reason this method receives a +Nokogiri::XML::Attr+ object instead of the attribute's
+    #   value is that some attributes have meaning merely by existing, even if they don't have a
+    #   value. For example, the +checked+ attribute of a checkbox or radio button does not need to
+    #   have a value. If it doesn't have a value, +element[:checked]+ will return +nil+ in the JRuby
+    #   implementation of Nokogiri, which would make <tt>with_attribute(:checked => true)</tt> fail
+    #   in JRuby.
+    #
+    # @param [Nokogiri::XML::Attr]              attribute   The attribute to be tested.
+    # @param [String, Symbol, Regexp, Boolean]  expected    The expected value of +attribute+.
+    #
+    # @return [Boolean]
+    #
+    # @see #with_attribute
+    def test_attribute(attribute, expected)
+      actual = attribute && attribute.value
+
+      case expected
+      when String
+        actual == expected
+      when Symbol
+        actual =~ /^#{expected}$/i
+      when Regexp
+        actual =~ expected
+      when true
+        !attribute.nil?
+      when false
+        attribute.nil?
+      end
+    end
+
+    private
+
+
+    # Answers whether or not +element+ matches the attributes in the attributes hash given to
+    # {#with_attribute}.
+    #
+    # @param [Nokogiri::XML::Node]  element   The element to be tested.
+    #
+    # @return [Boolean]
+    def matches_attributes?(element) # :api: public
+      @attributes.all? do |key, value|
+        test_attribute(element.attribute(key.to_s), value)
+      end
+    end
+
+    # Answers whether or not +element+ matches the custom criteria set by {#with_criteria}.
+    #
+    # @param [Nokogiri::XML::Node]  element   The element to be tested.
+    #
+    # @return [Boolean]
+    def matches_criteria?(element)
+      @criteria.all? do |method|
+        case method
+        when Symbol
+          send(method, element)
+        when Proc
+          method.call(element)
+        end
+      end
+    end
+  end
+end

data/lib/rspec/tag_matchers/has_time_select.rb

@@ -0,0 +1,22 @@
+require 'rspec/tag_matchers/multiple_input_matcher'
+
+module RSpec::TagMatchers
+  # Matches inputs generated by Rails' +time_select+ helper.
+  #
+  # @example Matching a time select for an event's +start_time+
+  #   it { should have_time_select.for(:event => :start_time) }
+  #
+  # @return [HasTimeSelect]
+  def have_time_select
+    HasTimeSelect.new
+  end
+
+  # A matcher that matches Rails' +time_select+ drop-downs.
+  class HasTimeSelect < MultipleInputMatcher
+
+    # Initializes a HasTimeSelect matcher.
+    def initialize
+      super(4 => HasSelect.new, 5 => HasSelect.new)
+    end
+  end
+end

data/lib/rspec/tag_matchers/multiple_input_matcher.rb

@@ -0,0 +1,114 @@
+module RSpec::TagMatchers
+  # A matcher that matches multiple input elements. It is intended to serve as a base class for
+  # building more specific matchers that must match multiple input elements. For example, a matcher
+  # to test for Rails' +time_select+ drop-downs must test that the HTML contains a drop-down for
+  # hours and another drop-down for minutes.
+  #
+  # @example Building a date matcher
+  #   matcher = MultipleInputMatcher.new(
+  #       1 => HasSelect.new,
+  #       2 => HasSelect.new,
+  #       3 => HasSelect.new
+  #     )
+  #   matcher.for(:user => :birthday) # will match <select> tags with names
+  #                                   # "user[birthday(1i)]", "user[birthday(2i)]", and
+  #                                   # "user[birthday(3i)]"
+  #
+  # @example Building a time matcher
+  #   MultipleInputMatcher.new(       # by default, will match <select> tags with names by regular
+  #       4 => HasSelect.new,         # expressions: /\(4i\)/ and /\(5i\)/
+  #       5 => HasSelect.new
+  #     )
+  #
+  #
+  class MultipleInputMatcher
+
+    # Initializes a matcher that matches multiple input elements.
+    #
+    # @param [Hash] components  A hash of matchers. The keys serve as indices and the values are the
+    #                           matchers that must be satisfied.
+    def initialize(components)
+      @components = components
+      @components.each do |index, matcher|
+        matcher.with_attribute(:name => /\(#{index}i\)/)
+      end
+    end
+
+    # Tests whether the matcher matches the +rendered+ string. It delegates matching to its
+    # matchers. It returns true if all of its matchers return true. It returns false if *any* of its
+    # matchers return false.
+    #
+    # @param [String] rendered  A string of HTML or an Object whose +to_s+ method returns HTML.
+    #                           (That includes Nokogiri classes.)
+    #
+    # @return [Boolean]
+    def matches?(rendered)
+      @failures = matchers.reject do |matcher|
+        matcher.matches?(rendered)
+      end
+
+      @failures.empty?
+    end
+
+    # Specifies the inputs names with more accuracy than the default regular expressions. It
+    # delegates to each matcher's +for+ method. But it first appends the matcher's index to the last
+    # component of the input's name.
+    #
+    # @example Input naming delegation
+    #   hour_matcher   = HasSelect.new
+    #   minute_matcher = HasSelect.new
+    #   time_matcher   = MultipleInputMatcher.new(4 => hour_matcher, 5 => minute_matcher)
+    #
+    #   time_matcher.for(:event => :start_time) # calls hour_matcher.for("event", "start_time(4i)")
+    #                                           # and minute_matcher.for("event", "start_time(5i)")
+    #
+    # @param [Array, Hash]  args  A hierarchy of string that specify the attribute name.
+    #
+    # @return [MultipleInputMatcher] self
+    def for(*args)
+      @components.each do |index, matcher|
+        delegated_for(index, matcher, args)
+      end
+      self
+    end
+
+    # Returns the failure messages from each failed matcher.
+    #
+    # @return [String] Failure message
+    def failure_message
+      @failures.map(&:failure_message).join(" and ")
+    end
+
+    # Returns the negative failure messages from every matcher.
+    #
+    # @return [String] Negative failure message
+    def negative_failure_message
+      matchers.map(&:negative_failure_message).join(" and ")
+    end
+
+    private
+
+    # Returns all the matchers.
+    #
+    # @return [Array] Matchers
+    def matchers
+      @components.values
+    end
+
+    # Set's +matcher+'s input name according to +args+ and +index+.
+    #
+    # @param [Integer]      index   The matcher's index.
+    # @param [HasInput]     matcher The matcher.
+    # @param [Arrah, Hash]  args    A hierarchy of names that would normally be passed to
+    #                               {HasInput#for}.
+    def delegated_for(index, matcher, args)
+      args = args.dup
+      args.extend(DeepFlattening)
+      args = args.deep_flatten
+
+      args[-1]  = args[-1].to_s
+      args[-1] += "(#{index}i)"
+      matcher.for(*args)
+    end
+  end
+end

data/lib/rspec/tag_matchers.rb

@@ -0,0 +1,13 @@
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', '..', 'core_ext'))
+
+module RSpec
+  module TagMatchers
+  end
+end
+
+require 'rspec/tag_matchers/has_tag'
+require 'rspec/tag_matchers/has_form'
+require 'rspec/tag_matchers/has_input'
+require 'rspec/tag_matchers/has_checkbox'
+require 'rspec/tag_matchers/has_select'
+require 'rspec/tag_matchers/has_time_select'

data/lib/rspec-tag_matchers.rb

@@ -0,0 +1 @@
+require 'rspec/tag_matchers'

data/spec/core_ext/deep_flattening_spec.rb

@@ -0,0 +1,133 @@
+require 'spec_helper'
+
+RSpec::Matchers.define :flatten_to do |expected|
+  match do |subject|
+    actual = subject.deep_flatten
+
+    if actual == expected
+      if !expected.respond_to?(:deep_flatten)
+        true
+      else
+        @failure_message = "expected #{actual.inspect} to not respond to #deep_flatten"
+        false
+      end
+    else
+      @failure_message = "expected #{subject.inspect} to flatten to #{expected.inspect}, but flattened to #{actual.inspect}"
+      false
+    end
+  end
+
+  failure_message do
+    @failure_message
+  end
+end
+
+describe DeepFlattening do
+  def extended(object)
+    object.extend(DeepFlattening)
+    object
+  end
+
+  describe Array do
+    context "when not extended" do
+      subject { Array.new }
+      it      { should_not respond_to(:deep_flatten) }
+    end
+
+    context "when extended" do
+      subject { extended([]) }
+      it      { should respond_to(:deep_flatten) }
+
+      context "[]" do
+        subject { extended([]) }
+        it      { should flatten_to([]) }
+      end
+
+      context "[1,2,3]" do
+        subject { extended([1,2,3]) }
+        it      { should flatten_to([1,2,3]) }
+      end
+
+      context "[[1,2,3]]" do
+        subject { extended([[1,2,3]]) }
+        it      { should flatten_to([1,2,3]) }
+      end
+
+      context "[[1], [2], [3]]" do
+        subject { extended([[1], [2], [3]]) }
+        it      { should flatten_to([1,2,3]) }
+      end
+
+      context "[1, [2, [3, [4]]]]" do
+        subject { extended([1, [2, [3, [4]]]]) }
+        it      { should flatten_to([1,2,3,4]) }
+      end
+    end
+  end
+
+  describe Hash do
+    context "when not extended" do
+      subject { Hash.new }
+      it      { should_not respond_to(:deep_flatten) }
+    end
+
+    context "when extended" do
+      subject { extended(Hash.new) }
+      it      { should respond_to(:deep_flatten) }
+
+      context "{}" do
+        subject { extended({}) }
+        it      { should flatten_to([]) }
+      end
+
+      context "{:foo => :bar}" do
+        subject { extended({:foo => :bar}) }
+        it      { should flatten_to([:foo, :bar]) }
+      end
+
+      context "{:foo => {:bar => :baz}}" do
+        subject { extended({:foo => {:bar => :baz}}) }
+        it      { should flatten_to([:foo, :bar, :baz]) }
+      end
+
+      context "{:foo => {bar => {:baz => :qux}}}" do
+        subject { extended({:foo => {:bar => {:baz => :qux}}}) }
+        it      { should flatten_to([:foo, :bar, :baz, :qux]) }
+      end
+    end
+  end
+
+  describe "Mixed data structure" do
+    context "when extended" do
+      context "[1, {:foo => :bar}]" do
+        subject { extended([1, {:foo => :bar}]) }
+        it      { should flatten_to([1, :foo, :bar]) }
+      end
+
+      context "{:foo => [1,2]}" do
+        subject { extended({:foo => [1,2]}) }
+        it      { should flatten_to([:foo, 1, 2]) }
+      end
+
+      context "[1, {:foo => [2,3]}]" do
+        subject { extended([1, {:foo => [2,3]}]) }
+        it      { should flatten_to([1, :foo, 2, 3]) }
+      end
+
+      context "{:foo => {:bar => [1,2]}}" do
+        subject { extended({:foo => {:bar => [1,2]}}) }
+        it      { should flatten_to([:foo, :bar, 1, 2]) }
+      end
+
+      context "[1, {:foo => [2, {:bar => {:baz => [3,4]}}, 5]}]" do
+        subject { extended([1, {:foo => [2, {:bar => {:baz => [3,4]}}, 5]}]) }
+        it      { should flatten_to([1, :foo, 2, :bar, :baz, 3, 4, 5]) }
+      end
+
+      context "{:foo => {:bar => [1, {:baz => :qux}, 2]}}" do
+        subject { extended({:foo => {:bar => [1, {:baz => :qux}, 2]}}) }
+        it      { should flatten_to([:foo, :bar, 1, :baz, :qux, 2]) }
+      end
+    end
+  end
+end

data/spec/lib/rspec/tag_matchers/has_checkbox_spec.rb

@@ -0,0 +1,45 @@
+require 'spec_helper'
+
+describe RSpec::TagMatchers::HasCheckbox do
+  include RSpec::TagMatchers
+
+  describe "matching checkbox tags" do
+    context "have_checkbox" do
+      subject { have_checkbox }
+      it { should_not match("<input />") }
+      it { should     match("<input type='checkbox' />") }
+      it { should     match("<input TYPE='CHECKBOX' />") }
+      it { should_not match("<input type='text' />") }
+      it { should_not match("<input type='checkboxer' />") }
+      it { should_not match("input checkbox") }
+    end
+  end
+
+  describe "matching checkbox state" do
+    context "have_checkbox.checked" do
+      subject { have_checkbox.checked }
+      it      { should_not match("<input type='checkbox' />") }
+      it      { should     match("<input type='checkbox' checked />") }
+      it      { should     match("<input type='checkbox' checked='checked' />") }
+      it      { should     match("<input type='checkbox' checked='1' />") }
+    end
+
+    context "have_checkbox.not_checked" do
+      subject { have_checkbox.not_checked }
+      it      { should     match("<input type='checkbox' />") }
+      it      { should_not match("<input type='checkbox' checked />") }
+      it      { should_not match("<input type='checkbox' checked='checked' />") }
+      it      { should_not match("<input type='checkbox' checked='1' />") }
+    end
+  end
+
+  describe "matching input names" do
+    context "have_checkbox.for(:user => :admin)" do
+      subject { have_checkbox.for(:user => :admin) }
+      it      { should_not match("<input type='checkbox' />") }
+      it      { should_not match("<input type='checkbox' name='user' />") }
+      it      { should     match("<input type='checkbox' name='user[admin]' />") }
+      it      { should_not match("<input type='checkbox' name='user[admin][root]' />") }
+    end
+  end
+end

data/spec/lib/rspec/tag_matchers/has_form_spec.rb

@@ -0,0 +1,56 @@
+require 'spec_helper'
+
+describe RSpec::TagMatchers::HasForm do
+  include RSpec::TagMatchers
+
+  describe "matching form tags" do
+    context "have_form" do
+      subject { have_form }
+      it      { should     match("<form></form>") }
+      it      { should     match("<form method='POST'></form>") }
+      it      { should     match("<FORM></FORM>") }
+      it      { should_not match("<foo></foo>") }
+      it      { should_not match("<former></former>") }
+      it      { should_not match("form") }
+    end
+  end
+
+  describe "matching form methods" do
+    context "have_form.with_verb(:get)" do
+      subject { have_form.with_verb(:get) }
+      it      { should_not match("<form></form>") }
+      it      { should     match("<form method='GET'></form>") }
+      it      { should     match("<form method='get'></form>") }
+      it      { should_not match("<form method='POST'></form>") }
+    end
+
+    context "have_form.with_verb(:post)" do
+      subject { have_form.with_verb(:post) }
+      it      { should_not match("<form></form>") }
+      it      { should_not match("<form method='GET'></form>") }
+      it      { should     match("<form method='POST'></form>") }
+      it      { should     match("<form method='post'></form>") }
+      it      { should_not match("<form method='post'><input type='hidden' name='_method' value='put' /></form>") }
+      it      { should_not match("<form method='post'><input type='hidden' name='_method' value='PUT' /></form>") }
+    end
+
+    context "have_form.with_verb(:put)" do
+      subject { have_form.with_verb(:put) }
+      it      { should_not match("<form></form>") }
+      it      { should_not match("<form method='POST'></form>") }
+      it      { should_not match("<form method='post'></form>") }
+      it      { should     match("<form method='post'><input type='hidden' name='_method' value='put' /></form>") }
+      it      { should     match("<form method='post'><input type='hidden' name='_method' value='PUT' /></form>") }
+    end
+  end
+
+  describe "matching form actions" do
+    context "have_form.with_action('/foobar')" do
+      subject { have_form.with_action("/foobar") }
+      it      { should_not match("<form></form>") }
+      it      { should     match("<form action='/foobar'></form>") }
+      it      { should_not match("<form action='/foobarz'></form>") }
+      it      { should_not match("<form action='/baz'></form>") }
+    end
+  end
+end

data/spec/lib/rspec/tag_matchers/has_input_spec.rb

@@ -0,0 +1,53 @@
+require 'spec_helper'
+
+describe RSpec::TagMatchers::HasInput do
+  include RSpec::TagMatchers
+
+  describe "matching input tags" do
+    context "have_input" do
+      subject { have_input }
+      it      { should     match("<input />") }
+      it      { should     match("<input type='text' />") }
+      it      { should     match("<INPUT />") }
+      it      { should_not match("<inputer />") }
+      it      { should_not match("input") }
+    end
+  end
+
+  describe "matching input names" do
+    context "have_input.for(:user => :name)" do
+      subject { have_input.for(:user => :name) }
+      it      { should_not match("<input />") }
+      it      { should     match("<input name='user[name]' />") }
+      it      { should_not match("<input name='user[name][first]' />") }
+    end
+
+    context "have_input.for(:user, :name)" do
+      subject { have_input.for(:user, :name) }
+      it      { should_not match("<input />") }
+      it      { should     match("<input name='user[name]' />") }
+      it      { should_not match("<input name='user[name][first]' />") }
+    end
+
+    context "have_input.for(:user => {:name => :first})" do
+      subject { have_input.for(:user => {:name => :first}) }
+      it      { should_not match("<input />") }
+      it      { should_not match("<input name='user[name]' />") }
+      it      { should     match("<input name='user[name][first]' />") }
+    end
+
+    context "have_input.for(:user, :name => :first)" do
+      subject { have_input.for(:user, :name => :first) }
+      it      { should_not match("<input />") }
+      it      { should_not match("<input name='user[name]' />") }
+      it      { should     match("<input name='user[name][first]' />") }
+    end
+
+    context "have_input.for(:user, :name, :first)" do
+      subject { have_input.for(:user, :name, :first) }
+      it      { should_not match("<input />") }
+      it      { should_not match("<input name='user[name]' />") }
+      it      { should     match("<input name='user[name][first]' />") }
+    end
+  end
+end