api_matchers 0.6.2 → 1.0.0

data/lib/api_matchers/json_structure/have_json_type.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module APIMatchers
+  module JsonStructure
+    class HaveJsonType < Base
+      TYPE_MAP = {
+        Integer => [Integer],
+        Float => [Float],
+        Numeric => [Integer, Float],
+        String => [String],
+        TrueClass => [TrueClass],
+        FalseClass => [FalseClass],
+        :boolean => [TrueClass, FalseClass],
+        Array => [Array],
+        Hash => [Hash],
+        NilClass => [NilClass]
+      }.freeze
+
+      def initialize(expected_type)
+        @expected_type = expected_type
+        @path = nil
+      end
+
+      def at_path(path)
+        @path = path
+        self
+      end
+
+      def failure_message
+        "expected JSON value at '#{@path || 'root'}' to be of type #{expected_type_name}. " \
+          "Got: #{@value.inspect} (#{@value.class})"
+      end
+
+      def failure_message_when_negated
+        "expected JSON value at '#{@path || 'root'}' NOT to be of type #{expected_type_name}. " \
+          "Got: #{@value.inspect} (#{@value.class})"
+      end
+
+      def description
+        desc = "have JSON type #{expected_type_name}"
+        desc += " at path '#{@path}'" if @path
+        desc
+      end
+
+      protected
+
+      def perform_match
+        @value = json_at_path(@path)
+        type_matches?
+      rescue ::APIMatchers::Core::Exceptions::PathNotFound
+        @value = nil
+        false
+      end
+
+      private
+
+      def type_matches?
+        allowed_types = TYPE_MAP[@expected_type] || [@expected_type]
+        allowed_types.any? { |type| @value.is_a?(type) }
+      end
+
+      def expected_type_name
+        case @expected_type
+        when :boolean
+          "Boolean"
+        else
+          @expected_type.to_s
+        end
+      end
+    end
+  end
+end

data/lib/api_matchers/pagination/base.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module APIMatchers
+  module Pagination
+    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
+
+      def meta_path
+        setup.pagination_meta_path || 'meta'
+      end
+
+      def links_path
+        setup.pagination_links_path || 'links'
+      end
+    end
+  end
+end

data/lib/api_matchers/pagination/be_paginated.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module APIMatchers
+  module Pagination
+    class BePaginated < Base
+      COMMON_PAGINATION_KEYS = %w[
+        page per_page total total_pages total_count
+        current_page next_page prev_page
+        offset limit count
+      ].freeze
+
+      def failure_message
+        "expected response to be paginated (have pagination metadata). " \
+          "Looked for pagination keys at '#{meta_path}' and '#{links_path}'. " \
+          "Got: #{truncate_json(parsed_json)}"
+      end
+
+      def failure_message_when_negated
+        "expected response NOT to be paginated, but pagination metadata was found"
+      end
+
+      def description
+        "be paginated"
+      end
+
+      protected
+
+      def perform_match
+        has_meta_pagination? || has_links_pagination? || has_root_pagination?
+      end
+
+      private
+
+      def has_meta_pagination?
+        meta = safe_json_at_path(meta_path)
+        return false unless meta.is_a?(Hash)
+
+        has_pagination_keys?(meta)
+      end
+
+      def has_links_pagination?
+        links = safe_json_at_path(links_path)
+        return false unless links.is_a?(Hash)
+
+        # Check for common link keys like next, prev, first, last
+        link_keys = links.keys.map(&:to_s).map(&:downcase)
+        (link_keys & %w[next prev previous first last self]).any?
+      end
+
+      def has_root_pagination?
+        return false unless parsed_json.is_a?(Hash)
+
+        has_pagination_keys?(parsed_json)
+      end
+
+      def has_pagination_keys?(hash)
+        keys = hash.keys.map(&:to_s).map(&:downcase)
+        (keys & COMMON_PAGINATION_KEYS).any?
+      end
+
+      def safe_json_at_path(path)
+        json_at_path(path)
+      rescue ::APIMatchers::Core::Exceptions::PathNotFound
+        nil
+      end
+
+      def truncate_json(json)
+        str = json.to_json
+        str.length > 200 ? "#{str[0..200]}..." : str
+      end
+    end
+  end
+end

