rspec-rest 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e72f8991e5d53bdb5bd0ccfa7524a42fcf5c99afead0caba45bb8876ef66bf8c
-  data.tar.gz: c33cdc064fc0d12c76f42f036b1490732ecbd6aaa1c6c8213bfaef6260e99d03
+  metadata.gz: 3fef8eafbf21f5d0f307fa44423fa4549ad602de47671f6bec67257121e66263
+  data.tar.gz: fbea7383a57565b80277d093d66c4e1bd80a24b3343bf1118f86699ed04e88f8
 SHA512:
-  metadata.gz: 240876e213f49ac41ddc68015bd1d91744df3af41454e53f4cd561a10042f839544fae0ac7537dd3eee68f4c76727e9f1ff07136b8a1e060fcbc068e401aca69
-  data.tar.gz: d9c09b903fe84ef94c2290633b1770fd0d05263a909ffa4a9d2aeec6c8aa26e8a7e26dbff6622073d6bf99b8d24b988898a5040a12b7dc4b19a09981c78b02fd
+  metadata.gz: 00a1efa6d45045ac68fb5df02fadc8acae07465c9e1a82e7561da4ecdb135a8557123eb9c31a70fa1b61bff95c676e6095a21d8fba77c48881f9a1908831437b
+  data.tar.gz: 12e146f01dd7b46a1ffa2a014c7392f66af342d594b07c5171f56bb63e36232fa45ec35dc353bbb2e44c9e589c10628d85d7903bd43b7993a32e618722da2805

data/CHANGELOG.md

@@ -7,6 +7,19 @@ Semantic Versioning.
 
 ## [Unreleased]
 
+## [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

data/Gemfile.lock

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

data/README.md

@@ -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,6 +407,16 @@ 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
@@ -439,9 +455,13 @@ end
 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`

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/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.4.0"
+    VERSION = "0.5.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rspec-rest
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Carl
@@ -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