api_matchers 0.6.1 → 1.0.0

data/TODO.markdown

@@ -1,3 +1,39 @@
-* Refactor Core::FindInJSON#find method.
-* Improve the error messages from all matchers.
-* Adding some include matcher about node arrays.
+# TODO
+
+## Future Improvements
+
+### New Matchers
+- [ ] `include_json` - Deep partial JSON matching for flexible assertions
+- [ ] `have_json_path` - Verify a JSON path exists without checking value
+- [ ] `match_json_pattern` - Pattern-based JSON matching with wildcards
+- [ ] `be_valid_uuid` - Validate UUID format in responses
+- [ ] `be_valid_iso8601` - Validate ISO 8601 date/time formats
+- [ ] `have_etag` - Check for ETag header presence and format
+- [ ] `be_gzip_encoded` - Verify response compression
+
+### Enhancements
+- [ ] Add `at_index` chain for collection matchers (e.g., `have_json_keys(:id).at_index(0)`)
+- [ ] Support JSONPath syntax as alternative to dot-notation paths
+- [ ] Add `including` chain for partial key matching
+- [ ] Support regex patterns in `with_value` and `with_href` chains
+- [ ] Add `within` tolerance for numeric comparisons
+
+### Configuration
+- [ ] Add configurable JSON parser (support Oj, Yajl as alternatives)
+- [ ] Add configurable date/time parsing for sorting comparisons
+- [ ] Support custom error message formatters
+
+### Documentation
+- [ ] Add YARD documentation for all public methods
+- [ ] Create a cookbook with real-world API testing examples
+- [ ] Add migration guide from other API testing libraries
+
+### Performance
+- [ ] Lazy JSON parsing - only parse when needed
+- [ ] Cache parsed JSON across chained matchers
+- [ ] Benchmark suite for performance regression testing
+
+### Compatibility
+- [ ] Minitest adapter for non-RSpec users
+- [ ] Integration examples with popular HTTP clients (Faraday, HTTParty, RestClient)
+- [ ] Rails system test integration guide

data/api_matchers.gemspec

@@ -1,12 +1,14 @@
-# -*- encoding: utf-8 -*-
+# frozen_string_literal: true
+
 require File.expand_path('../lib/api_matchers/version', __FILE__)
 
 Gem::Specification.new do |gem|
   gem.authors       = ["Tomas D'Stefano"]
   gem.email         = ["tomas_stefano@successoft.com"]
-  gem.description   = %q{Collection of RSpec matchers for create your API.}
-  gem.summary       = %q{Collection of RSpec matchers for create your API.}
+  gem.description   = %q{Collection of RSpec matchers for your API.}
+  gem.summary       = %q{Collection of RSpec matchers for your API.}
   gem.homepage      = "https://github.com/tomas-stefano/api_matchers"
+  gem.license       = "MIT"
 
   gem.files         = `git ls-files`.split($\)
   gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
@@ -15,7 +17,12 @@ Gem::Specification.new do |gem|
   gem.require_paths = ["lib"]
   gem.version       = APIMatchers::VERSION
 
-  gem.add_dependency 'rspec', '~> 3.1'
-  gem.add_dependency 'activesupport', '>= 3.2.5'
-  gem.add_dependency 'nokogiri', '>= 1.5.2'
+  gem.required_ruby_version = '>= 3.1'
+
+  gem.add_dependency 'rspec', '>= 3.12', '< 4.0'
+  gem.add_dependency 'activesupport', '>= 7.0', '< 9.0'
+  gem.add_dependency 'nokogiri', '>= 1.15'
+
+  gem.add_development_dependency 'rake', '~> 13.0'
+  gem.add_development_dependency 'json_schemer', '~> 2.0'
 end

data/lib/api_matchers/collection/base.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module APIMatchers
+  module Collection
+    class Base
+      attr_reader :actual
+
+      def setup
+        ::APIMatchers::Core::Setup
+      end
+
+      def matches?(actual)
+        @actual = actual
+        perform_match
+      end
+
+      def failure_message
+        raise NotImplementedError, "Subclasses must implement #failure_message"
+      end
+
+      def failure_message_when_negated
+        raise NotImplementedError, "Subclasses must implement #failure_message_when_negated"
+      end
+
+      protected
+
+      def perform_match
+        raise NotImplementedError, "Subclasses must implement #perform_match"
+      end
+
+      def response_body
+        if setup.response_body_method.present?
+          @actual.send(setup.response_body_method)
+        else
+          @actual
+        end
+      end
+
+      def parsed_json
+        @parsed_json ||= begin
+          body = response_body
+          case body
+          when Hash, Array
+            body
+          when String
+            JSON.parse(body)
+          else
+            raise ::APIMatchers::InvalidJSON, "Invalid JSON: '#{body}'"
+          end
+        end
+      rescue JSON::ParserError
+        raise ::APIMatchers::InvalidJSON, "Invalid JSON: '#{response_body}'"
+      end
+
+      def json_at_path(path)
+        return parsed_json if path.nil? || path.empty?
+
+        finder = ::APIMatchers::Core::JsonPathFinder.new(parsed_json)
+        finder.find(path)
+      end
+    end
+  end
+end

