rspec-api-matchers 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d7bafa7be5d9a9a73eec85c9c1fa473844e348a1
-  data.tar.gz: b95d6c0afaa31f027647e56645e97030e4bd654e
+  metadata.gz: 20a535eed35e5707a7481654ed0b950564909105
+  data.tar.gz: 7f0bd00909ec5a02ad347d32e208ae6fc7e88365
 SHA512:
-  metadata.gz: e7bf0a450c8600f4b1d93f7ca503fe50280356700b34b72701cd1bde563dcdb96498d3ef3620e62ff81be6587cb130db2645c06404650084f3ff1b11e02cb1a8
-  data.tar.gz: 500abca1395d180d69c261e486af6821a52102f3603762369a1984d81db200dc9e0bfd7450854407bc0297207c4ae7034db12d57f8ffe8c32199612fd007c51b
+  metadata.gz: e5aac6339f3c1a600d56f3a606cbd9c62c87b3c1019aa9eecfa49cc9800e6815d8851fc4952ec8c56dc98cd387690f40f19b90b40ad38bf1121d89afde4ceff4
+  data.tar.gz: ddbc5ed30cd8e3f9ba422bfc7091737e276775c300d33bcefa7d748b5dace486c9fd3ab5a16f436e316249756e76d23907a2d4e2ba5d38fbdbf594b0b22cef00

data/README.md

@@ -5,7 +5,9 @@ RSpecApi::Matchers lets you express outcomes on the response of web APIs.
 
     expect(response).to have_status(:not_found)
 
