rspec-rest 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 47e2dfd9b5b01a159c9d81dffc650b0a807d6491669100f3e4c0939b9012eb3e
-  data.tar.gz: 0b5f6d62d08a5139fa60ce2d2a193d92949193767a08378f5212e576bc762f50
+  metadata.gz: 3fef8eafbf21f5d0f307fa44423fa4549ad602de47671f6bec67257121e66263
+  data.tar.gz: fbea7383a57565b80277d093d66c4e1bd80a24b3343bf1118f86699ed04e88f8
 SHA512:
-  metadata.gz: ca75926bef46af5c64380a992281242afada213a4e4975ef41f0e1e8c525395c41a88618fd04accec24613cb13b107a8a0ae04b25a4e32cb4ded5464e6093760
-  data.tar.gz: f9762615e58277d690c7cdc7b7426dac3818e3f1fe7f12eb6e3e753d9cf0e19d366a7eae198911b5f33d7911ef72ded6826dabe63dd5b66bde19f98c7954fd87
+  metadata.gz: 00a1efa6d45045ac68fb5df02fadc8acae07465c9e1a82e7561da4ecdb135a8557123eb9c31a70fa1b61bff95c676e6095a21d8fba77c48881f9a1908831437b
+  data.tar.gz: 12e146f01dd7b46a1ffa2a014c7392f66af342d594b07c5171f56bb63e36232fa45ec35dc353bbb2e44c9e589c10628d85d7903bd43b7993a32e618722da2805

data/.gitignore

@@ -70,3 +70,6 @@ yarn-debug.log*
 
 # Local planning notes
 /docs/plans/
+
+# Built gem artifacts
+/rspec-rest-*.gem

data/CHANGELOG.md

@@ -7,7 +7,31 @@ Semantic Versioning.
 
 ## [Unreleased]
 
-No changes yet.
+## [0.5.0] - 2026-03-12
+
+### Added
+- `expect_json_at` now supports top-level shorthand selectors:
+  - Symbol keys (for example `:message`)
+  - plain String keys (for example `"message"`)
+  Full JSONPath selectors (for example `"$.items[0].id"`) remain supported.
+- `contract_with(:name, overrides)` for contract matcher composition with specific
+  value assertions while preserving the base contract shape/type expectations.
+- Raw body expectation helpers for non-JSON/text responses:
+  - `expect_body_includes(fragment)`
+  - `expect_body_matches(pattern)`
+
+## [0.4.0] - 2026-03-11
+
+### Added
+- Verb DSL now supports keyword request paths:
+  - `get path: "/users", description: "..." do ... end`
+  - same keyword `path:` support for `post`, `put`, `patch`, and `delete`.
+
+### Deprecated
+- Positional verb path arguments are deprecated and scheduled for removal in `1.0`:
+  - `get "/users", description: "..." do ... end`
+  Use keyword paths instead:
+  - `get path: "/users", description: "..." do ... end`
 
 ## [0.3.0] - 2026-03-10
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    rspec-rest (0.3.0)
+    rspec-rest (0.5.0)
       rack-test (~> 2.1)
 
 GEM

data/README.md

@@ -48,13 +48,13 @@ RSpec.describe "Users API" do
   end
 
   resource "/users" do
-    get "/" do
+    get path: "/" do
       expect_status 200
       expect_header "Content-Type", "application/json"
       expect_json array_of(hash_including("id" => integer, "email" => string))
     end
 
-    post "/" do
+    post path: "/" do
       json "email" => "carl@example.com", "name" => "Carl"
       expect_status 201
       capture :user_id, "$.id"
@@ -112,7 +112,7 @@ RSpec.describe "Posts API" do
   resource "/posts" do
     with_auth auth_token
 
-    get "/", description: "returns posts page 1" do
+    get path: "/", description: "returns posts page 1" do
       query page: 1, per_page: 10
 
       expect_status 200
@@ -152,14 +152,14 @@ RSpec.describe "Posts API" do
   resource "/posts" do
     with_auth auth_token
 
-    get "/" do
+    get path: "/" do
       query page: 1, per_page: 10
       expect_status 200
       expect_json array_of(contract(:post_summary))
       expect_page_size 10
     end
 
-    get "/{id}" do
+    get path: "/{id}" do
       path_params id: 999_999
       expect_error status: 404, message: "Post not found"
     end
@@ -168,7 +168,7 @@ RSpec.describe "Posts API" do
   resource "/uploads" do
     with_auth auth_token
 
-    post "/" do
+    post path: "/" do
       multipart!
       file :file, Rails.root.join("spec/fixtures/files/sample_upload.txt"), content_type: "text/plain"
       expect_status 201
@@ -206,16 +206,17 @@ Supported config:
 
 - `resource "/users" do ... end`
 - `get`, `post`, `put`, `patch`, `delete`
-  - preferred description form: `get(path, description: "...") { ... }`
-  - legacy positional form `get(path, "description")` is deprecated and will be removed in `1.0`.
+  - preferred form: `get(path: "/users", description: "...") { ... }`
+  - legacy positional path form `get("/users", description: "...")` is deprecated and will be removed in `1.0`.
     It is deprecated to avoid `Rails/HttpPositionalArguments` false-positives in RuboCop.
+  - legacy positional description form `get "/users", "description"` is deprecated and will be removed in `1.0`.
 
 Resource paths are composable and support placeholders:
 
 ```ruby
 resource "/users" do
   resource "/{id}/posts" do
-    get "/" do
+    get path: "/" do
       path_params id: 1
       expect_status 404
     end
@@ -227,7 +228,7 @@ Example with an explicit behavior name:
 
 ```ruby
 resource "/users" do
-  get "/", description: "returns public users for authenticated client" do
+  get path: "/", description: "returns public users for authenticated client" do
     expect_status 200
   end
 end
@@ -243,9 +244,8 @@ Note: Example names (including `base_path`) are composed when the verb macro is
 `rspec-rest` verbs (`get`, `post`, etc.) define examples via DSL macros, and can trigger
 false-positives in some RuboCop cops:
 
-- `Rails/HttpPositionalArguments`: use keyword descriptions (`description:`), not positional descriptions.
+- `Rails/HttpPositionalArguments`: use keyword paths (`path:`) and keyword descriptions (`description:`), not positional arguments.
 - `RSpec/EmptyExampleGroup`: a `context` that only contains `resource` + verb DSL may be flagged as empty.
-
 Recommended mitigation is scoped configuration for files that use `rspec-rest`:
 
 ```yaml
@@ -261,7 +261,7 @@ If you only have a few affected groups, use an inline disable around the DSL gro
 # rubocop:disable RSpec/EmptyExampleGroup
 context "when authenticated" do
   resource "/posts" do
-    get "/", description: "returns posts" do
+    get path: "/", description: "returns posts" do
       expect_status 200
     end
   end
@@ -303,12 +303,12 @@ resource "/posts" do
   with_auth ENV.fetch("API_TOKEN", "token-123")
   with_headers "X-Client" => "mobile"
 
-  get "/" do
+  get path: "/" do
     query page: 2
     expect_status 200
   end
 
-  get "/admin" do
+  get path: "/admin" do
     header "X-Client", "internal-tool" # request-level override
     query locale: "fr"                 # request-level override
     expect_status 200
@@ -333,7 +333,7 @@ Inside verb blocks:
 Example:
 
 ```ruby
-post "/" do
+post path: "/" do
   headers "X-Trace-Id" => "abc-123"
   bearer "token-123"
   query include_details: "true"
@@ -345,7 +345,7 @@ end
 Multipart upload example:
 
 ```ruby
-post "/uploads" do
+post path: "/uploads" do
   multipart!
   file :file, Rails.root.join("spec/fixtures/files/sample_upload.txt"), content_type: "text/plain"
   expect_status 201
@@ -361,8 +361,11 @@ Available expectation helpers:
 - `expect_header(key, value_or_regex)`
 - `expect_json(expected = nil, &block)`
 - `contract(name)` (lookup helper for reusable JSON contracts)
+- `contract_with(name, overrides)` (contract lookup with value overrides)
 - `expect_json_contract(name)` (deprecated; use `contract(name)`)
 - `expect_json_at(selector, expected = nil, &block)`
+- `expect_body_includes(fragment)`
+- `expect_body_matches(pattern)` (`String` or `Regexp`)
 - `expect_json_first(expected = nil, &block)`
 - `expect_json_item(index, expected = nil, &block)`
 - `expect_json_last(expected = nil, &block)`
@@ -388,6 +391,9 @@ Available expectation helpers:
   - `expect_json_at "$.user.email", "jane@example.com"`
 - block mode:
   - `expect_json_at "$.items[0]" { |item| expect(item["id"]).to integer }`
+- top-level shorthand:
+  - `expect_json_at :message, "Not found"`
+  - `expect_json_at "message", "Not found"`
 
 For common array-item checks, use Ruby-style helpers instead of selector strings:
 
@@ -401,10 +407,20 @@ expect_json_item 2, hash_including("name" => "Third")
 expect_json_last { |item| expect(item["id"]).to integer }
 ```
 
+Raw body assertions for text/non-JSON endpoints:
+
+```ruby
+get path: "/bad_json" do
+  expect_status 200
+  expect_body_includes "not json"
+  expect_body_matches(/this is not json/)
+end
+```
+
 `expect_error` is a convenience helper for common API error payload assertions:
 
 ```ruby
-get "/{id}" do
+get path: "/{id}" do
   path_params id: 999
   expect_error status: 404, message: "Post not found"
 end
@@ -413,7 +429,7 @@ end
 Pagination helpers:
 
 ```ruby
-get "/" do
+get path: "/" do
   query page: 2, per_page: 10
   expect_status 200
   expect_page_size 10
@@ -436,12 +452,16 @@ contract :post_summary do
   )
 end
 
-get "/" do
+get path: "/" do
   expect_status 200
   expect_json array_of(contract(:post_summary))
+  expect_json array_of(contract_with(:post_summary, id: 1, title: "My Title", author: { id: 1 }))
 end
 ```
 
+Use `contract_with` when you want the base contract shape/types plus specific values
+for selected keys. Override keys must exist in the contract definition.
+
 JSON type helpers:
 
 - `integer`
@@ -465,7 +485,7 @@ Selector syntax (minimal JSON selector):
 Example:
 
 ```ruby
-post "/" do
+post path: "/" do
   json "email" => "flow@example.com", "name" => "Flow"
   expect_status 201
   capture :user_id, "$.id"

data/lib/rspec/rest/body_expectations.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module RSpec
+  module Rest
+    module BodyExpectations
+      def expect_body_includes(fragment)
+        with_request_dump_on_failure do
+          case fragment
+          when String
+            expect(rest_response.body).to include(fragment)
+          else
+            raise ArgumentError, "expect_body_includes requires a String fragment, got #{fragment.class}"
+          end
+        end
+      end
+
+      def expect_body_matches(pattern)
+        with_request_dump_on_failure do
+          case pattern
+          when String, Regexp
+            expect(rest_response.body).to match(pattern)
+          else
+            raise ArgumentError, "expect_body_matches requires a String or Regexp pattern, got #{pattern.class}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rspec/rest/contract_expectations.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require_relative "contract_matcher"
+require_relative "contract_overrides_builder"
+require_relative "contract_with_matcher"
 
 module RSpec
   module Rest
@@ -25,6 +27,45 @@ module RSpec
         contract_matcher_for(name, lookup_name: :expect_json_contract)
       end
 
+      def contract_with(name, overrides = nil, **keyword_overrides)
+        overrides_builder = ContractOverridesBuilder.new(context: self)
+        resolved_overrides = overrides_builder.normalize!(overrides, keyword_overrides)
+        contract_name = normalize_contract_name(name)
+        return unknown_contract_matcher(name_error_message(name, lookup_name: :contract_with)) if contract_name.nil?
+
+        definition = self.class.rest_contract_definition(contract_name)
+        if definition.nil?
+          available = self.class.send(:rest_contracts).keys.map(&:inspect).sort
+          message = "Unknown contract #{contract_name.inspect}. Available contracts: [#{available.join(', ')}]"
+          return unknown_contract_matcher(message)
+        end
+
+        definition_for_matcher = definition
+
+        if resolved_overrides.any?
+          base_contract_value = instance_exec(&definition)
+          key_tree = overrides_builder.key_tree_for(base_contract_value)
+          if key_tree.nil?
+            return unknown_contract_matcher(
+              "Contract #{contract_name.inspect} does not declare hash keys, so overrides cannot be applied."
+            )
+          end
+
+          validation_error = overrides_builder.validate_keys(key_tree, resolved_overrides)
+          return unknown_contract_matcher(validation_error) unless validation_error.nil?
+
+          # Reuse the already-evaluated contract value inside the matcher so the
+          # contract definition is executed at most once per `contract_with` call.
+          definition_for_matcher = proc { base_contract_value }
+        end
+
+        ContractWithMatcher.new(
+          name: contract_name,
+          contract_matcher: ContractMatcher.new(name: contract_name, definition: definition_for_matcher, context: self),
+          overrides_matcher: overrides_builder.build_matcher(resolved_overrides)
+        )
+      end
+
       private
 
       def contract_matcher_for(name, lookup_name:)
@@ -50,7 +91,14 @@ module RSpec
       end
 
       def name_error_message(name, lookup_name:)
-        lookup_hint = lookup_name == :expect_json_contract ? "expect_json_contract" : "contract(:name)"
+        lookup_hint = case lookup_name
+                      when :expect_json_contract
+                        "expect_json_contract"
+                      when :contract_with
+                        "contract_with(:name, ...)"
+                      else
+                        "contract(:name)"
+                      end
         "Invalid contract name #{name.inspect} (#{name.class}). " \
           "#{lookup_hint} requires a contract name that responds to #to_sym."
       end

data/lib/rspec/rest/contract_overrides_builder.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module RSpec
+  module Rest
+    class ContractOverridesBuilder
+      def initialize(context:)
+        @context = context
+      end
+
+      def normalize!(overrides, keyword_overrides)
+        unless keyword_overrides.empty?
+          raise ArgumentError, "contract_with received both positional Hash and keyword overrides" unless overrides.nil?
+
+          return keyword_overrides
+        end
+
+        return {} if overrides.nil?
+        return overrides if overrides.is_a?(Hash)
+
+        raise ArgumentError,
+              "contract_with requires overrides to be a Hash or keyword arguments, got #{overrides.class}"
+      end
+
+      def key_tree_for(contract_value)
+        hash = extract_contract_hash(contract_value)
+        return nil if hash.nil?
+
+        hash.each_with_object({}) do |(key, nested), memo|
+          memo[key.to_s] = key_tree_for(nested)
+        end
+      end
+
+      def validate_keys(key_tree, overrides, path = [])
+        overrides.each do |key, value|
+          key_name = key.to_s
+          unless key_tree.key?(key_name)
+            available_keys = key_tree.keys.sort
+            location = path.empty? ? "contract root" : "$.#{path.join('.')}"
+            return "Unknown override key #{key_name.inspect} at #{location}. " \
+                   "Available keys: [#{available_keys.map(&:inspect).join(', ')}]"
+          end
+
+          next unless value.is_a?(Hash)
+
+          nested_tree = key_tree[key_name]
+          if nested_tree.nil?
+            location = (path + [key_name]).join(".")
+            return "Override key #{key_name.inspect} at $.#{location} does not support nested overrides."
+          end
+
+          nested_error = validate_keys(nested_tree, value, path + [key_name])
+          return nested_error unless nested_error.nil?
+        end
+
+        nil
+      end
+
+      def build_matcher(overrides)
+        @context.hash_including(
+          overrides.each_with_object({}) do |(key, value), memo|
+            memo[key.to_s] = value.is_a?(Hash) ? build_matcher(value) : value
+          end
+        )
+      end
+
+      private
+
+      def extract_contract_hash(value)
+        return value if value.is_a?(Hash)
+
+        return nil unless value.respond_to?(:matcher_name) && value.respond_to?(:expecteds)
+
+        matcher_name = value.matcher_name
+        return nil unless matcher_name == :a_hash_including
+
+        expecteds = value.expecteds
+        return nil unless expecteds.is_a?(Array) && expecteds.first.is_a?(Hash)
+
+        expecteds.first
+      end
+    end
+  end
+end

data/lib/rspec/rest/contract_with_matcher.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module RSpec
+  module Rest
+    class ContractWithMatcher
+      def initialize(name:, contract_matcher:, overrides_matcher:)
+        @name = name
+        @contract_matcher = contract_matcher
+        @overrides_matcher = overrides_matcher
+      end
+
+      def matches?(actual)
+        @contract_matched = @contract_matcher.matches?(actual)
+        return false unless @contract_matched
+
+        @overrides_matcher.matches?(actual)
+      end
+
+      def failure_message
+        return @contract_matcher.failure_message unless @contract_matched
+
+        "Contract #{@name.inspect} override assertion failed: #{@overrides_matcher.failure_message}"
+      end
+
+      def failure_message_when_negated
+        "Expected value not to match contract #{@name.inspect} with overrides"
+      end
+
+      def description
+        "match contract #{@name.inspect} with overrides"
+      end
+    end
+  end
+end

data/lib/rspec/rest/dsl.rb

@@ -117,11 +117,44 @@ module RSpec
         end
       end
 
+      module PathArgumentSupport
+        private
+
+        def warn_on_deprecated_positional_path(_method)
+          Deprecation.warn(
+            key: :verb_positional_path,
+            message: "Positional request paths (for example: get(\"/users\")) are deprecated and will be " \
+                     "removed in 1.0. Use keyword paths instead (for example: get(path: \"/users\")). " \
+                     "This avoids RuboCop Rails/HttpPositionalArguments false-positives."
+          )
+        end
+
+        def resolve_path_options(method:, positional_path:, keyword_path:)
+          if !positional_path.nil? && !keyword_path.nil?
+            raise ArgumentError,
+                  "#{method}(...) received both positional and keyword paths. Use only `path:`."
+          end
+
+          effective_path = keyword_path.nil? ? positional_path : keyword_path
+          if effective_path.nil?
+            raise ArgumentError,
+                  "#{method}(...) requires a request path. Pass it as `path:` (preferred) " \
+                  "or as the first positional argument."
+          end
+
+          {
+            path: effective_path,
+            using_positional_path: !positional_path.nil? && keyword_path.nil?
+          }
+        end
+      end
+
       module ClassMethods
         include ClassLevelContracts
         include ClassLevelPresets
         include RouteNamingSupport
         include DescriptionArgumentSupport
+        include PathArgumentSupport
 
         def api(&)
           builder = ApiConfigBuilder.new(rest_config)
@@ -141,25 +174,28 @@ module RSpec
         end
 
         HTTP_METHODS.each do |method|
-          define_method(method) do |path, positional_description = nil, description: nil, &block|
-            description_options = resolve_verb_description_options(method, positional_description, description)
+          define_method(method) do |positional_path = nil, positional_description = nil, path: nil,
+                                    description: nil, &block|
+            path_options, description_options = resolve_verb_options(
+              method, positional_path, path, positional_description, description
+            )
             resource_path = current_resource_path
             request_presets = deep_dup_presets(current_request_presets)
             example_name = build_example_name(
               method: method,
-              path: path,
+              path: path_options[:path],
               resource_path: resource_path,
               description: description_options[:description]
             )
             it(example_name) do
               start_rest_request(
                 method: method,
-                path: path,
+                path: path_options[:path],
                 resource_path: resource_path,
                 presets: request_presets
               )
               instance_eval(&block) if block
-              self.class.send(:emit_positional_description_warning, method, description_options)
+              self.class.send(:emit_verb_deprecation_warnings, method, path_options, description_options)
               execute_rest_request_if_pending
             end
           end
@@ -181,12 +217,31 @@ module RSpec
 
         private
 
+        def emit_verb_deprecation_warnings(method, path_options, description_options)
+          emit_positional_path_warning(method, path_options)
+          emit_positional_description_warning(method, description_options)
+        end
+
+        def emit_positional_path_warning(method, path_options)
+          return unless path_options[:using_positional_path]
+
+          send(:warn_on_deprecated_positional_path, method)
+        end
+
         def emit_positional_description_warning(method, description_options)
           return unless description_options[:using_positional_description]
 
           send(:warn_on_deprecated_positional_description, method)
         end
 
+        def resolve_verb_path_options(method, positional_path, path)
+          resolve_path_options(
+            method: method,
+            positional_path: positional_path,
+            keyword_path: path
+          )
+        end
+
         def resolve_verb_description_options(method, positional_description, description)
           resolve_description_options(
             method: method,
@@ -194,6 +249,13 @@ module RSpec
             keyword_description: description
           )
         end
+
+        def resolve_verb_options(method, positional_path, path, positional_description, description)
+          [
+            resolve_verb_path_options(method, positional_path, path),
+            resolve_verb_description_options(method, positional_description, description)
+          ]
+        end
       end
 
       module InstanceMethods

data/lib/rspec/rest/expectations.rb

@@ -2,6 +2,7 @@
 
 require_relative "formatters/request_dump"
 require_relative "formatters/request_recorder"
+require_relative "body_expectations"
 require_relative "error_expectations"
 require_relative "contract_expectations"
 require_relative "header_expectations"
@@ -14,6 +15,7 @@ module RSpec
   module Rest
     module Expectations
       include ContractExpectations
+      include BodyExpectations
       include ErrorExpectations
       include HeaderExpectations
       include JsonItemExpectations
@@ -35,13 +37,32 @@ module RSpec
 
       def expect_json_at(selector, expected = nil, &block)
         with_request_dump_on_failure do
-          selected = JsonSelector.extract(rest_response.json, selector)
+          selected = JsonSelector.extract(rest_response.json, normalize_json_selector(selector))
           evaluate_json_value(selected, expected, &block)
         end
       end
 
       private
 
+      def normalize_json_selector(selector)
+        case selector
+        when Symbol
+          "$.#{selector}"
+        when String
+          return selector if selector.start_with?("$")
+          return "$.#{selector}" if selector.match?(/\A[a-zA-Z_][a-zA-Z0-9_]*\z/)
+
+          raise InvalidJsonSelectorError,
+                "Invalid selector #{selector.inspect}. Top-level shorthand accepts Symbol or simple String " \
+                "keys (for example :message or \"message\"). Use JSONPath for nested selectors " \
+                "(for example \"$.items[0].id\")."
+        else
+          raise InvalidJsonSelectorError,
+                "Invalid selector #{selector.inspect}. Selector must be a Symbol, a String top-level key, " \
+                "or a JSONPath String starting with '$'."
+        end
+      end
+
       def evaluate_json_value(value, expected = nil, &block)
         if block
           instance_exec(value, &block)

data/lib/rspec/rest/version.rb

@@ -2,6 +2,6 @@
 
 module RSpec
   module Rest
-    VERSION = "0.3.0"
+    VERSION = "0.5.0"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rspec-rest
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Carl
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-03-10 00:00:00.000000000 Z
+date: 2026-03-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack-test
@@ -105,12 +105,15 @@ files:
 - Rakefile
 - exe/rspec-rest
 - lib/rspec/rest.rb
+- lib/rspec/rest/body_expectations.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/contract_overrides_builder.rb
+- lib/rspec/rest/contract_with_matcher.rb
 - lib/rspec/rest/deprecation.rb
 - lib/rspec/rest/dsl.rb
 - lib/rspec/rest/error_expectations.rb