api_matchers 0.6.2 → 1.0.0

data/lib/api_matchers.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "api_matchers/version"
 require "active_support/core_ext/object"
 require "active_support/core_ext/class"
@@ -5,26 +7,15 @@ require "active_support/core_ext/class"
 module APIMatchers
   autoload :RSpecMatchers, 'api_matchers/core/rspec_matchers'
 
-  # HTTP Status Code Matchers
-  #
-  module HTTPStatusCode
-    autoload :Base, 'api_matchers/http_status_code/base'
-    autoload :BeBadRequest, 'api_matchers/http_status_code/be_bad_request'
-    autoload :BeNotFound, 'api_matchers/http_status_code/be_not_found'
-    autoload :BeInternalServerError, 'api_matchers/http_status_code/be_internal_server_error'
-    autoload :BeUnauthorized, 'api_matchers/http_status_code/be_unauthorized'
-    autoload :BeOk, 'api_matchers/http_status_code/be_ok'
-    autoload :BeUnprocessableEntity, 'api_matchers/http_status_code/be_unprocessable_entity'
-    autoload :BeForbidden, 'api_matchers/http_status_code/be_forbidden'
-    autoload :CreateResource, 'api_matchers/http_status_code/create_resource'
-  end
-
   # Content Type Matchers
   #
   module Headers
     autoload :Base, 'api_matchers/headers/base'
     autoload :BeXML, 'api_matchers/headers/be_xml'
     autoload :BeJSON, 'api_matchers/headers/be_json'
+    autoload :HaveHeader, 'api_matchers/headers/have_header'
+    autoload :HaveCorsHeaders, 'api_matchers/headers/have_cors_headers'
+    autoload :HaveCacheControl, 'api_matchers/headers/have_cache_control'
   end
 
   # Response Body Matchers
@@ -35,15 +26,85 @@ module APIMatchers
     autoload :HaveJson, 'api_matchers/response_body/have_json'
     autoload :HaveXmlNode,  'api_matchers/response_body/have_xml_node'
     autoload :HaveNode, 'api_matchers/response_body/have_node'
+    autoload :MatchJsonSchema, 'api_matchers/response_body/match_json_schema'
+  end
+
+  # HTTP Status Matchers
+  #
+  module HTTPStatus
+    autoload :Base, 'api_matchers/http_status/base'
+    autoload :HaveHttpStatus, 'api_matchers/http_status/have_http_status'
+    autoload :BeSuccessful, 'api_matchers/http_status/be_successful'
+    autoload :BeRedirect, 'api_matchers/http_status/be_redirect'
+    autoload :BeClientError, 'api_matchers/http_status/be_client_error'
+    autoload :BeServerError, 'api_matchers/http_status/be_server_error'
+    autoload :BeNotFound, 'api_matchers/http_status/be_not_found'
+    autoload :BeUnauthorized, 'api_matchers/http_status/be_unauthorized'
+    autoload :BeForbidden, 'api_matchers/http_status/be_forbidden'
+    autoload :BeUnprocessable, 'api_matchers/http_status/be_unprocessable'
+    autoload :BeNoContent, 'api_matchers/http_status/be_no_content'
+  end
+
+  # JSON Structure Matchers
+  #
+  module JsonStructure
+    autoload :Base, 'api_matchers/json_structure/base'
+    autoload :HaveJsonKeys, 'api_matchers/json_structure/have_json_keys'
+    autoload :HaveJsonType, 'api_matchers/json_structure/have_json_type'
+  end
+
+  # Collection Matchers
+  #
+  module Collection
+    autoload :Base, 'api_matchers/collection/base'
+    autoload :HaveJsonSize, 'api_matchers/collection/have_json_size'
+    autoload :BeSortedBy, 'api_matchers/collection/be_sorted_by'
+  end
+
+  # Pagination Matchers
+  #
+  module Pagination
+    autoload :Base, 'api_matchers/pagination/base'
+    autoload :BePaginated, 'api_matchers/pagination/be_paginated'
+    autoload :HavePaginationLinks, 'api_matchers/pagination/have_pagination_links'
+    autoload :HaveTotalCount, 'api_matchers/pagination/have_total_count'
+  end
+
+  # Error Response Matchers
+  #
+  module ErrorResponse
+    autoload :Base, 'api_matchers/error_response/base'
+    autoload :HaveError, 'api_matchers/error_response/have_error'
+    autoload :HaveErrorOn, 'api_matchers/error_response/have_error_on'
+  end
+
+  # JSON:API Matchers
+  #
+  module JsonApi
+    autoload :Base, 'api_matchers/json_api/base'
+    autoload :BeJsonApiCompliant, 'api_matchers/json_api/be_json_api_compliant'
+    autoload :HaveJsonApiData, 'api_matchers/json_api/have_json_api_data'
+    autoload :HaveJsonApiAttributes, 'api_matchers/json_api/have_json_api_attributes'
+    autoload :HaveJsonApiRelationships, 'api_matchers/json_api/have_json_api_relationships'
+  end
+
+  # HATEOAS Matchers
+  #
+  module Hateoas
+    autoload :Base, 'api_matchers/hateoas/base'
+    autoload :HaveLink, 'api_matchers/hateoas/have_link'
   end
 
   # Core
   #
   module Core
     autoload :FindInJSON, 'api_matchers/core/find_in_json'
+    autoload :ValueNormalizer, 'api_matchers/core/value_normalizer'
     autoload :Parser, 'api_matchers/core/parser'
     autoload :Setup, 'api_matchers/core/setup'
     autoload :Exceptions, 'api_matchers/core/exceptions'
+    autoload :HTTPStatusCodes, 'api_matchers/core/http_status_codes'
+    autoload :JsonPathFinder, 'api_matchers/core/json_path_finder'
   end
   include ::APIMatchers::Core::Exceptions
 

data/spec/api_matchers/collection/be_sorted_by_spec.rb

@@ -0,0 +1,110 @@
+require 'spec_helper'
+
+RSpec.describe APIMatchers::Collection::BeSortedBy do
+  describe "actual.to be_sorted_by" do
+    context "ascending order (default)" do
+      it "passes when array is sorted ascending" do
+        json = '[{"id": 1}, {"id": 2}, {"id": 3}]'
+        expect(json).to be_sorted_by(:id)
+      end
+
+      it "passes when array is sorted ascending (explicit)" do
+        json = '[{"id": 1}, {"id": 2}, {"id": 3}]'
+        expect(json).to be_sorted_by(:id).ascending
+      end
+
+      it "fails when array is not sorted ascending" do
+        json = '[{"id": 3}, {"id": 1}, {"id": 2}]'
+        expect {
+          expect(json).to be_sorted_by(:id).ascending
+        }.to fail_with(/expected JSON array at 'root' to be sorted by 'id' ascending/)
+      end
+    end
+
+    context "descending order" do
+      it "passes when array is sorted descending" do
+        json = '[{"id": 3}, {"id": 2}, {"id": 1}]'
+        expect(json).to be_sorted_by(:id).descending
+      end
+
+      it "fails when array is not sorted descending" do
+        json = '[{"id": 1}, {"id": 2}, {"id": 3}]'
+        expect {
+          expect(json).to be_sorted_by(:id).descending
+        }.to fail_with(/expected JSON array at 'root' to be sorted by 'id' descending/)
+      end
+    end
+
+    context "with at_path" do
+      it "checks sorting at specified path" do
+        json = '{"users": [{"name": "Alice"}, {"name": "Bob"}, {"name": "Charlie"}]}'
+        expect(json).to be_sorted_by(:name).at_path("users")
+      end
+    end
+
+    context "with string values" do
+      it "sorts strings alphabetically" do
+        json = '[{"name": "Alice"}, {"name": "Bob"}, {"name": "Charlie"}]'
+        expect(json).to be_sorted_by(:name)
+      end
+    end
+
+    context "with date strings" do
+      it "sorts date strings" do
+        json = '[{"created_at": "2023-01-01"}, {"created_at": "2023-06-15"}, {"created_at": "2023-12-31"}]'
+        expect(json).to be_sorted_by(:created_at)
+      end
+
+      it "checks descending date order" do
+        json = '[{"created_at": "2023-12-31"}, {"created_at": "2023-06-15"}, {"created_at": "2023-01-01"}]'
+        expect(json).to be_sorted_by(:created_at).descending
+      end
+    end
+
+    context "with empty array" do
+      it "passes for empty array" do
+        json = '[]'
+        expect(json).to be_sorted_by(:id)
+      end
+    end
+
+    context "with single element" do
+      it "passes for single element array" do
+        json = '[{"id": 1}]'
+        expect(json).to be_sorted_by(:id)
+      end
+    end
+
+    context "when path does not exist" do
+      it "fails with descriptive message" do
+        json = '{"data": []}'
+        expect {
+          expect(json).to be_sorted_by(:id).at_path("users")
+        }.to fail_with(/but path was not found/)
+      end
+    end
+
+    context "when value is not an array" do
+      it "fails with descriptive message" do
+        json = '{"user": {"id": 1}}'
+        expect {
+          expect(json).to be_sorted_by(:id).at_path("user")
+        }.to fail_with(/path was not found or value was not an array/)
+      end
+    end
+  end
+
+  describe "actual.not_to be_sorted_by" do
+    it "passes when not sorted" do
+      json = '[{"id": 3}, {"id": 1}, {"id": 2}]'
+      expect(json).not_to be_sorted_by(:id)
+    end
+
+    it "fails when sorted" do
+      json = '[{"id": 1}, {"id": 2}, {"id": 3}]'
+      expect {
+        expect(json).not_to be_sorted_by(:id)
+      }.to fail_with(/expected JSON array at 'root' NOT to be sorted by 'id' ascending/)
+    end
+  end
+end

data/spec/api_matchers/collection/have_json_size_spec.rb

@@ -0,0 +1,101 @@
+require 'spec_helper'
+
+RSpec.describe APIMatchers::Collection::HaveJsonSize do
+  describe "actual.to have_json_size" do
+    context "with array at root" do
+      it "passes when size matches" do
+        json = '[1, 2, 3]'
+        expect(json).to have_json_size(3)
+      end
+
+      it "fails when size does not match" do
+        json = '[1, 2, 3]'
+        expect {
+          expect(json).to have_json_size(5)
+        }.to fail_with(/expected JSON collection at 'root' to have size 5. Got size: 3/)
+      end
+    end
+
+    context "with array at path" do
+      it "passes when size matches" do
+        json = '{"users": [{"id": 1}, {"id": 2}, {"id": 3}]}'
+        expect(json).to have_json_size(3).at_path("users")
+      end
+
+      it "fails when size does not match" do
+        json = '{"users": [{"id": 1}, {"id": 2}]}'
+        expect {
+          expect(json).to have_json_size(5).at_path("users")
+        }.to fail_with(/expected JSON collection at 'users' to have size 5. Got size: 2/)
+      end
+    end
+
+    context "with empty array" do
+      it "passes for size 0" do
+        json = '{"items": []}'
+        expect(json).to have_json_size(0).at_path("items")
+      end
+
+      it "fails when expecting non-zero size" do
+        json = '{"items": []}'
+        expect {
+          expect(json).to have_json_size(5).at_path("items")
+        }.to fail_with(/Got size: 0/)
+      end
+    end
+
+    context "with hash (keys count)" do
+      it "checks size of hash keys" do
+        json = '{"a": 1, "b": 2, "c": 3}'
+        expect(json).to have_json_size(3)
+      end
+    end
+
+    context "when path does not exist" do
+      it "fails with descriptive message" do
+        json = '{"data": []}'
+        expect {
+          expect(json).to have_json_size(5).at_path("users")
+        }.to fail_with(/but path was not found/)
+      end
+    end
+
+    context "when value is not a collection" do
+      it "fails with descriptive message" do
+        json = '{"count": "not a collection"}'
+        expect {
+          expect(json).to have_json_size(5).at_path("count")
+        }.to fail_with(/path was not found or value was not a collection/)
+      end
+    end
+  end
+
+  describe "actual.not_to have_json_size" do
+    it "passes when size does not match" do
+      json = '[1, 2, 3]'
+      expect(json).not_to have_json_size(5)
+    end
+
+    it "fails when size matches" do
+      json = '[1, 2, 3]'
+      expect {
+        expect(json).not_to have_json_size(3)
+      }.to fail_with(/expected JSON collection at 'root' NOT to have size 3/)
+    end
+  end
+
+  describe "with configuration" do
+    before do
+      APIMatchers.setup { |config| config.response_body_method = :body }
+    end
+
+    after do
+      APIMatchers.setup { |config| config.response_body_method = nil }
+    end
+
+    it "extracts body from response object" do
+      response = OpenStruct.new(body: '{"items": [1, 2, 3]}')
+      expect(response).to have_json_size(3).at_path("items")
+    end
+  end
+end

data/spec/api_matchers/error_response/have_error_on_spec.rb

@@ -0,0 +1,123 @@
+require 'spec_helper'
+
+RSpec.describe APIMatchers::ErrorResponse::HaveErrorOn do
+  describe "actual.to have_error_on" do
+    context "with array of error objects (standard API style)" do
+      it "passes when error exists on field" do
+        json = '{"errors": [{"field": "email", "message": "is invalid"}]}'
+        expect(json).to have_error_on(:email)
+      end
+
+      it "fails when no error on field" do
+        json = '{"errors": [{"field": "name", "message": "is required"}]}'
+        expect {
+          expect(json).to have_error_on(:email)
+        }.to fail_with(/Found errors on: \["name"\]/)
+      end
+    end
+
+    context "with Rails-style errors hash" do
+      it "passes when error exists on field" do
+        json = '{"email": ["is invalid", "is already taken"]}'
+        expect(json).to have_error_on(:email)
+      end
+
+      it "fails when no error on field" do
+        json = '{"name": ["is required"]}'
+        expect {
+          expect(json).to have_error_on(:email)
+        }.to fail_with(/Found errors on: \["name"\]/)
+      end
+    end
+
+    context "with with_message" do
+      it "passes when message matches" do
+        json = '{"errors": [{"field": "email", "message": "is invalid"}]}'
+        expect(json).to have_error_on(:email).with_message("is invalid")
+      end
+
+      it "fails when message does not match" do
+        json = '{"errors": [{"field": "email", "message": "is invalid"}]}'
+        expect {
+          expect(json).to have_error_on(:email).with_message("can't be blank")
+        }.to fail_with(/expected error on 'email' to have message/)
+      end
+
+      it "works with Rails-style errors" do
+        json = '{"email": ["is invalid", "is already taken"]}'
+        expect(json).to have_error_on(:email).with_message("is invalid")
+      end
+    end
+
+    context "with matching (regex)" do
+      it "passes when message matches pattern" do
+        json = '{"errors": [{"field": "email", "message": "Email format is invalid"}]}'
+        expect(json).to have_error_on(:email).matching(/invalid/i)
+      end
+
+      it "fails when message does not match pattern" do
+        json = '{"errors": [{"field": "email", "message": "is required"}]}'
+        expect {
+          expect(json).to have_error_on(:email).matching(/invalid/)
+        }.to fail_with(/expected error on 'email' to match/)
+      end
+    end
+
+    context "when no errors found" do
+      it "fails with descriptive message" do
+        json = '{"data": {"id": 1}}'
+        expect {
+          expect(json).to have_error_on(:email)
+        }.to fail_with(/but no errors were found/)
+      end
+    end
+
+    context "with attribute key instead of field" do
+      it "works with attribute key" do
+        json = '{"errors": [{"attribute": "email", "message": "is invalid"}]}'
+        expect(json).to have_error_on(:email)
+      end
+    end
+  end
+
+  describe "actual.not_to have_error_on" do
+    it "passes when no error on field" do
+      json = '{"errors": [{"field": "name", "message": "is required"}]}'
+      expect(json).not_to have_error_on(:email)
+    end
+
+    it "fails when error exists on field" do
+      json = '{"errors": [{"field": "email", "message": "is invalid"}]}'
+      expect {
+        expect(json).not_to have_error_on(:email)
+      }.to fail_with(/expected NOT to have error on 'email'/)
+    end
+  end
+
+  describe "with configuration" do
+    before do
+      APIMatchers.setup do |config|
+        config.response_body_method = :body
+        config.errors_path = 'response.errors'
+        config.error_field_key = 'attribute'
+        config.error_message_key = 'detail'
+      end
+    end
+
+    after do
+      APIMatchers.setup do |config|
+        config.response_body_method = nil
+        config.errors_path = nil
+        config.error_field_key = nil
+        config.error_message_key = nil
+      end
+    end
+
+    it "uses configured paths and keys" do
+      response = OpenStruct.new(
+        body: '{"response": {"errors": [{"attribute": "email", "detail": "is invalid"}]}}'
+      )
+      expect(response).to have_error_on(:email).with_message("is invalid")
+    end
+  end
+end

data/spec/api_matchers/error_response/have_error_spec.rb

@@ -0,0 +1,108 @@
+require 'spec_helper'
+
+RSpec.describe APIMatchers::ErrorResponse::HaveError do
+  describe "actual.to have_error" do
+    context "with errors array" do
+      it "passes when errors array is present" do
+        json = '{"errors": [{"message": "Name is required"}]}'
+        expect(json).to have_error
+      end
+
+      it "passes when errors array has multiple errors" do
+        json = '{"errors": [{"message": "Name is required"}, {"message": "Email is invalid"}]}'
+        expect(json).to have_errors
+      end
+
+      it "fails when errors array is empty" do
+        json = '{"errors": []}'
+        expect {
+          expect(json).to have_error
+        }.to fail_with(/expected response to have error/)
+      end
+    end
+
+    context "with error object" do
+      it "passes when error key is present" do
+        json = '{"error": "Something went wrong"}'
+        expect(json).to have_error
+      end
+
+      it "passes when error is an object" do
+        json = '{"error": {"code": "INVALID", "message": "Invalid input"}}'
+        expect(json).to have_error
+      end
+    end
+
+    context "with message key" do
+      it "passes when message is present" do
+        json = '{"message": "Resource not found"}'
+        expect(json).to have_error
+      end
+    end
+
+    context "with errors at configured path" do
+      before do
+        APIMatchers.setup { |config| config.errors_path = 'response.errors' }
+      end
+
+      after do
+        APIMatchers.setup { |config| config.errors_path = nil }
+      end
+
+      it "finds errors at configured path" do
+        json = '{"response": {"errors": [{"message": "Error"}]}}'
+        expect(json).to have_error
+      end
+    end
+
+    context "when no errors found" do
+      it "fails with descriptive message" do
+        json = '{"data": {"id": 1}}'
+        expect {
+          expect(json).to have_error
+        }.to fail_with(/expected response to have error/)
+      end
+    end
+  end
+
+  describe "actual.not_to have_error" do
+    it "passes when no errors present" do
+      json = '{"data": {"id": 1}}'
+      expect(json).not_to have_error
+    end
+
+    it "passes when errors array is empty" do
+      json = '{"errors": []}'
+      expect(json).not_to have_errors
+    end
+
+    it "fails when errors are present" do
+      json = '{"errors": [{"message": "Error"}]}'
+      expect {
+        expect(json).not_to have_error
+      }.to fail_with(/expected response NOT to have error/)
+    end
+  end
+
+  describe "alias have_errors" do
+    it "works as alias for have_error" do
+      json = '{"errors": [{"message": "Error"}]}'
+      expect(json).to have_errors
+    end
+  end
+
+  describe "with configuration" do
+    before do
+      APIMatchers.setup { |config| config.response_body_method = :body }
+    end
+
+    after do
+      APIMatchers.setup { |config| config.response_body_method = nil }
+    end
+
+    it "extracts body from response object" do
+      response = OpenStruct.new(body: '{"errors": [{"message": "Error"}]}')
+      expect(response).to have_error
+    end
+  end
+end

data/spec/api_matchers/hateoas/have_link_spec.rb

@@ -0,0 +1,105 @@
+require 'spec_helper'
+
+RSpec.describe APIMatchers::Hateoas::HaveLink do
+  describe "actual.to have_link" do
+    context "with HAL-style links" do
+      it "passes when link is present" do
+        json = '{"_links": {"self": {"href": "/users/1"}}}'
+        expect(json).to have_link(:self)
+      end
+
+      it "fails when link is not present" do
+        json = '{"_links": {"self": {"href": "/users/1"}}}'
+        expect {
+          expect(json).to have_link(:next)
+        }.to fail_with(/Available links: \["self"\]/)
+      end
+    end
+
+    context "with simple links object" do
+      it "passes when link is present" do
+        json = '{"links": {"self": "/users/1"}}'
+        expect(json).to have_link(:self)
+      end
+    end
+
+    context "with with_href (exact match)" do
+      it "passes when href matches exactly" do
+        json = '{"_links": {"self": {"href": "/users/1"}}}'
+        expect(json).to have_link(:self).with_href("/users/1")
+      end
+
+      it "fails when href does not match" do
+        json = '{"_links": {"self": {"href": "/users/1"}}}'
+        expect {
+          expect(json).to have_link(:self).with_href("/users/2")
+        }.to fail_with(/expected link 'self' to have href '\/users\/2'. Got: '\/users\/1'/)
+      end
+    end
+
+    context "with with_href (regex)" do
+      it "passes when href matches pattern" do
+        json = '{"_links": {"self": {"href": "/users/123"}}}'
+        expect(json).to have_link(:self).with_href(/\/users\/\d+/)
+      end
+
+      it "fails when href does not match pattern" do
+        json = '{"_links": {"self": {"href": "/posts/123"}}}'
+        expect {
+          expect(json).to have_link(:self).with_href(/\/users\/\d+/)
+        }.to fail_with(/expected link 'self' href to match/)
+      end
+    end
+
+    context "with simple string href" do
+      it "extracts href from string value" do
+        json = '{"links": {"self": "/users/1"}}'
+        expect(json).to have_link(:self).with_href("/users/1")
+      end
+    end
+
+    context "when links not found" do
+      it "fails with descriptive message" do
+        json = '{"data": {"id": 1}}'
+        expect {
+          expect(json).to have_link(:self)
+        }.to fail_with(/but no links were found/)
+      end
+    end
+  end
+
+  describe "actual.not_to have_link" do
+    it "passes when link is not present" do
+      json = '{"_links": {"self": {"href": "/users/1"}}}'
+      expect(json).not_to have_link(:next)
+    end
+
+    it "fails when link is present" do
+      json = '{"_links": {"self": {"href": "/users/1"}}}'
+      expect {
+        expect(json).not_to have_link(:self)
+      }.to fail_with(/expected response NOT to have link 'self', but it was present/)
+    end
+  end
+
+  describe "with configuration" do
+    before do
+      APIMatchers.setup do |config|
+        config.response_body_method = :body
+        config.links_path = 'links'
+      end
+    end
+
+    after do
+      APIMatchers.setup do |config|
+        config.response_body_method = nil
+        config.links_path = nil
+      end
+    end
+
+    it "uses configured links_path" do
+      response = OpenStruct.new(body: '{"links": {"self": {"href": "/users/1"}}}')
+      expect(response).to have_link(:self)
+    end
+  end
+end

data/spec/api_matchers/headers/base_spec.rb

@@ -1,12 +1,17 @@
 require 'spec_helper'
 
 RSpec.describe APIMatchers::Headers::Base do
-  let(:setup) { OpenStruct.new }
-  subject { APIMatchers::Headers::Base.new(setup) }
+  subject { APIMatchers::Headers::Base.new }
 
   describe "#matches?" do
     it "should raise Not Implement Exception" do
       expect { subject.matches?('application/xml') }.to raise_error(NotImplementedError, "not implemented on #{subject}")
     end
   end
-end
+
+  describe "#setup" do
+    it "returns the global Setup class" do
+      expect(subject.setup).to eq APIMatchers::Core::Setup
+    end
+  end
+end