json_expressions 0.5.0

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2012 Godfrey Chan
+
+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,361 @@
+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:
+
+```ruby
+# MiniTest::Unit example
+class UsersControllerTest < MiniTest::Unit::TestCase
+  def test_get_a_user
+    server_response = get '/users/chancancode.json'
+
+    json = JSON.parse server_response.body
+
+    assert user = json['user']
+
+    assert user_id = user['id']
+    assert_equal 'chancancode', user['username']
+    assert_equal 'Godfrey Chan', user['full_name']
+    assert_equal 'godfrey@example.com', user['email']
+    assert_equal 'Administrator', user['type']
+    assert_kind_of Fixnum, user['points']
+    assert_match /\Ahttps?\:\/\/.*\z/i, user['homepage']
+
+    assert posts = user['posts']
+
+    assert_kind_of Fixnum, posts[0]['id']
+    assert_equal 'Hello world!', posts[0]['subject']
+    assert_equal user_id, posts[0]['user_id']
+
+    assert_kind_of Fixnum, posts[1]['id']
+    assert_equal 'Hello world!', posts[1]['subject']
+    assert_equal user_id, posts[1]['user_id']
+  end
+end
+```
+
+There are many problems with this approach of JSON matching:
+
+* It could get out of hand really quickly
+* It is not very readable
+* It flattens the structure of the JSON and it's difficult to visualize what the JSON actually looks like
+* It does not guard against extra parameters that you might have accidentally included (password hashes, credit card numbers etc)
+* Matching nested objects and arrays is tricky, especially when you don't want to enforce a particular ordering of the returned objects
+
+json_expression allows you to express the structure and content of the JSON you're expecting with very readable Ruby code while preserving the flexibility of the "manual" approach.
+
+## Dependencies
+
+* Ruby 1.9+
+
+## Usage
+
+Add it to your Gemfile:
+
+```ruby
+gem 'json_expressions'
+```
+
+Then add this to your test/spec helper file:
+
+```ruby
+# MiniTest::Unit example
+require 'json_expressions/minitest'
+```
+
+Which allows you to do...
+
+```ruby
+# MiniTest::Unit example
+class UsersControllerTest < MiniTest::Unit::TestCase
+  def test_get_a_user
+    server_response = get '/users/chancancode.json'
+
+    # 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'      => [
+          {
+            'id'      => Fixnum,
+            'subject' => 'Hello world!',
+            'user_id' => :user_id                # Match against the captured value
+          }.ignore_extra_keys!,                  # Skip the uninteresting stuff
+          {
+            'id'      => Fixnum,
+            'subject' => 'An awesome blog post',
+            'user_id' => :user_id
+          }.ignore_extra_keys!
+        ].ordered!                               # Ensure they are returned in this exact order
+      }
+    }
+
+    matcher = assert_json_match pattern, server_response.body # Returns the Matcher object
+
+    # You can use the captured values for other purposes
+    assert matcher.captures[:user_id] > 0
+  end
+end
+```
+
+### 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,
+}
+```
+matches the JSON object
+```json
+{
+  "integer": 1,
+  "float": 1.1,
+  "string": "Hello world!",
+  "boolean": true,
+  "array": [1,2,3],
+  "object": {"key1": "value1", "key2": "value2"},
+  "null": null
+}
+```
+
+### 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).
+
+This pattern
+```ruby
+[ WILDCARD_MATCHER, WILDCARD_MATCHER, WILDCARD_MATCHER, WILDCARD_MATCHER, WILDCARD_MATCHER, WILDCARD_MATCHER, WILDCARD_MATCHER ]
+```
+matches the JSON array
+```json
+[ 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:
+```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:
+
+```ruby
+{ 'hex' => /\A0x[0-9a-f]+\z/i }
+```
+matches
+```json
+{ "hex": "0xC0FFEE" }
+```
+but not
+```json
+{ "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 "">`!).
+
+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 `==`).
+
+```ruby
+# This is the default setting
+JsonExpressions::Matcher.skip_match_on = [ String ]
+
+# To add more modules/classes
+# JsonExpressions::Matcher.skip_match_on << MyClass
+
+# To turn this off completely
+# JsonExpressions::Matcher.skip_match_on = [ BasicObject ]
+```
+
+### 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:
+```ruby
+{
+  'integer' => Fixnum,
+  'float'   => Float,
+  'string'  => String,
+  'boolean' => Boolean,
+  'array'   => Array,
+  'object'  => Hash,
+  'null'    => NilClass,
+}
+```
+matches the JSON object
+```json
+{
+  "integer": 1,
+  "float": 1.1,
+  "string": "Hello world!",
+  "boolean": true,
+  "array": [1,2,3],
+  "object": {"key1": "value1", "key2": "value2"},
+  "null": null
+}
+```
+
+You can specific a list of classes/modules with undesirable `===` behavior, and json_expression will fall back to calling `==` on them instead.
+
+```ruby
+# This is the default setting
+JsonExpressions::Matcher.skip_triple_equal_on = [ ]
+
+# To add more modules/classes
+# JsonExpressions::Matcher.skip_triple_equal_on << MyClass
+
+# To turn this off completely
+# JsonExpressions::Matcher.skip_triple_equal_on = [ BasicObject ]
+```
+
+### Capturing
+
+Similar to how "capturs" work in Regex, you can capture the value of certain keys for later use:
+```ruby
+matcher = JsonExpressions::Matcher.new({
+  'key1' => :key1,
+  'key2' => :key2,
+  'key3' => :key3
+})
+
+matcher =~ JSON.parse('{"key1":"value1", "key2":"value2", "key3":"value3"}') # => true
+
+matcher.captures[:key1] # => "value1"
+matcher.captures[:key2] # => "value2"
+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
+}
+```
+matches
+```json
+{
+  "key1": "Hello world!",
+  "key2": "Hello world!",
+  "key3": "Hello world!"
+}
+```
+but not
+```json
+{
+  "key1": "value1",
+  "key2": "value2",
+  "key3": "value3"
+}
+```
+
+### Ordering
+
+By default, all arrays and JSON objects (i.e. Ruby hashes) are assumed to be unordered. This means
+```ruby
+[ 1, 2, 3, 4, 5 ]
+```
+will match
+```json
+[ 5, 3, 2, 1, 4 ]
+```
+and
+```ruby
+{ 'key1' => 'value1', 'key2' => 'value2' }
+```
+will match
+```json
+{ "key2": "value2", "key1": "value1" }
+```
+
+You can change this behavior in a case-by-case manner:
+```ruby
+{
+  "unordered_array" => [1,2,3,4,5].unordered!, # calling unordered! is optional as it's the default
+  "ordered_array"   => [1,2,3,4,5].ordered!,
+  "unordered_hash"  => {'a'=>1, 'b'=>2}.unordered!,
+  "ordered_hash"    => {'a'=>1, 'b'=>2}.ordered!
+}
+```
+
+Or you can change the defaults:
+```ruby
+# Default for these are true
+JsonExpressions::Matcher.assume_unordered_arrays = false
+JsonExpressions::Matcher.assume_unordered_hashes = false
+```
+
+### 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
+[ 1, 2, 3, 4, 5 ]
+```
+will not match
+```json
+[ 1, 2, 3, 4, 5, 6 ]
+```
+and
+```ruby
+{ 'key1' => 'value1', 'key2' => 'value2' }
+```
+will not match
+```json
+{ "key1": "value1", "key2": "value2", "key3": "value3" }
+```
+
+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!
+}
+```
+
+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!
+}
+```
+
+Or you can change the defaults:
+```ruby
+# Default for these are true
+JsonExpressions::Matcher.assume_strict_arrays = false
+JsonExpressions::Matcher.assume_strict_hashes = false
+```
+
+## Testing Frameworks Support
+
+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).
+
+## Contributing
+
+Please use the [GitHub issue tracker](https://github.com/chancancode/json_expressions/issues) for bugs and feature requests. If you could submit a pull request - that's even better!
+
+## License
+
+This library is distributed under the MIT license. Please see the LICENSE file.

data/lib/json_expressions/core_extensions.rb

@@ -0,0 +1,68 @@
+module JsonExpressions
+  module Strict; end
+  module Forgiving; end
+  module Ordered; end
+  module Unordered; end
+
+  module CoreExtensions
+    def ordered?
+      self.is_a? Ordered
+    end
+
+    def unordered?
+      self.is_a? Unordered
+    end
+
+    def ordered!
+      if self.unordered?
+        raise "cannot mark an unordered #{self.class} as ordered!"
+      else
+        self.extend Ordered
+      end
+    end
+
+    def unordered!
+      if self.ordered?
+        raise "cannot mark an ordered #{self.class} as unordered!"
+      else
+        self.extend Unordered
+      end
+    end
+
+    def strict?
+      self.is_a? Strict
+    end
+
+    def forgiving?
+      self.is_a? Forgiving
+    end
+
+    def strict!
+      if self.forgiving?
+        raise "cannot mark a forgiving #{self.class} as strict!"
+      else
+        self.extend Strict
+      end
+    end
+
+    def forgiving!
+      if self.strict?
+        raise "cannot mark a strict #{self.class} as forgiving!"
+      else
+        self.extend Forgiving
+      end
+    end
+  end
+end
+
+class Hash
+  include JsonExpressions::CoreExtensions
+  alias_method :reject_extra_keys!, :strict!
+  alias_method :ignore_extra_keys!, :forgiving!
+end
+
+class Array
+  include JsonExpressions::CoreExtensions
+  alias_method :reject_extra_values!, :strict!
+  alias_method :ignore_extra_values!, :forgiving!
+end

data/lib/json_expressions/matcher.rb

@@ -0,0 +1,227 @@
+require 'json_expressions'
+require 'json_expressions/core_extensions'
+
+module JsonExpressions
+  class Matcher
+    class << self
+      # JsonExpressions::Matcher.skip_match_on (Array)
+      #   An array of classes and modules with undesirable `match` behavior
+      #   Default: [ String ]
+      attr_accessor :skip_match_on
+      JsonExpressions::Matcher.skip_match_on = [ String ]
+
+      # JsonExpressions::Matcher.skip_triple_equal_on (Array)
+      #   An array of classes and modules with undesirable `===` behavior
+      #   Default: []
+      attr_accessor :skip_triple_equal_on
+      JsonExpressions::Matcher.skip_triple_equal_on = []
+
+      # JsonExpressions::Matcher.assume_unordered_arrays (Boolean)
+      #   By default, assume arrays are unordered when not specified
+      #   Default: true
+      attr_accessor :assume_unordered_arrays
+      JsonExpressions::Matcher.assume_unordered_arrays = true
+
+      # JsonExpressions::Matcher.assume_strict_arrays (Boolean)
+      #   By default, reject arrays with extra elements when not specified
+      #   Default: true
+      attr_accessor :assume_strict_arrays
+      JsonExpressions::Matcher.assume_strict_arrays = true
+
+      # JsonExpressions::Matcher.assume_unordered_hashes (Boolean)
+      #   By default, assume hashes are unordered when not specified
+      #   Default: true
+      attr_accessor :assume_unordered_hashes
+      JsonExpressions::Matcher.assume_unordered_hashes = true
+
+      # JsonExpressions::Matcher.assume_strict_hashes (Boolean)
+      #   By default, reject hashes with extra keys when not specified
+      #   Default: true
+      attr_accessor :assume_strict_hashes
+      JsonExpressions::Matcher.assume_strict_hashes = true
+    end
+
+    attr_reader :last_error
+    attr_reader :captures
+
+    def initialize(json, options = {})
+      defaults = {}
+      @json = json
+      @options = defaults.merge(options)
+      reset!
+    end
+
+    def =~(other)
+      reset!
+      match_json('(JSON ROOT)', @json, other)
+    end
+
+    def match(other)
+      self =~ other
+    end
+
+    def to_s
+      @json.to_s
+    end
+
+    private
+
+    def reset!
+      @last_errot = nil
+      @captures   = {}
+    end
+
+    def match_json(path, matcher, other)
+      if matcher.is_a? Symbol
+        capture path, matcher, other
+      elsif matcher.is_a? Array
+        match_array path, matcher, other
+      elsif matcher.is_a? Hash
+        match_hash path, matcher, other
+      elsif matcher.respond_to?(:match) && matchable?(matcher)
+        match_obj path, matcher, other, :match
+      elsif triple_equable?(matcher)
+        match_obj path, matcher, other, :===
+      else
+        match_obj path, matcher, other, :==
+      end
+    end
+
+    def capture(path, name, value)
+      if @captures.key? name
+        if match_json nil, @captures[name], value
+          true
+        else
+          set_last_error path, "At %path%: expected capture with key #{name.inspect} and value #{@captures[name]} to match #{value.inspect}"
+          false
+        end
+      else
+        @captures[name] = value
+        true
+      end
+    end
+
+    def match_obj(path, matcher, other, meth)
+      if matcher.__send__ meth, other
+        true
+      else
+        set_last_error path, "At %path%: expected #{matcher.inspect} to match #{other.inspect}"
+        return false
+      end
+    end
+
+    def match_array(path, matcher, other)
+      unless other.is_a? Array
+        set_last_error path, "%path% is not an array"
+        return false
+      end
+
+      apply_array_defaults matcher
+
+      if matcher.size > other.size
+        set_last_error path, "%path% contains too few elements (#{matcher.size} expected but was #{other.size})"
+        return false
+      end
+
+      if matcher.strict? && matcher.size < other.size
+        set_last_error path, "%path% contains too many elements (#{matcher.size} expected but was #{other.size})"
+        return false
+      end
+
+      if matcher.ordered?
+        matcher.zip(other).each_with_index { |(v1,v2),i| return false unless match_json(make_path(path,i), v1, v2) }
+      else
+        other = other.clone
+
+        matcher.all? do |v1|
+          if i = other.find_index { |v2| match_json(nil, v1, v2) }
+            other.delete_at i
+            true
+          else
+            set_last_error path, "%path% does not contain an element matching #{v1.inspect}"
+            false
+          end
+        end
+      end
+    end
+
+    def match_hash(path, matcher, other)
+      unless other.is_a? Hash
+        set_last_error path, "%path% is not a hash"
+        return false
+      end
+
+      apply_hash_defaults matcher
+
+      missing_keys = matcher.keys - other.keys
+      extra_keys   = other.keys - matcher.keys
+
+      unless missing_keys.empty?
+        set_last_error path, "%path% does not contain the key #{missing_keys.first}"
+        return false
+      end
+
+      if matcher.strict? && ! extra_keys.empty?
+        set_last_error path, "%path% contains an extra key #{extra_keys.first}"
+        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})"
+        return false
+      end
+
+      matcher.keys.all? { |k| match_json make_path(path,k), matcher[k], other[k] }
+    end
+
+    def set_last_error(path, message)
+      @last_error = message.gsub('%path%',path) if path
+    end
+
+    def make_path(path, segment)
+      if path
+        if segment.is_a? Fixnum
+          path + "[#{segment}]"
+        else
+          path + ".#{segment}"
+        end
+      end
+    end
+
+    def apply_array_defaults(array)
+      if ! array.ordered? && ! array.unordered?
+        self.class.assume_unordered_arrays ? array.unordered! : array.ordered!
+      end
+
+      if ! array.strict? && ! array.forgiving?
+        self.class.assume_strict_arrays ? array.strict! : array.forgiving!
+      end
+    end
+
+    def apply_hash_defaults(hash)
+      if ! hash.ordered? && ! hash.unordered?
+        self.class.assume_unordered_hashes ? hash.unordered! : hash.ordered!
+      end
+
+      if ! hash.strict? && ! hash.forgiving?
+        self.class.assume_strict_hashes ? hash.strict! : hash.forgiving!
+      end
+    end
+
+    def matchable?(obj)
+      if self.class.skip_match_on.include? obj.class
+        false
+      else
+        self.class.skip_match_on.none? { |klass| obj.is_a? klass }
+      end
+    end
+
+    def triple_equable?(obj)
+      if self.class.skip_triple_equal_on.include? obj.class
+        false
+      else
+        self.class.skip_triple_equal_on.none? { |klass| obj.is_a? klass }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+require 'json'
+
+module JsonExpressions
+  module MiniTest
+    module Unit
+      module Helpers
+        def assert_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
+
+          assert exp =~ act, ->{exp.last_error}
+
+          # Return the matcher
+          return exp
+        end
+      end
+    end
+  end
+end

data/lib/json_expressions/minitest.rb

@@ -0,0 +1,7 @@
+require 'json_expressions'
+require 'json_expressions/minitest/unit/helpers'
+
+class MiniTest::Unit::TestCase
+	include JsonExpressions::MiniTest::Unit::Helpers
+	WILDCARD_MATCHER = JsonExpressions::WILDCARD_MATCHER
+end

data/lib/json_expressions.rb

@@ -0,0 +1,25 @@
+require 'json_expressions/matcher'
+
+module JsonExpressions
+  WILDCARD_MATCHER = Object.new
+
+  def WILDCARD_MATCHER.is_a?(klass)
+    false
+  end
+
+  def WILDCARD_MATCHER.==(other)
+    true
+  end
+
+  def WILDCARD_MATCHER.=~(other)
+    true
+  end
+
+  def WILDCARD_MATCHER.match(other)
+    true
+  end
+
+  def WILDCARD_MATCHER.to_s
+    'WILDCARD_MATCHER'
+  end
+end

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification
+name: json_expressions
+version: !ruby/object:Gem::Version
+  version: 0.5.0
+  prerelease: 
+platform: ruby
+authors:
+- Godfrey Chan
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-07-10 00:00:00.000000000 Z
+dependencies: []
+description: JSON matchmaking for all your API testing needs.
+email:
+- godfreykfc@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/json_expressions/core_extensions.rb
+- lib/json_expressions/matcher.rb
+- lib/json_expressions/minitest/unit/helpers.rb
+- lib/json_expressions/minitest.rb
+- lib/json_expressions.rb
+- README.md
+- LICENSE
+homepage: https://github.com/chancancode/json_expressions
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: 1.3.6
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: JSON Expressions
+test_files: []