api_matchers 0.6.1 → 1.0.0

data/lib/api_matchers/hateoas/base.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module APIMatchers
+  module Hateoas
+    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 links_path
+        setup.links_path || '_links'
+      end
+
+      def hateoas_links
+        # Try configured path first
+        links = parsed_json[links_path] || parsed_json[links_path.to_sym]
+        return links if links
+
+        # Try common HATEOAS link locations
+        parsed_json['_links'] || parsed_json[:_links] ||
+          parsed_json['links'] || parsed_json[:links]
+      end
+
+      def truncate_json(json)
+        str = json.to_json
+        str.length > 200 ? "#{str[0..200]}..." : str
+      end
+    end
+  end
+end

data/lib/api_matchers/hateoas/have_link.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module APIMatchers
+  module Hateoas
+    class HaveLink < Base
+      def initialize(rel)
+        @rel = rel.to_s
+        @expected_href = nil
+        @href_pattern = nil
+      end
+
+      def with_href(href_or_pattern)
+        case href_or_pattern
+        when Regexp
+          @href_pattern = href_or_pattern
+        else
+          @expected_href = href_or_pattern.to_s
+        end
+        self
+      end
+
+      def failure_message
+        links = hateoas_links
+
+        if links.nil?
+          "expected response to have link '#{@rel}', but no links were found. " \
+            "Looked at '#{links_path}'. Got: #{truncate_json(parsed_json)}"
+        elsif !link_exists?(links)
+          "expected response to have link '#{@rel}'. " \
+            "Available links: #{available_rels(links).inspect}"
+        elsif @expected_href
+          "expected link '#{@rel}' to have href '#{@expected_href}'. " \
+            "Got: '#{extract_href(links)}'"
+        elsif @href_pattern
+          "expected link '#{@rel}' href to match #{@href_pattern.inspect}. " \
+            "Got: '#{extract_href(links)}'"
+        else
+          "expected response to have link '#{@rel}'"
+        end
+      end
+
+      def failure_message_when_negated
+        if @expected_href
+          "expected link '#{@rel}' NOT to have href '#{@expected_href}', but it did"
+        elsif @href_pattern
+          "expected link '#{@rel}' NOT to match #{@href_pattern.inspect}, but it did"
+        else
+          "expected response NOT to have link '#{@rel}', but it was present"
+        end
+      end
+
+      def description
+        desc = "have link '#{@rel}'"
+        desc += " with href '#{@expected_href}'" if @expected_href
+        desc += " matching #{@href_pattern.inspect}" if @href_pattern
+        desc
+      end
+
+      protected
+
+      def perform_match
+        links = hateoas_links
+        return false unless links.is_a?(Hash)
+        return false unless link_exists?(links)
+
+        href = extract_href(links)
+
+        if @expected_href
+          href == @expected_href
+        elsif @href_pattern
+          href.to_s.match?(@href_pattern)
+        else
+          true
+        end
+      end
+
+      private
+
+      def link_exists?(links)
+        links.key?(@rel) || links.key?(@rel.to_sym)
+      end
+
+      def extract_href(links)
+        link = links[@rel] || links[@rel.to_sym]
+        return nil unless link
+
+        case link
+        when Hash
+          link['href'] || link[:href]
+        when String
+          link
+        else
+          nil
+        end
+      end
+
+      def available_rels(links)
+        links.keys.map(&:to_s)
+      end
+    end
+  end
+end

data/lib/api_matchers/headers/base.rb

@@ -1,10 +1,10 @@
+# frozen_string_literal: true
+
 module APIMatchers
   module Headers
     class Base
-      attr_reader :setup
-
-      def initialize(setup)
-        @setup = setup
+      def setup
+        ::APIMatchers::Core::Setup
       end
 
       def matches?(actual)
@@ -14,9 +14,9 @@ module APIMatchers
       end
 
       def content_type_response
-        if @setup.header_method.present? and @setup.header_content_type_key.present?
-          headers = @actual.send(@setup.header_method)
-          headers[@setup.header_content_type_key] || headers if headers.present?
+        if setup.header_method.present? && setup.header_content_type_key.present?
+          headers = @actual.send(setup.header_method)
+          headers.present? ? (headers[setup.header_content_type_key] || headers) : nil
         else
           @actual
         end

data/lib/api_matchers/headers/be_json.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module APIMatchers
   module Headers
     class BeJSON < Base
@@ -16,10 +18,6 @@ module APIMatchers
       def description
         "be in JSON"
       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/headers/be_xml.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module APIMatchers
   module Headers
     class BeXML < Base
@@ -16,10 +18,6 @@ module APIMatchers
       def description
         "be in XML"
       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/headers/have_cache_control.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module APIMatchers
+  module Headers
+    class HaveCacheControl
+      VALID_DIRECTIVES = %w[
+        public private no-cache no-store no-transform must-revalidate
+        proxy-revalidate max-age s-maxage immutable stale-while-revalidate
+        stale-if-error
+      ].freeze
+
+      attr_reader :actual
+
+      def initialize(*directives)
+        @expected_directives = normalize_directives(directives.flatten)
+      end
+
+      def setup
+        ::APIMatchers::Core::Setup
+      end
+
+      def matches?(actual)
+        @actual = actual
+        cache_control = fetch_cache_control
+        return false if cache_control.nil?
+
+        @actual_directives = parse_cache_control(cache_control)
+
+        @expected_directives.all? do |directive|
+          @actual_directives.include?(directive) ||
+            @actual_directives.any? { |d| d.start_with?("#{directive}=") }
+        end
+      end
+
+      def failure_message
+        cache_control = fetch_cache_control
+
+        if cache_control.nil?
+          "expected response to have Cache-Control header with #{@expected_directives.inspect}, " \
+            "but Cache-Control header was not present"
+        else
+          "expected Cache-Control to include #{@expected_directives.inspect}. " \
+            "Got: '#{cache_control}' (parsed: #{@actual_directives.inspect})"
+        end
+      end
+
+      def failure_message_when_negated
+        "expected Cache-Control NOT to include #{@expected_directives.inspect}, " \
+          "but it did: '#{fetch_cache_control}'"
+      end
+
+      def description
+        "have Cache-Control with #{@expected_directives.inspect}"
+      end
+
+      private
+
+      def normalize_directives(directives)
+        directives.map do |d|
+          d.to_s.tr('_', '-')
+        end
+      end
+
+      def fetch_cache_control
+        headers = available_headers
+        return nil unless headers
+
+        headers['Cache-Control'] ||
+          headers['cache-control'] ||
+          headers.find { |k, _| k.to_s.downcase == 'cache-control' }&.last
+      end
+
+      def parse_cache_control(value)
+        value.to_s.split(',').map(&:strip).map(&:downcase)
+      end
+
+      def available_headers
+        if setup.header_method.present?
+          @actual.send(setup.header_method)
+        elsif @actual.respond_to?(:headers)
+          @actual.headers
+        elsif @actual.is_a?(Hash)
+          @actual
+        else
+          {}
+        end
+      end
+    end
+  end
+end

data/lib/api_matchers/headers/have_cors_headers.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module APIMatchers
+  module Headers
+    class HaveCorsHeaders
+      CORS_HEADERS = %w[
+        Access-Control-Allow-Origin
+      ].freeze
+
+      OPTIONAL_CORS_HEADERS = %w[
+        Access-Control-Allow-Methods
+        Access-Control-Allow-Headers
+        Access-Control-Allow-Credentials
+        Access-Control-Expose-Headers
+        Access-Control-Max-Age
+      ].freeze
+
+      attr_reader :actual
+
+      def initialize
+        @expected_origin = nil
+      end
+
+      def setup
+        ::APIMatchers::Core::Setup
+      end
+
+      def for_origin(origin)
+        @expected_origin = origin
+        self
+      end
+
+      def matches?(actual)
+        @actual = actual
+        headers = available_headers
+        return false unless headers
+
+        has_required_headers = CORS_HEADERS.all? { |h| header_present?(headers, h) }
+        return false unless has_required_headers
+
+        if @expected_origin
+          origin_value = fetch_header(headers, 'Access-Control-Allow-Origin')
+          return false unless origin_value == @expected_origin || origin_value == '*'
+        end
+
+        true
+      end
+
+      def failure_message
+        headers = available_headers
+        missing = CORS_HEADERS.reject { |h| header_present?(headers, h) }
+
+        if missing.any?
+          "expected response to have CORS headers. Missing: #{missing.inspect}. " \
+            "Available headers: #{headers&.keys&.inspect}"
+        elsif @expected_origin
+          origin_value = fetch_header(headers, 'Access-Control-Allow-Origin')
+          "expected Access-Control-Allow-Origin to be '#{@expected_origin}' or '*'. " \
+            "Got: '#{origin_value}'"
+        else
+          "expected response to have CORS headers"
+        end
+      end
+
+      def failure_message_when_negated
+        "expected response NOT to have CORS headers, but they were present"
+      end
+
+      def description
+        desc = "have CORS headers"
+        desc += " for origin '#{@expected_origin}'" if @expected_origin
+        desc
+      end
+
+      private
+
+      def available_headers
+        if setup.header_method.present?
+          @actual.send(setup.header_method)
+        elsif @actual.respond_to?(:headers)
+          @actual.headers
+        elsif @actual.is_a?(Hash)
+          @actual
+        else
+          {}
+        end
+      end
+
+      def header_present?(headers, name)
+        fetch_header(headers, name) != nil
+      end
+
+      def fetch_header(headers, name)
+        return nil unless headers
+
+        headers[name] ||
+          headers[name.downcase] ||
+          headers.find { |k, _| k.to_s.downcase == name.downcase }&.last
+      end
+    end
+  end
+end

data/lib/api_matchers/headers/have_header.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module APIMatchers
+  module Headers
+    class HaveHeader
+      attr_reader :actual
+
+      def initialize(header_name)
+        @header_name = header_name.to_s
+        @expected_value = nil
+        @value_pattern = nil
+      end
+
+      def setup
+        ::APIMatchers::Core::Setup
+      end
+
+      def with_value(value)
+        @expected_value = value
+        self
+      end
+
+      def matching(pattern)
+        @value_pattern = pattern
+        self
+      end
+
+      def matches?(actual)
+        @actual = actual
+        header_value = fetch_header_value
+
+        return false if header_value.nil?
+
+        if @expected_value
+          header_value == @expected_value
+        elsif @value_pattern
+          header_value.to_s.match?(@value_pattern)
+        else
+          true
+        end
+      end
+
+      def failure_message
+        header_value = fetch_header_value
+
+        if header_value.nil?
+          "expected response to have header '#{@header_name}', but it was not present. " \
+            "Available headers: #{available_headers.keys.inspect}"
+        elsif @expected_value
+          "expected header '#{@header_name}' to have value '#{@expected_value}'. " \
+            "Got: '#{header_value}'"
+        elsif @value_pattern
+          "expected header '#{@header_name}' to match #{@value_pattern.inspect}. " \
+            "Got: '#{header_value}'"
+        else
+          "expected response to have header '#{@header_name}'"
+        end
+      end
+
+      def failure_message_when_negated
+        if @expected_value
+          "expected header '#{@header_name}' NOT to have value '#{@expected_value}', but it did"
+        elsif @value_pattern
+          "expected header '#{@header_name}' NOT to match #{@value_pattern.inspect}, but it did"
+        else
+          "expected response NOT to have header '#{@header_name}', but it was present"
+        end
+      end
+
+      def description
+        desc = "have header '#{@header_name}'"
+        desc += " with value '#{@expected_value}'" if @expected_value
+        desc += " matching #{@value_pattern.inspect}" if @value_pattern
+        desc
+      end
+
+      private
+
+      def fetch_header_value
+        headers = available_headers
+        return nil unless headers
+
+        # Try exact match first, then case-insensitive
+        headers[@header_name] ||
+          headers[@header_name.downcase] ||
+          headers.find { |k, _| k.to_s.downcase == @header_name.downcase }&.last
+      end
+
+      def available_headers
+        if setup.header_method.present?
+          @actual.send(setup.header_method)
+        elsif @actual.respond_to?(:headers)
+          @actual.headers
+        elsif @actual.is_a?(Hash)
+          @actual
+        else
+          {}
+        end
+      end
+    end
+  end
+end

data/lib/api_matchers/http_status/base.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module APIMatchers
+  module HTTPStatus
+    class Base
+      attr_reader :actual
+
+      def setup
+        ::APIMatchers::Core::Setup
+      end
+
+      def matches?(actual)
+        @actual = actual
+        expected_status_match?
+      end
+
+      def failure_message
+        "expected response to #{expectation_description}. Got: #{actual_status}"
+      end
+
+      def failure_message_when_negated
+        "expected response NOT to #{expectation_description}. Got: #{actual_status}"
+      end
+
+      def description
+        expectation_description
+      end
+
+      protected
+
+      def expected_status_match?
+        raise NotImplementedError, "Subclasses must implement #expected_status_match?"
+      end
+
+      def expectation_description
+        raise NotImplementedError, "Subclasses must implement #expectation_description"
+      end
+
+      def actual_status
+        if setup.http_status_method.present?
+          @actual.send(setup.http_status_method)
+        else
+          @actual
+        end
+      end
+    end
+  end
+end

data/lib/api_matchers/http_status/be_client_error.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module APIMatchers
+  module HTTPStatus
+    class BeClientError < Base
+      protected
+
+      def expected_status_match?
+        ::APIMatchers::Core::HTTPStatusCodes.client_error?(actual_status)
+      end
+
+      def expectation_description
+        "be client error (4xx)"
+      end
+    end
+  end
+end

data/lib/api_matchers/http_status/be_forbidden.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module APIMatchers
+  module HTTPStatus
+    class BeForbidden < Base
+      protected
+
+      def expected_status_match?
+        actual_status.to_i == 403
+      end
+
+      def expectation_description
+        "be forbidden (403)"
+      end
+    end
+  end
+end

data/lib/api_matchers/http_status/be_no_content.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module APIMatchers
+  module HTTPStatus
+    class BeNoContent < Base
+      protected
+
+      def expected_status_match?
+        actual_status.to_i == 204
+      end
+
+      def expectation_description
+        "be no content (204)"
+      end
+    end
+  end
+end

data/lib/api_matchers/http_status/be_not_found.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module APIMatchers
+  module HTTPStatus
+    class BeNotFound < Base
+      protected
+
+      def expected_status_match?
+        actual_status.to_i == 404
+      end
+
+      def expectation_description
+        "be not found (404)"
+      end
+    end
+  end
+end

data/lib/api_matchers/http_status/be_redirect.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module APIMatchers
+  module HTTPStatus
+    class BeRedirect < Base
+      protected
+
+      def expected_status_match?
+        ::APIMatchers::Core::HTTPStatusCodes.redirect?(actual_status)
+      end
+
+      def expectation_description
+        "be redirect (3xx)"
+      end
+    end
+  end
+end

data/lib/api_matchers/http_status/be_server_error.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module APIMatchers
+  module HTTPStatus
+    class BeServerError < Base
+      protected
+
+      def expected_status_match?
+        ::APIMatchers::Core::HTTPStatusCodes.server_error?(actual_status)
+      end
+
+      def expectation_description
+        "be server error (5xx)"
+      end
+    end
+  end
+end