json_expressions 0.5.0 → 0.6.0

data/README.md

@@ -3,7 +3,7 @@ JSON Expressions
 
 ## Introduction
 
-Your API is a contract between your service and your developers. Therefore it is important to know what exactly your JSON API is returning to the developers and make sure you don't accidentally change that contract without updating the documentations. Perhaps you should write some controller tests for your JSON endpoints:
+Your API is a contract between your service and your developers. It is important for you to know exactly what your JSON API is returning to the developers in order to make sure you don't accidentally change things without updating the documentations and/or bumping the API version number. Perhaps some controller tests for your JSON endpoints would help:
 
 ```ruby
 # MiniTest::Unit example
@@ -28,10 +28,15 @@ class UsersControllerTest < MiniTest::Unit::TestCase
     assert_kind_of Fixnum, posts[0]['id']
     assert_equal 'Hello world!', posts[0]['subject']
     assert_equal user_id, posts[0]['user_id']
+    assert_include posts[0]['tags'], 'announcement'
+    assert_include posts[0]['tags'], 'welcome'
+    assert_include posts[0]['tags'], 'introduction'
 
     assert_kind_of Fixnum, posts[1]['id']
-    assert_equal 'Hello world!', posts[1]['subject']
+    assert_equal 'An awesome blog post', posts[1]['subject']
     assert_equal user_id, posts[1]['user_id']
+    assert_include posts[0]['tags'], 'blog'
+    assert_include posts[0]['tags'], 'life'
   end
 end
 ```
@@ -58,15 +63,16 @@ Add it to your Gemfile:
 gem 'json_expressions'
 ```
 
-Then add this to your test/spec helper file:
-
+Add this to your test/spec helper file:
 ```ruby
-# MiniTest::Unit example
+# For MiniTest::Unit
 require 'json_expressions/minitest'
+
+# For RSpec
+require 'json_expressions/rspec'
 ```
 
 Which allows you to do...
-
 ```ruby
 # MiniTest::Unit example
 class UsersControllerTest < MiniTest::Unit::TestCase