-More documentation and examples about RSpecApi are available at [http://rspec-api.github.io](http://rspec-api.github.io)
+The full documentation is available at [rubydoc.info](http://rubydoc.info/github/rspec-api/rspec-api-matchers/master/frames).
+
+More information about the parent project RSpecApi is available at [rspec-api.github.io](http://rspec-api.github.io)
 
 [![Build Status](https://travis-ci.org/rspec-api/rspec-api-matchers.png?branch=master)](https://travis-ci.org/rspec-api/rspec-api-matchers)
 [![Code Climate](https://codeclimate.com/github/rspec-api/rspec-api-matchers.png)](https://codeclimate.com/github/rspec-api/rspec-api-matchers)
@@ -21,10 +23,9 @@ Available matchers
     expect(response).to be_a_collection
     expect(response).to be_wrapped_in_callback('alert')
     expect(response).to be_sorted(by: :id, verse: :desc)
-    expect(response).to be_filtered(by: :id, value: 10)
+    expect(response).to be_filtered(by: :id, value: 10, compare_with: :>)
     expect(response).to have_attributes(id: {value: 1.2}, url: {type: {string: :url}})
 
-
 How to install
 ==============
 
@@ -41,7 +42,6 @@ Indicating the full version in your Gemfile (*major*.*minor*.*patch*) guarantees
 that your project won’t occur in any error when you `bundle update` and a new
 version of RSpecApi::Matchers is released.
 
-
 How to contribute
 =================
 

data/lib/rspec-api/matchers.rb

@@ -11,6 +11,22 @@ require 'rspec-api/matchers/sort/be_sorted'
 require 'rspec-api/matchers/status/have_status'
 
 module RSpecApi
+  # Provides RSpec Matchers for RESTful web APIs.
+  #
+  # To have these matchers available inside of an RSpec `describe` block,
+  # tag that block with the `:rspec_api` metadata, or explicitly include the
+  # RSpecApi::Matchers module inside the example group
+  #
+  # @example Tag a `describe` block as `:rspec_api`:
+  #   describe "Artists", rspec_api: true do
+  #      ... # here you can write `expect(response).to have_status :ok`, etc.
+  #   end
+  #
+  # @example Explicitly include the RSpecApi::Matchers module
+  #   describe "Artists" do
+  #      include RSpecApi::Matchers
+  #      ... # here you can write `expect(response).to have_status :ok`, etc.
+  #   end
   module Matchers
     include Attributes
     include Collection
@@ -25,20 +41,4 @@ module RSpecApi
   end
 end
 
-# RSpecApi::Matchers adds matchers to test RESTful APIs.
-#
-# To have these matchers available inside of an RSpec `describe` block, tag that
-# block with the `:rspec_api` metadata:
-#
-#  describe "Artists", rspec_api: true do
-#     ... # here you can write `expect(response).to have_status :ok`, etc.
-#  end
-RSpec.configuration.include RSpecApi::Matchers, rspec_api: true
-
-# You can also explicitly include the RSpec::Api module inside the example group:
-#
-#  describe "Artists" do
-#     include RSpecApi::Matchers
-#     ... # here you can write `expect(response).to have_status :ok`, etc.
-#  end
-#
+RSpec.configuration.include RSpecApi::Matchers, rspec_api: true

data/lib/rspec-api/matchers/attributes/have_attributes.rb

@@ -3,18 +3,28 @@ require 'rspec-api/matchers/attributes/matcher'
 module RSpecApi
   module Matchers
     module Attributes
-      # Passes if the response body is either a JSON object or a collection of
-      # JSON objects that include all the +attributes+.
+      # Passes if the object includes the expected attributes in the body.
       #
-      # @example
+      # @example Passes if the body is a collection of objects with a URL site
+      #   require 'rspec-api-matchers'
       #
-      #   # Passes if the body is an object with a URL-formatted String :site
-      #   response = OpenStruct.new body: '{"site": "http://www.example.com"}'
-      #   expect(response).to have_attributes(site: {type: {string: :url}})
+      #   body = '[{"site": "http://www.foo.com"}, {"site": "http://bar.com"}]'
+      #   obj = OpenStruct.new body: body
       #
-      # For more examples check +have_attributes_spec.rb+.
-
-      # TODO: add &block options
+      #   describe 'have_attributes' do
+      #     include RSpecApi::Matchers::Attributes
+      #     it { expect(obj).to have_attributes(site: {type: {string: :url}}) }
+      #   end
+      #
+      #   # => (rspec) 1 example, 0 failures
+      #
+      # @param [Hash] attributes The expected attributes in the body
+      #
+      # The method works only if the object is a JSON object or a collection of
+      # JSON objects; in the latter case all the objects need to include the
+      # expected attributes for the expectation to pass.
+      #
+      # @see http://git.io/w2dLnw have_attributes_spec.rb for more examples
       def have_attributes(*attributes)
         RSpecApi::Matchers::Attributes::Matcher.new *attributes
       end

data/lib/rspec-api/matchers/attributes/matcher.rb

@@ -27,7 +27,7 @@ module RSpecApi
       private
 
         def has_attributes?(items, attrs)
-          attrs.deep_symbolize_keys!
+          attrs.symbolize_keys!
           attrs.all?{|name, options| has_attribute? items, name, options}
         end
 

data/lib/rspec-api/matchers/collection/be_a_collection.rb

@@ -3,15 +3,22 @@ require 'rspec-api/matchers/collection/matcher'
 module RSpecApi
   module Matchers
     module Collection
-      # Passes if the response body is a collection of JSON objects
+      # Passes if the object has a collection of JSON objects in the body.
       #
-      # @example
+      # @example Passes if the body is a JSON array
+      #   require 'rspec-api-matchers'
       #
-      #   # Passes if the body is a JSON array
-      #   body = '[{"id": 1}]'
-      #   expect(OpenStruct.new body: body).to be_a_collection
+      #   body = '[{"id": 1}, {"name": "foo"}, {"name": "bar"}]'
+      #   obj = OpenStruct.new body: body
       #
-      # For more examples check +be_a_collection_spec.rb+.
+      #   describe 'be_a_collection' do
+      #     include RSpecApi::Matchers::Collection
+      #     it { expect(obj).to be_a_collection }
+      #   end
+      #
+      #   # => (rspec) 1 example, 0 failures
+      #
+      # @see http://git.io/Bl5qJQ be_a_collection_spec.rb for more examples
       def be_a_collection
         RSpecApi::Matchers::Collection::Matcher.new
       end

data/lib/rspec-api/matchers/content_type/have_content_type.rb

@@ -3,15 +3,26 @@ require 'rspec-api/matchers/content_type/matcher'
 module RSpecApi
   module Matchers
     module ContentType
-      # Passes if the response headers specify the provided content +type+
+      # Passes if the object includes the expected content type in the headers.
       #
-      # @example
+      # @param [Symbol or String] type The expected content type. Can either
+      #   be the exact Content-Type string or just the format. The special
+      #   value +:any+ matches any content type.
+      #
+      # @example Passes if the headers matches the provided JSON content type
+      #   require 'rspec-api-matchers'
       #
-      #   # Passes if the headers matches the provided JSON content type
       #   headers ={'Content-Type' => 'application/json; charset=utf-8'}
-      #   expect(OpenStruct.new headers: headers).to have_content_type(:json)
+      #   obj = OpenStruct.new headers: headers
+      #
+      #   describe 'have_content_type' do
+      #     include RSpecApi::Matchers::ContentType
+      #     it { expect(obj).to have_content_type(:json) }
+      #   end
+      #
+      #   # => (rspec) 1 example, 0 failures
       #
-      # For more examples check +have_content_type_spec.rb+.
+      # @see http://git.io/qwv-RQ have_content_type_spec.rb for more examples
       def have_content_type(type = nil)
         content_type = case type
           when :json then 'application/json; charset=utf-8'

data/lib/rspec-api/matchers/filter/be_filtered.rb

@@ -3,15 +3,28 @@ require 'rspec-api/matchers/filter/matcher'
 module RSpecApi
   module Matchers
     module Filter
-      # Passes if the response body is a non-empty filtered JSON collection
+      # Passes if the object has a non-empty filtered JSON collection in the body.
       #
-      # @example
+      # @param [Hash] options how the body is expected to be filtered.
+      # @option options [Symbol or String] :by The JSON key to be filtered by
+      # @option options [Object] :value The expected value for the field
+      # @option options [Proc or Symbol] :compare_with (:==) The operator used
+      #   to compare the expected value with the values in the collection
       #
-      #   # Passes if the body only contains objects with ID = 1
-      #   body = '[{"id": 1}, {"id": 1}, {"id": 1}]'
-      #   expect(OpenStruct.new body: body).to be_filtered by: :id, value: 1
+      # @example Passes if the body only contains objects with ID > 1
+      #   require 'rspec-api-matchers'
       #
-      # For more examples check +be_filtered_spec.rb+.
+      #   body = '[{"id": 2}, {"id": 3}]'
+      #   obj = OpenStruct.new body: body
+      #
+      #   describe 'be_filtered' do
+      #     include RSpecApi::Matchers::Filter
+      #     it { expect(obj).to be_filtered by: :id, value: 1, compare_with: :> }
+      #   end
+      #
+      #   # => (rspec) 1 example, 0 failures
+      #
+      # @see http://git.io/lHO7nw be_filtered_spec.rb for more examples
       def be_filtered(options = {})
         RSpecApi::Matchers::Filter::Matcher.new options
       end

data/lib/rspec-api/matchers/filter/matcher.rb

@@ -13,7 +13,7 @@ module RSpecApi
         end
 
         def matches?(response)
-          super && all_objects_have_field? && has_two_objects? && is_filtered?
+          super && all_objects_have_field? && has_one_object? && is_filtered?
         end
 
         def description
@@ -34,8 +34,8 @@ module RSpecApi
           end
         end
 
-        def has_two_objects?
-          if json.length < 2
+        def has_one_object?
+          if json.length < 1
             msg = "Cannot test filtering on an array with #{json.length} items"
             raise RSpec::Core::Pending::PendingDeclaredInExample.new msg
           else
@@ -45,7 +45,13 @@ module RSpecApi
 
         def is_filtered?
           values = json.map{|item| item[field]}
-          values.all?{|v| v.send compare_with, value}
+          values.all? do |v|
+            if compare_with.is_a?(Proc)
+              compare_with.call value, v
+            elsif compare_with.is_a?(Symbol)
+              v.send compare_with, value
+            end
+          end
         end
 
         def reverse?

data/lib/rspec-api/matchers/headers/have_headers.rb

@@ -3,15 +3,22 @@ require 'rspec-api/matchers/headers/matcher'
 module RSpecApi
   module Matchers
     module Headers
-      # Passes if the response has a non-empty headers Hash.
+      # Passes if the object has a non-empty Hash in the headers.
       #
-      # @example
+      # @example Passes if the headers include the content length
+      #   require 'rspec-api-matchers'
       #
-      #   # Passes if the headers include the content length
       #   headers = {'Content-Length' => 17372}
-      #   expect(OpenStruct.new headers: headers).to have_headers
+      #   obj = OpenStruct.new headers: headers
       #
-      # For more examples check +have_headers_spec.rb+.
+      #   describe 'have_headers' do
+      #     include RSpecApi::Matchers::Headers
+      #     it { expect(obj).to have_headers }
+      #   end
+      #
+      #   # => (rspec) 1 example, 0 failures
+      #
+      # @see http://git.io/-Wb61A have_headers_spec.rb for more examples
       def have_headers
         RSpecApi::Matchers::Headers::Matcher.new
       end

data/lib/rspec-api/matchers/json/be_valid_json.rb

@@ -3,15 +3,25 @@ require 'rspec-api/matchers/json/matcher'
 module RSpecApi
   module Matchers
     module Json
-      # Passes if response body is a valid JSON or callback-wrapped JSON
+      # Passes if the object has valid JSON or JSONP in the body
       #
-      # @example
+      # @example Passes if the body is valid JSON
+      #   require 'rspec-api-matchers'
       #
-      #   # Passes if the body is valid JSON
       #   body = '[{"id": 1}]'
-      #   expect(OpenStruct.new body: body).to be_valid_json
+      #   obj = OpenStruct.new body: body
       #
-      # For more examples check +be_valid_json_spec.rb+.
+      #   describe 'be_valid_json' do
+      #     include RSpecApi::Matchers::Json
+      #     it { expect(obj).to be_valid_json }
+      #   end
+      #
+      #   # => (rspec) 1 example, 0 failures
+      #
+      # @note The JSONP option is debatable, since an API that returns a JSONP
+      #   should probably set the content-type to application/javascript.
+      #
+      # @see http://git.io/Rq3lVg be_valid_json_spec.rb for more examples
       def be_valid_json
         RSpecApi::Matchers::Json::Matcher.new
       end

data/lib/rspec-api/matchers/jsonp/be_wrapped_in_callback.rb

@@ -3,19 +3,24 @@ require 'rspec-api/matchers/jsonp/matcher'
 module RSpecApi
   module Matchers
     module Jsonp
-      # Passes if response body is a valid JSON wrapped in a JSONP callback
+      # Passes if the object has a JSONP callback-wrapped body
       #
-      # @example
+      # @param [Symbol or String] callback Name of the wrapping JSONP callback
+      #
+      # @example Passes if the body is wrapped in the function "alert"
+      #   require 'rspec-api-matchers'
       #
-      #   # Passes if the body is wrapped in "alert"
       #   body = 'alert([{"id": 1}])'
-      #   expect(OpenStruct.new body: body).to be_wrapped_in_callback(:alert)
+      #   obj = OpenStruct.new body: body
       #
-      # @note
+      #   describe 'be_wrapped_in_callback' do
+      #     include RSpecApi::Matchers::Jsonp
+      #     it { expect(obj).to be_wrapped_in_callback(:alert) }
+      #   end
       #
-      # A JSONP should actually return application/javascript...
+      #   # => (rspec) 1 example, 0 failures
       #
-      # For more examples check +be_wrapped_in_callback_spec.rb+.
+      # @see http://git.io/XLeIOg be_wrapped_in_callback_spec.rb for more examples
       def be_wrapped_in_callback(callback = nil)
         RSpecApi::Matchers::Jsonp::Matcher.new callback
       end

data/lib/rspec-api/matchers/page_links/have_page_links.rb

@@ -3,20 +3,27 @@ require 'rspec-api/matchers/page_links/matcher'
 module RSpecApi
   module Matchers
     module PageLinks
-      # Passes if response headers include pagination links ()
+      # Passes if the object includes pagination links in the headers
       #
-      # @example
+      # @example Passes if the headers include a link to the previous page
+      #   require 'rspec-api-matchers'
       #
-      #   # Passes if the headers include a link to the previous page
       #   headers = {'Link' => '<https://example.com/1>; rel="prev"'}
-      #   expect(OpenStruct.new headers: headers).to have_page_links
+      #   obj = OpenStruct.new headers: headers
       #
-      # @note
+      #   describe 'have_page_links' do
+      #     include RSpecApi::Matchers::PageLinks
+      #     it { expect(obj).to have_page_links }
+      #   end
       #
-      # Checking for the rel="prev" is probably enough for the purpose.
-      # See http://tools.ietf.org/html/rfc5988#page-6 for Link specification.
+      #   # => (rspec) 1 example, 0 failures
       #
-      # For more examples check +have_page_links_spec.rb+.
+      # @note The method only checks the presence of a rel="prev" link.
+      #   This may be extended in future versions.
+      #
+      # @see http://tools.ietf.org/html/rfc5988#page-6 RFC 5988 Link header specification
+      #
+      # @see http://git.io/yRiqYQ have_page_links_spec.rb for more examples
       def have_page_links
         RSpecApi::Matchers::PageLinks::Matcher.new
       end

data/lib/rspec-api/matchers/response/be_a_valid_response.rb

@@ -3,15 +3,21 @@ require 'rspec-api/matchers/response/matcher'
 module RSpecApi
   module Matchers
     module Response
-      # Passes if response is present
+      # Passes if the object has either a status, headers or a body.
       #
-      # @example
+      # @example Passes if the response has a status
+      #   require 'rspec-api-matchers'
       #
-      #   # Passes if the response has a status
-      #   response = OpenStruct.new status: 100
-      #   expect(response).to be_a_valid_response
+      #   obj = OpenStruct.new status: 100
       #
-      # For more examples check +be_a_valid_response_spec.rb+.
+      #   describe 'be_a_valid_response' do
+      #     include RSpecApi::Matchers::Response
+      #     it { expect(obj).to be_a_valid_response }
+      #   end
+      #
+      #   # => (rspec) 1 example, 0 failures
+      #
+      # @see http://git.io/dc2QFg be_a_valid_response_spec.rb for more examples
       def be_a_valid_response
         RSpecApi::Matchers::Response::Matcher.new
       end

data/lib/rspec-api/matchers/sort/be_sorted.rb

@@ -3,15 +3,28 @@ require 'rspec-api/matchers/sort/matcher'
 module RSpecApi
   module Matchers
     module Sort
-      # Passes if the response body is a non-empty sorted JSON collection
+      # Passes if the object has a non-empty sorted JSON collection in the body.
       #
-      # @example
+      # @param [Hash] options how the body is expected to be sorted.
+      # @option options [Symbol or String] :by The JSON key to sort by
+      # @option options [Symbol or String] :verse (:asc) The sorting direction
+      #
+      # Sorting is ascending unless +verse.to_s+ is 'desc' or 'descending'
+      #
+      # @example Passes if the body is sorted by descending IDs
+      #   require 'rspec-api-matchers'
       #
-      #   # Passes if the body is sorted by descending IDs
       #   body = '[{"id": 3}, {"id": 2}, {"id": 1}]'
-      #   expect(OpenStruct.new body: body).to be_sorted(by: :id, verse: :desc)
+      #   obj = OpenStruct.new body: body
+      #
+      #   describe 'be_sorted' do
+      #     include RSpecApi::Matchers::Sort
+      #     it { expect(obj).to be_sorted(by: :id, verse: :desc) }
+      #   end
+      #
+      #   # => (rspec) 1 example, 0 failures
       #
-      # For more examples check +be_sorted_spec.rb+.
+      # @see http://git.io/UhC4MQ be_sorted_spec.rb for more examples
       def be_sorted(options = {})
         RSpecApi::Matchers::Sort::Matcher.new options
       end

data/lib/rspec-api/matchers/status/have_status.rb

@@ -3,20 +3,25 @@ require 'rspec-api/matchers/status/matcher'
 module RSpecApi
   module Matchers
     module Status
-      # Passes if the response has a status that matches +status+.
+      # Passes if the object has a status that matches +status+.
       #
-      # @example
+      # @param [Symbol or Integer] status The expected status code
       #
-      #   # Passes if the response status matches :ok
-      #   status = :ok
-      #   expect(OpenStruct.new status: status).to have_status 200
+      # @example Passes if the response status matches :ok
+      #   require 'rspec-api-matchers'
       #
-      # @note
+      #   obj = OpenStruct.new status: 200
       #
-      #   The full list of symbolic HTTP status codes is available at:
-      #   http://git.io/YwpDnA#L542
+      #   describe 'have_status' do
+      #     include RSpecApi::Matchers::Status
+      #     it { expect(obj).to have_status :ok }
+      #   end
       #
-      # For more examples check +have_headers_spec.rb+.
+      #   # => (rspec) 1 example, 0 failures
+      #
+      # @see http://git.io/YwpDnA#L542 List of symbolic HTTP status codes
+      #
+      # @see http://git.io/Gvb-nQ have_headers_spec.rb for more examples
       def have_status(status)
         RSpecApi::Matchers::Status::Matcher.new status
       end

data/lib/rspec-api/matchers/version.rb

@@ -1,5 +1,5 @@
 module RSpecApi
   module Matchers
-    VERSION = '0.6.1'
+    VERSION = '0.7.0'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rspec-api-matchers
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.7.0
 platform: ruby
 authors:
 - claudiob
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-11-10 00:00:00.000000000 Z
+date: 2013-11-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -80,6 +80,20 @@ dependencies:
     - - '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: coveralls
   requirement: !ruby/object:Gem::Requirement
@@ -154,3 +168,4 @@ specification_version: 4
 summary: Methods extracted from rspec-api to chech validity of the response of pragmatic
   RESTful web APIs.
 test_files: []
+has_rdoc: