restful-matchers 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fa23bf113f67c1d2ebcec7749f06a5297fe44ad0
-  data.tar.gz: 2ef8175345a2c7abc59b4f3cc2a0f00b3bcb9bdd
+  metadata.gz: 1ebf655f0413ddd8082f291573ce0072759b5578
+  data.tar.gz: 60d70c76fdc3491752fec9639bfc87129b759b04
 SHA512:
-  metadata.gz: e694f1dfa908ccdb0292d6f8ffb0c04ce130ee345072c7640ebed3cf2afed1993e2637bd93fb2965c8b93cfd38e76cfd7680684d3ec79c8a6f970db5efb54f4f
-  data.tar.gz: 23bac76446ef247fdcf053e98d65032bca1245b1d6f21b53b0d2eaaf1742bee9fe41730a4cb3a1c419c752336515642e4f673b33652164eed052d2aac92da999
+  metadata.gz: 94c24744350d3810781943ea6e4c6db4029c8fbc82a8fab38ce65d65b31daca232d8fdf0cbf6b039a0b95365b0f9d952a5836ca290bd17063cc15bc3c915fbb2
+  data.tar.gz: 73146b6bae167a0443c4cb072220bab85b9b07c39c8a59906ffa9648c70f8d607fd89b8e247a405758d62bdd4e653cc33d9ced3a9702cb2e841bc486892bb7f3

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+# HEAD
+nothing yet.
+
+# v0.3.0
+* New matcher `have_links` to match many links at once.
+
+# v0.2.1
+* Show matched content on failure;
+
+# v0.2.0
+* Process both raw and parsed (hash) JSON representations;
+* Attribute `href` is now optional;
+* `have_restful_json_link` is an alias for `have_link` matcher (preffered).
+
+# v0.1
+* Initial version with `have_restful_json_link` matcher.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    restful-matchers (0.2.1)
+    restful-matchers (0.3.0)
       rspec (~> 2.0)
 
 GEM
@@ -26,9 +26,6 @@ GEM
       diff-lcs (>= 1.1.3, < 2.0)
     rspec-mocks (2.14.3)
     slop (3.4.6)
-    step-up (0.9.1)
-      thor (>= 0.14.6)
-    thor (0.18.1)
 
 PLATFORMS
   ruby
@@ -39,4 +36,3 @@ DEPENDENCIES
   pry-nav (~> 0.2)
   rake (~> 10.1)
   restful-matchers!
-  step-up (~> 0.9)

data/README.md

@@ -5,32 +5,47 @@ RSpec matchers to test RESTful HATEOAS-compliant resource links. Currently it su
 
 ## Usage
 
-Given the following JSON response:
+Let's say we have a `MyRestfulController#index` controller action that returns the following JSON representation, with links represented as an array of `{rel: ... , href: ...}` objects:
 
 ```json
 {
   "attribute1": "value1",
   "attribute2": "value2",
   "links": [
-    { "rel": "self", "href": "http://example.com" }
+    { "rel": "foo", "href": "http://example.com/foo" }
+    { "rel": "bar", "href": "http://example.com/bar" }
+    { "rel": "baz", "href": "http://example.com/baz" }
+    { "rel": "qux", "href": "http://example.com/qux" }
   ]
 }
 ```
 
-You can match links represented as an array of `{rel: ... , href: ...}` objects named as `links`:
+You can match those links using `have_link` or `have_links` matchers as follow:
 
 ```ruby
 describe MyRestfulController do
-  render_views
+  render_views # don't forget this!
 
   it "should have links" do
     get :index
     
-    response.body.should have_link "resource1", "http://example.com/resource1"
-    response.body.should have_link "resource2", "http://example.com/resource1"
+    # you can match against both raw ...
+    response.body.should have_link "foo", "http://example.com/foo"
+    response.body.should have_link "bar", "http://example.com/bar"
 
-    parsed_json = JSON.parse(response.body) # you can match both raw or parsed (hash) JSON
-    parsed_json.should have_link "self"     # href attribute is optional
+    # ... or parsed JSON (as a Hash)
+    parsed_json = JSON.parse(response.body)
+
+    # href attribute is optional
+    parsed_json.should have_link "baz"
+
+    # match many links at once using have_links matcher
+    response.body.should have_links([
+      { rel: "foo", href: "http://example.com/foo" },
+      { rel: "bar", href: "http://example.com/bar" },
+      { rel: "baz", href: "http://example.com/baz" },
+      { rel: "qux", href: "http://example.com/qux" },
+    ])
   end
 end
 ```
