rspec-tag_matchers 0.1.0

data/.document

@@ -0,0 +1,7 @@
+lib/**/*.rb
+bin/*
+-
+features/**/*.feature
+LICENSE.txt
+--protected
+--name-tag modifier:Modifiers

data/.rspec

@@ -0,0 +1 @@
+--color

data/.travis.yml

@@ -0,0 +1,8 @@
+bundler_args: "--without osx"
+rvm:
+  - 1.8.7
+  - 1.9.2
+  - 1.9.3
+  - ree
+  - rbx-2.0
+  - jruby

data/Gemfile

@@ -0,0 +1,21 @@
+source "http://rubygems.org"
+
+gem "nokogiri"
+
+group :development do
+  gem "rspec"
+  gem "yard"
+  gem "bundler"
+  gem "jeweler"
+  gem "guard"
+  gem "guard-rspec"
+  gem "guard-bundler"
+end
+
+group :osx do
+  # Needed for Guard to operate optimally on OSX
+  platforms :mri do
+    gem 'rb-fsevent'
+    gem 'growl_notify'
+  end
+end

data/Gemfile.lock

@@ -0,0 +1,49 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    diff-lcs (1.1.3)
+    git (1.2.5)
+    growl_notify (0.0.3)
+      rb-appscript
+    guard (0.8.8)
+      thor (~> 0.14.6)
+    guard-bundler (0.1.3)
+      bundler (>= 1.0.0)
+      guard (>= 0.2.2)
+    guard-rspec (0.5.2)
+      guard (>= 0.8.4)
+    jeweler (1.6.4)
+      bundler (~> 1.0)
+      git (>= 1.2.5)
+      rake
+    nokogiri (1.5.0)
+    nokogiri (1.5.0-java)
+    rake (0.9.2.2)
+    rb-appscript (0.6.1)
+    rb-fsevent (0.4.3.1)
+    rspec (2.7.0)
+      rspec-core (~> 2.7.0)
+      rspec-expectations (~> 2.7.0)
+      rspec-mocks (~> 2.7.0)
+    rspec-core (2.7.1)
+    rspec-expectations (2.7.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.7.0)
+    thor (0.14.6)
+    yard (0.7.3)
+
+PLATFORMS
+  java
+  ruby
+
+DEPENDENCIES
+  bundler
+  growl_notify
+  guard
+  guard-bundler
+  guard-rspec
+  jeweler
+  nokogiri
+  rb-fsevent
+  rspec
+  yard

data/Guardfile

