rspec-api-matchers 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 52d99afa65e3dc027e30e06fe06e5abdb6ca7b77
-  data.tar.gz: 670f2f96336bf3b7ffdd41434f7a756fc358da4c
+  metadata.gz: 7a9cb40b04968465419bdc9816a1002fe6a29761
+  data.tar.gz: f1ca85d85451586be343f9edf7bb2d6405590578
 SHA512:
-  metadata.gz: 76fcda35ccae07f245892ec5773f20dc43c875714cf2bda6f7f44efdcafafc98e493739b2d4e0c7056d91f3aabe1055397d95c3e278ec3bc11983e345fa397db
-  data.tar.gz: 8e71adfec9954e778684d3ecce2ac4bce83c9319cb7a5f0acd7dfaf9efa6363d8ddc60101d646aa43a30c08ee5b8869cd9d4069ac4ed525e3eab927d68ff01dc
+  metadata.gz: a5315d2e00d92d287059754dbef2aa689305f43ed5e66b5a580b332aed9430a1cc4741b9a1f96b768f5c074e45910c1d31a4b9c6ad04301461407d6f1bdfcbbd
+  data.tar.gz: 59b6add713ca2f7988ffca56bddbb5fb64efc069066f01e283ac135ed00382fcf3834f573c7dba9d7920c59fad110ce850c903e4ccdc54738eb267ae429dae89

data/README.md

@@ -1,42 +1,47 @@
-RSpec API Matchers
+RSpecApi::Matchers
 ==================
 
 RSpecApi::Matchers lets you express outcomes on the response of web APIs.
 
     expect(response).to have_status(:not_found)
 
-More documentation and examples about RSpec Api are available at [http://rspec-api.github.io](http://rspec-api.github.io)
+More documentation and examples about RSpecApi are available at [http://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)
 [![Coverage Status](https://coveralls.io/repos/rspec-api/rspec-api-matchers/badge.png)](https://coveralls.io/r/rspec-api/rspec-api-matchers)
 [![Dependency Status](https://gemnasium.com/rspec-api/rspec-api-matchers.png)](https://gemnasium.com/rspec-api/rspec-api-matchers)
 
-Install
--------
-
-Add `gem 'rspec-api-matchers'` to your `Gemfile` and run `bundle`.
-Or install yourself by running `gem install rspec-api-matchers`.
-
-Version changes respect [Semantic Versioning](http://semver.org).
-To ensure `bundle update` won't cause problems in your repository,
-always indicate the patch version until version 1.0.0 is released, e.g.:
-
-    gem 'rspec-api-matchers', '~> 0.5.0'
-
-
 Available matchers
 ------------------
 
     expect(response).to have_status(:ok)
-    expect(response).to include_content_type(:json)
-    expect(response).to have_prev_page_link
+    expect(response).to have_content_type(:json)
+    expect(response).to have_page_links
     expect(response).to be_a_collection
-    expect(response).to be_a_jsonp('alert')
+    expect(response).to be_wrapped_in_callback('alert')
     expect(response).to be_sorted(by: :id, verse: :desc)
-    expect(response).to be_filtered(10, by: :id)
+    expect(response).to be_filtered(by: :id, value: 10)
     expect(response).to have_attributes(id: {value: 1.2}, url: {type: {string: :url}})
 
+
+How to install
+==============
+
+To install on your system, run `gem install rspec-api-matchers`.
+To use inside a bundled Ruby project, add this line to the Gemfile:
+
+    gem 'rspec-api-matchers', '~> 0.5.0'
+
+The rspec-api-matchers gem follows [Semantic Versioning](http://semver.org).
+Any new release that is fully backward-compatible bumps the *patch* version (0.5.1).
+Any new version that breaks compatibility bumps the *minor* version (0.6.0)
+
+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

@@ -1,27 +1,44 @@
-require 'rspec-api/dsl/have_status'
-require 'rspec-api/dsl/include_content_type'
-require 'rspec-api/dsl/have_prev_page_link'
-require 'rspec-api/dsl/be_a_jsonp'
-require 'rspec-api/dsl/be_sorted'
-require 'rspec-api/dsl/be_a_collection'
-require 'rspec-api/dsl/be_filtered'
-require 'rspec-api/dsl/have_attributes'
-
-require 'rspec/matchers'
-
-# Convert RSpecAPI::Matchers classes into RSpec-compatible matchers, e.g.:
-# makes RSpecApi::Matchers::Status available as expect(...).to match_status
+require 'rspec/core'
+require 'rspec-api/matchers/attributes/have_attributes'
+require 'rspec-api/matchers/collection/be_a_collection'
+require 'rspec-api/matchers/content_type/have_content_type'
+require 'rspec-api/matchers/filter/be_filtered'
+require 'rspec-api/matchers/json/be_valid_json'
+require 'rspec-api/matchers/jsonp/be_wrapped_in_callback'
+require 'rspec-api/matchers/page_links/have_page_links'
+require 'rspec-api/matchers/response/be_a_valid_response'
+require 'rspec-api/matchers/sort/be_sorted'
+require 'rspec-api/matchers/status/have_status'
 
 module RSpecApi
   module Matchers
-    module DSL
-    end
+    include Attributes
+    include Collection
+    include ContentType
+    include Filter
+    include Json
+    include Jsonp
+    include PageLinks
+    include Response
+    include Sort
+    include Status
   end
 end
 
-module RSpec
-  module Matchers
-    # Make RSpecApi::Matchers::DSL methods available inside RSpec
-    include ::RSpecApi::Matchers::DSL
-  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
+#

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

@@ -0,0 +1,23 @@
+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+.
+      #
+      # @example
+      #
+      #   # 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}})
+      #
+      # For more examples check +have_attributes_spec.rb+.
+
+      # TODO: add &block options
+      def have_attributes(*attributes)
+        RSpecApi::Matchers::Attributes::Matcher.new *attributes
+      end
+    end
+  end
+end

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

@@ -0,0 +1,101 @@
+require 'rspec-api/matchers/json/matcher'
+require 'active_support/core_ext/array/wrap'
+require 'active_support/core_ext/hash/keys'
+
+module RSpecApi
+  module Matchers
+    module Attributes
+      class Matcher < Json::Matcher
+        attr_accessor :attributes
+
+        def initialize(*attributes, &block)
+          @attributes = to_hash attributes
+        end
+
+        def matches?(response)
+          super && has_attributes?(json, attributes)
+        end
+
+        def description
+          if attributes.any?
+            %Q(have attributes #{attributes})
+          else
+            %Q(have attributes)
+          end
+        end
+
+      private
+
+        def has_attributes?(items, attrs)
+          attrs.deep_symbolize_keys!
+          attrs.all?{|name, options| has_attribute? items, name, options}
+        end
+
+        def has_attribute?(items, name, options)
+          return false unless Array.wrap(items).all?{|item| item.key? name}
+          values = Array.wrap(items).map{|item| item[name]}
+          attr_types = Array.wrap(options.fetch :type, :any)
+          attr_value = options.fetch :value, :any
+          values.all? do |v|
+            matches_value?(v, attr_value) && matches_types?(v, attr_types)
+          end
+        end
+
+        def matches_value?(value, expected_value)
+          case expected_value
+          when :any then true
+          when Proc then expected_value.call value
+          else value == expected_value
+          end
+        end
+
+        def matches_types?(value, expected_types)
+          expected_types.any?{|type| matches_type_and_format? value, type}
+        end
+
+        def matches_type_and_format?(value, type)
+          type = Hash[type, :any] unless type.is_a?(Hash)
+          type.any? do |type, format|
+            matches_type?(value, type) && matches_format?(value, format)
+          end
+        end
+
+        def matches_type?(value, type)
+          type_to_classes(type).any?{|klass| value.is_a? klass}
+        end
+
+        def matches_format?(value, format)
+          case format
+          when :url then value =~ URI::regexp
+          when :integer then value.is_a? Integer
+          when :timestamp then DateTime.iso8601 value rescue false
+          when :email then value =~ %r{(?<name>.+?)@(?<host>.+?)\.(?<domain>.+?)}
+          when Hash, Array then value.any? ? has_attributes?(value, to_hash(format)) : true
+          when String then matches_format?(value, format.to_sym)
+          when :any then true
+          end
+        end
+
+        def type_to_classes(type)
+          Array.wrap case type
+            when :string then String
+            when :array then Array
+            when :object then Hash
+            when :null then NilClass
+            when :boolean then [TrueClass, FalseClass]
+            when :number then Numeric
+            when String then type_to_classes(type.to_sym)
+            when :any then Object
+          end
+        end
+
+        def to_hash(attrs)
+          array = Array.wrap(attrs).map do |item|
+            item.is_a?(Hash) ? [item.keys.first, item.values.first] : [item, {}]
+          end.flatten
+          Hash[*array]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+require 'rspec-api/matchers/collection/matcher'
+
+module RSpecApi
+  module Matchers
+    module Collection
+      # Passes if the response body is a collection of JSON objects
+      #
+      # @example
+      #
+      #   # Passes if the body is a JSON array
+      #   body = '[{"id": 1}]'
+      #   expect(OpenStruct.new body: body).to be_a_collection
+      #
+      # For more examples check +be_a_collection_spec.rb+.
+      def be_a_collection
+        RSpecApi::Matchers::Collection::Matcher.new
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+require 'rspec-api/matchers/json/matcher'
+
+module RSpecApi
+  module Matchers
+    module Collection
+      class Matcher < Json::Matcher
+
+        def matches?(response)
+          super
+          json.is_a? Array
+        end
+
+        def description
+          %Q(be a collection)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+require 'rspec-api/matchers/content_type/matcher'
+
+module RSpecApi
+  module Matchers
+    module ContentType
+      # Passes if the response headers specify the provided content +type+
+      #
+      # @example
+      #
+      #   # 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)
+      #
+      # For more examples check +have_content_type_spec.rb+.
+      def have_content_type(type = nil)
+        content_type = case type
+          when :json then 'application/json; charset=utf-8'
+          when :any then %r{}
+        end
+        RSpecApi::Matchers::ContentType::Matcher.new content_type
+      end
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+require 'rspec-api/matchers/headers/matcher'
+
+module RSpecApi
+  module Matchers
+    module ContentType
+      class Matcher < Headers::Matcher
+        attr_accessor :content_type
+
+        def initialize(content_type)
+          @content_type = content_type
+        end
+
+        def matches?(response)
+          super && headers.key?('Content-Type') && content_type.match(headers['Content-Type'])
+        end
+
+        def description
+          %Q{include 'Content-Type': '#{content_type}'}
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+require 'rspec-api/matchers/filter/matcher'
+
+module RSpecApi
+  module Matchers
+    module Filter
+      # Passes if the response body is a non-empty filtered JSON collection
+      #
+      # @example
+      #
+      #   # 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
+      #
+      # For more examples check +be_filtered_spec.rb+.
+      def be_filtered(options = {})
+        RSpecApi::Matchers::Filter::Matcher.new options
+      end
+    end
+  end
+end

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

@@ -0,0 +1,57 @@
+require 'rspec-api/matchers/collection/matcher'
+
+module RSpecApi
+  module Matchers
+    module Filter
+      class Matcher < Collection::Matcher
+        attr_accessor :field, :value, :compare_with
+
+        def initialize(options = {})
+          @field = options[:by]
+          @value = options[:value]
+          @compare_with = options.fetch :compare_with, :==
+        end
+
+        def matches?(response)
+          super && all_objects_have_field? && has_two_objects? && is_filtered?
+        end
+
+        def description
+          if field
+            %Q(be filtered by #{field}#{compare_with}#{value})
+          else
+            %Q(be filtered)
+          end
+        end
+
+      private
+
+        def all_objects_have_field?
+          if field
+            json.all?{|item| item.is_a?(Hash) && item.key?(field)}
+          else
+            true
+          end
+        end
+
+        def has_two_objects?
+          if json.length < 2
+            msg = "Cannot test filtering on an array with #{json.length} items"
+            raise RSpec::Core::Pending::PendingDeclaredInExample.new msg
+          else
+            true
+          end
+        end
+
+        def is_filtered?
+          values = json.map{|item| item[field]}
+          values.all?{|v| v.send compare_with, value}
+        end
+
+        def reverse?
+          ['desc', 'descending'].include? verse.to_s
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+require 'rspec-api/matchers/headers/matcher'
+
+module RSpecApi
+  module Matchers
+    module Headers
+      # Passes if the response has a non-empty headers Hash.
+      #
+      # @example
+      #
+      #   # Passes if the headers include the content length
+      #   headers = {'Content-Length' => 17372}
+      #   expect(OpenStruct.new headers: headers).to have_headers
+      #
+      # For more examples check +have_headers_spec.rb+.
+      def have_headers
+        RSpecApi::Matchers::Headers::Matcher.new
+      end
+    end
+  end
+end