api_matchers 0.6.1 → 1.0.0

data/lib/api_matchers/http_status/be_successful.rb

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

data/lib/api_matchers/http_status/be_unauthorized.rb

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

data/lib/api_matchers/http_status/be_unprocessable.rb

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

data/lib/api_matchers/http_status/have_http_status.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module APIMatchers
+  module HTTPStatus
+    class HaveHttpStatus < Base
+      def initialize(expected)
+        @expected = expected
+      end
+
+      protected
+
+      def expected_status_match?
+        actual_status.to_i == expected_code
+      end
+
+      def expectation_description
+        if @expected.is_a?(Symbol)
+          "have HTTP status #{expected_code} (#{@expected})"
+        else
+          "have HTTP status #{expected_code}"
+        end
+      end
+
+      private
+
+      def expected_code
+        case @expected
+        when Symbol
+          ::APIMatchers::Core::HTTPStatusCodes.symbol_to_code(@expected) ||
+            raise(ArgumentError, "Unknown status code symbol: #{@expected}")
+        when Integer
+          @expected
+        else
+          raise ArgumentError, "Expected status must be a Symbol or Integer, got: #{@expected.class}"
+        end
+      end
+    end
+  end
+end

data/lib/api_matchers/json_api/base.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module APIMatchers
+  module JsonApi
+    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_api_data
+        parsed_json['data'] || parsed_json[:data]
+      end
+
+      def json_api_errors
+        parsed_json['errors'] || parsed_json[:errors]
+      end
+
+      def json_api_meta
+        parsed_json['meta'] || parsed_json[:meta]
+      end
+
+      def json_api_included
+        parsed_json['included'] || parsed_json[:included]
+      end
+
+      def json_api_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/json_api/be_json_api_compliant.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module APIMatchers
+  module JsonApi
+    class BeJsonApiCompliant < Base
+      REQUIRED_TOP_LEVEL_MEMBERS = %w[data errors meta].freeze
+      VALID_TOP_LEVEL_MEMBERS = %w[data errors meta links included jsonapi].freeze
+      REQUIRED_RESOURCE_MEMBERS = %w[id type].freeze
+
+      def failure_message
+        "expected response to be JSON:API compliant. Violations: #{@violations.join('; ')}. " \
+          "Got: #{truncate_json(parsed_json)}"
+      end
+
+      def failure_message_when_negated
+        "expected response NOT to be JSON:API compliant, but it was"
+      end
+
+      def description
+        "be JSON:API compliant"
+      end
+
+      protected
+
+      def perform_match
+        @violations = []
+        validate_top_level_structure
+        return @violations.empty? unless parsed_json.is_a?(Hash)
+
+        validate_data_member if has_data?
+        validate_errors_member if has_errors?
+
+        @violations.empty?
+      end
+
+      private
+
+      def validate_top_level_structure
+        unless parsed_json.is_a?(Hash)
+          @violations << "top-level must be an object"
+          return
+        end
+
+        # Must have at least one of: data, errors, or meta
+        keys = parsed_json.keys.map(&:to_s)
+        unless (keys & REQUIRED_TOP_LEVEL_MEMBERS).any?
+          @violations << "must contain at least one of: data, errors, or meta"
+        end
+
+        # data and errors must not coexist
+        if has_data? && has_errors?
+          @violations << "data and errors must not coexist"
+        end
+      end
+
+      def validate_data_member
+        data = json_api_data
+
+        case data
+        when Hash
+          validate_resource_object(data)
+        when Array
+          data.each_with_index do |resource, index|
+            validate_resource_object(resource, "data[#{index}]")
+          end
+        when nil
+          # null is valid for data
+        else
+          @violations << "data must be null, an object, or an array"
+        end
+      end
+
+      def validate_resource_object(resource, path = "data")
+        unless resource.is_a?(Hash)
+          @violations << "#{path} must be an object"
+          return
+        end
+
+        keys = resource.keys.map(&:to_s)
+
+        # Must have id and type (unless it's a new resource being created)
+        unless keys.include?('type')
+          @violations << "#{path} must contain 'type'"
+        end
+
+        # id must be a string
+        if resource.key?('id') || resource.key?(:id)
+          id = resource['id'] || resource[:id]
+          unless id.is_a?(String) || id.is_a?(Integer)
+            @violations << "#{path}.id must be a string or integer"
+          end
+        end
+
+        # type must be a string
+        type = resource['type'] || resource[:type]
+        if type && !type.is_a?(String)
+          @violations << "#{path}.type must be a string"
+        end
+
+        # Validate attributes
+        attributes = resource['attributes'] || resource[:attributes]
+        if attributes && !attributes.is_a?(Hash)
+          @violations << "#{path}.attributes must be an object"
+        end
+
+        # Validate relationships
+        relationships = resource['relationships'] || resource[:relationships]
+        if relationships
+          validate_relationships(relationships, path)
+        end
+      end
+
+      def validate_relationships(relationships, path)
+        unless relationships.is_a?(Hash)
+          @violations << "#{path}.relationships must be an object"
+          return
+        end
+
+        relationships.each do |name, rel|
+          rel_path = "#{path}.relationships.#{name}"
+          unless rel.is_a?(Hash)
+            @violations << "#{rel_path} must be an object"
+            next
+          end
+
+          # Must have at least one of: links, data, or meta
+          rel_keys = rel.keys.map(&:to_s)
+          unless (rel_keys & %w[links data meta]).any?
+            @violations << "#{rel_path} must contain links, data, or meta"
+          end
+        end
+      end
+
+      def validate_errors_member
+        errors = json_api_errors
+
+        unless errors.is_a?(Array)
+          @violations << "errors must be an array"
+          return
+        end
+
+        errors.each_with_index do |error, index|
+          unless error.is_a?(Hash)
+            @violations << "errors[#{index}] must be an object"
+          end
+        end
+      end
+
+      def has_data?
+        parsed_json.key?('data') || parsed_json.key?(:data)
+      end
+
+      def has_errors?
+        parsed_json.key?('errors') || parsed_json.key?(:errors)
+      end
+    end
+  end
+end

