rspec-solr 0.1.0 → 0.1.2

data/.yardopts

@@ -0,0 +1,3 @@
+--title 'RSpecSolr Documentation'
+lib/**/*.rb -
+README.rdoc MATCHERS.rdoc LICENSE.txt 

data/{expectation_matchers.rdoc → MATCHERS.rdoc}

@@ -44,25 +44,26 @@
        To change the id field name, use my_solr_response_hash.id_field='my_id_fldname'
 ===== Hash
 * ("fldname" => "value")
-* ("fld1" => "val1", "fld2" => "val2")
- NOTE: single Solr document must have all key value pairs
-* ("fldname" => ["val1", "val2", "val3"])
+* ("fldname" => /regex_to_match_val/)
+* ("fld1" => "val1", "fld2" => /val2_regex/)
+ NOTE: single Solr document must satisfy all key value pairs
+* ("fldname" => ["val1", /val2_regex/, "val3"])
  NOTE: all of the Array values must be present for the fld in a single Solr document
        should_not for Array implies NONE of the values should be present in a single document
 TODO:
-* document("fldname" => "/regex/")
 * include_title("val") (i.e. include_anyFieldName("val") )
 
 ==== Specifying Multiple Documents
 ===== Array
 * by id strings: (["id1", "id2", "id3"])
-* by hashes: ([{"title" => "green is best"}, {"title" => "blue is best"}, {"fld" => "val"}])
+* by hashes: ([{"title" => "green is best"}, {"title" => /blue/}, {"fld" => "val"}])
  NOTE: you cannot do this:  ([{"title" => ["Solr doc 1 title", "Solr doc 2 title"]} ]) to specify multiple documents
 * by mix of id strings and hashes: ([{"title" => "green is best"}, "id3", {"author" => "steinbeck"}])
 
 ==== Full Examples
 * rspec-solr_resp_hash.should include("fld1" => "val1")
-* rspec-solr_resp_hash.should include("f1" => "v1", "f2" => ["val1", "val2", "val3"])
+* rspec-solr_resp_hash.should include("fld1" => /regex_for_val/)
+* rspec-solr_resp_hash.should include("f1" => "v1", "f2" => ["val1", "val2", /regex_for_val/])
 * rspec-solr_resp_hash.should include("idval")
 * rspec-solr_resp_hash.should include(["id1", "id2", "id3"])
 * rspec-solr_resp_hash.should include([{"title" => "title1"}, {"title" => "title2"}])
@@ -85,6 +86,7 @@ TODO:
 
 TODO:
 * include_at_least(3).of_these_documents().in_first(3).results
+* start_with()
 
 === Usage
 See above for information on how to specify specific documents

data/README.rdoc