@@ -75,28 +81,34 @@ class UsersControllerTest < MiniTest::Unit::TestCase
 
     # This is what we expect the returned JSON to look like
     pattern = {
-      'user' => {
-        'id'         => :user_id,                # "Capture" this value for later
-        'username'   => 'chancancode',           # Match this exact string
-        'full_name'  => 'Godfrey Chan',
-        'email'      => 'godfrey@example.com',
-        'type'       => 'Administrator',
-        'points'     => Fixnum,                  # Any integer value
-        'homepage'   => /\Ahttps?\:\/\/.*\z/i,   # Let's get serious
-        'created_at' => WILDCARD_MATCHER,        # Don't care as long as it exists
-        'updated_at' => WILDCARD_MATCHER,
-        'posts'      => [
+      user: {
+        id:         :user_id,                # "Capture" this value for later
+        username:   'chancancode',           # Match this exact string
+        full_name:  'Godfrey Chan',
+        email:      'godfrey@example.com',
+        type:       'Administrator',
+        points:     Fixnum,                  # Any integer value
+        homepage:   /\Ahttps?\:\/\/.*\z/i,   # Let's get serious
+        created_at: WILDCARD_MATCHER,        # Don't care as long as it exists
+        updated_at: WILDCARD_MATCHER,
+        posts:      [
           {
-            'id'      => Fixnum,
-            'subject' => 'Hello world!',
-            'user_id' => :user_id                # Match against the captured value
+            id:      Fixnum,
+            subject: 'Hello world!',
+            user_id: :user_id,               # Match against the captured value
+            tags:    [
+              'announcement',
+              'welcome',
+              'introduction'
+            ]                                    # Ordering of elements does not matter by default
           }.ignore_extra_keys!,                  # Skip the uninteresting stuff
           {
-            'id'      => Fixnum,
-            'subject' => 'An awesome blog post',
-            'user_id' => :user_id
+            id:      Fixnum,
+            subject: 'An awesome blog post',
+            user_id: :user_id,
+            tags:    ['blog' , 'life']
           }.ignore_extra_keys!
-        ].ordered!                               # Ensure they are returned in this exact order
+        ].ordered!                               # Ensure the posts are in this exact order
       }
     }
 
@@ -106,20 +118,35 @@ class UsersControllerTest < MiniTest::Unit::TestCase
     assert matcher.captures[:user_id] > 0
   end
 end
+
+# RSpec example
+describe UsersController, "#show" do
+  it "returns a user" do
+    pattern = # See above...
+
+    server_response = get '/users/chancancode.json'
+
+    server_response.body.should match_json_expression(pattern)
+  end
+end
 ```
 
+### `RSpec` Integration
+
+
+
 ### Basic Matching
 
 This pattern
 ```ruby
 {
-  'integer' => 1,
-  'float'   => 1.1,
-  'string'  => 'Hello world!',
-  'boolean' => true,
-  'array'   => [1,2,3],
-  'object'  => {'key1' => 'value1','key2' => 'value2'},
-  'null'    => nil,
+  integer: 1,
+  float:   1.1,
+  string:  'Hello world!',
+  boolean: true,
+  array:   [1,2,3],
+  object:  {key1: 'value1',key2: 'value2'},
+  null:    nil,
 }
 ```
 matches the JSON object
@@ -137,7 +164,7 @@ matches the JSON object
 
 ### Wildcard Matching
 
-You can use the WILDCARD_MATCHER to ignore keys that you don't care about (other than the fact that the key is included in the JSON).
+You can use the WILDCARD_MATCHER to ignore keys that you don't care about (other than the fact that they exist).
 
 This pattern
 ```ruby
@@ -148,17 +175,17 @@ matches the JSON array
 [ 1, 1.1, "Hello world!", true, [1,2,3], {"key1": "value1","key2": "value2"}, null]
 ```
 
-Furthermore, because the pattern is expressed in plain old Ruby code, you can also write:
+Furthermore, because the pattern is just plain old Ruby code, you can also write:
 ```ruby
 [ WILDCARD_MATCHER ] * 7
 ```
 
 ### Pattern Matching
 
-When an object `.respond_to? :match`, `match` will be called to match against the corresponding value in the JSON. Notably, this includes `Regexp` objects, which means you can use regular expressions in your pattern:
+When an object `.respond_to? :match`, `match` will be called to by json_expression to match against the corresponding value in the target JSON. Notably, `Regexp` objects responds to `match`, which means you can use regular expressions in your pattern:
 
 ```ruby
-{ 'hex' => /\A0x[0-9a-f]+\z/i }
+{ hex: /\A0x[0-9a-f]+\z/i }
 ```
 matches
 ```json
@@ -169,9 +196,9 @@ but not
 { "hex": "Hello world!" }
 ```
 
-Sometimes this behavior is undesirable. For instance, String#match(other) converts `other` into a `Regexp` and use that to match against itself, which is probably not what you want (`'Hello wolrd!'.match '' => #<MatchData "">`!).
+Sometimes this behavior is undesirable. For instance, String#match(other) converts `other` into a `Regexp` and use that to match against itself, which is probably not what you want (`''.match 'Hello world!' # => nil` but `'Hello world!'.match '' # => #<MatchData "">`!).
 
-You can specific a list of classes/modules with undesirable `match` behavior, and json_expression will fall back to calling `===` on them instead (see the section below for `===` vs `==`).
+You can specific a list of classes/modules with undesirable `match` behavior, and json_expression will fall back to calling `===` on these objects instead (see the section below for `===` vs `==`).
 
 ```ruby
 # This is the default setting
@@ -186,16 +213,16 @@ JsonExpressions::Matcher.skip_match_on = [ String ]
 
 ### Type Matching
 
-For objects that does not `respond_to? :match` or those you opt-ed out explicitly (such as `String`), `===` will be called to match against the corresponding value in the JSON. For most classes, this behaves identical to `==`. A notably exception would be `Module` (and by inheritance, `Class`) objects, which overrides `===` to mean `instance of`. You can exploit this behavior to do type matching:
+For objects that do not `respond_to? :match` or those you opt-ed out explicitly (such as `String`), `===` will be called instead. For most objects, it behaves identical to `==`. A notable exception would be `Module` (and by inheritance, `Class`) objects, which overrides `===` to mean `instance of`. You can exploit this behavior to do type matching:
 ```ruby
 {
-  'integer' => Fixnum,
-  'float'   => Float,
-  'string'  => String,
-  'boolean' => Boolean,
-  'array'   => Array,
-  'object'  => Hash,
-  'null'    => NilClass,
+  integer: Fixnum,
+  float:   Float,
+  string:  String,
+  boolean: Boolean,
+  array:   Array,
+  object:  Hash,
+  null:    NilClass,
 }
 ```
 matches the JSON object
@@ -226,12 +253,12 @@ JsonExpressions::Matcher.skip_triple_equal_on = [ ]
 
 ### Capturing
 
-Similar to how "capturs" work in Regex, you can capture the value of certain keys for later use:
+Similar to how "captures" work in Regexp, you can capture the value of certain keys for later use:
 ```ruby
 matcher = JsonExpressions::Matcher.new({
-  'key1' => :key1,
-  'key2' => :key2,
-  'key3' => :key3
+  key1: :key1,
+  key2: :key2,
+  key3: :key3
 })
 
 matcher =~ JSON.parse('{"key1":"value1", "key2":"value2", "key3":"value3"}') # => true
@@ -244,9 +271,9 @@ matcher.captures[:key3] # => "value3"
 If the same symbol is used multiple times, json_expression will make sure they agree. This pattern
 ```ruby
 {
-  'key1' => :capture_me,
-  'key2' => :capture_me,
-  'key3' => :capture_me
+  key1: :capture_me,
+  key2: :capture_me,
+  key3: :capture_me
 }
 ```
 matches
@@ -278,7 +305,7 @@ will match
 ```
 and
 ```ruby
-{ 'key1' => 'value1', 'key2' => 'value2' }
+{ key1: 'value1', key2: 'value2' }
 ```
 will match
 ```json
@@ -302,7 +329,7 @@ JsonExpressions::Matcher.assume_unordered_arrays = false
 JsonExpressions::Matcher.assume_unordered_hashes = false
 ```
 
-### Strictness
+### "Strictness"
 
 By default, all arrays and JSON objects (i.e. Ruby hashes) are assumed to be "strict". This means any extra elements or keys in the JSON target will cause the match to fail:
 ```ruby
@@ -314,7 +341,7 @@ will not match
 ```
 and
 ```ruby
-{ 'key1' => 'value1', 'key2' => 'value2' }
+{ key1: 'value1', key2: 'value2' }
 ```
 will not match
 ```json
@@ -324,20 +351,20 @@ will not match
 You can change this behavior in a case-by-case manner:
 ```ruby
 {
-  "strict_array"    => [1,2,3,4,5].strict!, # calling strict! is optional as it's the default
-  "forgiving_array" => [1,2,3,4,5].forgiving!,
-  "strict_hash"     => {'a'=>1, 'b'=>2}.strict!,
-  "forgiving_hash"  => {'a'=>1, 'b'=>2}.forgiving!
+  strict_array:    [1,2,3,4,5].strict!, # calling strict! is optional as it's the default
+  forgiving_array: [1,2,3,4,5].forgiving!,
+  strict_hash:     {'a'=>1, 'b'=>2}.strict!,
+  forgiving_hash:  {'a'=>1, 'b'=>2}.forgiving!
 }
 ```
 
 They also come with some more sensible aliases:
 ```ruby
 {
-  "strict_array"    => [1,2,3,4,5].reject_extra_values!,
-  "forgiving_array" => [1,2,3,4,5].ignore_extra_values!,
-  "strict_hash"     => {'a'=>1, 'b'=>2}.reject_extra_keys!,
-  "forgiving_hash"  => {'a'=>1, 'b'=>2}.ignore_extra_keys!
+  strict_array:    [1,2,3,4,5].reject_extra_values!,
+  forgiving_array: [1,2,3,4,5].ignore_extra_values!,
+  strict_hash:     {'a'=>1, 'b'=>2}.reject_extra_keys!,
+  forgiving_hash:  {'a'=>1, 'b'=>2}.ignore_extra_keys!
 }
 ```
 
@@ -348,9 +375,9 @@ JsonExpressions::Matcher.assume_strict_arrays = false
 JsonExpressions::Matcher.assume_strict_hashes = false
 ```
 
-## Testing Frameworks Support
+## Support for `MiniTest::Spec` (and other testing frameworks)
 
-The `Matcher` class itself is written in a testing-framework-agnostic manner. This allows you to easily write custom helpers/matchers for your favorite testing framework. Currently, the gem only ships with helpers for `MiniTest::Unit`. `MiniTest::Spec` and `RSpec` are on my TODO list, but it is not a high priority for me personally, as I currently don't use these frameworks actively in my projects. If you need this now, write it yourself (and submit a pull request) - it's really easy, I promise (see `lib/json_expressions/minitest/unit/helpers.rb` for inspiration).
+The `Matcher` class itself is written in a testing-framework-agnostic manner. This allows you to easily write custom helpers/matchers for your favorite testing framework. `MiniTest::Spec` is on my TODO list, but it is not a high priority for me personally, as I currently don't use it. If you need this now, write it yourself and submit a pull request - it's really easy, I promise (see `lib/json_expressions/minitest/unit/helpers.rb` for inspiration).
 
 ## Contributing
 

data/lib/json_expressions/core_extensions.rb

@@ -13,6 +13,14 @@ module JsonExpressions
       self.is_a? Unordered
     end
 
+    def ordered
+      self.clone.ordered!
+    end
+
+    def unordered
+      self.clone.unordered!
+    end
+
     def ordered!
       if self.unordered?
         raise "cannot mark an unordered #{self.class} as ordered!"
@@ -37,6 +45,14 @@ module JsonExpressions
       self.is_a? Forgiving
     end
 
+    def strict
+      self.clone.strict!
+    end
+
+    def forgiving
+      self.clone.forgiving!
+    end
+
     def strict!
       if self.forgiving?
         raise "cannot mark a forgiving #{self.class} as strict!"
@@ -57,12 +73,16 @@ end
 
 class Hash
   include JsonExpressions::CoreExtensions
+  alias_method :reject_extra_keys, :strict
   alias_method :reject_extra_keys!, :strict!
+  alias_method :ignore_extra_keys, :forgiving
   alias_method :ignore_extra_keys!, :forgiving!
 end
 
 class Array
   include JsonExpressions::CoreExtensions
+  alias_method :reject_extra_values, :strict
   alias_method :reject_extra_values!, :strict!
+  alias_method :ignore_extra_values, :forgiving
   alias_method :ignore_extra_values!, :forgiving!
 end

data/lib/json_expressions/matcher.rb

@@ -153,25 +153,25 @@ module JsonExpressions
 
       apply_hash_defaults matcher
 
-      missing_keys = matcher.keys - other.keys
-      extra_keys   = other.keys - matcher.keys
+      missing_keys = matcher.keys.map(&:to_s) - other.keys.map(&:to_s)
+      extra_keys   = other.keys.map(&:to_s) - matcher.keys.map(&:to_s)
 
       unless missing_keys.empty?
-        set_last_error path, "%path% does not contain the key #{missing_keys.first}"
+        set_last_error path, "%path% does not contain the key #{missing_keys.first.to_s}"
         return false
       end
 
       if matcher.strict? && ! extra_keys.empty?
-        set_last_error path, "%path% contains an extra key #{extra_keys.first}"
+        set_last_error path, "%path% contains an extra key #{extra_keys.first.to_s}"
         return false
       end
 
       if matcher.ordered? && matcher.keys != other.keys
-        set_last_error path, "Incorrect key-ordering at %path% (#{matcher.keys.inspect} expected but was #{other.keys.inspect})"
+        set_last_error path, "Incorrect key-ordering at %path% (#{matcher.keys.map(&:to_s).inspect} expected but was #{other.keys.map(&:to_s).inspect})"
         return false
       end
 
-      matcher.keys.all? { |k| match_json make_path(path,k), matcher[k], other[k] }
+      matcher.keys.all? { |k| match_json make_path(path,k), matcher[k] , other[k.to_s] || other[k.to_sym] }
     end
 
     def set_last_error(path, message)
@@ -180,11 +180,7 @@ module JsonExpressions
 
     def make_path(path, segment)
       if path
-        if segment.is_a? Fixnum
-          path + "[#{segment}]"
-        else
-          path + ".#{segment}"
-        end
+        segment.is_a?(Fixnum) ? path + "[#{segment}]" : path + ".#{segment.to_s}"
       end
     end
 

data/lib/json_expressions/minitest.rb

@@ -1,3 +1,4 @@
+require 'minitest'
 require 'json_expressions'
 require 'json_expressions/minitest/unit/helpers'
 

data/lib/json_expressions/minitest/unit/helpers.rb

@@ -13,7 +13,22 @@ module JsonExpressions
             assert act = JSON.parse(act), "Expected #{mu_pp(act)} to be valid JSON"
           end
 
-          assert exp =~ act, ->{exp.last_error}
+          assert exp =~ act, ->{ "Expected #{mu_pp(exp)} to match #{mu_pp(act)}\n" + exp.last_error}
+
+          # Return the matcher
+          return exp
+        end
+
+        def refute_json_match(exp, act, msg = nil)
+          unless JsonExpressions::Matcher === exp
+            exp = JsonExpressions::Matcher.new(exp)
+          end
+
+          if String === act
+            assert act = JSON.parse(act), "Expected #{mu_pp(act)} to be valid JSON"
+          end
+
+          refute exp =~ act, "Expected #{mu_pp(exp)} to not match #{mu_pp(act)}"
 
           # Return the matcher
           return exp

data/lib/json_expressions/rspec.rb

@@ -0,0 +1,7 @@
+require 'rspec'
+require 'json_expressions'
+require 'json_expressions/rspec/matchers'
+
+RSpec::configure do |config|
+  config.include(JsonExpressions::RSpec::Matchers)
+end

data/lib/json_expressions/rspec/matchers.rb

@@ -0,0 +1 @@
+require 'json_expressions/rspec/matchers/match_json_expression'

data/lib/json_expressions/rspec/matchers/match_json_expression.rb

@@ -0,0 +1,34 @@
+require 'json'
+
+module JsonExpressions
+  module RSpec
+    module Matchers
+      class MatchJsonExpression
+        def initialize(expected)
+          if JsonExpressions::Matcher === expected
+            @expected = expected
+          else
+            @expected = JsonExpressions::Matcher.new(expected)
+          end
+        end
+
+        def matches?(target)
+          @target = (String === target) ? JSON.parse(target) : target
+          @expected =~ @target
+        end
+
+        def failure_message_for_should
+          "expected #{@target.inspect} to match JSON expression #{@expected.inspect}\n" + @expected.last_error
+        end
+
+        def failure_message_for_should_not
+          "expected #{@target.inspect} not to match JSON expression #{@expected.inspect}"
+        end
+      end
+
+      def match_json_expression(expected)
+        MatchJsonExpression.new(expected)
+      end
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: json_expressions
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-07-10 00:00:00.000000000 Z
+date: 2012-07-11 00:00:00.000000000 Z
 dependencies: []
 description: JSON matchmaking for all your API testing needs.
 email:
@@ -22,6 +22,9 @@ files:
 - lib/json_expressions/matcher.rb
 - lib/json_expressions/minitest/unit/helpers.rb
 - lib/json_expressions/minitest.rb
+- lib/json_expressions/rspec/matchers/match_json_expression.rb
+- lib/json_expressions/rspec/matchers.rb
+- lib/json_expressions/rspec.rb
 - lib/json_expressions.rb
 - README.md
 - LICENSE