rspec-hal 1.3.2 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 85d20df14665e358ca885f51e704037f76921549
-  data.tar.gz: 34be55d63db57e860c59f58414a7cc1327a188e2
+  metadata.gz: 1c835ecfb6c798d5dfb5c41101dd5c61cde75c1e
+  data.tar.gz: ab13e80124286588ddc088a3ff1cb773544a84d8
 SHA512:
-  metadata.gz: 3160252d521538cbcb3cce0119edf2265104a33ca03eb1fb0d55ab8d4fb4f3961ed64102400e5c657a9224b36176272b88d73267d163ffa490c18bfefcb30b77
-  data.tar.gz: 3d28dade0333bf9732bd6ff535ae25b542a2b922eb7f2dc9642d9fa283de1db342ac92c5503a6baefa0c23d7d2c08866014a6ce23e520c71fc0f787f68cbb0b7
+  metadata.gz: 2e3fd356bb643b6dd6ac9edcc16dfea03bee88fe2cca2039b6a75709ebd340be389b035e6ebd623fe56ea12c6498bd3de52a53831ee7deb97544ff5a4ea5ab4f
+  data.tar.gz: a08fd297f02eb699afaa48b3298aedb14603d3c7fe1e45441de4c633e45d24b70bb6f78550eb1f9ce15608a5923f17ef5ea81b7058600c318a0844206104ac35

data/README.md

@@ -7,37 +7,55 @@ Provides matchers and convenience methods for verifying HAL documents.
 
 ## Usage
 
-Include the matchers by adding this to your spec_helper
+Given the following string stored in `a_user_doc`.
+
+```json
+ {
+   "name": "Alice",
+   "hobbies": [{"name": "Basketball", "type": "sport"},
+               {"name": "Basket weaving", "type": "craft"}],
+   "_links": {
+     "self": { "href": "http://example.com/alice" },
+     "knows": [{ "href": "http://example.com/bob" },
+               { "href": "http://example.com/jane" }],
+     "checkBusy": { "href": "http://example.com/is_alice_busy{?at}",
+                    "templated": true }
+   }
+ }
+```
+
+Rspec Hal allows very expressive validation of documents.
 
 ```ruby
-RSpec.configuration.include RSpec::Hal::Matchers
-```
+    expect(a_user_doc).to be_hal
 