data/lib/api_matchers/pagination/have_pagination_links.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module APIMatchers
+  module Pagination
+    class HavePaginationLinks < Base
+      VALID_LINK_TYPES = %w[next prev previous first last self].freeze
+
+      def initialize(*link_types)
+        @expected_links = normalize_link_types(link_types.flatten)
+      end
+
+      def failure_message
+        links = safe_json_at_path(links_path)
+
+        if links.nil?
+          "expected response to have pagination links at '#{links_path}', " \
+            "but no links were found. Got: #{truncate_json(parsed_json)}"
+        else
+          missing = @expected_links - actual_link_types(links)
+          "expected pagination links to include #{@expected_links.inspect}. " \
+            "Missing: #{missing.inspect}. Available: #{actual_link_types(links).inspect}"
+        end
+      end
+
+      def failure_message_when_negated
+        "expected response NOT to have pagination links #{@expected_links.inspect}, " \
+          "but they were present"
+      end
+
+      def description
+        "have pagination links #{@expected_links.inspect}"
+      end
+
+      protected
+
+      def perform_match
+        links = safe_json_at_path(links_path)
+        return false unless links.is_a?(Hash)
+
+        actual_links = actual_link_types(links)
+        @expected_links.all? { |link| actual_links.include?(link) }
+      end
+
+      private
+
+      def normalize_link_types(types)
+        types.map do |t|
+          normalized = t.to_s.downcase
+          normalized = 'prev' if normalized == 'previous'
+          normalized
+        end
+      end
+
+      def actual_link_types(links)
+        links.keys.map do |k|
+          normalized = k.to_s.downcase
+          normalized = 'prev' if normalized == 'previous'
+          normalized
+        end
+      end
+
+      def safe_json_at_path(path)
+        json_at_path(path)
+      rescue ::APIMatchers::Core::Exceptions::PathNotFound
+        nil
+      end
+
+      def truncate_json(json)
+        str = json.to_json
+        str.length > 200 ? "#{str[0..200]}..." : str
+      end
+    end
+  end
+end

data/lib/api_matchers/pagination/have_total_count.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module APIMatchers
+  module Pagination
+    class HaveTotalCount < Base
+      TOTAL_COUNT_KEYS = %w[total total_count totalCount count total_items totalItems].freeze
+
+      def initialize(expected_count)
+        @expected_count = expected_count
+      end
+
+      def failure_message
+        if @actual_count.nil?
+          "expected response to have total count of #{@expected_count}, " \
+            "but no total count field was found. " \
+            "Looked for keys: #{TOTAL_COUNT_KEYS.inspect} at '#{meta_path}' and root level. " \
+            "Got: #{truncate_json(parsed_json)}"
+        else
+          "expected total count to be #{@expected_count}. Got: #{@actual_count}"
+        end
+      end
+
+      def failure_message_when_negated
+        "expected total count NOT to be #{@expected_count}, but it was"
+      end
+
+      def description
+        "have total count of #{@expected_count}"
+      end
+
+      protected
+
+      def perform_match
+        @actual_count = find_total_count
+        @actual_count == @expected_count
+      end
+
+      private
+
+      def find_total_count
+        # First, try meta path
+        meta = safe_json_at_path(meta_path)
+        if meta.is_a?(Hash)
+          count = find_count_in_hash(meta)
+          return count unless count.nil?
+        end
+
+        # Then try root level
+        if parsed_json.is_a?(Hash)
+          count = find_count_in_hash(parsed_json)
+          return count unless count.nil?
+        end
+
+        nil
+      end
+
+      def find_count_in_hash(hash)
+        TOTAL_COUNT_KEYS.each do |key|
+          value = hash[key] || hash[key.to_sym]
+          return value.to_i if value
+        end
+        nil
+      end
+
+      def safe_json_at_path(path)
+        json_at_path(path)
+      rescue ::APIMatchers::Core::Exceptions::PathNotFound
+        nil
+      end
+
+      def truncate_json(json)
+        str = json.to_json
+        str.length > 200 ? "#{str[0..200]}..." : str
+      end
+    end
+  end
+end

data/lib/api_matchers/response_body/base.rb

@@ -1,12 +1,17 @@
+# frozen_string_literal: true
+
 module APIMatchers
   module ResponseBody
     class Base
-      attr_reader :setup, :expected_node, :actual
+      attr_reader :expected_node, :actual
       attr_writer :actual
 
-      def initialize(options={})
+      def initialize(options = {})
         @expected_node = options.fetch(:expected_node)
-        @setup = options.fetch(:setup)
+      end
+
+      def setup
+        ::APIMatchers::Core::Setup
       end
 
       def matches?(actual)
@@ -24,8 +29,8 @@ module APIMatchers
       end
 
       def response_body
-        if @setup.response_body_method.present?
-          @actual.send(@setup.response_body_method)
+        if setup.response_body_method.present?
+          @actual.send(setup.response_body_method)
         else
           @actual
         end
@@ -39,10 +44,6 @@ module APIMatchers
         "expected to NOT have node called: '#{@expected_node}'" << added_message << ". Got: '#{response_body}'"
       end
 
-      # RSpec 2 compatibility:
-      alias_method :failure_message_for_should, :failure_message
-      alias_method :failure_message_for_should_not, :failure_message_when_negated
-
       def added_message
         if @with_value
           " with value: '#{@with_value}'"

data/lib/api_matchers/response_body/have_json.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module APIMatchers
   module ResponseBody
     class HaveJson
@@ -21,10 +23,6 @@ module APIMatchers
       def failure_message_when_negated
         "expect to NOT have json: '#{response_body}'."
       end
-
-      # RSpec 2 compatibility:
-      alias_method :failure_message_for_should, :failure_message
-      alias_method :failure_message_for_should_not, :failure_message_when_negated
     end
   end
 end

data/lib/api_matchers/response_body/have_json_node.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'json'
 require 'active_support/core_ext/hash'
 
