api_matchers 0.6.1 → 1.0.0

data/lib/api_matchers/core/rspec_matchers.rb

@@ -1,69 +1,162 @@
+# frozen_string_literal: true
+
 module APIMatchers
   module RSpecMatchers
-    def be_bad_request
-      ::APIMatchers::HTTPStatusCode::BeBadRequest.new(::APIMatchers::Core::Setup)
+    # Content Type Matchers
+    def be_xml
+      ::APIMatchers::Headers::BeXML.new
     end
-    alias :be_a_bad_request :be_bad_request
+    alias :be_in_xml :be_xml
 
-    def be_not_found
-      ::APIMatchers::HTTPStatusCode::BeNotFound.new(::APIMatchers::Core::Setup)
+    def be_json
+      ::APIMatchers::Headers::BeJSON.new
     end
+    alias :be_in_json :be_json
+    alias :be_a_json  :be_json
 
-    def be_internal_server_error
-      ::APIMatchers::HTTPStatusCode::BeInternalServerError.new(::APIMatchers::Core::Setup)
+    # Response Body Matchers
+    def have_json_node(expected_node)
+      ::APIMatchers::ResponseBody::HaveJsonNode.new(expected_node: expected_node)
+    end
+
+    def have_xml_node(expected_node)
+      ::APIMatchers::ResponseBody::HaveXmlNode.new(expected_node: expected_node)
+    end
+
+    def have_json(expected_json)
+      ::APIMatchers::ResponseBody::HaveJson.new(expected_json)
+    end
+
+    def have_node(expected_node)
+      if ::APIMatchers::Core::Setup.have_node_matcher.equal?(:json)
+        have_json_node(expected_node)
+      else
+        have_xml_node(expected_node)
+      end
+    end
+
+    def match_json_schema(schema)
+      ::APIMatchers::ResponseBody::MatchJsonSchema.new(schema: schema)
+    end
+
+    # HTTP Status Matchers
+    def have_http_status(expected)
+      ::APIMatchers::HTTPStatus::HaveHttpStatus.new(expected)
+    end
+
+    def be_successful
+      ::APIMatchers::HTTPStatus::BeSuccessful.new
+    end
+    alias :be_success :be_successful
+
+    def be_redirect
+      ::APIMatchers::HTTPStatus::BeRedirect.new
+    end
+    alias :be_redirection :be_redirect
+
+    def be_client_error
+      ::APIMatchers::HTTPStatus::BeClientError.new
+    end
+
+    def be_server_error
+      ::APIMatchers::HTTPStatus::BeServerError.new
+    end
+
+    def be_not_found
+      ::APIMatchers::HTTPStatus::BeNotFound.new
     end
-    alias :be_an_internal_server_error :be_internal_server_error
 
     def be_unauthorized
-      ::APIMatchers::HTTPStatusCode::BeUnauthorized.new(::APIMatchers::Core::Setup)
+      ::APIMatchers::HTTPStatus::BeUnauthorized.new
     end
 
     def be_forbidden
-      ::APIMatchers::HTTPStatusCode::BeForbidden.new(::APIMatchers::Core::Setup)
+      ::APIMatchers::HTTPStatus::BeForbidden.new
     end
 
-    def be_ok
-      ::APIMatchers::HTTPStatusCode::BeOk.new(::APIMatchers::Core::Setup)
+    def be_unprocessable
+      ::APIMatchers::HTTPStatus::BeUnprocessable.new
     end
+    alias :be_unprocessable_entity :be_unprocessable
 
-    def be_unprocessable_entity
-      ::APIMatchers::HTTPStatusCode::BeUnprocessableEntity.new(::APIMatchers::Core::Setup)
+    def be_no_content
+      ::APIMatchers::HTTPStatus::BeNoContent.new
     end
 
-    def create_resource
-      ::APIMatchers::HTTPStatusCode::CreateResource.new(::APIMatchers::Core::Setup)
+    # JSON Structure Matchers
+    def have_json_keys(*keys)
+      ::APIMatchers::JsonStructure::HaveJsonKeys.new(*keys)
     end
-    alias :created_resource :create_resource
 
-    def be_xml
-      ::APIMatchers::Headers::BeXML.new(::APIMatchers::Core::Setup)
+    def have_json_type(expected_type)
+      ::APIMatchers::JsonStructure::HaveJsonType.new(expected_type)
     end
