rspec-api-expectations 0.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: fda99c3899642eb3cfc68d5be22833ec6608111b
+  data.tar.gz: b30aa6e5fc91427c927090f942874034ba466267
+SHA512:
+  metadata.gz: 43a66db64f8b79f52fffd84116419779e09202f154033a1d4261c13bbc6cedf72c2aa8f643c4d178acb897f8a308198e293b5ea67eacf29cd8e13928b1893c5f
+  data.tar.gz: 4c6a318a4b16cc27086e9abd70830a9e1395048fc68e2f57ab72f44e36afeed8a6e2d54c28b8069c5b636e1950ae41b297a2b8501f727201197083f9804ba444

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2013 claudiob
+
+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.md

@@ -0,0 +1,103 @@
+RSpec API Expectations
+======================
+
+RSpecApi::Expectations provides the `expect_resourceful` helper to any
+RSpec example group tagged as `:rspec_api_resource`.
+
+[![Build Status](https://travis-ci.org/rspec-api/rspec-api-expectations.png?branch=master)](https://travis-ci.org/rspec-api/rspec-api-expectations)
+[![Code Climate](https://codeclimate.com/github/rspec-api/rspec-api-expectations.png)](https://codeclimate.com/github/rspec-api/rspec-api-expectations)
+[![Coverage Status](https://coveralls.io/repos/rspec-api/rspec-api-expectations/badge.png)](https://coveralls.io/r/rspec-api/rspec-api-expectations)
+[![Dependency Status](https://gemnasium.com/rspec-api/rspec-api-expectations.png)](https://gemnasium.com/rspec-api/rspec-api-expectations)
+
+Basic example
+-------------
+
+    require 'faraday'
+    response = Faraday.new('http://example.com/').get('/concerts')
+
+    describe 'GET http://example.com/concerts', :rspec_api_resource do
+      expect_resourceful response, status: :ok, type: :json, array: true
+    end
+
+The example above makes a `GET `'http://example.com/concerts'` request, then
+check that the response:
+
+* has a status code of 200 OK
+* has the 'Content-Type' header set to 'application/json'
+* has a JSON Array of Hashes (also called 'objects') in the body
+
+Running the test above in RSpec produces the following output:
+
+...
+
+Available expectations
+======================
+
+The purpose of RSpecApi::Expectations is to give developers a tool to quickly
+test that API endpoints respect some best practices that are common to
+RESTful resourceful web APIs.
+
+A list of best practices is available in [this great article by ...]; they
+span from something as simple as "the status of a successful GET request should
+be 200 OK" to something more complex as "the headers of a GET request for a
+paginated list should include a link to the previous page".
+
+RSpecApi::Expectations makes it easy to test whether any web API respects these
+best practices by means of the `expect_resourceful` method. Here are all the
+available expectations that can be tested with this method:
+
+Status
+------
+
+    expect_resourceful response, status: :ok
+
+Expects a specific HTTP status code in the response.
+The status can be specified either as a number or as a [symbol](...)
+
+Content Type
+------------
+
+    expect_resourceful response, type: :json
+
+Expects a specific 'Content-Type' header in the response.
+The status can be specified either as a string or as a [symbol](...).
+By default, the expectation (best practice) is 'application/json'.
+Note that this expectation always passes if the response status indicates
+that there is no content at all (e.g. if the status is '204 No Content').
+
+Collection
+----------
+
+    expect_resourceful response, collection: true
+
+Expects the response body to either contain one or a collection of resources.
+By default, the expectation is `collection: false`.
+
+An example of a JSON response with one resource is:
+`{"id": 1, "name": "foo"}`.
+An example of a JSON response with a collection of resources is:
+`[{"id": 1, "name": "foo"}, {"id": 2, "name": "bar"}]`.
+
+More to add
+-----------
+
+  ....
+
+
+How to install
+==============
+
+Add `gem 'rspec-api-expectations'` to your `Gemfile` and run `bundle`.
+Or install yourself by running `gem install rspec-api-expectations`.
+
+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-expectations', '~> 0.5.0'
+
+How to contribute
+=================
+
+Don’t hesitate to send me code comments, issues or pull requests through GitHub!
+All feedback is appreciated. Thanks :)

data/lib/rspec-api-expectations.rb

@@ -0,0 +1 @@
+require 'rspec-api/expectations'

data/lib/rspec-api/configure.rb

@@ -0,0 +1,8 @@
+require 'rspec'
+require 'rspec-api/resourceful'
+
+# Make `expect_resourceful` available in every RSpec ExampleGroup tagged
+# as `rspec_api_resource`
+RSpec.configure do |c|
+  c.extend(RSpecApi::Expectations::Resourceful, rspec_api_resource: true)
+end

data/lib/rspec-api/expectations.rb

@@ -0,0 +1,2 @@
+require 'rspec-api/resourceful'
+require 'rspec-api/configure'

data/lib/rspec-api/expectations/body.rb

@@ -0,0 +1,38 @@
+require 'rspec-api/matchers'
+require 'rack/utils'
+
+module RSpecApi
+  module Expectations
+    module BodyExpectations
+      def expect_a_collection(response, is_collection)
+        if is_collection
+          expect(response).to be_a_collection
+        else
+          expect(response).not_to be_a_collection
+        end
+      end
+
+      def expect_callback_wrapped(response, callback)
+        expect(response).to be_a_jsonp callback
+      end
+
+      def expect_a_sorted(response, sort = {})
+        expect(response).to be_sorted sort
+      end
+
+      def expect_a_filtered(response, filter = {})
+        expect(response).to be_filtered filter[:value], filter.except(:value)
+      end
+
+      def expect_attributes(response, attributes)
+        expect(response).to have_attributes attributes
+      end
+
+    private
+
+      def successful?(response)
+        response.status < 400 && !Rack::Utils::STATUS_WITH_NO_ENTITY_BODY.include?(response.status)
+      end
+    end
+  end
+end

data/lib/rspec-api/expectations/headers.rb

@@ -0,0 +1,20 @@
+require 'rspec-api/matchers'
+require 'rack/utils'
+
+module RSpecApi
+  module Expectations
+    module HeadersExpectations
+      def expect_content_type_header(response, type)
+        expect(response).to include_content_type type
+      end
+
+      def expect_prev_page_link_header(response, has_prev_page)
+        if has_prev_page == false
+          expect(response).not_to have_prev_page_link
+        else
+          expect(response).to have_prev_page_link
+        end
+      end
+    end
+  end
+end

data/lib/rspec-api/expectations/status.rb

@@ -0,0 +1,11 @@
+require 'rspec-api/matchers'
+
+module RSpecApi
+  module Expectations
+    module StatusExpectations
+      def expect_status(response, status)
+        expect(response).to have_status status
+      end
+    end
+  end
+end

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

@@ -0,0 +1,5 @@
+module RSpecApi
+  module Expectations
+    VERSION = '0.5.0'
+  end
+end

data/lib/rspec-api/resourceful.rb

@@ -0,0 +1,34 @@
+require 'active_support/core_ext/hash/slice'
+require 'rspec-api/resourceful/status'
+require 'rspec-api/resourceful/headers'
+require 'rspec-api/resourceful/body'
+
+module RSpecApi
+  module Expectations
+    module Resourceful
+      include ResourcefulStatus
+      include ResourcefulHeaders
+      include ResourcefulBody
+
+      def expect_resourceful(response, expectations)
+        expect_resourceful_status response, expectations.slice(*on_status)
+        expect_resourceful_headers response, expectations.slice(*on_headers)
+        expect_resourceful_body response, expectations.slice(*on_body)
+      end
+
+    private
+
+      def on_status
+        [:status]
+      end
+
+      def on_headers
+        [:type, :has_prev_page]
+      end
+
+      def on_body
+        [:collection, :callback, :sort, :filter, :attributes]
+      end
+    end
+  end
+end

data/lib/rspec-api/resourceful/body.rb

@@ -0,0 +1,27 @@
+require 'rspec-api/expectations/body'
+require 'rack/utils'
+
+module RSpecApi
+  module Expectations
+    module ResourcefulBody
+      # Creates an example group for expectations on the response body of the
+      # last API request and runs it to verify that it matches best practices:
+      # * if response is succesful and has a body
+      #   -  the body should be a JSON-marshalled Array or Hash
+      #   -  if request has a callback parameter, the body should be JSONP
+      #   -  if request has a sort parameter, the body should be sorted
+      #   -  if request has a filter parameter, the body should be filtered
+      #   -  if some attributes are expected, the body should include them
+      def expect_resourceful_body(response, expectations = {})
+        include BodyExpectations
+        context 'responds with a body that' do
+          it { expect_a_collection response, expectations[:collection] } if expectations.key?(:collection)  && response.status && response.status < 400 && !Rack::Utils::STATUS_WITH_NO_ENTITY_BODY.include?(response.status)
+          it { expect_callback_wrapped response, expectations[:callback] } if expectations[:callback]
+          it { expect_a_sorted response, expectations[:sort] } if expectations[:sort]
+          it { expect_a_filtered response, expectations[:filter] } if expectations[:filter]
+          it { expect_attributes response, expectations[:attributes] } if expectations[:attributes] && response.status && response.status < 400 && !Rack::Utils::STATUS_WITH_NO_ENTITY_BODY.include?(response.status)
+        end if expectations.any?
+      end
+    end
+  end
+end

data/lib/rspec-api/resourceful/headers.rb

@@ -0,0 +1,20 @@
+require 'rspec-api/expectations/headers'
+
+module RSpecApi
+  module Expectations
+    module ResourcefulHeaders
+      # Creates an example group for expectations on the response headers of
+      # last API request and runs it to verify that it matches best practices:
+      # * if request has entity body, the Content-Type header should be JSON
+      # * if request has pages, the Link header should have a 'rel=prev' link
+      def expect_resourceful_headers(response, expectations = {})
+        include HeadersExpectations
+
+        context 'responds with headers that' do
+          it { expect_content_type_header response, expectations[:type] } if expectations[:type] && !Rack::Utils::STATUS_WITH_NO_ENTITY_BODY.include?(response.status)
+          it { expect_prev_page_link_header response, expectations[:has_prev_page] } if expectations.key?(:has_prev_page)
+        end if expectations.any?
+      end
+    end
+  end
+end

data/lib/rspec-api/resourceful/status.rb

@@ -0,0 +1,17 @@
+require 'rspec-api/expectations/status'
+
+module RSpecApi
+  module Expectations
+    module ResourcefulStatus
+      # Creates an example group for expectations on the HTTP status code of the
+      # last API request and runs it to verify that it matches +status+.
+      def expect_resourceful_status(response, expectations = {})
+        include StatusExpectations
+
+        context 'responds with a status code that' do
+          it { expect_status response, expectations[:status] } if expectations[:status]
+        end if expectations.any?
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,170 @@
+--- !ruby/object:Gem::Specification
+name: rspec-api-expectations
+version: !ruby/object:Gem::Version
+  version: 0.5.0
+platform: ruby
+authors:
+- claudiob
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-11-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec-api-matchers
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.5.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.5.0
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  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
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: RSpec expectations useful to test web APIs.
+email:
+- claudiob@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/rspec-api/configure.rb
+- lib/rspec-api/expectations/body.rb
+- lib/rspec-api/expectations/headers.rb
+- lib/rspec-api/expectations/status.rb
+- lib/rspec-api/expectations/version.rb
+- lib/rspec-api/expectations.rb
+- lib/rspec-api/resourceful/body.rb
+- lib/rspec-api/resourceful/headers.rb
+- lib/rspec-api/resourceful/status.rb
+- lib/rspec-api/resourceful.rb
+- lib/rspec-api-expectations.rb
+- MIT-LICENSE
+- README.md
+homepage: https://github.com/rspec-api/rspec-api-expectations
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: 1.9.3
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: 1.3.6
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.1.10
+signing_key: 
+specification_version: 4
+summary: Expectations extracted from rspec-api to chech response of pragmatic RESTful
+  web APIs.
+test_files: []