-(Don't forget to `require "rspec-hal"` if you are not using bundler.)
+    expect(a_user_doc).not_to be_hal_collection
+
+    expect(a_user_doc).to have_property "name"
+    expect(a_user_doc).to have_property 'name', eq("Alice")
+    expect(a_user_doc).to have_property :name, matching(/ice$/)
+    expect(a_user_doc).to have_property 'hobbies', including(a_hash_including('type' => 'sport'))
 
-If you are using rspec-rails and want only include the matchers for views do this
+    expect(a_user_doc).to have_relation "knows"
+    expect(a_user_doc).to have_relation "knows", eq("http://example.com/jane")
 
-```ruby
-RSpec.configuration.include RSpec::Hal::Matchers, type: 'view'
+    expect(a_user_doc).to have_templated_relation "checkBusy"
+    expect(a_user_doc).to have_templated_relation "checkBusy", with_variable("at")
+    expect(a_user_doc).to have_templated_relation("checkBusy").with_variables("at")
+
+    expect(parse_hal(users_collection_doc).first).to have_property "name"
 ```
 
-Once you have the matchers included you can use it like this
+Any matcher (actually anything that responds to `#===`) can
+be passed as the second argument and will be used to verify the
+property value or the link href.
 
-```ruby
-    expect(a_user_doc).to be_hal
+`be_hal_collection` checks that the document is both a valid HAL
+document and is a page of an RFC 6573 collection
 
-    expect(first_page_of_users).to be_hal_collection
+`be_hal` checks that the document is both a valid HAL
+document.
 
-    expect(a_user_doc).to have_property "name"
-    expect(a_user_doc).to have_property('name').matching(/ice$/)
-    expect(a_user_doc).to have_property('name').matching(end_with('ice'))
-    expect(a_user_doc).to have_property('hobbies')
-      .including(a_hash_including('type' => 'sport'))
-
-    expect(a_user_doc).to have_relation('tag')
-    expect(a_user_doc).to have_templated_relation("search")
-    expect(a_user_doc).to have_templated_relation("search").with_variables("q", "limit")
-```
 
 ## Installation
 
@@ -53,6 +71,24 @@ Or install it yourself as:
 
     $ gem install rspec-hal
 
+Then include the matchers by adding this to your spec_helper
+
+```ruby
+RSpec.configuration.include RSpec::Hal::Matchers
+RSpec.configuration.include RSpec::Hal::Helpers
+```
+
+(Don't forget to `require "rspec-hal"` if you are not using bundler.)
+
+If you want to only include the matchers for certain type of specs
+(say, view specs for example)
+
+```ruby
+RSpec.configuration.include RSpec::Hal::Matchers, type: 'view'
+RSpec.configuration.include RSpec::Hal::Helpers, type: 'view'
+```
+
+
 ## Contributing
 
 1. Fork it ( http://github.com/pezra/rspec-hal/fork )

data/lib/rspec/hal.rb

@@ -3,5 +3,6 @@ require "rspec/hal/version"
 module RSpec
   module Hal
     autoload :Matchers, "rspec/hal/matchers"
+    autoload :Helpers,  "rspec/hal/helpers"
   end
 end

data/lib/rspec/hal/helpers.rb

@@ -0,0 +1,32 @@
+module RSpec
+  module Hal
+    module Helpers
+      # Returns HalClient::Representation for `jsonish` (or
+      # HalClient::Collection if `jsonish` is a RFC 6573 collection)
+      #
+      # jsonish - A HAL document (as a string or pre-parsed hash) or
+      #   an object that can be converted into one via its `#to_hal`
+      #   or `#to_json` methods.
+      def parse_hal(jsonish)
+        json = if jsonish.kind_of? String
+                 jsonish
+
+               elsif jsonish.respond_to? :to_hal
+                 jsonish.to_hal
+
+               else jsonish.respond_to? :to_json
+                 jsonish.to_json
+               end
+
+        repr = HalClient::Representation.new(parsed_json: MultiJson.load(json))
+
+        if repr.has_related? "item"
+          HalClient::Collection.new(repr)
+        else
+          repr
+        end
+      end
+
+    end
+  end
+end

data/lib/rspec/hal/matchers.rb

@@ -51,18 +51,15 @@ module RSpec
       # Signature
       #
       #  expect(a_uri_template_str).to have_variables "q", "limit"
-      def have_variables(*args)
-        UriTemplateHasVariablesMatcher.new(*args)
-      end
-
-      # Signature
-      #
       #  expect(a_uri_template_str).to has_variable "q"
-      def has_variable(*args)
+      def have_variables(*args)
         UriTemplateHasVariablesMatcher.new(*args)
       end
+      alias_method :has_variable,   :have_variables
+      alias_method :with_variables, :have_variables
+      alias_method :with_variable,  :have_variables
 
-      module Document
+      module DocumentMatchers
         extend RSpec::Matchers::DSL
 
         # Provide a 3.0 compatible DSL methods for 2.x RSpec.
@@ -97,10 +94,12 @@ module RSpec
           failure_message do |a_json_doc|
             message = begin
                         JSON.load(a_json_doc)
-                      rescue err
+                      rescue => err
                         err.message
                       end
-            message + " while parsing:\n" + a_json_doc
+
+            "Expected a HAL document but it wasn't because #{message} in:\n" +
+              a_json_doc
           end
         end
 
@@ -122,7 +121,8 @@ module RSpec
           end
         end
       end
-      include Document
+
+      include DocumentMatchers
     end
   end
 end

data/lib/rspec/hal/matchers/hal_matcher_helpers.rb

@@ -2,6 +2,9 @@ module RSpec
   module Hal
     module Matchers
       module HalMatcherHelpers
+
+        # A matcher that always matches. Useful for avoiding special
+        # cases in value testing logic.
         NullMatcher = Class.new do
           def matches?(*args)
             true
@@ -58,16 +61,20 @@ module RSpec
           HalClient::Representation.new(parsed_json: MultiJson.load(json))
         end
 
+        # Returns `expected` coerced into an RSpec matcher
         def matcherize(expected)
           if matcher? expected
             expected
-          elsif expected.kind_of? Regexp
+
+          elsif expected.respond_to? :===
             RSpec::Matchers::BuiltIn::Match.new(expected)
+
           else
             RSpec::Matchers::BuiltIn::Eq.new(expected)
           end
         end
 
+        # Returns true if object is an RSpec matcher
         def matcher?(obj)
           obj.respond_to?(:matches?) and (obj.respond_to?(:failure_message) or
                                           obj.respond_to?(:failure_message_for_should))

data/lib/rspec/hal/matchers/have_property_matcher.rb

@@ -11,7 +11,7 @@ module RSpec
         include HalMatcherHelpers
 
         def initialize(property_name, expected=NullMatcher)
-          @prop_name = property_name
+          @prop_name = property_name.to_s
           @expected = matcherize expected
         end
 

data/lib/rspec/hal/matchers/relation_matcher.rb

@@ -17,7 +17,7 @@ module RSpec
         #     expect(doc).to have_relation link_rel, template_variables
         #     expect(doc).to have_relation link_rel, template_variables, href_matcher
         def initialize(link_rel, *args)
-          @link_rel = link_rel
+          @link_rel = link_rel.to_s
 
           @tmpl_vars, @expected = *if args.empty?
                                      [{},NullMatcher]

data/lib/rspec/hal/matchers/templated_relation_matcher.rb

@@ -14,7 +14,7 @@ module RSpec
         include HalMatcherHelpers
 
         def initialize(link_rel, expected=NullMatcher)
-          @link_rel = link_rel
+          @link_rel = link_rel.to_s
           @expected = expected
         end
 

data/lib/rspec/hal/matchers/uri_template_has_variables_matcher.rb

@@ -6,7 +6,7 @@ module RSpec
     module Matchers
       class UriTemplateHasVariablesMatcher
         def initialize(vars)
-          @expected_vars = Set.new(vars)
+          @expected_vars = Set.new(vars.map(&:to_s))
         end
 
         def matches?(actual)

data/lib/rspec/hal/version.rb

@@ -1,5 +1,5 @@
 module RSpec
   module Hal
-    VERSION = "1.3.2"
+    VERSION = "1.4.0"
   end
 end

data/spec/rspec/hal/helpers_spec.rb

@@ -0,0 +1,25 @@
+require_relative "../../spec_helper"
+require "rspec/version"
+
+describe RSpec::Hal::Helpers do
+  subject { Class.new do
+      include RSpec::Hal::Helpers
+    end.new }
+
+  specify { expect(subject.parse_hal(hal_doc)).to be_kind_of HalClient::Representation  }
+  specify { expect(subject.parse_hal(hal_collection)).to be_kind_of HalClient::Collection  }
+
+  # Background/Support
+  # ---
+
+  let(:hal_collection) { <<-HAL }
+    { "_embedded": { "item": [
+          #{hal_doc}
+    ]}}
+  HAL
+
+  let(:hal_doc) { <<-HAL }
+    { "name": "Alice"
+    }
+  HAL
+end

data/spec/rspec/hal/matchers/have_property_matcher_spec.rb

@@ -88,6 +88,13 @@ describe RSpec::Hal::Matchers::HavePropertyMatcher do
     specify { expect(matcher.failure_message).to match(/eq "hector"/) }
   end
 
+  context "name as symbol" do
+    subject(:matcher) { described_class.new(a_prop_name.to_sym) }
+
+    specify { expect(matcher.matches?(json_str_w_property)).to be_truthy}
+    specify { expect(matcher.matches?(json_str_wo_property)).to be_falsey}
+  end
+
 
   # Background
   # ---

data/spec/rspec/hal/matchers/relation_matcher_spec.rb

@@ -13,6 +13,13 @@ describe RSpec::Hal::Matchers::RelationMatcher do
   specify{ expect(matcher.matches?(json_str_w_link)).to be_truthy }
   specify{ expect(matcher.matches?(json_str_wo_link)).to be_falsey }
 
+  context "name as symbol" do
+    subject(:matcher) { described_class.new(a_link_rel.to_sym) }
+
+    specify{ expect(matcher.matches?(json_str_w_link)).to be_truthy }
+    specify{ expect(matcher.matches?(json_str_wo_link)).to be_falsey }
+  end
+
   context "curries" do
     let(:a_link_rel) { "http://example.com/rels/foo" }
     specify{ expect(matcher.matches?(json_str_w_curied_link)).to be_truthy }
@@ -78,7 +85,6 @@ describe RSpec::Hal::Matchers::RelationMatcher do
     specify{ expect(matcher.matches? json_str_w_link).to be_falsy }
   end
 
-
   context "failed due to missing relation matcher" do
     before do
       matcher.matches? json_str_wo_link

data/spec/rspec/hal/matchers/templated_relation_matcher_spec.rb

@@ -26,6 +26,13 @@ describe RSpec::Hal::Matchers::TemplatedRelationMatcher do
   specify { expect(matcher.with_variables("since", "before")).to be_a_matcher }
   specify { expect(matcher.with_variable("since")).to be_a_matcher }
 
+  context "symbol rel name" do
+    subject(:matcher) { described_class.new(a_link_rel.to_sym) }
+
+    specify{ expect(matcher.matches?(json_str_w_link)).to be }
+    specify{ expect(matcher.matches?(json_str_wo_link)).not_to be }
+  end
+
   context "failed due to missing relation matcher" do
     before do
       matcher.matches? json_str_wo_link

data/spec/rspec/hal/matchers/uri_template_has_variables_matcher_spec.rb

@@ -13,6 +13,13 @@ describe RSpec::Hal::Matchers::UriTemplateHasVariablesMatcher do
   specify { expect(matcher.matches?("http://example.com{?foo}")).to be_falsy }
   specify { expect(matcher.description).to match /foo, bar/ }
 
+  context "names as symbol" do
+    subject(:matcher) { described_class.new([:foo, :bar]) }
+
+    specify { expect(matcher.matches?("http://example.com{?foo,bar}")).to be_truthy }
+    specify { expect(matcher.matches?("http://example.com{?foo}")).to be_falsy }
+  end
+
   describe "failed matcher" do
     before do matcher.matches?("http://example.com{?foo}") end
 

data/spec/rspec/hal/matchers_spec.rb

@@ -22,12 +22,18 @@ describe RSpec::Hal::Matchers do
   end
 end
 
-describe RSpec::Hal::Matchers::Document do
+describe RSpec::Hal::Matchers::DocumentMatchers do
   describe "be_hal" do
     subject(:matcher) { be_hal }
 
     specify { expect(matcher.matches?(hal_doc)).to be_truthy }
     specify { expect(matcher.matches?("What's HAL?")).to be_falsey }
+
+    context "failed matcher" do
+      before do matcher.matches?("What's HAL?") end
+
+      specify { expect(matcher.failure_message).to match "unexpected token" }
+    end
   end
 
   describe "be_hal_collection" do
@@ -39,7 +45,7 @@ describe RSpec::Hal::Matchers::Document do
   end
 
   before do
-    extend RSpec::Hal::Matchers::Document
+    extend described_class
   end
 
   let(:hal_collection) { <<-HAL }

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rspec-hal
 version: !ruby/object:Gem::Version
-  version: 1.3.2
+  version: 1.4.0
 platform: ruby
 authors:
 - Peter Williams
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-08-14 00:00:00.000000000 Z
+date: 2014-11-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -109,6 +109,7 @@ files:
 - gemfiles/rspec3_0.gemfile
 - lib/rspec-hal.rb
 - lib/rspec/hal.rb
+- lib/rspec/hal/helpers.rb
 - lib/rspec/hal/matchers.rb
 - lib/rspec/hal/matchers/hal_matcher_helpers.rb
 - lib/rspec/hal/matchers/have_property_matcher.rb
@@ -117,6 +118,7 @@ files:
 - lib/rspec/hal/matchers/uri_template_has_variables_matcher.rb
 - lib/rspec/hal/version.rb
 - rspec-hal.gemspec
+- spec/rspec/hal/helpers_spec.rb
 - spec/rspec/hal/matchers/have_property_matcher_spec.rb
 - spec/rspec/hal/matchers/relation_matcher_spec.rb
 - spec/rspec/hal/matchers/templated_relation_matcher_spec.rb
@@ -148,9 +150,11 @@ signing_key:
 specification_version: 4
 summary: Matchers and helpers for specing HAL documents.
 test_files:
+- spec/rspec/hal/helpers_spec.rb
 - spec/rspec/hal/matchers/have_property_matcher_spec.rb
 - spec/rspec/hal/matchers/relation_matcher_spec.rb
 - spec/rspec/hal/matchers/templated_relation_matcher_spec.rb
 - spec/rspec/hal/matchers/uri_template_has_variables_matcher_spec.rb
 - spec/rspec/hal/matchers_spec.rb
 - spec/spec_helper.rb
+has_rdoc: