rspec-rest 0.1.0

data/lib/rspec/rest/header_expectations.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module RSpec
+  module Rest
+    module HeaderExpectations
+      def expect_header(key, value_or_regex)
+        with_request_dump_on_failure do
+          actual = header_value_for(key)
+          available_keys = rest_response.headers.keys.map(&:to_s).sort.join(", ")
+          message = "Expected response header #{key.inspect} to be present. " \
+                    "Available headers: [#{available_keys}]"
+          raise ::RSpec::Expectations::ExpectationNotMetError, message if actual.nil?
+
+          if value_or_regex.is_a?(Regexp)
+            expect(actual).to match(value_or_regex)
+          else
+            expect(actual).to eq(value_or_regex)
+          end
+        end
+      end
+
+      private
+
+      def header_value_for(key)
+        headers = rest_response.headers
+        return headers[key] if headers.key?(key)
+
+        key_str = key.to_s
+        pair = headers.find do |header_key, _|
+          header_key.to_s.casecmp(key_str).zero?
+        end
+        pair&.last
+      end
+    end
+  end
+end

data/lib/rspec/rest/json_selector.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+module RSpec
+  module Rest
+    class JsonSelector
+      TOKEN_PATTERN = /
+        (?:
+          \.([a-zA-Z_][a-zA-Z0-9_]*)
+        )|
+        (?:
+          \[(\d+)\]
+        )
+      /x
+
+      class << self
+        def extract(json, selector)
+          tokens = parse(selector)
+          current = json
+
+          tokens.each do |token|
+            current = dig(current, token, selector)
+          end
+
+          current
+        end
+
+        private
+
+        def parse(selector)
+          selector_str = selector.to_s
+          unless selector_str.start_with?("$")
+            raise InvalidJsonSelectorError, "Invalid selector #{selector.inspect}. Selector must start with '$'."
+          end
+
+          remaining = selector_str[1..]
+          tokens = []
+
+          until remaining.empty?
+            match = TOKEN_PATTERN.match(remaining)
+            if match.nil? || match.begin(0) != 0
+              raise InvalidJsonSelectorError,
+                    "Invalid selector #{selector.inspect}. Supported forms include '$.a.b' and '$.items[0].id'."
+            end
+
+            tokens << if match[1]
+                        [:key, match[1]]
+                      else
+                        [:index, match[2].to_i]
+                      end
+
+            remaining = remaining[match[0].length..]
+          end
+
+          tokens
+        end
+
+        def dig(value, token, selector)
+          type, key = token
+
+          case type
+          when :key
+            unless value.is_a?(Hash) && value.key?(key)
+              raise MissingJsonPathError, "Selector #{selector.inspect} did not match path segment #{key.inspect}."
+            end
+
+            value[key]
+          when :index
+            unless value.is_a?(Array) && key < value.length
+              raise MissingJsonPathError, "Selector #{selector.inspect} did not match array index #{key}."
+            end
+
+            value[key]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rspec/rest/json_type_helpers.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module RSpec
+  module Rest
+    module JsonTypeHelpers
+      def integer
+        be_a(Integer)
+      end
+
+      def string
+        be_a(String)
+      end
+
+      def boolean
+        satisfy("be boolean") { |value| [true, false].include?(value) }
+      end
+
+      def array_of(matcher)
+        all(matcher)
+      end
+
+      def hash_including(*)
+        a_hash_including(*)
+      end
+    end
+  end
+end

data/lib/rspec/rest/pagination_expectations.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module RSpec
+  module Rest
+    module PaginationExpectations
+      def expect_page_size(size, selector: "$")
+        with_request_dump_on_failure do
+          collection = extract_collection(selector)
+          expect(collection.size).to eq(size)
+          collection
+        end
+      end
+
+      def expect_max_page_size(max, selector: "$")
+        with_request_dump_on_failure do
+          collection = extract_collection(selector)
+          expect(collection.size).to be <= max
+          collection
+        end
+      end
+
+      def expect_ids_in_order(ids, selector: "$[*].id")
+        with_request_dump_on_failure do
+          actual_ids = extract_id_list(selector)
+          expect(actual_ids).to eq(ids)
+          actual_ids
+        end
+      end
+
+      private
+
+      def extract_collection(selector)
+        payload = rest_response.json
+        selected = selector == "$" ? payload : JsonSelector.extract(payload, selector)
+
+        unless selected.is_a?(Array)
+          raise ::RSpec::Expectations::ExpectationNotMetError,
+                "Expected selector #{selector.inspect} to resolve to an Array, got #{selected.class}."
+        end
+
+        selected
+      end
+
+      def extract_id_list(selector)
+        wildcard_match = /\A\$\[\*\]\.([a-zA-Z_][a-zA-Z0-9_]*)\z/.match(selector.to_s)
+        return JsonSelector.extract(rest_response.json, selector) unless wildcard_match
+
+        key = wildcard_match[1]
+        extract_collection("$").map.with_index do |item, index|
+          unless item.is_a?(Hash) && item.key?(key)
+            raise ::RSpec::Expectations::ExpectationNotMetError,
+                  "Selector #{selector.inspect} did not match element #{index} for key #{key.inspect}."
+          end
+
+          item[key]
+        end
+      end
+    end
+  end
+end