@@ -0,0 +1,12 @@
+# vim: filetype=ruby
+
+guard 'bundler' do
+  watch('Gemfile')
+end
+
+guard 'rspec', :version => 2, :all_on_start => true, :all_after_pass => true do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})       { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch(%r{^core_ext/(.+)\.rb$})  { |m| "spec/core_ext/#{m[1]}_spec.rb" }
+  watch("spec/spec_helper.rb")    { "spec" }
+end

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2011 David Cuddeback
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,45 @@
+= rspec-tag_matchers
+
+<tt>rspec-tag_matchers</tt> is a collection of RSpec matchers for testing Rails views. The matchers
+can match against any string containing HTML or any object whose +to_s+ method returns a string
+containing HTML (this includes Nokogiri classes). They assume Rails conventions. For example, the
++has_form+ matcher looks for a hidden input named +_method+ when testing a form's method.
+
+== Example
+
+  describe "users/new.html.haml" do
+    before(:each) do
+      assign(:user, User.new)
+      render
+    end
+
+    it { should have_form.with_verb(:post).with_action(user_path) }
+    it { should have_checkbox.for(:user => :terms_of_service) }
+  end
+
+== Status
+
+<tt>rspec-tag_matchers</tt> is tested against Ruby 1.8.7, 1.9.2, 1.9.3, REE,
+Rubinius (1.8 mode) and JRuby.
+
+{<img src="http://travis-ci.org/dcuddeback/rspec-tag_matchers.png?branch=master" />}[http://travis-ci.org/dcuddeback/rspec-tag_matchers]
+
+The library is well tested, but the collection of matchers is incomplete. I'm adding more on an
+as-needed basis.  Please feel free to fork this repository to add your own then send me a pull
+request.
+
+== Contributing to rspec-tag_matchers
+
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
+* Fork the project
+* Start a feature/bugfix branch
+* Commit and push until you are happy with your contribution
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+== Copyright
+
+Copyright (c) 2011 David Cuddeback. See LICENSE.txt for
+further details.
+

data/Rakefile

@@ -0,0 +1,37 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name        = "rspec-tag_matchers"
+  gem.homepage    = "http://github.com/dcuddeback/rspec-tag_matchers"
+  gem.license     = "MIT"
+  gem.summary     = %Q{RSpec matchers for Rails views}
+  gem.description = %Q{A collection of RSpec matchers that understand Rails conventions, allowing for more concise specs.}
+  gem.email       = "david.cuddeback@gmail.com"
+  gem.authors     = ["David Cuddeback"]
+  # dependencies defined in Gemfile
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+task :default => :spec
+
+require 'yard'
+YARD::Rake::YardocTask.new

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/core_ext/deep_flattening.rb

@@ -0,0 +1,37 @@
+# Mixin for Array and Hash objects that allows deep flattening of nested, heterogeneous data
+# structures. Since it is only intended for internal use within this library, it is meant to extend
+# existing Array or Hash objects instead of being included in the Array or Hash classes. This avoids
+# inconsistencies between test and production environments by not affecting hashes or arrays in the
+# user's codebase.
+#
+# @example
+#   hash = {:foo => {:bar => [1, [2], :baz]}}
+#   hash.respond_to?(:deep_flatten)   # => false
+#   hash.extend(DeepFlattening)
+#   hash.respond_to?(:deep_flatten)   # => true
+#
+#   hash.deep_flatten   # => [:foo, :bar, 1, 2, :baz]
+#
+#   array = [1, [2, {:foo => {:bar => [3, 4]}}, 5]
+#   array.respond_to?(:deep_flatten)  # => false
+#   array.extend(DeepFlattening)
+#   array.respond_to?(:deep_flatten)  # => true
+#
+#   array.deep_flatten  # => [1, 2, :foo, :bar, 3, 4, 5]
+module DeepFlattening
+  # Flattens a nested, heterogeneous data structure to an array.
+  def deep_flatten
+    # Could be called on an array or a hash. Hashes in 1.9 have a flatten
+    # method, but hashes in 1.8 do not. Therefor, we must call Hash#to_a before
+    # we can flatten the hash in a compatible way.
+    to_a.flatten.map do |object|
+      case object
+      when Array, Hash
+        object.extend(DeepFlattening)
+        object.deep_flatten
+      else
+        object
+      end
+    end.flatten
+  end
+end

data/lib/rspec/tag_matchers/has_checkbox.rb

@@ -0,0 +1,60 @@
+module RSpec::TagMatchers
+  # Matches <tt><input type="checkbox"></tt> tags in HTML.
+  #
+  # @modifier checked
+  #   Specifies that the checkbox must be checked.
+  #
+  # @modifier not_checked
+  #   Specifies that the checkbox must *not* be checked.
+  #
+  # @example Matching a checked checkbox for +terms_of_service+
+  #   it { should have_checkbox.for(:terms_of_service).checked }
+  #
+  # @example Matching an unchecked checkbox for +terms_of_service+
+  #   it { should have_checkbox.for(:terms_of_service).not_checked }
+  #
+  # @return [HasCheckbox]
+  #
+  # @see HasCheckbox.checked
+  # @see HasCheckbox.not_checked
+  def have_checkbox
+    HasCheckbox.new
+  end
+
+  # A matcher that matches <tt><input type="checkbox"></tt> tags.
+  class HasCheckbox < HasInput
+
+    # Initializes a HasCheckbox matcher that matches elements named +input+ with a +type+ attribute
+    # of +checkbox+.
+    def initialize
+      super
+      with_attribute(:type => :checkbox)
+    end
+
+    # Specifies that the checkbox must be selected. A checkbox is considered to be checked if it has
+    # a +checked+ attribute.
+    #
+    # @example Checkboxes which are considered checked
+    #   <input type="checkbox" checked="checked" />
+    #   <input type="checkbox" checked="1" />
+    #   <input type="checkbox" checked />
+    #
+    # @return [HasCheckbox] self
+    def checked
+      with_attribute(:checked => true)
+      self
+    end
+
+    # Specifies that the checkbox must *not* be selected. A checkbox is not checked if it has no
+    # +checked+ attribute.
+    #
+    # @example An unchecked checkbox
+    #   <input type="checkbox" />
+    #
+    # @return [HasCheckbox] self
+    def not_checked
+      with_attribute(:checked => false)
+      self
+    end
+  end
+end

data/lib/rspec/tag_matchers/has_form.rb

@@ -0,0 +1,84 @@
+module RSpec::TagMatchers
+  # Matches +<form>+ tags in HTML.
+  #
+  # @modifier with_verb
+  #   Adds a criteria that the form must have the given HTTP verb.
+  #
+  # @modifier with_action
+  #   Adds a criteria that the form must target the given URL as its action.
+  #
+  # @example Matching a simple form
+  #   it { should have_form.with_verb(:post).with_action("/signup") }
+  #
+  # @example Matching a form with an overridden method
+  #   it { should have_form.with_verb(:put) }
+  #
+  # @return [HasForm]
+  #
+  # @see HasForm#with_verb
+  # @see HasForm#with_action
+  def have_form
+    HasForm.new
+  end
+
+  # A matcher that matches +<form>+ tags.
+  class HasForm < HasTag
+
+    # Initializes a HasForm matcher that matches +form+ elements.
+    def initialize
+      super(:form)
+    end
+
+    # Specifies that the form will use the given HTTP verb, following Rails conventions. It first
+    # looks for a method override value (a hidden input named +_method+). If the method override
+    # value doesn't exist, then it looks for the +method+ attribute on the +form+ tag. Whichever
+    # value it finds will be compared to the value passed in as the +verb+ argument to +with_verb+.
+    #
+    # @param [Symbol] verb  An HTTP verb, e.g., :get, :post, :put, or :delete.
+    #
+    # @return [HasForm] self
+    def with_verb(verb)
+      with_criteria do |element|
+        matches_verb?(element, verb)
+      end
+    end
+    alias :with_method :with_verb
+
+    # Specifies that the form must target the given URL as its action. It compares the +action+
+    # attribute on the +form+ tag to the +action+ argument passed to +with_action+.
+    #
+    # @param [String, Regexp] action  The URL that the form should target.
+    #
+    # @return [HasForm] self
+    def with_action(action)
+      with_attribute(:action => action)
+    end
+
+    private
+
+    # Tests whether +element+ will use the given HTTP +verb+.
+    #
+    # @param [Nokogiri::XML::Node]  element A +form+ element to be tested.
+    # @param [Symbol]               verb    An HTTP verb (:get, :post, :put, etc).
+    #
+    # @return [Boolean]
+    def matches_verb?(element, verb)
+      test_attribute(form_method(element), verb)
+    end
+
+    # Returns the attribute that specifies which HTTP verb the form will use. It considers a method
+    # override value as well as the +form+ tag's +method+ attribute.
+    #
+    # @param [Nokogiri::XML::Node]  element A +form+ element to be tested.
+    #
+    # @return [Nokogiri::XML::Attr] The attribute that specifies the HTTP verb.
+    def form_method(element)
+      method_override(element) || element.attribute("method")
+    end
+
+    def method_override(element)
+      override = element.css("input[type=hidden][name=_method]")
+      override && override.first && override.attribute("value")
+    end
+  end
+end

data/lib/rspec/tag_matchers/has_input.rb

@@ -0,0 +1,111 @@
+require 'deep_flattening'
+
+module RSpec::TagMatchers
+  # Matches +<input>+ tags in HTML.
+  #
+  # @modifier for
+  #   Adds a criteria that the input must be for the given attribute.
+  #
+  # @example Matching an input for the +name+ attribute on +user+
+  #   it { should have_input.for(:user => :name) }
+  #   it { should have_input.for(:user, :name) }
+  #
+  # @return [HasInput]
+  #
+  # @see HasInput#for
+  def have_input
+    HasInput.new
+  end
+
+  # A base class for form input matchers.
+  #
+  # == Subclassing
+  #
+  # HasInput is intended to be subclassed to create more expressive matchers for specific types of
+  # form inputs. The helper methods in HasInput, e.g., {#for}, are intended to be useful for all
+  # types of form inputs.
+  #
+  # By default, HasInput matches +<input>+ elements, but this can be overridden by subclasses, e.g.,
+  # HasSelect matches +<select>+ elements. This can be done in the matcher's constructor:
+  #
+  #   class HasSelect < HasInput
+  #     def initialize
+  #       super(:select)
+  #     end
+  #   end
+  #
+  # Some matchers might want to add more criteria inside their constructors. For example, matchers
+  # that match specific types of +<input>+ tags will want to add a criteria for matching the +type+
+  # attribute:
+  #
+  #   class HasCheckbox < HasInput
+  #     def initialize
+  #       super(:checkbox)
+  #       with_attribute(:type => :checkbox)
+  #     end
+  #   end
+  #
+  #
+  class HasInput < HasTag
+
+    # Initializes a HasInput matcher that matches elements named +name+.
+    #
+    # @param [Symbol] name  The type of HTML tag to match.
+    def initialize(name = :input)
+      super
+    end
+
+    # Adds a criteria that the input tag should be for a given attribute.
+    #
+    # HasInput provides the {#for} modifier to all of its subclasses, which is useful for matching
+    # the input's name with Rails conventions. For example, a Rails template that uses +form_for+
+    # might output HTML that looks like this:
+    #
+    #   <form method="POST" action="/users">
+    #     <input type="text" name="user[name]" />
+    #   </form>
+    #
+    # Instead of writing:
+    #
+    #   it { should have_input.with_attribute(:name => "user[name]") }
+    #
+    # the user can write a more concise spec using {#for}:
+    #
+    #   it { should have_input.for(:user => :name) }
+    #
+    # @example Match an input for the +name+ attribute of +user+
+    #   it { should have_input.for(:user => :name) }
+    #
+    # @example Match an input for a nested attribute
+    #   it { should have_input.for(:user => {:role => :admin}) }
+    #   it { should have_input.for(:user, :role => :admin) }
+    #
+    # @param [Array, Hash]  args  A hierarchy of strings that specifiy the attribute name.
+    #
+    # @return [HasInput] self
+    def for(*args)
+      with_attribute(:name => build_name(*args))
+      self
+    end
+
+    private
+
+    # Converts an array or hash of names to a name for an input form.
+    #
+    # @example
+    #   build_name(:foo => :bar)            # => "foo[bar]"
+    #   build_name(:foo, :bar)              # => "foo[bar]"
+    #   build_name(:foo => {:bar => :baz})  # => "foo[bar][baz]"
+    #   build_name(:foo, :bar => :baz)      # => "foo[bar][baz]"
+    #
+    # @param [Array, Hash]  args  A hierarchy of strings.
+    #
+    # @return [String] The expected name of the form input.
+    def build_name(*args)
+      args.extend(DeepFlattening)
+      args = args.deep_flatten
+      name = args.shift.to_s
+      name + args.map {|piece| "[#{piece}]"}.join
+    end
+  end
+end

data/lib/rspec/tag_matchers/has_select.rb

@@ -0,0 +1,20 @@
+module RSpec::TagMatchers
+  # Matches +<select>+ tags in HTML.
+  #
+  # @example Matching a select tag for a user's role
+  #   it { should have_select.for(:user => :role) }
+  #
+  # @return [HasSelect]
+  def have_select
+    HasSelect.new
+  end
+
+  # A matcher that matches +<select>+ tags.
+  class HasSelect < HasInput
+
+    # Initializes a HasSelect matcher that matches +select+ elements.
+    def initialize
+      super(:select)
+    end
+  end
+end