@@ -2,7 +2,7 @@
 
 {<img src="https://secure.travis-ci.org/sul-dlss/rspec-solr.png?branch=master" alt="Build Status" />}[http://travis-ci.org/sul-dlss/rspec-solr]
 
-Provides RSpec custom matchers to be used with Solr response objects.
+A Gem to provide RSpec custom matchers to be used with Solr response objects.
 
 == Installation
 
@@ -20,11 +20,122 @@ Or install it yourself as:
 
 == Usage
 
-See expecation_matchers.rdoc 
+See MATCHERS.rdoc for syntax of supported expectations.
+
+=== Examples:
+
+ it "q of 'Buddhism' should get 8,500-10,500 results" do
+   resp = solr_resp_doc_ids_only({'q'=>'Buddhism'})
+   resp.should have_at_least(8500).documents
+   resp.should have_at_most(10500).documents
+ end
+ 
+  it "q of 'Two3' should have excellent results", :jira => 'VUF-386' do
+    resp = solr_resp_doc_ids_only({'q'=>'Two3'})
+    resp.should have_at_most(10).documents
+    resp.should include("5732752").as_first_result
+    resp.should include("8564713").in_first(2).results
+    resp.should_not include("5727394")
+    resp.should have_the_same_number_of_results_as(solr_resp_doc_ids_only({'q'=>'two3'}))
+    resp.should have_fewer_results_than(solr_resp_doc_ids_only({'q'=>'two 3'}))
+  end
+ 
+  it "Traditional Chinese chars 三國誌 should get the same results as simplified chars 三国志" do
+    resp = solr_resp_doc_ids_only({'q'=>'三國誌'})  
+    resp.should have_at_least(240).documents
+    resp.should have_the_same_number_of_results_as(solr_resp_doc_ids_only({'q'=>'三国志'})) 
+  end
+
+=== How Do I Do That?
+
+Essentially, you write a bunch of specs that
+* send a request to your Solr index
+* wrap the Solr Ruby response into the RSpecSolr::SolrResponseHash  (blah = RSpecSolr::SolrResponseHash.new(orig_resp))
+* utilize the matchers (blah.should have_document("222")) -- see MATCHERS.rdoc
+
+There is an exemplar project utilizing rspec-solr at https://github.com/sul-dlss/sw_index_tests.  
+
+Besides the specs themselves, it has essentially 4 files to smooth the way.
+
+==== 1. Gemfile
+Indicate the required gems for bundler
+
+ source :rubygems
+
+ gem 'RedCloth' 		# for textile formatting used in Readme
+ gem 'rake'
+ gem 'rsolr'       # for sending requests to and getting responses from solr
+ gem 'rspec-solr'  # for rspec assertions against solr response object
+
+==== 2. Rakefile
+Make it easy to run various groups of specs from the command line
+
+ require 'rspec/core/rake_task'
+
+ desc "run specs expected to pass" 
+ RSpec::Core::RakeTask.new(:rspec) do |spec|
+   spec.rspec_opts = ["-c", "-f progress", "-r ./spec/spec_helper.rb"]
+ end
+
+==== 3. config/solr.yml
+Your Solr base url goes here
+
+ test:
+  :url: http://your_solr_baseurl
+
+ dev:
+   :url: http://your_solr_baseurl
+
+==== 4. spec/spec_helper.rb
+Do a one time setup of Solr connection, and methods to make it easier to make desired Solr requests
+
+  require "yaml"
+  require 'rsolr'
+  
+  $LOAD_PATH.unshift(File.dirname(__FILE__))
+  
+  RSpec.configure do |config|
+    # FIXME:  hardcoded yml group
+    solr_config = YAML::load_file('config/solr.yml')["test"]
+    @@solr = RSolr.connect(solr_config)
+    puts "Solr URL: #{@@solr.uri}"
+  end
+  
+  # send a GET request to the default Solr request handler with the indicated Solr parameters
+  # @param solr_params [Hash] the key/value pairs to be sent to Solr as HTTP parameters, in addition to 
+  #  those to get only id fields and no facets in the response
+  # @return [RSpecSolr::SolrResponseHash] object for rspec-solr testing the Solr response 
+  def solr_resp_doc_ids_only(solr_params)
+    solr_response(solr_params.merge(@@doc_ids_only))
+  end
+  
+  private
+  
+  # send a GET request to the indicated Solr request handler with the indicated Solr parameters
+  # @param solr_params [Hash] the key/value pairs to be sent to Solr as HTTP parameters
+  # @param req_handler [String] the pathname of the desired Solr request handler (defaults to 'select') 
+  # @return [RSpecSolr::SolrResponseHash] object for rspec-solr testing the Solr response 
+  def solr_response(solr_params, req_handler='select')  
+    RSpecSolr::SolrResponseHash.new(@@solr.send_and_receive(req_handler, {:method => :get, :params => solr_params}))
+  end
+  
+  # use these Solr HTTP params to reduce the size of the Solr responses
+  # response documents will only have id fields, and there will be no facets in the response
+  # @return [Hash] Solr HTTP params to reduce the size of the Solr responses
+  def doc_ids_only
+    {'fl'=>'id', 'facet'=>'false'}
+  end
+  
 
 == Ruby Version Compatibility
 
-This should work with various rubies 1.8.7, but currently some tests expected ordered hashes (though the code itself doesn't require them).
+This should work with various rubies 1.8.7, but currently some tests expected ordered hashes (though the code itself doesn't require them - just THIS gem's TEST code).
+
+== Contribute
+
+I'm currently envisioning helper methods shared somehow - either on the github wikis, or in this gem as exemplars, or in a separate gem, or ...
+
+Please share yours!
 
 == Contributing
 
@@ -33,3 +144,7 @@ This should work with various rubies 1.8.7, but currently some tests expected or
 3. Commit your changes (`git commit -am 'Added some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create new Pull Request
+
+== Releases
+- in progress ... 0.1.1 improve README
+- <b>0.1.0</b> Initial release

data/lib/rspec-solr/solr_response_hash.rb

@@ -36,6 +36,7 @@ class RSpecSolr
     # @example expected_doc Array
     #   ["1", "2", "3"]  implies we expect Solr docs with ids 1, 2, 3 included in this response
     #   [{"title" => "warm fuzzies"}, {"title" => "cool fuzzies"}]  implies we expect at least one Solr doc in this response matching each Hash in the Array
+    #   [{"title" => /rm fuzz/}, {"title" => /^cool/}]  implies we expect at least one Solr doc in this response matching each Hash in the Array
     # @param [FixNum] max_doc_position maximum acceptable position (1-based) of document in results.  (e.g. if 2, it must be the 1st or 2nd doc in the results)
     def has_document?(expected_doc, max_doc_position = nil)
       if expected_doc.is_a?(Hash)
@@ -47,7 +48,12 @@ class RSpecSolr
               # if it's an Array, then all expected values must be present
               Array(exp_vals).all? { | exp_val |
                 # a doc's fld values can be a String or an Array
-                Array(doc[exp_fname]).include?(exp_val)
+                case exp_val
+                  when Regexp
+                    Array(doc[exp_fname]).any? { |val| val =~ exp_val }
+                  else
+                    Array(doc[exp_fname]).include?(exp_val)
+                end
               } &&
               # satisfy doc's position in the results
               (max_doc_position ? docs.find_index(doc) < max_doc_position : true)

data/lib/rspec-solr/version.rb

@@ -1,3 +1,3 @@
 class RSpecSolr
-  VERSION = "0.1.0"
+  VERSION = "0.1.2"
 end

data/lib/tasks/doc.rake

@@ -11,7 +11,7 @@ begin
     yt.options = ['--output-dir', doc_dest_dir, 
                   '--readme', 'README.rdoc', 
                   '--title', 'RSpec-Solr Documentation', 
-                  '--files', 'expectation_matchers.rdoc']
+                  '--files', 'MATCHERS.rdoc']
   end
 rescue LoadError
   desc "Generate YARD Documentation"

data/rspec-solr.gemspec

@@ -11,7 +11,7 @@ Gem::Specification.new do |gem|
   gem.summary       = "RSpec custom matchers for Solr response objects"
   gem.homepage      = "http://github.com/sul-dlss/rspec-solr"
 
-  gem.extra_rdoc_files = ["LICENSE.txt", "README.rdoc", "expectation_matchers.rdoc"]
+  gem.extra_rdoc_files = ["LICENSE.txt", "README.rdoc", "MATCHERS.rdoc"]
   gem.files         = `git ls-files`.split($\)
   gem.test_files    = gem.files.grep(%r{^spec/})
   gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }

data/spec/include_document_spec.rb

@@ -93,8 +93,7 @@ describe RSpecSolr do
       it "passes if no part of the expectatio is met" do
         @solr_resp_5_docs.should_not include("id" => "not_there", "not_there" => "anything")
       end
-    end # should_not include('fld1'=>'val1', 'fld2'=>'val2')
-    
+    end # should_not include('fld1'=>'val1', 'fld2'=>'val2')    
     
     context "multi-valued fields and expectations" do
       
@@ -285,7 +284,7 @@ describe RSpecSolr do
       
       context "should include(Array_of_Hashes)" do
         it "passes if all Hashes in Array match all Solr documents in the response" do
-          @solr_resp_5_docs.should include([{"id"=>"111", "fld"=>"val", "fld2"=>"val2"}, 
+          @solr_resp_5_docs.should include([{"id"=>"111", "fld"=>/val/, "fld2"=>"val2"}, 
                                             {"id"=>"222"}, 
                                             {"id"=>"333", "fld"=>"val"}, 
                                             {"id"=>"444", "fld"=>["val1", "val2", "val3"]}, 
@@ -361,11 +360,46 @@ describe RSpecSolr do
     
     context "regex value" do
 
-      context 'should include(:key => "/regex/")' do
-        it "does something" do
-          pending "to be implemented"
+      context "should include('fld' => /regex/)" do
+        it "passes if Solr document in response matches regex in named field" do
+          @solr_resp_5_docs.should include("id" => /\d{3}/)
+          @solr_resp_5_docs.should include("fld" => /^va/)  # 2 docs match 
         end
-      end
+        it "passes if single value expectation is expressed as an Array" do
+          @solr_resp_5_docs.should include("id" => [/111/])
+        end
+        it "fails if no Solr document in response has 'fldval' for the named field" do
+          lambda {
+            @solr_resp_5_docs.should include("id" => /not there/)
+          }.should fail_matching('} to include {"id"=>/not there/}')
+        end
+        it "fails if no Solr document in response has the named field" do
+          lambda {
+            @solr_resp_5_docs.should include("not_there" => /anything/)
+            }.should fail_matching('} to include {"not_there"=>/anything/}')
+        end
+      end # should include('fld' => /regex/)
+
+      context "should_NOT include('fld' => /regex/)" do
+        it "fails if Solr document in response matches regex in named field" do
+          lambda {
+            @solr_resp_5_docs.should_not include("id" => /\d{3}/)
+          }.should fail_matching('not to include {"id"=>/\d{3}/}')
+          lambda {
+            @solr_resp_5_docs.should_not include("fld" => /^va/) 
+          }.should fail_matching('not to include {"fld"=>/^va/}')
+        end
+        it "passes if no Solr document in response has 'fldval' for the named field" do
+            @solr_resp_5_docs.should_not include({"id" => /not there/})
+        end
+        it "passes if no Solr document in response has the named field" do
+            @solr_resp_5_docs.should_not include({"not_there" => /anything/})
+        end
+        it "passes if single field value is expressed as Array" do
+          @solr_resp_5_docs.should_not include({"id" => [/not there/]})
+        end
+
+      end # should_NOT include('fld' => /regex/)
 
     end # regex value
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rspec-solr
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
   prerelease: 
 platform: ruby
 authors:
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-08-15 00:00:00.000000000 Z
+date: 2012-10-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -133,16 +133,17 @@ extensions: []
 extra_rdoc_files:
 - LICENSE.txt
 - README.rdoc
-- expectation_matchers.rdoc
+- MATCHERS.rdoc
 files:
 - .gitignore
 - .rvmrc
 - .travis.yml
+- .yardopts
 - Gemfile
 - LICENSE.txt
+- MATCHERS.rdoc
 - README.rdoc
 - Rakefile
-- expectation_matchers.rdoc
 - lib/rspec-solr.rb
 - lib/rspec-solr/compare_num_docs_matcher.rb
 - lib/rspec-solr/have_documents_matcher.rb
@@ -176,7 +177,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 2828541133057888426
+      hash: -4597988063406856522
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -185,7 +186,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 2828541133057888426
+      hash: -4597988063406856522
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.24