data/lib/rspec/rest/request_builders.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "rack/test"
+
+module RSpec
+  module Rest
+    module RequestBuilders
+      def header(key, value)
+        rest_request_state[:headers][key] = value
+      end
+
+      def headers(value)
+        rest_request_state[:headers].merge!(value)
+      end
+
+      def query(value)
+        rest_request_state[:query] ||= {}
+        rest_request_state[:query].merge!(value)
+      end
+
+      def json(value)
+        rest_request_state[:json] = value
+      end
+
+      def multipart!
+        rest_request_state[:multipart] = true
+        rest_request_state[:params] ||= {}
+      end
+
+      def file(param_key, file_or_path, content_type: nil, filename: nil)
+        multipart!
+        rest_request_state[:params][param_key] = build_uploaded_file(
+          file_or_path,
+          content_type: content_type,
+          filename: filename
+        )
+      end
+
+      def path_params(value)
+        rest_request_state[:path_params].merge!(value.transform_keys(&:to_s))
+      end
+
+      def bearer(token)
+        header("Authorization", "Bearer #{token}")
+      end
+
+      def unauthenticated!
+        header("Authorization", nil)
+      end
+
+      private
+
+      def build_uploaded_file(file_or_path, content_type:, filename:)
+        if file_or_path.is_a?(Rack::Test::UploadedFile)
+          if content_type || filename
+            raise ArgumentError,
+                  "content_type and filename cannot be specified when file_or_path is a Rack::Test::UploadedFile"
+          end
+
+          return file_or_path
+        end
+
+        path = if file_or_path.respond_to?(:to_path)
+                 file_or_path.to_path
+               else
+                 file_or_path.to_s
+               end
+
+        Rack::Test::UploadedFile.new(path, content_type, false, original_filename: filename)
+      end
+    end
+  end
+end

data/lib/rspec/rest/response.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "errors"
+
+module RSpec
+  module Rest
+    class Response
+      attr_reader :raw_response
+
+      def initialize(raw_response)
+        @raw_response = raw_response
+      end
+
+      def status
+        raw_response.status
+      end
+
+      def headers
+        raw_response.headers
+      end
+
+      def body
+        raw_response.body.to_s
+      end
+
+      def json
+        return @json if instance_variable_defined?(:@json)
+
+        @json = JSON.parse(body)
+      rescue JSON::ParserError => e
+        snippet = body[0, 200]
+        raise InvalidJsonError, "Failed to parse JSON response: #{e.message}. Body snippet: #{snippet.inspect}"
+      end
+    end
+  end
+end

