apiwork-rspec 0.1.1

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

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module RSpec
+    module Matchers
+      # @api public
+      # Matcher for params in type definitions.
+      class HaveParamMatcher < BaseMatcher
+        BOOLEAN_CHECKS = {
+          deprecated: { expected: true, key: :deprecated },
+          nullable: { expected: true, key: :nullable },
+          optional: { expected: true, key: :optional },
+          required: { expected: false, key: :optional },
+        }.freeze
+
+        VALUE_CHECKS = %i[default description enum example format max min type].freeze
+
+        def initialize(name)
+          super()
+          @name = name
+          @checks = {}
+        end
+
+        # @api public
+        # Requires the param to have the expected type.
+        #
+        # @param type [Symbol] [:array, :binary, :boolean, :date, :datetime, :decimal, :integer, :number, :object, :record, :string, :time, :unknown, :uuid]
+        #   The type.
+        # @return [self]
+        def of_type(type)
+          @checks[:type] = type
+          self
+        end
+
+        # @api public
+        # Requires the param to be required.
+        #
+        # @return [self]
+        def required
+          @checks[:required] = true
+          self
+        end
+
+        # @api public
+        # Requires the param to be optional.
+        #
+        # @return [self]
+        def optional
+          @checks[:optional] = true
+          self
+        end
+
+        # @api public
+        # Requires the param to be nullable.
+        #
+        # @return [self]
+        def nullable
+          @checks[:nullable] = true
+          self
+        end
+
+        # @api public
+        # Requires the param to be deprecated.
+        #
+        # @return [self]
+        def deprecated
+          @checks[:deprecated] = true
+          self
+        end
+
+        # @api public
+        # Requires the param to have the expected enum values.
+        #
+        # @param values [Array]
+        #   The enum values.
+        # @return [self]
+        def with_enum(values)
+          @checks[:enum] = values
+          self
+        end
+
+        # @api public
+        # Requires the param to have the expected format.
+        #
+        # @param format [Symbol] [:date, :datetime, :double, :email, :float, :hostname, :int32, :int64, :ipv4, :ipv6, :password, :text, :url, :uuid]
+        #   The format. Valid formats by type: `:decimal`/`:number` (`:double`, `:float`), `:integer` (`:int32`, `:int64`),
+        #   `:string` (`:date`, `:datetime`, `:email`, `:hostname`, `:ipv4`, `:ipv6`, `:password`, `:text`, `:url`, `:uuid`).
+        # @return [self]
+        def with_format(format)
+          @checks[:format] = format
+          self
+        end
+
+        # @api public
+        # Requires the param to have the expected minimum.
+        #
+        # @param value [Numeric]
+        #   The minimum.
+        # @return [self]
+        def with_min(value)
+          @checks[:min] = value
+          self
+        end
+
+        # @api public
+        # Requires the param to have the expected maximum.
+        #
+        # @param value [Numeric]
+        #   The maximum.
+        # @return [self]
+        def with_max(value)
+          @checks[:max] = value
+          self
+        end
+
+        # @api public
+        # Requires the param to have the expected default.
+        #
+        # @param value [Object]
+        #   The default.
+        # @return [self]
+        def with_default(value)
+          @checks[:default] = value
+          self
+        end
+
+        # @api public
+        # Requires the param 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 param 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
+          param = subject.params[@name]
+          return fail_with("expected #{format_subject} to have param #{@name.inspect}") unless param
+
+          verify_all(param)
+        end
+
+        def description
+          parts = ["have param #{@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 - [:type]).each do |key|
+            parts << "with #{key} #{@checks[key].inspect}" if @checks.key?(key)
+          end
+          parts.join(' ')
+        end
+
+        private
+
+        def verify_all(param)
+          verify_value_checks(param) &&
+            verify_boolean_checks(param)
+        end
+
+        def verify_value_checks(param)
+          VALUE_CHECKS.each do |key|
+            next unless @checks.key?(key)
+
+            actual = param[key]
+            next if actual == @checks[key]
+
+            return fail_with(
+              "expected #{format_subject} to have param #{@name.inspect} " \
+              "#{format_value_check(key, @checks[key])}, but got #{actual.inspect}",
+            )
+          end
+          true
+        end
+
+        def verify_boolean_checks(param)
+          BOOLEAN_CHECKS.each do |check_name, config|
+            next unless @checks.key?(check_name)
+
+            actual = param[config[:key]]
+            next if actual == config[:expected]
+
+            return fail_with(
+              "expected #{format_subject} to have param #{@name.inspect} " \
+              "that is #{check_name}, but it is not",
+            )
+          end
+          true
+        end
+
+        def format_value_check(key, value)
+          case key
+          when :type
+            "of type #{value.inspect}"
+          else
+            "with #{key} #{value.inspect}"
+          end
+        end
+
+        def boolean_description_parts
+          parts = []
+          BOOLEAN_CHECKS.each_key { |key| parts << key.to_s if @checks.key?(key) }
+          parts
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module RSpec
+    module Matchers
+      # @api public
+      # Matcher for verifying an API has the expected path format.
+      class HavePathFormatMatcher < BaseMatcher
+        def initialize(format)
+          super()
+          @format = format
+        end
+
+        def matches?(subject)
+          @subject = subject
+          actual = subject.path_format
+          return true if actual == @format
+
+          fail_with(
+            "expected #{format_subject} to have path format #{@format.inspect}, but got #{actual.inspect}",
+          )
+        end
+
+        def description
+          "have path format #{@format.inspect}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module RSpec
+    module Matchers
+      # @api public
+      # Matcher for verifying an action has the expected raises.
+      class HaveRaisesMatcher < BaseMatcher
+        def initialize(codes)
+          super()
+          @codes = codes
+        end
+
+        def matches?(subject)
+          @subject = subject
+          actual = subject.raises
+          return true if actual == @codes
+
+          fail_with(
+            "expected #{format_subject} to have raises #{@codes.inspect}, but got #{actual.inspect}",
+          )
+        end
+
+        def description
+          "have raises #{@codes.inspect}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module RSpec
+    module Matchers
+      # @api public
+      # Matcher for verifying a contract has the expected representation.
+      class HaveRepresentationMatcher < BaseMatcher
+        def initialize(klass)
+          super()
+          @klass = klass
+        end
+
+        def matches?(subject)
+          @subject = subject
+          actual = subject.representation_class
+          return true if actual == @klass
+
+          fail_with(
+            "expected #{format_subject} to have representation #{@klass.inspect}, but got #{actual.inspect}",
+          )
+        end
+
+        def description
+          "have representation #{@klass.inspect}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module RSpec
+    module Matchers
+      # @api public
+      # Matcher for API resource structure.
+      class HaveResourceMatcher < BaseMatcher
+        VALUE_CHECKS = {
+          except: :except,
+          only: :only,
+        }.freeze
+
+        def initialize(name)
+          super()
+          @name = name
+          @parents = []
+          @checks = {}
+        end
+
+        # @api public
+        # Specifies the parent resources for a nested resource.
+        #
+        # @param parents [Array<Symbol>]
+        #   The parent resource names.
+        # @return [self]
+        def under(*parents)
+          @parents = parents
+          self
+        end
+
+        # @api public
+        # Requires the resource to be singular.
+        #
+        # @return [self]
+        def singular
+          @checks[:singular] = true
+          self
+        end
+
+        # @api public
+        # Requires the resource to have the expected allowed actions.
+        #
+        # @param actions [Array<Symbol>] [:create, :destroy, :index, :show, :update]
+        #   The allowed actions.
+        # @return [self]
+        def with_only(*actions)
+          @checks[:only] = actions.flatten
+          self
+        end
+
+        # @api public
+        # Requires the resource to have the expected excluded actions.
+        #
+        # @param actions [Array<Symbol>] [:create, :destroy, :index, :show, :update]
+        #   The excluded actions.
+        # @return [self]
+        def with_except(*actions)
+          @checks[:except] = actions.flatten
+          self
+        end
+
+        def matches?(subject)
+          @subject = subject
+          resource = find_resource(subject)
+          return false unless resource
+
+          verify_singular(resource) &&
+            verify_value_checks(resource)
+        end
+
+        def description
+          parts = ["have resource #{@name.inspect}"]
+          parts << "under #{@parents.map(&:inspect).join(', ')}" if @parents.any?
+          parts << 'that is singular' if @checks.key?(:singular)
+          VALUE_CHECKS.each_key do |key|
+            parts << "with #{key} #{@checks[key].inspect}" if @checks.key?(key)
+          end
+          parts.join(' ')
+        end
+
+        private
+
+        def find_resource(subject)
+          parent = subject.root_resource
+
+          @parents.each do |parent_name|
+            child = parent.resources[parent_name]
+            unless child
+              fail_with(
+                "expected #{format_subject} to have resource #{@name.inspect} " \
+                "under #{@parents.map(&:inspect).join(', ')}, " \
+                "but #{parent_name.inspect} was not found",
+              )
+              return nil
+            end
+            parent = child
+          end
+
+          resource = parent.resources[@name]
+          unless resource
+            if @parents.any?
+              fail_with(
+                "expected #{format_subject} to have resource #{@name.inspect} " \
+                "under #{@parents.map(&:inspect).join(', ')}",
+              )
+            else
+              fail_with("expected #{format_subject} to have resource #{@name.inspect}")
+            end
+            return nil
+          end
+
+          resource
+        end
+
+        def verify_singular(resource)
+          return true unless @checks.key?(:singular)
+          return true if resource.singular
+
+          fail_with(
+            "expected #{format_subject} to have resource #{@name.inspect} that is singular, but it is not",
+          )
+        end
+
+        def verify_value_checks(resource)
+          VALUE_CHECKS.each do |key, method|
+            next unless @checks.key?(key)
+
+            actual = resource.public_send(method)
+            next if actual == @checks[key]
+
+            return fail_with(
+              "expected #{format_subject} to have resource #{@name.inspect} " \
+              "with #{key} #{@checks[key].inspect}, but got #{actual.inspect}",
+            )
+          end
+          true
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module RSpec
+    module Matchers
+      # @api public
+      # Matcher for verifying a representation has the expected root key.
+      class HaveRootMatcher < BaseMatcher
+        def initialize(singular, plural)
+          super()
+          @singular = singular
+          @plural = plural
+        end
+
+        def matches?(subject)
+          @subject = subject
+          root = subject.root_key
+          actual_singular = root.singular
+          actual_plural = root.plural
+
+          return true if actual_singular == @singular && actual_plural == @plural
+
+          fail_with(
+            "expected #{format_subject} to have root #{@singular.inspect}, #{@plural.inspect}, " \
+            "but got #{actual_singular.inspect}, #{actual_plural.inspect}",
+          )
+        end
+
+        def description
+          "have root #{@singular.inspect}, #{@plural.inspect}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module RSpec
+    module Matchers
+      # @api public
+      # Matcher for verifying an action has the expected summary.
+      class HaveSummaryMatcher < BaseMatcher
+        def initialize(text)
+          super()
+          @text = text
+        end
+
+        def matches?(subject)
+          @subject = subject
+          actual = subject.summary
+          return true if actual == @text
+
+          fail_with(
+            "expected #{format_subject} to have summary #{@text.inspect}, but got #{actual.inspect}",
+          )
+        end
+
+        def description
+          "have summary #{@text.inspect}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module RSpec
+    module Matchers
+      # @api public
+      # Matcher for verifying an action has the expected tags.
+      class HaveTagsMatcher < BaseMatcher
+        def initialize(tags)
+          super()
+          @tags = tags
+        end
+
+        def matches?(subject)
+          @subject = subject
+          actual = subject.tags
+          return true if actual == @tags
+
+          fail_with(
+            "expected #{format_subject} to have tags #{@tags.inspect}, but got #{actual.inspect}",
+          )
+        end
+
+        def description
+          "have tags #{@tags.inspect}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module RSpec
+    module Matchers
+      # @api public
+      # Matcher for verifying an API info has the expected terms of service.
+      class HaveTermsOfServiceMatcher < BaseMatcher
+        def initialize(url)
+          super()
+          @url = url
+        end
+
+        def matches?(subject)
+          @subject = subject
+          actual = subject.terms_of_service
+          return true if actual == @url
+
+          fail_with(
+            "expected #{format_subject} to have terms of service #{@url.inspect}, but got #{actual.inspect}",
+          )
+        end
+
+        def description
+          "have terms of service #{@url.inspect}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module RSpec
+    module Matchers
+      # @api public
+      # Matcher for verifying an API info has the expected title.
+      class HaveTitleMatcher < BaseMatcher
+        def initialize(text)
+          super()
+          @text = text
+        end
+
+        def matches?(subject)
+          @subject = subject
+          actual = subject.title
+          return true if actual == @text
+
+          fail_with(
+            "expected #{format_subject} to have title #{@text.inspect}, but got #{actual.inspect}",
+          )
+        end
+
+        def description
+          "have title #{@text.inspect}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module RSpec
+    module Matchers
+      # @api public
+      # Matcher for verifying a representation has the expected type name.
+      class HaveTypeNameMatcher < BaseMatcher
+        def initialize(value)
+          super()
+          @value = value
+        end
+
+        def matches?(subject)
+          @subject = subject
+          actual = subject.type_name
+          return true if actual == @value
+
+          fail_with(
+            "expected #{format_subject} to have type name #{@value.inspect}, but got #{actual.inspect}",
+          )
+        end
+
+        def description
+          "have type name #{@value.inspect}"
+        end
+      end
+    end
+  end
+end