data/lib/api_matchers/json_api/have_json_api_attributes.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module APIMatchers
+  module JsonApi
+    class HaveJsonApiAttributes < Base
+      def initialize(*attributes)
+        @expected_attributes = attributes.flatten.map(&:to_s)
+      end
+
+      def failure_message
+        data = json_api_data
+        attrs = extract_attributes(data)
+
+        if attrs.nil?
+          "expected JSON:API data to have attributes #{@expected_attributes.inspect}, " \
+            "but no attributes were found. Got: #{truncate_json(parsed_json)}"
+        else
+          missing = @expected_attributes - attrs.keys.map(&:to_s)
+          "expected JSON:API data to have attributes #{@expected_attributes.inspect}. " \
+            "Missing: #{missing.inspect}. Available: #{attrs.keys.map(&:to_s).inspect}"
+        end
+      end
+
+      def failure_message_when_negated
+        "expected JSON:API data NOT to have attributes #{@expected_attributes.inspect}, " \
+          "but all were present"
+      end
+
+      def description
+        "have JSON:API attributes #{@expected_attributes.inspect}"
+      end
+
+      protected
+
+      def perform_match
+        data = json_api_data
+        return false unless data
+
+        attrs = extract_attributes(data)
+        return false unless attrs.is_a?(Hash)
+
+        available_attrs = attrs.keys.map(&:to_s)
+        (@expected_attributes - available_attrs).empty?
+      end
+
+      private
+
+      def extract_attributes(data)
+        case data
+        when Hash
+          data['attributes'] || data[:attributes]
+        when Array
+          # For collections, check the first item
+          first = data.first
+          first['attributes'] || first[:attributes] if first.is_a?(Hash)
+        else
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/api_matchers/json_api/have_json_api_data.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module APIMatchers
+  module JsonApi
+    class HaveJsonApiData < Base
+      def initialize
+        @expected_type = nil
+        @expected_id = nil
+      end
+
+      def of_type(type)
+        @expected_type = type.to_s
+        self
+      end
+
+      def with_id(id)
+        @expected_id = id.to_s
+        self
+      end
+
+      def failure_message
+        data = json_api_data
+
+        if data.nil? && !parsed_json.key?('data') && !parsed_json.key?(:data)
+          "expected response to have JSON:API data. Got: #{truncate_json(parsed_json)}"
+        elsif @expected_type && !type_matches?(data)
+          "expected JSON:API data to have type '#{@expected_type}'. " \
+            "Got type: '#{extract_type(data)}'"
+        elsif @expected_id && !id_matches?(data)
+          "expected JSON:API data to have id '#{@expected_id}'. " \
+            "Got id: '#{extract_id(data)}'"
+        else
+          "expected response to have JSON:API data"
+        end
+      end
+
+      def failure_message_when_negated
+        if @expected_type || @expected_id
+          "expected JSON:API data NOT to have " \
+            "#{[@expected_type && "type '#{@expected_type}'", @expected_id && "id '#{@expected_id}'"].compact.join(' and ')}, " \
+            "but it did"
+        else
+          "expected response NOT to have JSON:API data, but it did"
+        end
+      end
+
+      def description
+        desc = "have JSON:API data"
+        desc += " of type '#{@expected_type}'" if @expected_type
+        desc += " with id '#{@expected_id}'" if @expected_id
+        desc
+      end
+
+      protected
+
+      def perform_match
+        data = json_api_data
+
+        # data: null is valid JSON:API
+        return true if data.nil? && (parsed_json.key?('data') || parsed_json.key?(:data))
+
+        return false unless data
+
+        if @expected_type && !type_matches?(data)
+          return false
+        end
+
+        if @expected_id && !id_matches?(data)
+          return false
+        end
+
+        true
+      end
+
+      private
+
+      def type_matches?(data)
+        case data
+        when Hash
+          extract_type(data) == @expected_type
+        when Array
+          data.all? { |d| extract_type(d) == @expected_type }
+        else
+          false
+        end
+      end
+
+      def id_matches?(data)
+        case data
+        when Hash
+          extract_id(data) == @expected_id
+        when Array
+          data.any? { |d| extract_id(d) == @expected_id }
+        else
+          false
+        end
+      end
+
+      def extract_type(resource)
+        return nil unless resource.is_a?(Hash)
+        (resource['type'] || resource[:type])&.to_s
+      end
+
+      def extract_id(resource)
+        return nil unless resource.is_a?(Hash)
+        (resource['id'] || resource[:id])&.to_s
+      end
+    end
+  end
+end

data/lib/api_matchers/json_api/have_json_api_relationships.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module APIMatchers
+  module JsonApi
+    class HaveJsonApiRelationships < Base
+      def initialize(*relationships)
+        @expected_relationships = relationships.flatten.map(&:to_s)
+      end
+
+      def failure_message
+        data = json_api_data
+        rels = extract_relationships(data)
+
+        if rels.nil?
+          "expected JSON:API data to have relationships #{@expected_relationships.inspect}, " \
+            "but no relationships were found. Got: #{truncate_json(parsed_json)}"
+        else
+          missing = @expected_relationships - rels.keys.map(&:to_s)
+          "expected JSON:API data to have relationships #{@expected_relationships.inspect}. " \
+            "Missing: #{missing.inspect}. Available: #{rels.keys.map(&:to_s).inspect}"
+        end
+      end
+
+      def failure_message_when_negated
+        "expected JSON:API data NOT to have relationships #{@expected_relationships.inspect}, " \
+          "but all were present"
+      end
+
+      def description
+        "have JSON:API relationships #{@expected_relationships.inspect}"
+      end
+
+      protected
+
+      def perform_match
+        data = json_api_data
+        return false unless data
+
+        rels = extract_relationships(data)
+        return false unless rels.is_a?(Hash)
+
+        available_rels = rels.keys.map(&:to_s)
+        (@expected_relationships - available_rels).empty?
+      end
+
+      private
+
+      def extract_relationships(data)
+        case data
+        when Hash
+          data['relationships'] || data[:relationships]
+        when Array
+          # For collections, check the first item
+          first = data.first
+          first['relationships'] || first[:relationships] if first.is_a?(Hash)
+        else
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/api_matchers/json_structure/base.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module APIMatchers
+  module JsonStructure
+    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/json_structure/have_json_keys.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module APIMatchers
+  module JsonStructure
+    class HaveJsonKeys < Base
+      def initialize(*keys)
+        @expected_keys = keys.flatten.map(&:to_s)
+        @path = nil
+      end
+
+      def at_path(path)
+        @path = path
+        self
+      end
+
+      def failure_message
+        "expected JSON to have keys: #{@expected_keys.inspect}. " \
+          "Missing: #{missing_keys.inspect}. " \
+          "Got keys: #{actual_keys.inspect}"
+      end
+
+      def failure_message_when_negated
+        "expected JSON NOT to have keys: #{@expected_keys.inspect}, but all were present"
+      end
+
+      def description
+        desc = "have JSON keys #{@expected_keys.inspect}"
+        desc += " at path '#{@path}'" if @path
+        desc
+      end
+
+      protected
+
+      def perform_match
+        @json_data = json_at_path(@path)
+        return false unless @json_data.is_a?(Hash)
+
+        missing_keys.empty?
+      rescue ::APIMatchers::Core::Exceptions::PathNotFound
+        @json_data = nil
+        false
+      end
+
+      private
+
+      def actual_keys
+        @json_data.is_a?(Hash) ? @json_data.keys.map(&:to_s) : []
+      end
+
+      def missing_keys
+        @expected_keys - actual_keys
+      end
+    end
+  end
+end