data/lib/rspec/rest/session.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "json"
+require "rack/test"
+require "rack/utils"
+require_relative "errors"
+require_relative "response"
+
+module RSpec
+  module Rest
+    class Session
+      SUPPORTED_HTTP_METHODS = %i[get post put patch delete].freeze
+
+      attr_reader :config, :last_request
+
+      def initialize(config)
+        @config = config
+        validate_config!
+        @rack_session = Rack::Test::Session.new(Rack::MockSession.new(config.app))
+        @last_request = nil
+      end
+
+      def request(method:, path:, **options)
+        method = validate_http_method!(method)
+        resource_path = options[:resource_path]
+        headers = options[:headers]
+        query = options[:query]
+        json = options[:json]
+        params = options[:params]
+
+        request_path = build_path(config.base_path, resource_path, path)
+        request_path = append_query(request_path, query)
+
+        request_headers = build_headers(headers, include_json_content_type: !json.nil?)
+        rack_env_headers = build_rack_env_headers(request_headers)
+        request_payload = build_payload(json: json, params: params)
+
+        @last_request = {
+          method: method.upcase,
+          path: request_path,
+          url: build_url(config.base_url, request_path),
+          headers: request_headers,
+          env: rack_env_headers,
+          body: request_payload
+        }
+
+        @rack_session.public_send(method, request_path, request_payload, rack_env_headers)
+        response
+      end
+
+      def response
+        Response.new(@rack_session.last_response)
+      end
+
+      private
+
+      def validate_config!
+        return unless config.app.nil?
+
+        raise MissingAppError, "Config#app is required to initialize RSpec::Rest::Session"
+      end
+
+      def validate_http_method!(method)
+        normalized = method.to_s.downcase
+        return normalized if SUPPORTED_HTTP_METHODS.include?(normalized.to_sym)
+
+        supported = SUPPORTED_HTTP_METHODS.map(&:to_s).join(", ")
+        raise UnsupportedHttpMethodError,
+              "Unsupported HTTP method: #{method.inspect}. Supported methods: #{supported}"
+      end
+
+      def build_headers(request_headers, include_json_content_type:)
+        headers = config.base_headers.dup
+
+        if config.default_format == :json
+          headers["Accept"] ||= "application/json"
+        end
+
+        merge_request_headers!(headers, request_headers || {})
+        if include_json_content_type
+          headers["Content-Type"] ||= "application/json"
+        end
+
+        headers
+      end
+
+      def merge_request_headers!(headers, request_headers)
+        request_headers.each do |key, value|
+          if value.nil?
+            headers.delete_if { |header_key, _| header_key.to_s.casecmp(key.to_s).zero? }
+            next
+          end
+
+          existing_key = headers.keys.find { |header_key| header_key.to_s.casecmp(key.to_s).zero? }
+          headers.delete(existing_key) if existing_key && existing_key != key
+          headers[key] = value
+        end
+      end
+
+      def build_payload(json:, params:)
+        return JSON.dump(json) unless json.nil?
+
+        params || {}
+      end
+
+      def build_rack_env_headers(headers)
+        headers.transform_keys { |key| normalize_header_key(key) }
+      end
+
+      def normalize_header_key(key)
+        key_str = key.to_s
+        return key_str if key_str.start_with?("HTTP_", "CONTENT_TYPE", "CONTENT_LENGTH", "rack.")
+        return "CONTENT_TYPE" if key_str.casecmp("Content-Type").zero?
+        return "CONTENT_LENGTH" if key_str.casecmp("Content-Length").zero?
+
+        "HTTP_#{key_str.tr('-', '_').upcase}"
+      end
+
+      def append_query(path, query)
+        return path if query.nil? || query.empty?
+
+        "#{path}?#{Rack::Utils.build_query(query)}"
+      end
+
+      def build_path(base_path, resource_path, endpoint_path)
+        segments = [base_path, resource_path, endpoint_path].compact.map(&:to_s)
+        normalized = segments.map { |segment| segment.gsub(%r{\A/+|/+\z}, "") }.reject(&:empty?)
+        "/#{normalized.join('/')}"
+      end
+
+      def build_url(base_url, path)
+        "#{base_url.to_s.sub(%r{/+\z}, '')}#{path}"
+      end
+    end
+  end
+end

data/lib/rspec/rest/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RSpec
+  module Rest
+    VERSION = "0.1.0"
+  end
+end

data/lib/rspec/rest.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "rest/version"
+require_relative "rest/errors"
+require_relative "rest/config"
+require_relative "rest/response"
+require_relative "rest/session"
+require_relative "rest/json_selector"
+require_relative "rest/formatters/request_recorder"
+require_relative "rest/dsl"
+
+module RSpec
+  module Rest
+    def self.included(base)
+      base.include(DSL)
+    end
+  end
+end

metadata

@@ -0,0 +1,157 @@
+--- !ruby/object:Gem::Specification
+name: rspec-rest
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Carl
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-03-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rack-test
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.72'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.72'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+description: A Ruby gem for concise, behavior-first REST API specs backed by Rack::Test
+  and RSpec.
+email:
+- carl@example.com
+executables:
+- rspec-rest
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rubocop.yml"
+- CHANGELOG.md
+- Gemfile
+- Gemfile.lock
+- LICENSE
+- README.md
+- Rakefile
+- exe/rspec-rest
+- lib/rspec/rest.rb
+- lib/rspec/rest/captures.rb
+- lib/rspec/rest/class_level_contracts.rb
+- lib/rspec/rest/class_level_presets.rb
+- lib/rspec/rest/config.rb
+- lib/rspec/rest/contract_expectations.rb
+- lib/rspec/rest/contract_matcher.rb
+- lib/rspec/rest/dsl.rb
+- lib/rspec/rest/error_expectations.rb
+- lib/rspec/rest/errors.rb
+- lib/rspec/rest/expectations.rb
+- lib/rspec/rest/formatters/helpers.rb
+- lib/rspec/rest/formatters/request_dump.rb
+- lib/rspec/rest/formatters/request_recorder.rb
+- lib/rspec/rest/header_expectations.rb
+- lib/rspec/rest/json_selector.rb
+- lib/rspec/rest/json_type_helpers.rb
+- lib/rspec/rest/pagination_expectations.rb
+- lib/rspec/rest/request_builders.rb
+- lib/rspec/rest/response.rb
+- lib/rspec/rest/session.rb
+- lib/rspec/rest/version.rb
+homepage: https://github.com/llwebconsulting/rspec-rest
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/llwebconsulting/rspec-rest
+  source_code_uri: https://github.com/llwebconsulting/rspec-rest
+  changelog_uri: https://github.com/llwebconsulting/rspec-rest/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.18
+signing_key:
+specification_version: 4
+summary: Rack::Test + RSpec DSL for REST API testing
+test_files: []