sunspot_matchers_testunit 1.0

data/.gitignore

@@ -0,0 +1,3 @@
+pkg/*
+*.gem
+.bundle

data/Gemfile

@@ -0,0 +1,4 @@
+source :gemcutter
+
+# Specify your gem's dependencies in sunspot_matchers_testunit.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,27 @@
+PATH
+  remote: .
+  specs:
+    sunspot_matchers_testunit (1.0)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    builder (3.0.0)
+    escape (0.0.4)
+    pr_geohash (1.0.0)
+    rake (0.8.7)
+    rsolr (0.12.1)
+      builder (>= 2.1.2)
+    sunspot (1.2.1)
+      escape (= 0.0.4)
+      pr_geohash (~> 1.0)
+      rsolr (= 0.12.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (>= 1.0.0)
+  rake
+  sunspot (~> 1.2.1)
+  sunspot_matchers_testunit!

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2011 Joseph Palermo, Pivotal Labs, Inc.
+
+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.markdown

@@ -0,0 +1,238 @@
+# Sunspot Matchers
+
+[Sunspot](http://outoftime.github.com/sunspot/) is a great Ruby library for constructing searches against Solr.  However,
+because of the way the Sunspot DSL is constructed, it can be difficult to do simple assertions about your searches
+without doing full integration tests.
+
+The goal of these matchers are to make it easier to unit test search logic without having to construct the individual
+fixture scenarios inside of Solr and then actually perform a search against Solr.
+
+This is a direct port of the excellent [Sunspot Matchers](http://github.com/pivotal/sunspot_matchers) library by Joseph
+Palermo, rewritten for use with Test::Unit.
+
+# Installation
+
+You will need to replace the Sunspot Session object with the spy provided.  You can do this globally by putting the
+following in a setup block or your test_helper.
+
+    def setup
+      Sunspot.session = SunspotMatchers::SunspotSessionSpy.new(Sunspot.session)
+    end
+
+Keep in mind, this will prevent any test from actually hitting Solr, so if you have integration tests, you'll either
+need to be more careful which tests you replace the session for, or you'll need to restore the original session before
+those tests
+
+    Sunspot.session = Sunspot.session.original_session
+
+You will also need to include the matchers in your tests.  Again, this can be done globally in your test_helper.
+
+    require 'sunspot_matchers_testunit'
+    include SunspotMatchersTestunit
+
+Alternately, you could include them into individual tests if needed.
+
+# Matchers
+
+## assert_is_search_for
+
+If you perform a search against your Post model, you could write this assertion:
+
+`assert_is_search_for Sunspot.session, Post`
+
+Individual searches are stored in an array, so if you perform multiple, you'll have to match against them manually.  Without
+an explicit search specified, it will use the last one.
+
+`assert_is_search_for Sunspot.session.searches.first, Post`
+
+## assert_has_search_params
+
+This is where the bulk of the functionality lies.  There are seven types of search matches you can perform: `keywords`,
+`with`, `without`, `paginate`, `order_by`, `facet`, and `boost`.
+
+In all of the examples below, the arguments fully match the search terms.  This is not expected or required.  You can
+have a dozen `with` restrictions on a search and still write an expectation on a single one of them.
+
+Negative expectations also work correctly.  `assert_has_no_search_params` will fail if the search actually includes the
+provided arguments.
+
+With all matchers, you can specify a `Proc` as the second argument, and perform multi statement expectations inside the
+Proc.  Keep in mind, that only the search type specified in the first argument will actually be checked.  So if you specify
+`keywords` and `with` restrictions in the same Proc, but you said `assert_has_search_params Sunspot.session, :keywords, ...`
+the `with` restrictions are simply ignored.
+
+### wildcard matching
+
+keywords, with, without, and order_by support wildcard expectations using the `any_param` parameter:
+
+    Sunspot.search(Post) do
+      with :blog_id, 4
+      order_by :blog_id, :desc
+    end
+
+    assert_has_search_params Sunspot.session, [ :with, :blog_id, any_param ]
+    assert_has_search_params Sunspot.session, [ :order_by, :blog_id, any_param ]
+    assert_has_search_params Sunspot.session, [ :order_by, any_param ]
+    assert_has_no_search_params Sunspot.session, [ :order_by, :category_ids, any_param ]
+
+### :keywords
+
+You can match against a keyword search:
+
+    Sunspot.search(Post) do
+      keywords 'great pizza'
+    end
+
+    assert_has_search_params Sunspot.session, [ :keywords, 'great pizza' ]
+
+### :with
+
+You can match against a with restriction:
+
+    Sunspot.search(Post) do
+      with :author_name, 'Mark Twain'
+    end
+
+    assert_has_search_params Sunspot.session, [ :with, :author_name, 'Mark Twain' ]
+
+Complex conditions can be matched by using a Proc instead of a value.  Be aware that order does matter, not for
+the actual results that would come out of Solr, but the matcher will fail of the order of `with` restrictions is
+different.
+
+    Sunspot.search(Post) do
+      any_of do
+        with :category_ids, 1
+        with :category_ids, 2
+      end
+    end
+
+    assert_has_search_params Sunspot.session, [ :with, Proc.new {
+      any_of do
+        with :category_ids, 1
+        with :category_ids, 2
+      end
+    } ]
+
+### :without
+
+Without is nearly identical to with:
+
+    Sunspot.search(Post) do
+      without :author_name, 'Mark Twain'
+    end
+
+    assert_has_search_params Sunspot.session, [ :without, :author_name, 'Mark Twain' ]
+
+### :paginate
+
+You can also specify only page or per_page, both are not required.
+
+    Sunspot.search(Post) do
+      paginate :page => 3, :per_page => 15
+    end
+
+    assert_has_search_params Sunspot.session, [ :paginate, :page => 3, :per_page => 15 ]
+
+### :order_by
+
+Expectations on multiple orderings are supported using using the Proc format mentioned above.
+
+    Sunspot.search(Post) do
+      order_by :published_at, :desc
+    end
+
+    assert_has_search_params Sunspot.session, [ :order_by, :published_at, :desc ]
+
+### :facet
+
+Standard faceting expectation:
+
+    Sunspot.search(Post) do
+      facet :category_ids
+    end
+
+    assert_has_search_params Sunspot.session, [ :facet, :category_ids ]
+
+Faceting where a query is excluded:
+
+    Sunspot.search(Post) do
+      category_filter = with(:category_ids, 2)
+      facet(:category_ids, :exclude => category_filter)
+    end
+
+    assert_has_search_params Sunspot.session, [ :facet, Proc.new {
+      category_filter = with(:category_ids, 2)
+      facet(:category_ids, :exclude => category_filter)
+    } ]
+
+Query faceting:
+
+    Sunspot.search(Post) do
+      facet(:average_rating) do
+        row(1.0..2.0) do
+          with(:average_rating, 1.0..2.0)
+        end
+        row(2.0..3.0) do
+          with(:average_rating, 2.0..3.0)
+        end
+      end
+    end
+    
+    assert_has_search_params Sunspot.session, [ :facet, Proc.new {
+      facet(:average_rating) do
+        row(1.0..2.0) do
+          with(:average_rating, 1.0..2.0)
+        end
+        row(2.0..3.0) do
+          with(:average_rating, 2.0..3.0)
+        end
+      end
+    } ]
+
+### :boost
+
+Field boost matching:
+
+    Sunspot.search(Post) do
+      keywords 'great pizza' do
+        boost_fields :body => 2.0
+      end
+    end
+
+    assert_has_search_params Sunspot.session, [ :boost, Proc.new {
+      keywords 'great pizza' do
+        boost_fields :body => 2.0
+      end
+    } ]
+
+Boost query matching:
+
+    Sunspot.search(Post) do
+      keywords 'great pizza' do
+        boost(2.0) do
+          with :blog_id, 4
+        end
+      end
+    end
+
+    assert_has_search_params Sunspot.session, [ :boost, Proc.new {
+      keywords 'great pizza' do
+        boost(2.0) do
+          with :blog_id, 4
+        end
+      end
+    } ]
+
+Boost function matching:
+
+    Sunspot.search(Post) do
+      keywords 'great pizza' do
+        boost(function { sum(:average_rating, product(:popularity, 10)) })
+      end
+    end
+
+    assert_has_search_params Sunspot.session, [ :boost, Proc.new {
+      keywords 'great pizza' do
+        boost(function { sum(:average_rating, product(:popularity, 10)) })
+      end
+    } ]

data/Rakefile

@@ -0,0 +1,11 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/*_test.rb'
+  test.verbose = true
+end
+
+task :default => :test

data/lib/sunspot_matchers_testunit.rb

@@ -0,0 +1,2 @@
+require 'sunspot_matchers_testunit/matchers'
+require 'sunspot_matchers_testunit/sunspot_session_spy'

data/lib/sunspot_matchers_testunit/matchers.rb

@@ -0,0 +1,317 @@
+require 'test/unit/assertions'
+
+module SunspotMatchersTestunit
+  class BaseMatcher
+    attr_accessor :args
+
+    def initialize(session, args)
+      @session = session
+      @args = args
+      build_comparison_search
+    end
+
+    def build_comparison_search
+      @comparison_search = if(@args.last.is_a?(Proc))
+        SunspotMatchersTestunit::SunspotSessionSpy.new(@session).build_search(search_types, &args.last)
+      else
+        SunspotMatchersTestunit::SunspotSessionSpy.new(@session).build_search(search_types) do
+          send(search_method, *args)
+        end
+      end
+    end
+
+    def search_tuple
+      search_tuple = @session.is_a?(Array) ? @session : @session.searches.last
+      raise 'no search found' unless search_tuple
+      search_tuple
+    end
+
+    def actual_search
+      search_tuple.last
+    end
+
+    def search_types
+      search_tuple.first
+    end
+
+    def wildcard?
+      @args && @args.last == any_param
+    end
+
+    def field
+      @args && @args.first
+    end
+
+    def query_params_for_search(search)
+      search.instance_variable_get(:@query).to_params
+    end
+
+    def actual_params
+      @actual_params ||= query_params_for_search(actual_search)
+    end
+
+    def comparison_params
+      @comparison_params ||= query_params_for_search(@comparison_search)
+    end
+
+    def match?
+      differences.empty?
+    end
+
+    def missing_param_error_message
+      missing_params = differences
+      actual_values = missing_params.keys.collect {|key| "#{key} => #{actual_params[key]}"}
+      missing_values = missing_params.collect{ |key, value| "#{key} => #{value}"}
+      "expected search params: #{actual_values.join(' and ')} to match expected: #{missing_values.join(' and ')}"
+    end
+
+    def unexpected_match_error_message
+      actual_values = keys_to_compare.collect {|key| "#{key} => #{actual_params[key]}"}
+      comparison_values = keys_to_compare.collect {|key| "#{key} => #{comparison_params[key]}"}
+      "expected search params: #{actual_values.join(' and ')} NOT to match expected: #{comparison_values.join(' and ')}"
+    end
+
+    def differences
+      keys_to_compare.inject({}) do |hsh, key|
+        result = compare_key(key)
+        hsh[key] = result unless result.empty?
+        hsh
+      end
+    end
+
+    def compare_key(key)
+      if(actual_params[key].is_a?(Array) || comparison_params[key].is_a?(Array))
+        compare_multi_value(actual_params[key], comparison_params[key])
+      else
+        compare_single_value(actual_params[key], comparison_matcher_for_key(key))
+      end
+    end
+
+    def comparison_matcher_for_key(key)
+      if wildcard? && wildcard_matcher_for_keys.has_key?(key)
+        wildcard_matcher_for_keys[key]
+      else
+        comparison_params[key]
+      end
+    end
+
+    def compare_single_value(actual, comparison)
+      if comparison.is_a?(Regexp)
+        return [] if comparison =~ actual
+        return [comparison.source]
+      end
+      return [comparison] unless actual == comparison
+      []
+    end
+
+    def compare_multi_value(actual, comparison)
+      filter_values(comparison).reject do |value|
+        next false unless actual
+        value_matcher = Regexp.new(Regexp.escape(value))
+        actual.any?{ |actual_value| actual_value =~ value_matcher }
+      end
+    end
+
+    def filter_values(values)
+      return values unless wildcard?
+      field_matcher = Regexp.new(field.to_s)
+      values.select{ |value| field_matcher =~ value }.collect{|value| value.gsub(/:.*/, '')}
+    end
+
+    def wildcard_matcher_for_keys
+      {}
+    end
+  end
+
+  class HaveSearchParams
+    include Test::Unit::Assertions
+
+    def initialize(session, method, *args)
+      @session = session
+      @method = method
+      @args = args
+    end
+
+    def get_matcher
+      matcher_class = case @method
+        when :with
+          WithMatcher
+        when :without
+          WithoutMatcher
+        when :keywords
+          KeywordsMatcher
+        when :boost
+          BoostMatcher
+        when :facet
+          FacetMatcher
+        when :order_by
+          OrderByMatcher
+        when :paginate
+          PaginationMatcher
+      end
+      matcher_class.new(@session, @args)
+    end
+  end
+
+  def assert_has_search_params(session, method_and_args)
+    method, *args = method_and_args
+    matcher = HaveSearchParams.new(session, method, *args).get_matcher
+    assert matcher.match?, matcher.missing_param_error_message
+  end
+
+  def assert_has_no_search_params(session, method_and_args)
+    method, *args = method_and_args
+    matcher = HaveSearchParams.new(session, method, *args).get_matcher
+    assert !matcher.match?, matcher.unexpected_match_error_message
+  end
+
+  class WithMatcher < BaseMatcher
+    def search_method
+      :with
+    end
+
+    def keys_to_compare
+      [:fq]
+    end
+  end
+
+  class WithoutMatcher < BaseMatcher
+    def search_method
+      :without
+    end
+
+    def keys_to_compare
+      [:fq]
+    end
+  end
+
+  class KeywordsMatcher < BaseMatcher
+    def search_method
+      :keywords
+    end
+
+    def keys_to_compare
+      [:q, :qf]
+    end
+
+    def wildcard_matcher_for_keys
+      {:q => /./, :qf => /./}
+    end
+  end
+
+  class BoostMatcher < BaseMatcher
+    def search_method
+      :boost
+    end
+
+
+    def keys_to_compare
+      [:qf, :bq, :bf]
+    end
+  end
+
+  class FacetMatcher < BaseMatcher
+    def search_method
+      :facet
+    end
+
+    def keys_to_compare
+      comparison_params.keys.select {|key| /facet/ =~ key.to_s}
+    end
+  end
+
+  class OrderByMatcher < BaseMatcher
+    def search_method
+      :order_by
+    end
+
+    def keys_to_compare
+      [:sort]
+    end
+
+    def wildcard_matcher_for_keys
+      return {:sort => /./} if field_wildcard?
+      param = comparison_params[:sort]
+      regex = Regexp.new(param.gsub(any_param, '.*'))
+      {:sort => regex}
+    end
+
+    def field_wildcard?
+      @args.first == any_param
+    end
+
+    def direction_wildcard?
+      @args.length == 2 && @args.last == any_param
+    end
+
+    def args
+      return @args unless direction_wildcard?
+      @args[0...-1] + [:asc]
+    end
+
+    def build_comparison_search
+      if field_wildcard?
+        @comparison_params = {:sort => any_param}
+      elsif direction_wildcard?
+        super
+        @comparison_params = comparison_params
+        @comparison_params[:sort].gsub!("asc", any_param)
+      else
+        super
+      end
+    end
+  end
+
+  class PaginationMatcher < BaseMatcher
+    def search_method
+      :paginate
+    end
+
+    def keys_to_compare
+      [:rows, :start]
+    end
+  end
+
+  class BeASearchFor
+    def initialize(session, expected_class)
+      @session = session
+      @expected_class = expected_class
+    end
+
+    def match?
+      search_types.include?(@expected_class)
+    end
+
+    def search_tuple
+      search_tuple = @session.is_a?(Array) ? @session : @session.searches.last
+      raise 'no search found' unless search_tuple
+      search_tuple
+    end
+
+    def search_types
+      search_tuple.first
+    end
+
+    def failure_message_for_should
+      "expected search class: #{search_types.join(' and ')} to match expected class: #{@expected_class}"
+    end
+
+    def failure_message_for_should_not
+      "expected search class: #{search_types.join(' and ')} NOT to match expected class: #{@expected_class}"
+    end
+  end
+
+  def assert_is_search_for(session, expected_class)
+    matcher = BeASearchFor.new(session, expected_class)
+    assert matcher.match?, matcher.failure_message_for_should
+  end
+
+  def assert_is_not_search_for(session, expected_class)
+    matcher = BeASearchFor.new(session, expected_class)
+    assert !matcher.match?, matcher.failure_message_for_should_not
+  end
+end
+
+def any_param
+  "ANY_PARAM"
+end