data/lib/api_matchers/collection/be_sorted_by.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module APIMatchers
+  module Collection
+    class BeSortedBy < Base
+      def initialize(field)
+        @field = field.to_s
+        @path = nil
+        @direction = :ascending
+      end
+
+      def at_path(path)
+        @path = path
+        self
+      end
+
+      def ascending
+        @direction = :ascending
+        self
+      end
+
+      def descending
+        @direction = :descending
+        self
+      end
+
+      def failure_message
+        if @collection.nil?
+          "expected JSON at '#{@path || 'root'}' to be an array sorted by '#{@field}', " \
+            "but path was not found or value was not an array"
+        else
+          "expected JSON array at '#{@path || 'root'}' to be sorted by '#{@field}' #{@direction}. " \
+            "Got values: #{extract_values.inspect}"
+        end
+      end
+
+      def failure_message_when_negated
+        "expected JSON array at '#{@path || 'root'}' NOT to be sorted by '#{@field}' #{@direction}, " \
+          "but it was"
+      end
+
+      def description
+        desc = "be sorted by '#{@field}' #{@direction}"
+        desc += " at path '#{@path}'" if @path
+        desc
+      end
+
+      protected
+
+      def perform_match
+        value = json_at_path(@path)
+        unless value.is_a?(Array)
+          @collection = nil
+          return false
+        end
+
+        @collection = value
+        return true if @collection.empty? || @collection.size == 1
+
+        sorted?
+      rescue ::APIMatchers::Core::Exceptions::PathNotFound
+        @collection = nil
+        false
+      end
+
+      private
+
+      def sorted?
+        values = extract_values
+        sorted_values = @direction == :ascending ? values.sort : values.sort.reverse
+
+        values == sorted_values
+      end
+
+      def extract_values
+        @collection.map do |item|
+          value = item.is_a?(Hash) ? (item[@field] || item[@field.to_sym]) : item
+          normalize_for_comparison(value)
+        end
+      end
+
+      def normalize_for_comparison(value)
+        case value
+        when String
+          # Try to parse as date/time for proper comparison
+          begin
+            Time.parse(value)
+          rescue ArgumentError, TypeError
+            value
+          end
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/api_matchers/collection/have_json_size.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module APIMatchers
+  module Collection
+    class HaveJsonSize < Base
+      def initialize(expected_size)
+        @expected_size = expected_size
+        @path = nil
+      end
+
+      def at_path(path)
+        @path = path
+        self
+      end
+
+      def failure_message
+        if @collection.nil?
+          "expected JSON at '#{@path || 'root'}' to be a collection with size #{@expected_size}, " \
+            "but path was not found or value was not a collection"
+        else
+          "expected JSON collection at '#{@path || 'root'}' to have size #{@expected_size}. " \
+            "Got size: #{@collection.size}"
+        end
+      end
+
+      def failure_message_when_negated
+        "expected JSON collection at '#{@path || 'root'}' NOT to have size #{@expected_size}, " \
+          "but it did"
+      end
+
+      def description
+        desc = "have JSON size #{@expected_size}"
+        desc += " at path '#{@path}'" if @path
+        desc
+      end
+
+      protected
+
+      def perform_match
+        value = json_at_path(@path)
+        unless value.is_a?(Array) || value.is_a?(Hash)
+          @collection = nil
+          return false
+        end
+
+        @collection = value
+        @collection.size == @expected_size
+      rescue ::APIMatchers::Core::Exceptions::PathNotFound
+        @collection = nil
+        false
+      end
+    end
+  end
+end

data/lib/api_matchers/core/exceptions.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module APIMatchers
   module Core
     module Exceptions
@@ -6,6 +8,9 @@ module APIMatchers
 
       class InvalidJSON < StandardError
       end
+
+      class PathNotFound < StandardError
+      end
     end
   end
 end

data/lib/api_matchers/core/find_in_json.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module APIMatchers
   module Core
     class FindInJSON
@@ -7,41 +9,68 @@ module APIMatchers
         @json = json
       end
 
-      def find(options={})
+      def find(options = {})
         expected_key = options.fetch(:node).to_s
-        expected_value = options[:value]
-
-        @json.each do |key, value|
-          if key == expected_key
-            unless expected_value.nil?
-              if expected_value.is_a? DateTime or expected_value.is_a? Date
-                expected_value = expected_value.to_s
-              elsif expected_value.is_a? Time
-                expected_value = expected_value.to_datetime.to_s
-              end
-            end
-            return value if value == expected_value or expected_value.nil?
-          end
+        expected_value = ValueNormalizer.normalize(options[:value])
 
-          # do we have more to recurse through?
-          keep_going = nil
-          if value.is_a? Hash or value.is_a? Array
-            keep_going = value                  # hash or array, keep going
-          elsif value.nil? and key.is_a? Hash
-            keep_going = key                    # the array was passed in and now in the key, keep going
-          end
+        result = search(json, expected_key, expected_value)
+        return result[:value] if result[:found]
+
+        raise ::APIMatchers::Core::Exceptions::KeyNotFound, "key '#{expected_key}' was not found"
+      end
 
-          if keep_going
-            begin
-              # ignore nodes where the key doesn't match
-              return FindInJSON.new(keep_going).find(node: expected_key, value: expected_value)
-            rescue ::APIMatchers::Core::Exceptions::KeyNotFound
+      def available_keys
+        collect_keys(json)
+      end
+
+      private
+
+      def search(data, expected_key, expected_value)
+        case data
+        when Hash
+          search_in_hash(data, expected_key, expected_value)
+        when Array
+          search_in_array(data, expected_key, expected_value)
+        else
+          { found: false }
+        end
+      end
+
+      def search_in_hash(hash, expected_key, expected_value)
+        hash.each do |key, value|
+          if key.to_s == expected_key
+            if expected_value.nil? || value == expected_value
+              return { found: true, value: value }
             end
           end
 
+          result = search(value, expected_key, expected_value)
+          return result if result[:found]
+        end
+
+        { found: false }
+      end
+
+      def search_in_array(array, expected_key, expected_value)
+        array.each do |element|
+          result = search(element, expected_key, expected_value)
+          return result if result[:found]
+        end
+
+        { found: false }
+      end
+
+      def collect_keys(data, keys = [])
+        case data
+        when Hash
+          data.each do |key, value|
+            keys << key.to_s
+            collect_keys(value, keys)
+          end
+        when Array
+          data.each { |element| collect_keys(element, keys) }
         end
-         # we did not find the requested key
-        raise ::APIMatchers::Core::Exceptions::KeyNotFound.new("key was not found")
+        keys.uniq
       end
     end
   end

data/lib/api_matchers/core/http_status_codes.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module APIMatchers
+  module Core
+    module HTTPStatusCodes
+      SYMBOL_TO_STATUS_CODE = {
+        # 1xx Informational
+        continue: 100,
+        switching_protocols: 101,
+        processing: 102,
+        early_hints: 103,
+
+        # 2xx Success
+        ok: 200,
+        created: 201,
+        accepted: 202,
+        non_authoritative_information: 203,
+        no_content: 204,
+        reset_content: 205,
+        partial_content: 206,
+        multi_status: 207,
+        already_reported: 208,
+        im_used: 226,
+
+        # 3xx Redirection
+        multiple_choices: 300,
+        moved_permanently: 301,
+        found: 302,
+        see_other: 303,
+        not_modified: 304,
+        use_proxy: 305,
+        temporary_redirect: 307,
+        permanent_redirect: 308,
+
+        # 4xx Client Error
+        bad_request: 400,
+        unauthorized: 401,
+        payment_required: 402,
+        forbidden: 403,
+        not_found: 404,
+        method_not_allowed: 405,
+        not_acceptable: 406,
+        proxy_authentication_required: 407,
+        request_timeout: 408,
+        conflict: 409,
+        gone: 410,
+        length_required: 411,
+        precondition_failed: 412,
+        payload_too_large: 413,
+        uri_too_long: 414,
+        unsupported_media_type: 415,
+        range_not_satisfiable: 416,
+        expectation_failed: 417,
+        im_a_teapot: 418,
+        misdirected_request: 421,
+        unprocessable_entity: 422,
+        locked: 423,
+        failed_dependency: 424,
+        too_early: 425,
+        upgrade_required: 426,
+        precondition_required: 428,
+        too_many_requests: 429,
+        request_header_fields_too_large: 431,
+        unavailable_for_legal_reasons: 451,
+
+        # 5xx Server Error
+        internal_server_error: 500,
+        not_implemented: 501,
+        bad_gateway: 502,
+        service_unavailable: 503,
+        gateway_timeout: 504,
+        http_version_not_supported: 505,
+        variant_also_negotiates: 506,
+        insufficient_storage: 507,
+        loop_detected: 508,
+        not_extended: 510,
+        network_authentication_required: 511
+      }.freeze
+
+      STATUS_CODE_TO_SYMBOL = SYMBOL_TO_STATUS_CODE.invert.freeze
+
+      # Status code ranges
+      INFORMATIONAL_RANGE = (100...200).freeze
+      SUCCESSFUL_RANGE = (200...300).freeze
+      REDIRECT_RANGE = (300...400).freeze
+      CLIENT_ERROR_RANGE = (400...500).freeze
+      SERVER_ERROR_RANGE = (500...600).freeze
+
+      def self.symbol_to_code(symbol)
+        SYMBOL_TO_STATUS_CODE[symbol.to_sym]
+      end
+
+      def self.code_to_symbol(code)
+        STATUS_CODE_TO_SYMBOL[code.to_i]
+      end
+
+      def self.informational?(code)
+        INFORMATIONAL_RANGE.include?(code.to_i)
+      end
+
+      def self.successful?(code)
+        SUCCESSFUL_RANGE.include?(code.to_i)
+      end
+
+      def self.redirect?(code)
+        REDIRECT_RANGE.include?(code.to_i)
+      end
+
+      def self.client_error?(code)
+        CLIENT_ERROR_RANGE.include?(code.to_i)
+      end
+
+      def self.server_error?(code)
+        SERVER_ERROR_RANGE.include?(code.to_i)
+      end
+    end
+  end
+end

data/lib/api_matchers/core/json_path_finder.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module APIMatchers
+  module Core
+    class JsonPathFinder
+      attr_reader :json
+
+      def initialize(json)
+        @json = json
+      end
+
+      # Navigate JSON using dot-notation paths
+      # Example: "user.address.city" navigates to json["user"]["address"]["city"]
+      # Supports array indexing: "users.0.name" or "users[0].name"
+      def find(path)
+        return json if path.nil? || path.empty?
+
+        segments = parse_path(path)
+        navigate(json, segments, path)
+      end
+
+      # Check if a path exists in the JSON
+      def path_exists?(path)
+        find(path)
+        true
+      rescue ::APIMatchers::Core::Exceptions::PathNotFound
+        false
+      end
+
+      private
+
+      def parse_path(path)
+        # Handle both "items.0.name" and "items[0].name" syntax
+        path.to_s.gsub(/\[(\d+)\]/, '.\1').split('.')
+      end
+
+      def navigate(data, segments, full_path)
+        return data if segments.empty?
+
+        segment = segments.first
+        remaining = segments[1..]
+
+        value = access_segment(data, segment, full_path)
+        navigate(value, remaining, full_path)
+      end
+
+      def access_segment(data, segment, full_path)
+        case data
+        when Hash
+          access_hash(data, segment, full_path)
+        when Array
+          access_array(data, segment, full_path)
+        else
+          raise ::APIMatchers::Core::Exceptions::PathNotFound,
+                "Cannot navigate path '#{full_path}': '#{segment}' is not accessible on #{data.class}"
+        end
+      end
+
+      def access_hash(hash, key, full_path)
+        # Try both string and symbol keys
+        if hash.key?(key)
+          hash[key]
+        elsif hash.key?(key.to_sym)
+          hash[key.to_sym]
+        else
+          raise ::APIMatchers::Core::Exceptions::PathNotFound,
+                "Path '#{full_path}' not found: key '#{key}' does not exist"
+        end
+      end
+
+      def access_array(array, index_str, full_path)
+        unless index_str.match?(/\A\d+\z/)
+          raise ::APIMatchers::Core::Exceptions::PathNotFound,
+                "Path '#{full_path}' not found: '#{index_str}' is not a valid array index"
+        end
+
+        index = index_str.to_i
+        if index >= array.length
+          raise ::APIMatchers::Core::Exceptions::PathNotFound,
+                "Path '#{full_path}' not found: index #{index} out of bounds (array size: #{array.length})"
+        end
+
+        array[index]
+      end
+    end
+  end
+end

data/lib/api_matchers/core/parser.rb

@@ -1,10 +1,12 @@
+# frozen_string_literal: true
+
 module APIMatchers
   module Core
     module Parser
       def json
         JSON.parse(response_body)
-      rescue JSON::ParserError => exception
-        raise ::APIMatchers::InvalidJSON.new("Invalid JSON: '#{response_body}'")
+      rescue JSON::ParserError
+        raise ::APIMatchers::InvalidJSON, "Invalid JSON: '#{response_body}'"
       end
     end
   end