@@ -42,3 +57,11 @@ Add it to the `test` group in your Gemfile and be happy!
 ```ruby
 gem 'restful-matchers', '~> 0.2', :group => :test
 ```
+
+## Changelog
+
+See [CHANGELOG](https://github.com/marcoshack/restful-matchers/blob/master/CHANGELOG.md).
+
+## License
+
+restful-matchers is Copyright © 2013 Marcos Hack. It is free software, and may be redistributed under the terms specified in the LICENSE file.

data/lib/restful/matchers.rb

@@ -1,4 +1,7 @@
+require "restful/matchers/errors"
+require "restful/matchers/parsers"
 require "restful/matchers/have_link"
+require "restful/matchers/have_links"
 
 if defined?(RSpec)
   require 'restful/matchers/integrations/rspec'

data/lib/restful/matchers/errors.rb

@@ -0,0 +1,2 @@
+ERRORS_DIR = File.expand_path(File.join(File.dirname(__FILE__), 'errors')).freeze
+Dir[File.join(ERRORS_DIR, '**', '*.rb')].each { |file| require(file) }

data/lib/restful/matchers/errors/invalid_link.rb

@@ -0,0 +1,7 @@
+module RESTful
+  module Matchers
+    module Errors
+      class InvalidLink < StandardError; end
+    end
+  end
+end

data/lib/restful/matchers/have_link.rb

@@ -1,11 +1,13 @@
 require 'json'
+require 'restful/matchers/parsers'
 
 module RESTful
   module Matchers
     # Ensures that JSON response body has the given link.
     #
     # Example:
-    #   response.body.should have_json_link("self", "http://example.com")
+    #
+    #     response.body.should have_json_link("self", "http://example.com")
     #
     def have_link(rel, href = nil)
       HaveLink.new(rel, href)
@@ -20,7 +22,7 @@ module RESTful
 
       def matches?(content)
         @content = content
-        if links = parse_links_from(content)
+        if links = RESTful::Matchers::Parsers::JSONLinkParser.parse(content)
           return @href ? links[@rel] == @href : links.has_key?(@rel)
         else
           return false
@@ -39,16 +41,6 @@ module RESTful
       def error_message(message)
         "#{message} '{\"rel\": \"#{@rel}\", \"href\": \"#{@href || "<any>" }\"}' in '#{@content}'" 
       end
-
-      def parse_links_from(content)
-        json =  content.is_a?(Hash) ? content : JSON.parse(content)
-        links = nil
-        if json["links"]
-          links = {}
-          json["links"].each { |link| links[link["rel"]] = link["href"] }
-        end
-        return links
-      end
     end
   end
 end

data/lib/restful/matchers/have_links.rb

@@ -0,0 +1,68 @@
+require 'json'
+require 'restful/matchers/parsers'
+
+module RESTful
+  module Matchers
+    # Ensures that JSON response body has the given links, represented as an
+    # array of hashes with `rel` and `href` keys.
+    #
+    # Example:
+    #
+    #     response.body.should have_links([
+    #       { rel: "self", href: "http://example.com"     },
+    #       { rel: "foo" , href: "http://example.com/foo" },
+    #       { rel: "bar" , href: "http://example.com/bar" }
+    #     ])
+    #
+    def have_links(links)
+      HaveLinks.new(links)
+    end
+
+    class HaveLinks
+      def initialize(links)
+        @match_links = {}
+
+        if links.is_a?(Array)
+          links.each do |link|
+            rel  = link[:rel]  || link["rel"]
+            href = link[:href] || link["href"]
+            if rel
+              @match_links[rel.to_s] = href
+            else
+              raise ::Errors::InvalidLink("Link has no `rel`: #{link}")
+            end
+          end
+        else
+          raise ArgumentError.new("matcher expects an array of hashes containing `rel` and `href` keys as argument")
+        end
+      end
+
+      def matches?(content)
+        @content = content
+        @content_links = RESTful::Matchers::Parsers::JSONLinkParser.parse(content)
+        if @content_links
+          @content_links.each do |rel, href|
+            match = href ? @match_links[rel] == href : @match_links.has_key?(rel)
+            return false unless match
+          end
+          return true
+        else
+          return false
+        end
+      end
+
+      def failure_message_for_should
+        "Expected links weren't found. #{content_and_match_links_message}"
+      end
+
+      def failure_message_for_should_not
+        "Not expected links where found. #{content_and_match_links_message}"
+      end
+
+      private
+      def content_and_match_links_message
+        "Expect '#{@match_links}', but got '#{@content_links}'."
+      end
+    end
+  end
+end

data/lib/restful/matchers/parsers.rb

@@ -0,0 +1,2 @@
+PARSERS_DIR = File.expand_path(File.join(File.dirname(__FILE__), 'parsers')).freeze
+Dir[File.join(PARSERS_DIR, '**', '*.rb')].each { |file| require(file) }

data/lib/restful/matchers/parsers/json_link_parser.rb

@@ -0,0 +1,17 @@
+module RESTful
+  module Matchers
+    module Parsers
+      module JSONLinkParser
+        def self.parse(content)
+          json =  content.is_a?(Hash) ? content : JSON.parse(content)
+          links = nil
+          if json["links"]
+            links = {}
+            json["links"].each { |link| links[link["rel"]] = link["href"] }
+          end
+          return links
+        end
+      end
+    end
+  end
+end

data/lib/restful/matchers/version.rb

@@ -0,0 +1,5 @@
+module RESTful
+  module Matchers
+    VERSION = "0.3.0".freeze
+  end
+end

data/restful-matchers.gemspec

@@ -1,9 +1,10 @@
-# encoding: utf-8
+$LOAD_PATH << File.join(File.dirname(__FILE__), 'lib')
+require 'restful/matchers/version'
 
 Gem::Specification.new do |gem|
-  gem.name    = "restful-matchers"
-  gem.version = "0.2.1"
-
+  gem.name        = "restful-matchers"
+  gem.version     = RESTful::Matchers::VERSION.dup
+  gem.date        = Time.now.strftime("%Y-%m-%d")
   gem.authors     = [ "Marcos Hack" ]
   gem.email       = [ "marcoshack@gmail.com" ]
   gem.summary     = "RSpec matchers to test RESTful HATEOAS-compliant resource links."
@@ -11,10 +12,12 @@ Gem::Specification.new do |gem|
   gem.homepage    = "https://github.com/marcoshack/restful-matchers"
   gem.license     = "MIT"
 
+  gem.files         = `git ls-files`.split("\n")
+  gem.test_files    = `git ls-files -- {spec}/*`.split("\n")
+  gem.require_paths = ["lib"]
+
+  gem.required_ruby_version = '>= 1.9.2'
+
   gem.add_dependency "rspec", "~> 2.0"
   gem.add_development_dependency "bundler", "~> 1.0"
-
-  gem.files         = `git ls-files`.split($\)
-  gem.test_files    = gem.files.grep(/^(test)/)
-  gem.require_paths = ["lib"]
 end

data/spec/fixtures/json/resource_with_links.json

@@ -0,0 +1,9 @@
+{
+  "attr1": "value1",
+  "attr2": "value2",
+  "links": [
+    { "rel": "self", "href": "http://example.com" },
+    { "rel": "foo", "href": "http://example.com/foo" },
+    { "rel": "bar", "href": "http://example.com/bar" }
+  ]
+}

data/spec/restful/matchers/have_link_spec.rb

@@ -2,30 +2,18 @@ require 'spec_helper'
 
 describe RESTful::Matchers::HaveLink do
 
-  shared_examples_for "Matcher" do
-    it "should find a json link" do
-      @content.should have_restful_json_link("self", "http://example.com")
-      @content.should have_link("self", "http://example.com")
-    end
+  before(:each) { @content = open("spec/fixtures/json/resource_with_links.json").read }
 
-    it "should not find an unexistant link" do
-      @content.should_not have_restful_json_link("foo", "http://bar.com")
-      @content.should_not have_link("foo", "http://bar.com")
-    end
-
-    it "should find a link matching only the rel attribute" do
-      @content.should have_link("self")
-    end
+  it "should match a valid link" do
+    @content.should have_link("self", "http://example.com")
   end
 
-  context "when processing a JSON content" do
-    before(:each) { @content = open("spec/fixtures/json/resource.json").read }
-    it_behaves_like "Matcher"
+  it "should not match a non-existing link" do
+    @content.should_not have_link("foo", "http://bar.com")
   end
 
-  context "when processing a parsed JSON" do
-    before(:each) { @content = JSON.parse(open("spec/fixtures/json/resource.json").read) }
-    it_behaves_like "Matcher"
+  it "should match only by rel attribute" do
+    @content.should have_link("self")
   end
 
   it "should show matched content on fail" do

data/spec/restful/matchers/have_links_spec.rb

@@ -0,0 +1,38 @@
+require 'spec_helper'
+
+describe RESTful::Matchers::HaveLinks do
+
+  context "when processing a valid JSON with links" do
+    let(:content) { open("spec/fixtures/json/resource_with_links.json").read }
+
+    it "should match an array of links using symbols as keys" do
+      content.should have_links([
+        { rel: "self", href: "http://example.com"     },
+        { rel: "foo" , href: "http://example.com/foo" },
+        { rel: "bar" , href: "http://example.com/bar" }
+      ])
+    end
+
+    it "should match an array of links using string as keys" do
+      content.should have_links([
+        { "rel" => "self", "href" => "http://example.com"     },
+        { "rel" => "foo" , "href" => "http://example.com/foo" },
+        { "rel" => "bar" , "href" => "http://example.com/bar" }
+      ])
+    end
+
+    it "should not match an empty array" do
+      content.should_not have_links []
+    end
+
+    it "should fail to match an empty array" do
+      expect { content.should have_links [] }.to raise_error(/.*Expect '{}'.*/)
+    end
+
+    it "should fail to match an invalid argument" do
+      [ 1, "", {}, :a_symbol, nil ].each do |value|
+        expect { content.should have_links value }.to raise_error(ArgumentError)
+      end
+    end
+  end
+end

data/spec/restful/parsers/json_link_parser_spec.rb

@@ -0,0 +1,24 @@
+require 'spec_helper'
+require 'restful/matchers/parsers/json_link_parser'
+
+describe RESTful::Matchers::Parsers::JSONLinkParser do
+  shared_examples_for "parser" do
+    it "should parser links" do
+      links = RESTful::Matchers::Parsers::JSONLinkParser.parse(content)
+      links.keys.should include "self", "foo", "bar"
+      links["self"].should == "http://example.com"
+      links["foo" ].should == "http://example.com/foo"
+      links["bar" ].should == "http://example.com/bar"
+    end
+  end
+
+  context "when parsing raw JSON" do
+    let(:content) { open("spec/fixtures/json/resource_with_links.json").read }
+    it_behaves_like "parser"
+  end
+
+  context "when parsing parsed JSON" do
+    let(:content) { JSON.parse(open("spec/fixtures/json/resource_with_links.json").read) }
+    it_behaves_like "parser"
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: restful-matchers
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Marcos Hack
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-08-21 00:00:00.000000000 Z
+date: 2013-08-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -49,6 +49,7 @@ extra_rdoc_files: []
 files:
 - .gitignore
 - .travis.yml
+- CHANGELOG.md
 - Gemfile
 - Gemfile.lock
 - LICENSE
@@ -56,11 +57,19 @@ files:
 - Rakefile
 - lib/restful-matchers.rb
 - lib/restful/matchers.rb
+- lib/restful/matchers/errors.rb
+- lib/restful/matchers/errors/invalid_link.rb
 - lib/restful/matchers/have_link.rb
+- lib/restful/matchers/have_links.rb
 - lib/restful/matchers/integrations/rspec.rb
+- lib/restful/matchers/parsers.rb
+- lib/restful/matchers/parsers/json_link_parser.rb
+- lib/restful/matchers/version.rb
 - restful-matchers.gemspec
-- spec/fixtures/json/resource.json
+- spec/fixtures/json/resource_with_links.json
 - spec/restful/matchers/have_link_spec.rb
+- spec/restful/matchers/have_links_spec.rb
+- spec/restful/parsers/json_link_parser_spec.rb
 - spec/spec_helper.rb
 homepage: https://github.com/marcoshack/restful-matchers
 licenses:
@@ -74,7 +83,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - '>='
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.9.2
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - '>='

data/spec/fixtures/json/resource.json

@@ -1,7 +0,0 @@
-{
-  "attr1": "value1",
-  "attr2": "value2",
-  "links": [
-    { "rel": "self", "href": "http://example.com" }
-  ]
-}