apiwork-rspec 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 83aafbeb0b15f739a2b538f43f386322d94631de471addc08f1b69196a38e254
+  data.tar.gz: 34000a080944fe635de1e5bd6d4b07021e8f6c9f8d1d7feb86c496373e3f05e3
+SHA512:
+  metadata.gz: 186e6a9a8e19a7f5507dd9152e9e3d22284faecf4b97fbcf58d47b03d52e2ce3d6d143084d141786f444eb7b8ce2cfb0a9e75f122805b54052c9096c2761760e
+  data.tar.gz: e38d9d193b0b5ddf9b3df0282502402fd4da58caaddde442cef8227642330053ad9edc9140bb1aefe7f8f73ec7f726c2a14893ec5c2c5a3c1c80e6cf6f686789

data/LICENSE.txt

@@ -0,0 +1,21 @@
+Copyright (c) 2026 skiftle
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rubocop/rake_task'
+require 'rspec/core/rake_task'
+
+RuboCop::RakeTask.new
+RSpec::Core::RakeTask.new(:spec)
+
+task default: %i[rubocop spec]

data/lib/apiwork/rspec/matchers/base_matcher.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module RSpec
+    module Matchers
+      # @api public
+      # Base class for matchers.
+      class BaseMatcher
+        include ::RSpec::Matchers::Composable
+
+        attr_reader :failure_message
+
+        def initialize
+          @failure_message = nil
+        end
+
+        def does_not_match?(subject)
+          !matches?(subject)
+        end
+
+        def failure_message_when_negated
+          "expected #{format_subject} not to #{description}"
+        end
+
+        private
+
+        def format_subject
+          @subject.respond_to?(:name) ? @subject.name : @subject.to_s
+        end
+
+        def fail_with(message)
+          @failure_message = message
+          false
+        end
+
+        def join_sentence(words)
+          return words.join(' and ') if words.size <= 2
+
+          "#{words[0..-2].join(', ')}, and #{words[-1]}"
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/rspec/matchers/define_contact_matcher.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module RSpec
+    module Matchers
+      # @api public
+      # Matcher for verifying an API info defines a contact.
+      class DefineContactMatcher < BaseMatcher
+        VALUE_CHECKS = {
+          email: :email,
+          url: :url,
+        }.freeze
+
+        def initialize(name)
+          super()
+          @name = name
+          @checks = {}
+        end
+
+        # @api public
+        # Requires the contact to have the expected email.
+        #
+        # @param email [String]
+        #   The email.
+        # @return [self]
+        def with_email(email)
+          @checks[:email] = email
+          self
+        end
+
+        # @api public
+        # Requires the contact to have the expected URL.
+        #
+        # @param url [String]
+        #   The URL.
+        # @return [self]
+        def with_url(url)
+          @checks[:url] = url
+          self
+        end
+
+        def matches?(subject)
+          @subject = subject
+          contact = subject.contact
+          return fail_with("expected #{format_subject} to define contact #{@name.inspect}") unless contact
+          unless contact.name == @name
+            return fail_with("expected #{format_subject} to define contact #{@name.inspect}, but got #{contact.name.inspect}")
+          end
+
+          verify_value_checks(contact)
+        end
+
+        def description
+          parts = ["define contact #{@name.inspect}"]
+          VALUE_CHECKS.each_key do |key|
+            parts << "with #{key} #{@checks[key].inspect}" if @checks.key?(key)
+          end
+          parts.join(' ')
+        end
+
+        private
+
+        def verify_value_checks(contact)
+          VALUE_CHECKS.each do |key, method|
+            next unless @checks.key?(key)
+
+            actual = contact.public_send(method)
+            next if actual == @checks[key]
+
+            return fail_with(
+              "expected #{format_subject} to define contact #{@name.inspect} " \
+              "with #{key} #{@checks[key].inspect}, but got #{actual.inspect}",
+            )
+          end
+          true
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/rspec/matchers/define_enum_matcher.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module RSpec
+    module Matchers
+      # @api public
+      # Matcher for enum definitions.
+      class DefineEnumMatcher < BaseMatcher
+        VALUE_CHECKS = {
+          description: :description,
+          example: :example,
+        }.freeze
+
+        def initialize(name)
+          super()
+          @name = name
+          @expected_values = nil
+          @checks = {}
+        end
+
+        # @api public
+        # Requires the enum to have the expected values.
+        #
+        # @param values [Array]
+        #   The enum values.
+        # @return [self]
+        def with_values(values)
+          @expected_values = values
+          self
+        end
+
+        # @api public
+        # Requires the enum to be deprecated.
+        #
+        # @return [self]
+        def deprecated
+          @checks[:deprecated] = true
+          self
+        end
+
+        # @api public
+        # Requires the enum to have the expected description.
+        #
+        # @param text [String]
+        #   The description.
+        # @return [self]
+        def with_description(text)
+          @checks[:description] = text
+          self
+        end
+
+        # @api public
+        # Requires the enum to have the expected example.
+        #
+        # @param value [Object]
+        #   The example.
+        # @return [self]
+        def with_example(value)
+          @checks[:example] = value
+          self
+        end
+
+        def matches?(subject)
+          @subject = subject
+          values = subject.enum_values(@name)
+          return fail_with("expected #{format_subject} to define enum #{@name.inspect}") unless values
+
+          verify_values(values) &&
+            verify_metadata(subject)
+        end
+
+        def description
+          parts = ["define enum #{@name.inspect}"]
+          parts << 'that is deprecated' if @checks.key?(:deprecated)
+          parts << "with values #{@expected_values.inspect}" if @expected_values
+          VALUE_CHECKS.each_key do |key|
+            parts << "with #{key} #{@checks[key].inspect}" if @checks.key?(key)
+          end
+          parts.join(' ')
+        end
+
+        private
+
+        def verify_values(values)
+          return true unless @expected_values
+          return true if values == @expected_values
+
+          fail_with(
+            "expected #{format_subject} to define enum #{@name.inspect} " \
+            "with values #{@expected_values.inspect}, but got #{values.inspect}",
+          )
+        end
+
+        def verify_metadata(subject)
+          definition = find_enum_definition(subject)
+          return true unless definition_required?
+          return fail_with("expected #{format_subject} to support enum metadata (use API class)") unless definition
+
+          verify_deprecated(definition) &&
+            verify_value_checks(definition)
+        end
+
+        def find_enum_definition(subject)
+          return unless subject.respond_to?(:enum_registry)
+
+          subject.enum_registry[@name]
+        end
+
+        def definition_required?
+          @checks.key?(:deprecated) || @checks.key?(:description) || @checks.key?(:example)
+        end
+
+        def verify_deprecated(definition)
+          return true unless @checks.key?(:deprecated)
+          return true if definition.deprecated?
+
+          fail_with(
+            "expected #{format_subject} to define enum #{@name.inspect} that is deprecated, but it is not",
+          )
+        end
+
+        def verify_value_checks(definition)
+          VALUE_CHECKS.each do |key, method|
+            next unless @checks.key?(key)
+
+            actual = definition.public_send(method)
+            next if actual == @checks[key]
+
+            return fail_with(
+              "expected #{format_subject} to define enum #{@name.inspect} " \
+              "with #{key} #{@checks[key].inspect}, but got #{actual.inspect}",
+            )
+          end
+          true
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/rspec/matchers/define_license_matcher.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module RSpec
+    module Matchers
+      # @api public
+      # Matcher for verifying an API info defines a license.
+      class DefineLicenseMatcher < BaseMatcher
+        def initialize(name)
+          super()
+          @name = name
+          @checks = {}
+        end
+
+        # @api public
+        # Requires the license to have the expected URL.
+        #
+        # @param url [String]
+        #   The URL.
+        # @return [self]
+        def with_url(url)
+          @checks[:url] = url
+          self
+        end
+
+        def matches?(subject)
+          @subject = subject
+          license = subject.license
+          return fail_with("expected #{format_subject} to define license #{@name.inspect}") unless license
+          unless license.name == @name
+            return fail_with("expected #{format_subject} to define license #{@name.inspect}, but got #{license.name.inspect}")
+          end
+
+          return true unless @checks.key?(:url)
+
+          actual = license.url
+          return true if actual == @checks[:url]
+
+          fail_with(
+            "expected #{format_subject} to define license #{@name.inspect} " \
+            "with url #{@checks[:url].inspect}, but got #{actual.inspect}",
+          )
+        end
+
+        def description
+          parts = ["define license #{@name.inspect}"]
+          parts << "with url #{@checks[:url].inspect}" if @checks.key?(:url)
+          parts.join(' ')
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/rspec/matchers/define_server_matcher.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module RSpec
+    module Matchers
+      # @api public
+      # Matcher for verifying an API info defines a server.
+      class DefineServerMatcher < BaseMatcher
+        def initialize(url)
+          super()
+          @url = url
+          @checks = {}
+        end
+
+        # @api public
+        # Requires the server to have the expected description.
+        #
+        # @param text [String]
+        #   The description.
+        # @return [self]
+        def with_description(text)
+          @checks[:description] = text
+          self
+        end
+
+        def matches?(subject)
+          @subject = subject
+          server = subject.servers.find { |s| s.url == @url }
+          return fail_with("expected #{format_subject} to define server #{@url.inspect}") unless server
+
+          return true unless @checks.key?(:description)
+
+          actual = server.description
+          return true if actual == @checks[:description]
+
+          fail_with(
+            "expected #{format_subject} to define server #{@url.inspect} " \
+            "with description #{@checks[:description].inspect}, but got #{actual.inspect}",
+          )
+        end
+
+        def description
+          parts = ["define server #{@url.inspect}"]
+          parts << "with description #{@checks[:description].inspect}" if @checks.key?(:description)
+          parts.join(' ')
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/rspec/matchers/have_association_matcher.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module RSpec
+    module Matchers
+      # @api public
+      # Matcher for representation associations.
+      class HaveAssociationMatcher < BaseMatcher
+        BOOLEAN_CHECKS = {
+          allow_destroy: :allow_destroy,
+          deprecated: :deprecated?,
+          filterable: :filterable?,
+          nullable: :nullable?,
+          polymorphic: :polymorphic?,
+          sortable: :sortable?,
+        }.freeze
+
+        VALUE_CHECKS = {
+          description: :description,
+          example: :example,
+          include: :include,
+          representation: :representation_class,
+        }.freeze
+
+        def initialize(name)
+          super()
+          @name = name
+          @checks = {}
+        end
+
+        # @api public
+        # Requires the association to have the expected type.
+        #
+        # @param type [Symbol] [:belongs_to, :has_many, :has_one]
+        #   The type.
+        # @return [self]
+        def of_type(type)
+          @checks[:type] = type
+          self
+        end
+
+        # @api public
+        # Requires the association to be writable.
+        #
+        # @param action [Symbol, Boolean] (true) [Symbol: :create, :update]
+        #   The action to check writability for, or `true` for any action.
+        # @return [self]
+        def writable(action = true)
+          @checks[:writable] = action
+          self
+        end
+
+        # @api public
+        # Requires the association to allow destroy.
+        #
+        # @return [self]
+        def allow_destroy
+          @checks[:allow_destroy] = true
+          self
+        end
+
+        # @api public
+        # Requires the association to be deprecated.
+        #
+        # @return [self]
+        def deprecated
+          @checks[:deprecated] = true
+          self
+        end
+
+        # @api public
+        # Requires the association to be filterable.
+        #
+        # @return [self]
+        def filterable
+          @checks[:filterable] = true
+          self
+        end
+
+        # @api public
+        # Requires the association to be nullable.
+        #
+        # @return [self]
+        def nullable
+          @checks[:nullable] = true
+          self
+        end
+
+        # @api public
+        # Requires the association to be polymorphic.
+        #
+        # @return [self]
+        def polymorphic
+          @checks[:polymorphic] = true
+          self
+        end
+
+        # @api public
+        # Requires the association to be sortable.
+        #
+        # @return [self]
+        def sortable
+          @checks[:sortable] = true
+          self
+        end
+
+        # @api public
+        # Requires the association to have the expected inclusion strategy.
+        #
+        # @param value [Symbol] [:always, :optional]
+        #   The inclusion strategy.
+        # @return [self]
+        def with_include(value)
+          @checks[:include] = value
+          self
+        end
+
+        # @api public
+        # Requires the association to have the expected representation class.
+        #
+        # @param klass [Class]
+        #   The representation class.
+        # @return [self]
+        def with_representation(klass)
+          @checks[:representation] = klass
+          self
+        end
+
+        # @api public
+        # Requires the association to have the expected description.
+        #
+        # @param text [String]
+        #   The description.
+        # @return [self]
+        def with_description(text)
+          @checks[:description] = text
+          self
+        end
+
+        # @api public
+        # Requires the association to have the expected example.
+        #
+        # @param value [Object]
+        #   The example.
+        # @return [self]
+        def with_example(value)
+          @checks[:example] = value
+          self
+        end
+
+        def matches?(subject)
+          @subject = subject
+          association = subject.associations[@name]
+          return fail_with("expected #{format_subject} to have association #{@name.inspect}") unless association
+
+          verify_all(association)
+        end
+
+        def description
+          parts = ["have association #{@name.inspect}"]
+          parts << "of type #{@checks[:type].inspect}" if @checks.key?(:type)
+          boolean_parts = boolean_description_parts
+          parts << "that is #{join_sentence(boolean_parts)}" if boolean_parts.any?
+          VALUE_CHECKS.each_key do |key|
+            parts << "with #{key} #{@checks[key].inspect}" if @checks.key?(key)
+          end
+          parts.join(' ')
+        end
+
+        private
+
+        def verify_all(association)
+          verify_type(association) &&
+            verify_boolean_checks(association) &&
+            verify_writable(association) &&
+            verify_value_checks(association)
+        end
+
+        def verify_type(association)
+          return true unless @checks.key?(:type)
+          return true if association.type == @checks[:type]
+
+          fail_with(
+            "expected #{format_subject} to have association #{@name.inspect} " \
+            "of type #{@checks[:type].inspect}, but got #{association.type.inspect}",
+          )
+        end
+
+        def verify_boolean_checks(association)
+          BOOLEAN_CHECKS.each do |key, method|
+            next unless @checks.key?(key)
+            next if association.public_send(method)
+
+            return fail_with(
+              "expected #{format_subject} to have association #{@name.inspect} that is #{key}, but it is not",
+            )
+          end
+          true
+        end
+
+        def verify_writable(association)
+          return true unless @checks.key?(:writable)
+
+          expected = @checks[:writable]
+          if expected == true
+            return true if association.writable?
+
+            return fail_with(
+              "expected #{format_subject} to have association #{@name.inspect} that is writable, but it is not",
+            )
+          end
+
+          return true if association.writable_for?(expected)
+
+          fail_with(
+            "expected #{format_subject} to have association #{@name.inspect} " \
+            "that is writable for #{expected.inspect}, but it is not",
+          )
+        end
+
+        def verify_value_checks(association)
+          VALUE_CHECKS.each do |key, method|
+            next unless @checks.key?(key)
+
+            actual = association.public_send(method)
+            next if actual == @checks[key]
+
+            return fail_with(
+              "expected #{format_subject} to have association #{@name.inspect} " \
+              "with #{key} #{@checks[key].inspect}, but got #{actual.inspect}",
+            )
+          end
+          true
+        end
+
+        def boolean_description_parts
+          parts = []
+          BOOLEAN_CHECKS.each_key { |key| parts << key.to_s if @checks.key?(key) }
+          if @checks.key?(:writable)
+            parts << (@checks[:writable] == true ? 'writable' : "writable for #{@checks[:writable].inspect}")
+          end
+          parts
+        end
+      end
+    end
+  end
+end