rspec-rest 0.1.0

data/lib/rspec/rest/contract_matcher.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module RSpec
+  module Rest
+    class UnknownContractMatcher
+      def initialize(message)
+        @message = message
+      end
+
+      def matches?(_actual)
+        false
+      end
+
+      def failure_message
+        @message
+      end
+
+      def failure_message_when_negated
+        @message
+      end
+
+      def description
+        "unknown JSON contract"
+      end
+    end
+
+    class ContractMatcher
+      def initialize(name:, definition:, context:)
+        @name = name
+        @definition = definition
+        @context = context
+      end
+
+      def matches?(actual)
+        matcher.matches?(actual)
+      end
+
+      def failure_message
+        "Contract #{@name.inspect} failed: #{matcher.failure_message}"
+      end
+
+      def failure_message_when_negated
+        "Contract #{@name.inspect} failed: #{matcher.failure_message_when_negated}"
+      end
+
+      def description
+        "match contract #{@name.inspect}"
+      end
+
+      private
+
+      def matcher
+        @matcher ||= begin
+          value = @context.instance_exec(&@definition)
+          value.respond_to?(:matches?) ? value : @context.eq(value)
+        end
+      end
+    end
+  end
+end

data/lib/rspec/rest/dsl.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+require_relative "config"
+require_relative "captures"
+require_relative "class_level_contracts"
+require_relative "class_level_presets"
+require_relative "errors"
+require_relative "expectations"
+require_relative "json_selector"
+require_relative "request_builders"
+require_relative "session"
+module RSpec
+  module Rest
+    module DSL
+      HTTP_METHODS = ::RSpec::Rest::Session::SUPPORTED_HTTP_METHODS
+
+      class ApiConfigBuilder
+        def initialize(config)
+          @config = Config.new(
+            app: config.app,
+            base_path: config.base_path,
+            base_headers: config.base_headers,
+            default_format: config.default_format,
+            redact_headers: config.redact_headers,
+            base_url: config.base_url
+          )
+        end
+
+        def app(value)
+          @config.app = value
+        end
+
+        def base_path(value)
+          @config.base_path = value
+        end
+
+        def base_headers(value)
+          @config.base_headers = value.dup
+        end
+
+        def default_format(value)
+          @config.default_format = value
+        end
+
+        def redact_headers(value)
+          @config.redact_headers = value.dup
+        end
+
+        def base_url(value)
+          @config.base_url = value
+        end
+
+        def to_config
+          @config
+        end
+      end
+
+      module ClassMethods
+        include ClassLevelContracts
+        include ClassLevelPresets
+
+        def api(&)
+          builder = ApiConfigBuilder.new(rest_config)
+          builder.instance_eval(&)
+          @rest_config = builder.to_config
+        end
+
+        def resource(path, &)
+          @rest_resource_stack ||= []
+          @rest_preset_stack ||= []
+          @rest_resource_stack << path
+          @rest_preset_stack << blank_presets
+          class_eval(&)
+        ensure
+          @rest_preset_stack.pop
+          @rest_resource_stack.pop
+        end
+
+        HTTP_METHODS.each do |method|
+          define_method(method) do |path, &block|
+            resource_path = current_resource_path
+            request_presets = deep_dup_presets(current_request_presets)
+            it("#{method.to_s.upcase} #{path}") do
+              start_rest_request(
+                method: method,
+                path: path,
+                resource_path: resource_path,
+                presets: request_presets
+              )
+              instance_eval(&block) if block
+              execute_rest_request_if_pending
+            end
+          end
+        end
+
+        def rest_config
+          return @rest_config if instance_variable_defined?(:@rest_config)
+
+          parent = superclass.respond_to?(:rest_config) ? superclass.rest_config : Config.new
+          Config.new(
+            app: parent.app,
+            base_path: parent.base_path,
+            base_headers: parent.base_headers,
+            default_format: parent.default_format,
+            redact_headers: parent.redact_headers,
+            base_url: parent.base_url
+          )
+        end
+
+        private
+
+        def current_resource_path
+          stack = @rest_resource_stack || []
+          return nil if stack.empty?
+
+          first_had_leading_slash = stack.first.to_s.start_with?("/")
+          normalized_segments = stack.map do |segment|
+            segment.to_s.sub(%r{\A/+}, "").sub(%r{/+\z}, "")
+          end.reject(&:empty?)
+
+          path = normalized_segments.join("/")
+          first_had_leading_slash && !path.empty? ? "/#{path}" : path
+        end
+      end
+
+      module InstanceMethods
+        include Captures
+        include Expectations
+        include RequestBuilders
+
+        def rest_session
+          @rest_session ||= Session.new(self.class.rest_config)
+        end
+
+        def rest_response
+          ensure_request_context!
+          execute_rest_request_if_pending
+          @rest_response
+        end
+
+        def last_request
+          ensure_request_context!
+          execute_rest_request_if_pending
+          rest_session.last_request
+        end
+
+        private
+
+        def start_rest_request(method:, path:, resource_path:, presets: nil)
+          effective_presets = presets || ClassLevelPresets::DEFAULT_PRESETS
+          preset_headers = (effective_presets[:headers] || {}).dup
+          preset_query = (effective_presets[:query] || {}).dup
+
+          @rest_request_state = {
+            method: method,
+            path: path,
+            resource_path: resource_path,
+            headers: preset_headers,
+            query: preset_query.empty? ? nil : preset_query,
+            json: nil,
+            multipart: false,
+            params: nil,
+            path_params: {}
+          }
+          @rest_response = nil
+          @rest_request_executed = false
+        end
+
+        def execute_rest_request_if_pending
+          ensure_request_context!
+          return if @rest_request_executed
+
+          @rest_request_executed = true
+          execute_rest_request
+        end
+
+        def execute_rest_request
+          request_path = apply_path_params(
+            rest_request_state[:path],
+            rest_request_state[:path_params]
+          )
+          request_resource_path = apply_path_params(
+            rest_request_state[:resource_path],
+            rest_request_state[:path_params]
+          )
+          if rest_request_state[:multipart] && !rest_request_state[:json].nil?
+            raise ArgumentError, "Cannot use json(...) with multipart! requests. Use file(...) and params."
+          end
+
+          @rest_response = rest_session.request(
+            method: rest_request_state[:method],
+            path: request_path,
+            resource_path: request_resource_path,
+            headers: rest_request_state[:headers],
+            query: rest_request_state[:query],
+            json: rest_request_state[:json],
+            params: rest_request_state[:params]
+          )
+        end
+
+        def rest_request_state
+          unless defined?(@rest_request_state) && @rest_request_state
+            raise MissingRequestContextError,
+                  "REST request context is not initialized. Call this inside a verb block (get/post/put/patch/delete)."
+          end
+
+          @rest_request_state
+        end
+
+        def ensure_request_context!
+          return if defined?(@rest_request_state) && @rest_request_state
+
+          raise MissingRequestContextError,
+                "No active REST request context. Call this inside a verb block (get/post/put/patch/delete)."
+        end
+
+        def apply_path_params(path, params)
+          rendered = params.reduce(path.to_s) do |current, (key, value)|
+            current.gsub("{#{key}}", value.to_s)
+          end
+
+          # Detect any placeholders that were not replaced and provide a clear error
+          missing_placeholders = rendered.scan(/\{([^}]+)\}/).flatten.uniq
+          unless missing_placeholders.empty?
+            raise ArgumentError,
+                  "Missing path params for placeholders: #{missing_placeholders.join(', ')} in path '#{path}'"
+          end
+
+          rendered
+        end
+      end
+
+      def self.included(base)
+        base.extend(ClassMethods)
+        base.include(InstanceMethods)
+      end
+    end
+  end
+end

data/lib/rspec/rest/error_expectations.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module RSpec
+  module Rest
+    module ErrorExpectations
+      def expect_error(status:, message: nil, includes: nil, field: nil, key: "error")
+        with_request_dump_on_failure do
+          expect(rest_response.status).to eq(status)
+          error_value = extract_error_value(key)
+          expect_error_message!(error_value, message) if message
+          expect_error_includes!(error_value, includes) if includes
+          expect_error_field!(error_value, field) if field
+          error_value
+        end
+      end
+
+      private
+
+      def extract_error_value(key)
+        payload = rest_response.json
+        unless payload.is_a?(Hash)
+          raise ::RSpec::Expectations::ExpectationNotMetError,
+                "Expected JSON response to be an object with #{key.inspect} key, got #{payload.class}."
+        end
+
+        normalized_key = key.to_s
+        error_value = payload[normalized_key]
+        return error_value unless error_value.nil?
+
+        raise ::RSpec::Expectations::ExpectationNotMetError,
+              "Expected JSON response to include #{normalized_key.inspect} key."
+      end
+
+      def expect_error_message!(error_value, message)
+        if error_value.is_a?(Array)
+          expect(error_value).to include(message)
+        else
+          expect(error_value).to eq(message)
+        end
+      end
+
+      def expect_error_includes!(error_value, includes)
+        Array(includes).each do |expected_fragment|
+          expect(error_text(error_value)).to include(expected_fragment.to_s)
+        end
+      end
+
+      def expect_error_field!(error_value, field)
+        expect(error_text(error_value)).to include(field.to_s)
+      end
+
+      def error_text(error_value)
+        error_value.is_a?(Array) ? error_value.join(" ") : error_value.to_s
+      end
+    end
+  end
+end

data/lib/rspec/rest/errors.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module RSpec
+  module Rest
+    class Error < StandardError; end
+
+    class MissingAppError < Error; end
+
+    class InvalidJsonError < Error; end
+
+    class UnsupportedHttpMethodError < Error; end
+
+    class MissingRequestContextError < Error; end
+
+    class InvalidJsonSelectorError < Error; end
+
+    class MissingJsonPathError < Error; end
+
+    class MissingCaptureError < Error; end
+  end
+end

data/lib/rspec/rest/expectations.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require_relative "formatters/request_dump"
+require_relative "formatters/request_recorder"
+require_relative "error_expectations"
+require_relative "contract_expectations"
+require_relative "header_expectations"
+require_relative "json_selector"
+require_relative "json_type_helpers"
+require_relative "pagination_expectations"
+
+module RSpec
+  module Rest
+    module Expectations
+      include ContractExpectations
+      include ErrorExpectations
+      include HeaderExpectations
+      include JsonTypeHelpers
+      include PaginationExpectations
+
+      def expect_status(code)
+        with_request_dump_on_failure do
+          expect(rest_response.status).to eq(code)
+        end
+      end
+
+      def expect_json(expected = nil, &block)
+        with_request_dump_on_failure do
+          parsed = rest_response.json
+
+          if block
+            instance_exec(parsed, &block)
+            next parsed
+          end
+
+          next parsed if expected.nil?
+
+          if expected.respond_to?(:matches?)
+            expect(parsed).to expected
+          else
+            expect(parsed).to eq(expected)
+          end
+
+          parsed
+        end
+      end
+
+      def expect_json_at(selector, expected = nil, &block)
+        with_request_dump_on_failure do
+          selected = JsonSelector.extract(rest_response.json, selector)
+
+          if block
+            instance_exec(selected, &block)
+            next selected
+          end
+
+          next selected if expected.nil?
+
+          if expected.respond_to?(:matches?)
+            expect(selected).to expected
+          else
+            expect(selected).to eq(expected)
+          end
+
+          selected
+        end
+      end
+
+      private
+
+      def with_request_dump_on_failure
+        yield
+      rescue ::RSpec::Expectations::ExpectationNotMetError => e
+        message = "#{e.message}\n\n#{request_dump}\n\nReproduce with:\n#{request_curl}"
+        new_exception = e.exception(message)
+        new_exception.set_backtrace(e.backtrace)
+        raise new_exception
+      end
+
+      def request_dump
+        Formatters::RequestDump.new(
+          last_request: safe_last_request,
+          response: safe_rest_response,
+          redacted_headers: redacted_headers_for_dump
+        ).format
+      end
+
+      def safe_last_request
+        rest_session.last_request
+      rescue StandardError
+        nil
+      end
+
+      def safe_rest_response
+        rest_response
+      rescue MissingRequestContextError, StandardError
+        nil
+      end
+
+      def redacted_headers_for_dump
+        self.class.rest_config.redact_headers
+      rescue StandardError
+        nil
+      end
+
+      def request_curl
+        Formatters::RequestRecorder.new(
+          last_request: safe_last_request,
+          redacted_headers: redacted_headers_for_dump
+        ).to_curl
+      end
+    end
+  end
+end

data/lib/rspec/rest/formatters/helpers.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module RSpec
+  module Rest
+    module Formatters
+      module Helpers
+        private
+
+        def sanitize_for_json(value)
+          case value
+          when Hash
+            value.transform_values { |inner| sanitize_for_json(inner) }
+          when Array
+            value.map { |inner| sanitize_for_json(inner) }
+          else
+            value.respond_to?(:to_str) ? value.to_str : value.to_s
+          end
+        end
+
+        def normalize_redacted_headers(headers)
+          headers.map { |header| header.to_s.downcase }
+        end
+      end
+    end
+  end
+end

data/lib/rspec/rest/formatters/request_dump.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../config"
+require_relative "helpers"
+
+module RSpec
+  module Rest
+    module Formatters
+      class RequestDump
+        include Helpers
+
+        def initialize(last_request:, response:, redacted_headers: nil)
+          @last_request = last_request || {}
+          @response = response
+          @redacted_headers = normalize_redacted_headers(redacted_headers || Config::DEFAULT_REDACT_HEADERS)
+        end
+
+        def format
+          [
+            "Request:",
+            request_line,
+            "Headers:",
+            formatted_headers(@last_request[:headers]),
+            "Body:",
+            formatted_body(@last_request[:body]),
+            "",
+            "Response:",
+            "Status: #{response_status}",
+            "Headers:",
+            formatted_headers(response_headers),
+            "Body:",
+            formatted_body(response_body)
+          ].join("\n")
+        end
+
+        private
+
+        def request_line
+          method = @last_request[:method] || "UNKNOWN"
+          path = @last_request[:path] || "(unknown path)"
+          "#{method} #{path}"
+        end
+
+        def response_status
+          @response&.status || "(unknown status)"
+        end
+
+        def response_headers
+          @response&.headers || {}
+        end
+
+        def response_body
+          @response&.body
+        end
+
+        def formatted_headers(headers)
+          return "(none)" if headers.nil? || headers.empty?
+
+          headers.sort_by { |key, _| key.to_s.downcase }
+                 .map { |key, value| "#{key}: #{redacted_header_value(key, value)}" }
+                 .join("\n")
+        end
+
+        def formatted_body(body)
+          return "(empty)" if body.nil? || (body.respond_to?(:empty?) && body.empty?)
+
+          if body.is_a?(Hash) || body.is_a?(Array)
+            begin
+              return JSON.pretty_generate(body)
+            rescue TypeError
+              return JSON.pretty_generate(sanitize_for_json(body))
+            end
+          end
+
+          body_str = body.to_s
+          parsed = parse_json(body_str)
+          return JSON.pretty_generate(parsed) unless parsed.nil?
+
+          body_str
+        end
+
+        def parse_json(value)
+          JSON.parse(value)
+        rescue JSON::ParserError
+          nil
+        end
+
+        def redacted_header_value(key, value)
+          return value unless redacted_header?(key)
+
+          "[REDACTED]"
+        end
+
+        def redacted_header?(key)
+          @redacted_headers.include?(key.to_s.downcase)
+        end
+      end
+    end
+  end
+end

data/lib/rspec/rest/formatters/request_recorder.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../config"
+require_relative "helpers"
+
+module RSpec
+  module Rest
+    module Formatters
+      class RequestRecorder
+        include Helpers
+
+        def initialize(last_request:, redacted_headers: nil)
+          @last_request = last_request || {}
+          @redacted_headers = normalize_redacted_headers(redacted_headers || Config::DEFAULT_REDACT_HEADERS)
+        end
+
+        def to_curl
+          [
+            "curl",
+            "-X #{method}",
+            shell_escape(url),
+            formatted_headers,
+            formatted_body
+          ].compact.join(" ")
+        end
+
+        private
+
+        def method
+          (@last_request[:method] || "GET").to_s.upcase
+        end
+
+        def url
+          @last_request[:url] || @last_request[:path] || "http://example.org/"
+        end
+
+        def formatted_headers
+          headers = @last_request[:headers]
+          return nil if headers.nil? || headers.empty?
+
+          headers.sort_by { |key, _| key.to_s.downcase }
+                 .map { |key, value| %(-H #{shell_escape("#{key}: #{redacted_value(key, value)}")}) }
+                 .join(" ")
+        end
+
+        def formatted_body
+          body = @last_request[:body]
+          return nil if body.nil?
+          return nil if body.respond_to?(:empty?) && body.empty?
+
+          value = serialize_body(body)
+          "-d #{shell_escape(value)}"
+        end
+
+        def serialize_body(body)
+          return body.to_s unless body.is_a?(Hash) || body.is_a?(Array)
+
+          JSON.dump(body)
+        rescue TypeError
+          JSON.dump(sanitize_for_json(body))
+        end
+
+        def redacted_value(key, value)
+          return value unless @redacted_headers.include?(key.to_s.downcase)
+
+          "[REDACTED]"
+        end
+
+        def shell_escape(value)
+          "'#{value.to_s.gsub("'", %q('"'"'))}'"
+        end
+      end
+    end
+  end
+end