-    alias :be_in_xml :be_xml
 
-    def be_json
-      ::APIMatchers::Headers::BeJSON.new(::APIMatchers::Core::Setup)
+    # Collection Matchers
+    def have_json_size(expected_size)
+      ::APIMatchers::Collection::HaveJsonSize.new(expected_size)
     end
-    alias :be_in_json :be_json
-    alias :be_a_json  :be_json
 
-    def have_json_node(expected_node)
-      ::APIMatchers::ResponseBody::HaveJsonNode.new(expected_node: expected_node, setup: ::APIMatchers::Core::Setup)
+    def be_sorted_by(field)
+      ::APIMatchers::Collection::BeSortedBy.new(field)
     end
 
-    def have_xml_node(expected_node)
-      ::APIMatchers::ResponseBody::HaveXmlNode.new(expected_node: expected_node, setup: ::APIMatchers::Core::Setup)
+    # Header Matchers
+    def have_header(header_name)
+      ::APIMatchers::Headers::HaveHeader.new(header_name)
     end
 
-    def have_json(expected_json)
-      ::APIMatchers::ResponseBody::HaveJson.new(expected_json)
+    def have_cors_headers
+      ::APIMatchers::Headers::HaveCorsHeaders.new
     end
 
-    def have_node(expected_node)
-      if ::APIMatchers::Core::Setup.have_node_matcher.equal?(:json)
-        have_json_node(expected_node)
-      else
-        have_xml_node(expected_node)
-      end
+    def have_cache_control(*directives)
+      ::APIMatchers::Headers::HaveCacheControl.new(*directives)
+    end
+
+    # Pagination Matchers
+    def be_paginated
+      ::APIMatchers::Pagination::BePaginated.new
+    end
+
+    def have_pagination_links(*link_types)
+      ::APIMatchers::Pagination::HavePaginationLinks.new(*link_types)
+    end
+
+    def have_total_count(expected_count)
+      ::APIMatchers::Pagination::HaveTotalCount.new(expected_count)
+    end
+
+    # Error Response Matchers
+    def have_error
+      ::APIMatchers::ErrorResponse::HaveError.new
+    end
+    alias :have_errors :have_error
+
+    def have_error_on(field)
+      ::APIMatchers::ErrorResponse::HaveErrorOn.new(field)
+    end
+
+    # JSON:API Matchers
+    def be_json_api_compliant
+      ::APIMatchers::JsonApi::BeJsonApiCompliant.new
+    end
+
+    def have_json_api_data
+      ::APIMatchers::JsonApi::HaveJsonApiData.new
+    end
+
+    def have_json_api_attributes(*attributes)
+      ::APIMatchers::JsonApi::HaveJsonApiAttributes.new(*attributes)
+    end
+
+    def have_json_api_relationships(*relationships)
+      ::APIMatchers::JsonApi::HaveJsonApiRelationships.new(*relationships)
+    end
+
+    # HATEOAS Matchers
+    def have_link(rel)
+      ::APIMatchers::Hateoas::HaveLink.new(rel)
     end
   end
-end
+end

data/lib/api_matchers/core/setup.rb

@@ -1,28 +1,8 @@
+# frozen_string_literal: true
+
 module APIMatchers
   module Core
     class Setup
-      # The http status method that will be called when you call http status matchers
-      #
-      # ==== Examples
-      #
-      #  response.status.should create_resource
-      #  response.status.should be_bad_request
-      #  response.status.should be_unauthorized
-      #
-      #  # Instead calling #status everytime, you can configure:
-      #
-      #  APIMatchers.setup do |config|
-      #    config.http_status_method = :status
-      #  end
-      #
-      # Then:
-      #
-      #  response.should create_resource
-      #  response.should be_bad_request
-      #  response.should be_unauthorized
-      #
-      cattr_accessor :http_status_method
-
       # The response body method that will be called when you call the have_node matchers
       #
       # ==== Examples
@@ -34,7 +14,7 @@ module APIMatchers
       #  # Instead calling #body everytime, you can configure:
       #
       #  APIMatchers.setup do |config|
-      #    config.http_status_method = :body
+      #    config.response_body_method = :body
       #  end
       #
       # Then:
@@ -75,6 +55,52 @@ module APIMatchers
       #
       cattr_accessor :header_method
       cattr_accessor :header_content_type_key
+
+      # HTTP status method - for extracting status codes from response objects
+      #
+      # ==== Examples
+      #
+      #  APIMatchers.setup do |config|
+      #    config.http_status_method = :status  # or :code, :status_code
+      #  end
+      #
+      cattr_accessor :http_status_method
+
+      # Pagination configuration
+      #
+      # ==== Examples
+      #
+      #  APIMatchers.setup do |config|
+      #    config.pagination_meta_path = 'meta'           # path to pagination metadata
+      #    config.pagination_links_path = 'links'         # path to pagination links
+      #  end
+      #
+      cattr_accessor :pagination_meta_path
+      cattr_accessor :pagination_links_path
+
+      # Error response configuration
+      #
+      # ==== Examples
+      #
+      #  APIMatchers.setup do |config|
+      #    config.errors_path = 'errors'                  # path to errors array
+      #    config.error_message_key = 'message'           # key for error message
+      #    config.error_field_key = 'field'               # key for error field name
+      #  end
+      #
+      cattr_accessor :errors_path
+      cattr_accessor :error_message_key
+      cattr_accessor :error_field_key
+
+      # HATEOAS links configuration
+      #
+      # ==== Examples
+      #
+      #  APIMatchers.setup do |config|
+      #    config.links_path = '_links'                   # path to HATEOAS links (HAL style)
+      #  end
+      #
+      cattr_accessor :links_path
     end
   end
 end

data/lib/api_matchers/core/value_normalizer.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module APIMatchers
+  module Core
+    class ValueNormalizer
+      def self.normalize(value)
+        new(value).normalize
+      end
+
+      def initialize(value)
+        @value = value
+      end
+
+      def normalize
+        case @value
+        when DateTime, Date
+          @value.to_s
+        when Time
+          @value.to_datetime.to_s
+        else
+          @value
+        end
+      end
+    end
+  end
+end

data/lib/api_matchers/error_response/base.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module APIMatchers
+  module ErrorResponse
+    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 errors_path
+        setup.errors_path || 'errors'
+      end
+
+      def error_message_key
+        setup.error_message_key || 'message'
+      end
+
+      def error_field_key
+        setup.error_field_key || 'field'
+      end
+    end
+  end
+end

data/lib/api_matchers/error_response/have_error.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module APIMatchers
+  module ErrorResponse
+    class HaveError < Base
+      COMMON_ERROR_KEYS = %w[error errors message messages].freeze
+
+      def failure_message
+        "expected response to have error(s). " \
+          "Looked for keys: #{COMMON_ERROR_KEYS.inspect} and at path '#{errors_path}'. " \
+          "Got: #{truncate_json(parsed_json)}"
+      end
+
+      def failure_message_when_negated
+        "expected response NOT to have error(s), but errors were found"
+      end
+
+      def description
+        "have error(s)"
+      end
+
+      protected
+
+      def perform_match
+        has_errors_at_path? || has_error_keys_at_root?
+      end
+
+      private
+
+      def has_errors_at_path?
+        errors = safe_json_at_path(errors_path)
+        errors_present?(errors)
+      end
+
+      def has_error_keys_at_root?
+        return false unless parsed_json.is_a?(Hash)
+
+        COMMON_ERROR_KEYS.any? do |key|
+          value = parsed_json[key] || parsed_json[key.to_sym]
+          errors_present?(value)
+        end
+      end
+
+      def errors_present?(value)
+        case value
+        when Array
+          value.any?
+        when Hash
+          value.any?
+        when String
+          value.present?
+        else
+          false
+        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/error_response/have_error_on.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+module APIMatchers
+  module ErrorResponse
+    class HaveErrorOn < Base
+      def initialize(field)
+        @field = field.to_s
+        @expected_message = nil
+        @message_pattern = nil
+      end
+
+      def with_message(message)
+        @expected_message = message
+        self
+      end
+
+      def matching(pattern)
+        @message_pattern = pattern
+        self
+      end
+
+      def failure_message
+        errors = find_errors
+
+        if errors.nil? || errors.empty?
+          "expected response to have error on '#{@field}', but no errors were found. " \
+            "Got: #{truncate_json(parsed_json)}"
+        elsif !field_has_error?(errors)
+          "expected response to have error on '#{@field}'. " \
+            "Found errors on: #{error_fields(errors).inspect}"
+        elsif @expected_message
+          "expected error on '#{@field}' to have message '#{@expected_message}'. " \
+            "Got messages: #{field_messages(errors).inspect}"
+        elsif @message_pattern
+          "expected error on '#{@field}' to match #{@message_pattern.inspect}. " \
+            "Got messages: #{field_messages(errors).inspect}"
+        else
+          "expected response to have error on '#{@field}'"
+        end
+      end
+
+      def failure_message_when_negated
+        if @expected_message
+          "expected NOT to have error on '#{@field}' with message '#{@expected_message}', but it was found"
+        elsif @message_pattern
+          "expected NOT to have error on '#{@field}' matching #{@message_pattern.inspect}, but it was found"
+        else
+          "expected NOT to have error on '#{@field}', but it was found"
+        end
+      end
+
+      def description
+        desc = "have error on '#{@field}'"
+        desc += " with message '#{@expected_message}'" if @expected_message
+        desc += " matching #{@message_pattern.inspect}" if @message_pattern
+        desc
+      end
+
+      protected
+
+      def perform_match
+        errors = find_errors
+        return false if errors.nil? || errors.empty?
+        return false unless field_has_error?(errors)
+
+        if @expected_message
+          message_matches?(errors, @expected_message)
+        elsif @message_pattern
+          message_matches_pattern?(errors, @message_pattern)
+        else
+          true
+        end
+      end
+
+      private
+
+      def find_errors
+        # Try errors path first
+        errors = safe_json_at_path(errors_path)
+        return errors if errors.is_a?(Array) || errors.is_a?(Hash)
+
+        # Try root level
+        if parsed_json.is_a?(Hash)
+          # Rails-style errors: { field: ["message1", "message2"] }
+          return parsed_json if parsed_json.key?(@field) || parsed_json.key?(@field.to_sym)
+          return parsed_json['errors'] if parsed_json['errors']
+          return parsed_json[:errors] if parsed_json[:errors]
+          # Check if root has any field-like structure
+          return parsed_json if parsed_json.values.any? { |v| v.is_a?(Array) }
+        end
+
+        nil
+      end
+
+      def field_has_error?(errors)
+        case errors
+        when Array
+          errors.any? { |e| error_for_field?(e) }
+        when Hash
+          # Rails-style: { field: ["message1", "message2"] }
+          errors.key?(@field) || errors.key?(@field.to_sym) ||
+            # Or hash with field key
+            errors.any? { |_, v| v.is_a?(Hash) && error_for_field?(v) }
+        else
+          false
+        end
+      end
+
+      def error_for_field?(error)
+        return false unless error.is_a?(Hash)
+
+        field_key = error_field_key
+        field_value = error[field_key] || error[field_key.to_sym] ||
+                      error['field'] || error[:field] ||
+                      error['attribute'] || error[:attribute]
+
+        field_value.to_s == @field
+      end
+
+      def error_fields(errors)
+        case errors
+        when Array
+          errors.filter_map do |e|
+            next unless e.is_a?(Hash)
+            e[error_field_key] || e[error_field_key.to_sym] ||
+              e['field'] || e[:field] ||
+              e['attribute'] || e[:attribute]
+          end.map(&:to_s).uniq
+        when Hash
+          errors.keys.map(&:to_s)
+        else
+          []
+        end
+      end
+
+      def field_messages(errors)
+        case errors
+        when Array
+          errors.filter_map do |e|
+            next unless e.is_a?(Hash) && error_for_field?(e)
+            e[error_message_key] || e[error_message_key.to_sym] ||
+              e['message'] || e[:message]
+          end
+        when Hash
+          # Rails-style: { field: ["message1", "message2"] }
+          messages = errors[@field] || errors[@field.to_sym]
+          messages.is_a?(Array) ? messages : [messages].compact
+        else
+          []
+        end
+      end
+
+      def message_matches?(errors, expected)
+        field_messages(errors).any? { |m| m.to_s == expected.to_s }
+      end
+
+      def message_matches_pattern?(errors, pattern)
+        field_messages(errors).any? { |m| m.to_s.match?(pattern) }
+      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