@@ -10,10 +12,15 @@ module APIMatchers
         @actual = actual
 
         begin
-          node = Core::FindInJSON.new(json).find(node: @expected_node.to_s, value: @with_value)
+          @finder = Core::FindInJSON.new(json)
+          node = @finder.find(node: @expected_node.to_s, value: @with_value)
 
           if @expected_including_text
             node.to_s.include?(@expected_including_text)
+          elsif @including_matcher
+            match_including(node)
+          elsif @including_all_matcher
+            match_including_all(node)
           else
             true # the node is present
           end
@@ -21,6 +28,43 @@ module APIMatchers
           false # the key was not found
         end
       end
+
+      def including(expected_element)
+        @including_matcher = expected_element
+        self
+      end
+
+      def including_all(expected_elements)
+        @including_all_matcher = expected_elements
+        self
+      end
+
+      private
+
+      def match_including(node)
+        return false unless node.is_a?(Array)
+
+        node.any? { |element| element_matches?(element, @including_matcher) }
+      end
+
+      def match_including_all(node)
+        return false unless node.is_a?(Array)
+
+        @including_all_matcher.all? do |expected|
+          node.any? { |element| element_matches?(element, expected) }
+        end
+      end
+
+      def element_matches?(element, expected)
+        case expected
+        when Hash
+          expected.all? do |key, value|
+            element.is_a?(Hash) && element[key.to_s] == value
+          end
+        else
+          element == expected
+        end
+      end
     end
   end
 end

data/lib/api_matchers/response_body/have_node.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module APIMatchers
   module ResponseBody
     class HaveNode

data/lib/api_matchers/response_body/have_xml_node.rb

@@ -1,29 +1,28 @@
+# frozen_string_literal: true
+
 require 'nokogiri'
 
 module APIMatchers
   module ResponseBody
     class HaveXmlNode < Base
       def matches?(actual)
-        value = false
         @actual = actual
         xml = Nokogiri::XML(response_body)
 
         node_set = xml.xpath("//#{@expected_node}")
-        if node_set
-          node_set.each do |node|
-            if @with_value
-              value = (node.text == @with_value.to_s)
-            elsif @expected_including_text
-              value = (node.text.to_s.include?(@expected_including_text))
-            else
-              value = node.text.present?
-            end
-            # if value is true, time to return
-            return value if value
+        return false unless node_set
+
+        node_set.each do |node|
+          if @with_value
+            return true if node.text == @with_value.to_s
+          elsif @expected_including_text
+            return true if node.text.to_s.include?(@expected_including_text)
+          else
+            return true if node.text.present?
           end
         end
-        # at this point, it failed to match
-        return value
+
+        false
       end
     end
   end

data/lib/api_matchers/response_body/match_json_schema.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module APIMatchers
+  module ResponseBody
+    class MatchJsonSchema
+      attr_reader :schema, :actual
+
+      def initialize(options = {})
+        @schema = options.fetch(:schema)
+        @errors = []
+      end
+
+      def setup
+        ::APIMatchers::Core::Setup
+      end
+
+      def matches?(actual)
+        @actual = actual
+
+        unless json_schemer_available?
+          raise LoadError, "json_schemer gem is required for JSON schema validation. Add it to your Gemfile: gem 'json_schemer'"
+        end
+
+        schemer = JSONSchemer.schema(normalize_schema(@schema))
+        result = schemer.validate(parsed_json)
+        @errors = result.to_a
+
+        @errors.empty?
+      end
+
+      def failure_message
+        error_details = @errors.first(5).map do |error|
+          "  - #{error['error']} at #{error['data_pointer'].presence || 'root'}"
+        end.join("\n")
+
+        more = @errors.size > 5 ? "\n  ... and #{@errors.size - 5} more errors" : ""
+
+        "Expected JSON to match schema.\nErrors:\n#{error_details}#{more}\n\nResponse: #{response_body}"
+      end
+
+      def failure_message_when_negated
+        "Expected JSON to NOT match schema, but it did.\n\nResponse: #{response_body}"
+      end
+
+      private
+
+      def json_schemer_available?
+        require 'json_schemer'
+        true
+      rescue LoadError
+        false
+      end
+
+      def response_body
+        if setup.response_body_method.present?
+          @actual.send(setup.response_body_method)
+        else
+          @actual
+        end
+      end
+
+      def parsed_json
+        body = response_body
+        body.is_a?(String) ? JSON.parse(body) : body
+      rescue JSON::ParserError => e
+        raise ::APIMatchers::InvalidJSON, "Invalid JSON: '#{body}'"
+      end
+
+      def normalize_schema(schema)
+        case schema
+        when Hash
+          deep_stringify_keys(schema)
+        when String
+          JSON.parse(schema)
+        else
+          schema
+        end
+      end
+
+      def deep_stringify_keys(hash)
+        hash.each_with_object({}) do |(key, value), result|
+          result[key.to_s] = value.is_a?(Hash) ? deep_stringify_keys(value) : value
+        end
+      end
+    end
+  end
+end

data/lib/api_matchers/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module APIMatchers
-  VERSION = '0.6.2'
+  VERSION = '1.0.0'
 end