rspec-rest 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 93914e31c974ea40630915bca0148c886b24608cca438d627f58b7ae83a3c4b5
-  data.tar.gz: d31e2d01339e37c1d432dc8b36333ba8e707d2e2ebff5637c7ebbce94093ba9b
+  metadata.gz: 47e2dfd9b5b01a159c9d81dffc650b0a807d6491669100f3e4c0939b9012eb3e
+  data.tar.gz: 0b5f6d62d08a5139fa60ce2d2a193d92949193767a08378f5212e576bc762f50
 SHA512:
-  metadata.gz: 908e78cda54bbd8dc33be4001429e6d9ca36e0111fcd8da1aa54bded587a27225828663bcbf19c2a130c4c1d634af3f68d8d7eab270dbb2d5769459861b7d5cc
-  data.tar.gz: 8aed0d1c0d77ce8381169b1ed4babb90ed9f02b9b9749fe12f0f7f7724d6bc73cd9fb4fbb2ad46d75b2eeb2254c29fd7b1ea72fc3642b8ac92d2f9bd0269bdc3
+  metadata.gz: ca75926bef46af5c64380a992281242afada213a4e4975ef41f0e1e8c525395c41a88618fd04accec24613cb13b107a8a0ae04b25a4e32cb4ded5464e6093760
+  data.tar.gz: f9762615e58277d690c7cdc7b7426dac3818e3f1fe7f12eb6e3e753d9cf0e19d366a7eae198911b5f33d7911ef72ded6826dabe63dd5b66bde19f98c7954fd87

data/.gitignore

@@ -67,3 +67,6 @@ yarn-debug.log*
 /storage/*
 !/storage/.keep
 /public/uploads
+
+# Local planning notes
+/docs/plans/

data/CHANGELOG.md

@@ -9,6 +9,58 @@ Semantic Versioning.
 
 No changes yet.
 
+## [0.3.0] - 2026-03-10
+
+### Added
+- Contract lookup helper for matcher composition in examples:
+  - `contract(:name)`
+- Internal deprecation utility for gem APIs:
+  - `RSpec::Rest::Deprecation.warn(key:, message:)`
+  - once-per-key warning emission in RSpec output.
+- Keyword request description support on verb DSL calls:
+  - `get(path, description: "...") { ... }` (and same for other verbs).
+
+### Changed
+- Failure-time `curl` output now uses an auth token environment placeholder for redacted auth-like headers, improving copy/paste usability:
+  - `Authorization: Bearer $API_AUTH_TOKEN`
+- Redacted auth scheme prefixes are preserved in `curl` output for `Authorization` and `Proxy-Authorization` (for example `Basic`, `Digest`).
+- README examples now prefer:
+  - `contract(:name)` over nested `expect_json_contract(...)`
+  - keyword request descriptions (`description:`).
+- Added README RuboCop compatibility guidance for:
+  - `Rails/HttpPositionalArguments`
+  - `RSpec/EmptyExampleGroup`.
+
+### Deprecated
+- `expect_json_contract(name)` is deprecated and scheduled for removal in `1.0`.
+  Use `contract(:name)` for contract lookup in examples.
+- Positional verb descriptions are deprecated and scheduled for removal in `1.0`:
+  - `get(path, "description") { ... }`
+  Use keyword descriptions instead:
+  - `get(path, description: "...") { ... }`
+
+## [0.2.0] - 2026-03-08
+
+### Added
+- JSON array item expectation helpers:
+  - `expect_json_first(expected = nil, &block)`
+  - `expect_json_item(index, expected = nil, &block)`
+  - `expect_json_last(expected = nil, &block)`
+- Optional behavior descriptions on verb DSL calls:
+  - `get(path, description = nil) { ... }` (and same for other verbs)
+- Full-route example naming support in DSL output (composed from `base_path` + resource path + endpoint path).
+- Shared path composition utility used by both request execution and example naming.
+
+### Changed
+- README examples and expectation helper docs updated for:
+  - Ruby-style JSON item helpers
+  - Optional verb descriptions and full-route example names
+
+### Fixed
+- `expect_json_item` now validates index type and reports non-integer indexes via actionable expectation failures.
+- JSON value assertion semantics are centralized across `expect_json`, `expect_json_at`, and JSON item helpers to reduce drift.
+- Unknown/invalid JSON item and contract expectation failures continue to include enriched request/response/curl diagnostics.
+
 ## [0.1.0] - 2026-03-07
 
 ### Added

data/Gemfile.lock

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

data/README.md

@@ -11,10 +11,6 @@ It focuses on:
 - high-signal failure output with request/response context
 - auto-generated `curl` reproduction commands on failures
 
-## Status
-
-The gem is pre-release and in active development toward `0.1.0`.
-
 ## Installation
 
 When published:
@@ -69,7 +65,7 @@ end
 
 ## Before and After (Rack::Test to rspec-rest)
 
-The example below shows the same behavior test written two ways.
+The first two examples below test the same behavior in two styles.
 
 Before (`Rack::Test` + manual response parsing):
 
@@ -113,25 +109,54 @@ RSpec.describe "Posts API" do
     default_format :json
   end
 
-  with_query locale: "en"
-  with_headers "X-Tenant-Id" => "tenant-123"
+  resource "/posts" do
+    with_auth auth_token
+
+    get "/", description: "returns posts page 1" do
+      query page: 1, per_page: 10
+
+      expect_status 200
+      expect_json array_of(hash_including("id" => integer, "author" => hash_including("id" => integer)))
+      expect_json_first hash_including("id" => posts.first.id)
+      expect_json_item(0) { |item| expect(item["author"]["id"]).to eq(posts.first.author.id) }
+    end
+  end
+end
+```
+
+What improves in the apples-to-apples rewrite:
+
+- Request setup is declarative (`api`, `resource`, `with_auth`, `query`).
+- JSON assertions read closer to the business intent (`expect_json_first`, `expect_json_item`).
+- Failure output includes request/response context and a reproducible `curl`.
+
+Beyond the baseline rewrite, `rspec-rest` can also express additional API concerns
+with concise helpers:
+
+```ruby
+RSpec.describe "Posts API" do
+  include RSpec::Rest
+
+  let(:auth_token) { "test-token" }
+
+  api do
+    app MyApp::Base
+    base_path "/api/v1"
+    default_format :json
+  end
+
   contract :post_summary do
     hash_including("id" => integer, "author" => hash_including("id" => integer))
   end
 
   resource "/posts" do
     with_auth auth_token
-    with_query per_page: 10
 
     get "/" do
-      query page: 1
-
+      query page: 1, per_page: 10
       expect_status 200
-      expect_json array_of(expect_json_contract(:post_summary))
-      expect_json_at "$[0].id", posts.first.id
-      expect_json_at "$[0].author.id", posts.first.author.id
+      expect_json array_of(contract(:post_summary))
       expect_page_size 10
-      expect_max_page_size 20
     end
 
     get "/{id}" do
@@ -153,13 +178,6 @@ RSpec.describe "Posts API" do
 end
 ```
 
-What improves:
-
-- Request setup is declarative (`api`, `resource`, shared presets, `query`, `multipart!`, `file`).
-- JSON expectations are concise and structure-aware (`expect_json`, `expect_json_at`).
-- Common API outcomes are one-liners (`expect_error`, pagination helpers).
-- Failures include request/response context plus a reproducible `curl`.
-
 ## API Config (`api`)
 
 `api` defines shared runtime configuration for a spec group.
@@ -188,6 +206,9 @@ 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`.
+    It is deprecated to avoid `Rails/HttpPositionalArguments` false-positives in RuboCop.
 
 Resource paths are composable and support placeholders:
 
@@ -202,6 +223,59 @@ resource "/users" do
 end
 ```
 
+Example with an explicit behavior name:
+
+```ruby
+resource "/users" do
+  get "/", description: "returns public users for authenticated client" do
+    expect_status 200
+  end
+end
+```
+
+RSpec example output uses the composed full route (including `base_path`) and appends the optional description, for example:
+- `GET /v1/users - returns public users for authenticated client`
+
+Note: Example names (including `base_path`) are composed when the verb macro is evaluated. To ensure the example names include `base_path`, declare your `api` (and its `base_path`) before defining `resource` blocks and their verbs. If you configure `api`/`base_path` afterward, requests will use the configured `base_path`, but the previously defined example names will not reflect it.
+
+## RuboCop Compatibility
+
+`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.
+- `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
+# .rubocop.yml
+RSpec/EmptyExampleGroup:
+  Exclude:
+    - "spec/api/rest/**/*"
+```
+
+If you only have a few affected groups, use an inline disable around the DSL group:
+
+```ruby
+# rubocop:disable RSpec/EmptyExampleGroup
+context "when authenticated" do
+  resource "/posts" do
+    get "/", description: "returns posts" do
+      expect_status 200
+    end
+  end
+end
+# rubocop:enable RSpec/EmptyExampleGroup
+```
+
+Prefer scoped exclusions/disables over broad project-wide disables so non-DSL specs
+keep full lint coverage.
+
+We are also considering a dedicated RuboCop extension for `rspec-rest` (for example,
+`rubocop-rspec-rest`) to reduce manual configuration over time. Until then, the
+scoped patterns above are the recommended approach.
+
 ## Shared Request Presets
 
 Define shared request defaults at group/resource scope:
@@ -286,8 +360,12 @@ Available expectation helpers:
 - `expect_status(code)`
 - `expect_header(key, value_or_regex)`
 - `expect_json(expected = nil, &block)`
-- `expect_json_contract(name)`
+- `contract(name)` (lookup helper for reusable JSON contracts)
+- `expect_json_contract(name)` (deprecated; use `contract(name)`)
 - `expect_json_at(selector, expected = nil, &block)`
+- `expect_json_first(expected = nil, &block)`
+- `expect_json_item(index, expected = nil, &block)`
+- `expect_json_last(expected = nil, &block)`
 - `expect_error(status:, message: nil, includes: nil, field: nil, key: "error")`
 - `expect_page_size(size, selector: "$")`
 - `expect_max_page_size(max, selector: "$")`
@@ -311,6 +389,18 @@ Available expectation helpers:
 - block mode:
   - `expect_json_at "$.items[0]" { |item| expect(item["id"]).to integer }`
 
+For common array-item checks, use Ruby-style helpers instead of selector strings:
+
+- `expect_json_first(...)`
+- `expect_json_item(index, ...)`
+- `expect_json_last(...)`
+
+```ruby
+expect_json_first hash_including("id" => integer)
+expect_json_item 2, hash_including("name" => "Third")
+expect_json_last { |item| expect(item["id"]).to integer }
+```
+
 `expect_error` is a convenience helper for common API error payload assertions:
 
 ```ruby
@@ -335,7 +425,7 @@ end
 ## Lightweight Contracts
 
 A contract is a named, reusable JSON expectation (usually a response shape matcher).
-Define it once in your spec group, then apply it anywhere with `expect_json_contract`.
+Define it once in your spec group, then apply it anywhere with `contract(:name)`.
 
 ```ruby
 contract :post_summary do
@@ -348,7 +438,7 @@ end
 
 get "/" do
   expect_status 200
-  expect_json array_of(expect_json_contract(:post_summary))
+  expect_json array_of(contract(:post_summary))
 end
 ```
 
@@ -394,6 +484,48 @@ When an expectation fails, output includes:
 Sensitive headers are redacted by default and can be customized via
 `redact_headers`.
 
+Example (truncated):
+
+```text
+expected: 201
+     got: 422
+
+Request:
+POST /api/v1/posts
+Headers:
+  Accept: application/json
+  Authorization: [REDACTED]
+  Content-Type: application/json
+Body:
+{
+  "title": "",
+  "body": "Example"
+}
+
+Response:
+Status: 422
+Headers:
+  Content-Type: application/json
+Body:
+{
+  "error": "Validation failed",
+  "details": {
+    "title": ["can't be blank"]
+  }
+}
+
+Reproduce with:
+curl -X POST 'http://localhost:3000/api/v1/posts' -H 'Accept: application/json' -H "Authorization: Bearer $API_AUTH_TOKEN" -H 'Content-Type: application/json' -d '{"title":"","body":"Example"}'
+```
+
+Before running an authenticated command, set your token:
+
+```bash
+export API_AUTH_TOKEN="your_token_here"
+```
+
+Then paste the generated `curl` command directly in your terminal for fast manual debugging.
+
 ## Contributing
 
 Contributions are welcome.

data/lib/rspec/rest/contract_expectations.rb

@@ -5,9 +5,31 @@ require_relative "contract_matcher"
 module RSpec
   module Rest
     module ContractExpectations
+      def contract(name = nil, &)
+        if block_given?
+          raise ArgumentError,
+                "contract(:name) lookup does not accept a block in examples. " \
+                "Define contracts at the example group level with `contract(:name) { ... }`."
+        end
+
+        contract_matcher_for(name, lookup_name: :contract)
+      end
+
       def expect_json_contract(name)
+        Deprecation.warn(
+          key: :expect_json_contract,
+          message: "`expect_json_contract` is deprecated and will be removed in 1.0. " \
+                   "Use `contract(:name)` instead."
+        )
+
+        contract_matcher_for(name, lookup_name: :expect_json_contract)
+      end
+
+      private
+
+      def contract_matcher_for(name, lookup_name:)
         contract_name = normalize_contract_name(name)
-        return unknown_contract_matcher(name_error_message(name)) if contract_name.nil?
+        return unknown_contract_matcher(name_error_message(name, lookup_name: lookup_name)) if contract_name.nil?
 
         definition = self.class.rest_contract_definition(contract_name)
         return ContractMatcher.new(name: contract_name, definition: definition, context: self) unless definition.nil?
@@ -17,8 +39,6 @@ module RSpec
         unknown_contract_matcher(message)
       end
 
-      private
-
       def normalize_contract_name(name)
         return nil if name.nil? || !name.respond_to?(:to_sym)
 
@@ -29,9 +49,10 @@ module RSpec
         UnknownContractMatcher.new(message)
       end
 
-      def name_error_message(name)
+      def name_error_message(name, lookup_name:)
+        lookup_hint = lookup_name == :expect_json_contract ? "expect_json_contract" : "contract(:name)"
         "Invalid contract name #{name.inspect} (#{name.class}). " \
-          "expect_json_contract requires a contract name that responds to #to_sym."
+          "#{lookup_hint} requires a contract name that responds to #to_sym."
       end
     end
   end

data/lib/rspec/rest/deprecation.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module RSpec
+  module Rest
+    module Deprecation
+      module_function
+
+      def warn(key:, message:)
+        return if already_emitted?(key)
+
+        emit("DEPRECATION: #{message}")
+      end
+
+      def reset!
+        emitted_keys.clear
+      end
+
+      def already_emitted?(key)
+        normalized_key = key.to_s
+        return true if emitted_keys[normalized_key]
+
+        emitted_keys[normalized_key] = true
+        false
+      end
+      private_class_method :already_emitted?
+
+      def emitted_keys
+        @emitted_keys ||= {}
+      end
+      private_class_method :emitted_keys
+
+      def emit(message)
+        reporter = rspec_reporter
+        if reporter.respond_to?(:message)
+          reporter.message(message)
+        else
+          Kernel.warn(message)
+        end
+      end
+      private_class_method :emit
+
+      def rspec_reporter
+        return nil unless defined?(::RSpec) && ::RSpec.respond_to?(:configuration)
+
+        ::RSpec.configuration.reporter
+      rescue StandardError
+        nil
+      end
+      private_class_method :rspec_reporter
+    end
+  end
+end

data/lib/rspec/rest/dsl.rb

@@ -7,6 +7,7 @@ require_relative "class_level_presets"
 require_relative "errors"
 require_relative "expectations"
 require_relative "json_selector"
+require_relative "path_composer"
 require_relative "request_builders"
 require_relative "session"
 module RSpec
@@ -55,9 +56,72 @@ module RSpec
         end
       end
 
+      module RouteNamingSupport
+        private
+
+        def build_example_name(method:, path:, resource_path:, description:)
+          route = compose_route_for_example(resource_path: resource_path, endpoint_path: path)
+          base = "#{method.to_s.upcase} #{route}"
+          normalized_description = description.to_s.strip
+          return base if normalized_description.empty?
+
+          "#{base} - #{normalized_description}"
+        end
+
+        def compose_route_for_example(resource_path:, endpoint_path:)
+          PathComposer.compose(
+            base_path: rest_config.base_path,
+            resource_path: resource_path,
+            endpoint_path: endpoint_path
+          )
+        end
+
+        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 DescriptionArgumentSupport
+        private
+
+        def warn_on_deprecated_positional_description(_method)
+          Deprecation.warn(
+            key: :verb_positional_description,
+            message: "Positional request descriptions (for example: get(path, description)) are deprecated and " \
+                     "will be removed in 1.0. Use keyword descriptions " \
+                     "(for example: get(path, description: \"...\")). " \
+                     "This avoids RuboCop Rails/HttpPositionalArguments false-positives."
+          )
+        end
+
+        def resolve_description_options(method:, positional_description:, keyword_description:)
+          if !positional_description.nil? && !keyword_description.nil?
+            raise ArgumentError,
+                  "#{method}(...) received both positional and keyword descriptions. " \
+                  "Use only `description:`."
+          end
+
+          {
+            description: keyword_description.nil? ? positional_description : keyword_description,
+            using_positional_description: !positional_description.nil? && keyword_description.nil?
+          }
+        end
+      end
+
       module ClassMethods
         include ClassLevelContracts
         include ClassLevelPresets
+        include RouteNamingSupport
+        include DescriptionArgumentSupport
 
         def api(&)
           builder = ApiConfigBuilder.new(rest_config)
@@ -77,10 +141,17 @@ module RSpec
         end
 
         HTTP_METHODS.each do |method|
-          define_method(method) do |path, &block|
+          define_method(method) do |path, positional_description = nil, description: nil, &block|
+            description_options = resolve_verb_description_options(method, positional_description, description)
             resource_path = current_resource_path
             request_presets = deep_dup_presets(current_request_presets)
-            it("#{method.to_s.upcase} #{path}") do
+            example_name = build_example_name(
+              method: method,
+              path: path,
+              resource_path: resource_path,
+              description: description_options[:description]
+            )
+            it(example_name) do
               start_rest_request(
                 method: method,
                 path: path,
@@ -88,6 +159,7 @@ module RSpec
                 presets: request_presets
               )
               instance_eval(&block) if block
+              self.class.send(:emit_positional_description_warning, method, description_options)
               execute_rest_request_if_pending
             end
           end
@@ -109,17 +181,18 @@ module RSpec
 
         private
 
-        def current_resource_path
-          stack = @rest_resource_stack || []
-          return nil if stack.empty?
+        def emit_positional_description_warning(method, description_options)
+          return unless description_options[:using_positional_description]
 
-          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?)
+          send(:warn_on_deprecated_positional_description, method)
+        end
 
-          path = normalized_segments.join("/")
-          first_had_leading_slash && !path.empty? ? "/#{path}" : path
+        def resolve_verb_description_options(method, positional_description, description)
+          resolve_description_options(
+            method: method,
+            positional_description: positional_description,
+            keyword_description: description
+          )
         end
       end
 

data/lib/rspec/rest/expectations.rb

@@ -5,6 +5,7 @@ require_relative "formatters/request_recorder"
 require_relative "error_expectations"
 require_relative "contract_expectations"
 require_relative "header_expectations"
+require_relative "json_item_expectations"
 require_relative "json_selector"
 require_relative "json_type_helpers"
 require_relative "pagination_expectations"
@@ -15,6 +16,7 @@ module RSpec
       include ContractExpectations
       include ErrorExpectations
       include HeaderExpectations
+      include JsonItemExpectations
       include JsonTypeHelpers
       include PaginationExpectations
 
@@ -27,46 +29,35 @@ module RSpec
       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
+          evaluate_json_value(parsed, expected, &block)
         end
       end
 
       def expect_json_at(selector, expected = nil, &block)
         with_request_dump_on_failure do
           selected = JsonSelector.extract(rest_response.json, selector)
+          evaluate_json_value(selected, expected, &block)
+        end
+      end
 
-          if block
-            instance_exec(selected, &block)
-            next selected
-          end
+      private
 
-          next selected if expected.nil?
+      def evaluate_json_value(value, expected = nil, &block)
+        if block
+          instance_exec(value, &block)
+          return value
+        end
 
-          if expected.respond_to?(:matches?)
-            expect(selected).to expected
-          else
-            expect(selected).to eq(expected)
-          end
+        return value if expected.nil?
 
-          selected
+        if expected.respond_to?(:matches?)
+          expect(value).to expected
+        else
+          expect(value).to eq(expected)
         end
-      end
 
-      private
+        value
+      end
 
       def with_request_dump_on_failure
         yield

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

@@ -10,6 +10,18 @@ module RSpec
       class RequestRecorder
         include Helpers
 
+        AUTH_TOKEN_ENV_VAR = "API_AUTH_TOKEN"
+        AUTH_HEADER_KEYS = %w[
+          authorization
+          proxy-authorization
+          x-api-key
+          x-auth-token
+        ].freeze
+        AUTH_SCHEME_HEADER_KEYS = %w[
+          authorization
+          proxy-authorization
+        ].freeze
+
         def initialize(last_request:, redacted_headers: nil)
           @last_request = last_request || {}
           @redacted_headers = normalize_redacted_headers(redacted_headers || Config::DEFAULT_REDACT_HEADERS)
@@ -40,7 +52,7 @@ module RSpec
           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)}")}) }
+                 .map { |key, value| format_header_option(key, redacted_value(key, value)) }
                  .join(" ")
         end
 
@@ -63,13 +75,40 @@ module RSpec
 
         def redacted_value(key, value)
           return value unless @redacted_headers.include?(key.to_s.downcase)
+          return auth_header_placeholder(key, value) if auth_header?(key)
 
           "[REDACTED]"
         end
 
+        def auth_header?(key)
+          AUTH_HEADER_KEYS.include?(key.to_s.downcase)
+        end
+
+        def auth_header_placeholder(key, value)
+          value_string = value.to_s
+          if AUTH_SCHEME_HEADER_KEYS.include?(key.to_s.downcase)
+            scheme_match = value_string.match(/\A([A-Za-z][A-Za-z0-9._-]*)\s+/)
+            return "#{scheme_match[1]} $#{AUTH_TOKEN_ENV_VAR}" if scheme_match
+          end
+
+          "$#{AUTH_TOKEN_ENV_VAR}"
+        end
+
+        def format_header_option(key, value)
+          header = "#{key}: #{value}"
+          return %(-H #{shell_escape_with_env_expansion(header)}) if value.to_s.include?("$#{AUTH_TOKEN_ENV_VAR}")
+
+          %(-H #{shell_escape(header)})
+        end
+
         def shell_escape(value)
           "'#{value.to_s.gsub("'", %q('"'"'))}'"
         end
+
+        def shell_escape_with_env_expansion(value)
+          escaped = value.to_s.gsub("\\", "\\\\").gsub('"', '\"').gsub("`", "\\`")
+          "\"#{escaped}\""
+        end
       end
     end
   end

data/lib/rspec/rest/json_item_expectations.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module RSpec
+  module Rest
+    module JsonItemExpectations
+      def expect_json_item(index, expected = nil, &block)
+        with_request_dump_on_failure do
+          payload = json_array_payload
+          normalized_index = normalize_json_item_index(index)
+          item = payload.fetch(normalized_index)
+          evaluate_json_value(item, expected, &block)
+        rescue IndexError
+          raise ::RSpec::Expectations::ExpectationNotMetError,
+                "Index #{index.inspect} is out of bounds for JSON array of size #{payload.size}."
+        end
+      end
+
+      def expect_json_first(expected = nil, &)
+        expect_json_item(0, expected, &)
+      end
+
+      def expect_json_last(expected = nil, &block)
+        with_request_dump_on_failure do
+          payload = json_array_payload
+          if payload.empty?
+            raise ::RSpec::Expectations::ExpectationNotMetError,
+                  "Cannot select last item from an empty JSON array."
+          end
+
+          evaluate_json_value(payload.last, expected, &block)
+        end
+      end
+
+      private
+
+      def json_array_payload
+        payload = rest_response.json
+        return payload if payload.is_a?(Array)
+
+        raise ::RSpec::Expectations::ExpectationNotMetError,
+              "Expected JSON payload to be an Array, got #{payload.class}."
+      end
+
+      def normalize_json_item_index(index)
+        return index if index.is_a?(Integer)
+
+        raise ::RSpec::Expectations::ExpectationNotMetError,
+              "Expected JSON item index to be an Integer, got #{index.inspect} (#{index.class})."
+      end
+    end
+  end
+end

data/lib/rspec/rest/path_composer.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module RSpec
+  module Rest
+    module PathComposer
+      module_function
+
+      def compose(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
+    end
+  end
+end

data/lib/rspec/rest/session.rb

@@ -4,6 +4,7 @@ require "json"
 require "rack/test"
 require "rack/utils"
 require_relative "errors"
+require_relative "path_composer"
 require_relative "response"
 
 module RSpec
@@ -123,9 +124,11 @@ module RSpec
       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('/')}"
+        PathComposer.compose(
+          base_path: base_path,
+          resource_path: resource_path,
+          endpoint_path: endpoint_path
+        )
       end
 
       def build_url(base_url, path)

data/lib/rspec/rest/version.rb

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

data/lib/rspec/rest.rb

@@ -2,6 +2,7 @@
 
 require_relative "rest/version"
 require_relative "rest/errors"
+require_relative "rest/deprecation"
 require_relative "rest/config"
 require_relative "rest/response"
 require_relative "rest/session"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rspec-rest
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Carl
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-03-07 00:00:00.000000000 Z
+date: 2026-03-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack-test
@@ -111,6 +111,7 @@ files:
 - lib/rspec/rest/config.rb
 - lib/rspec/rest/contract_expectations.rb
 - lib/rspec/rest/contract_matcher.rb
+- lib/rspec/rest/deprecation.rb
 - lib/rspec/rest/dsl.rb
 - lib/rspec/rest/error_expectations.rb
 - lib/rspec/rest/errors.rb
@@ -119,9 +120,11 @@ files:
 - lib/rspec/rest/formatters/request_dump.rb
 - lib/rspec/rest/formatters/request_recorder.rb
 - lib/rspec/rest/header_expectations.rb
+- lib/rspec/rest/json_item_expectations.rb
 - lib/rspec/rest/json_selector.rb
 - lib/rspec/rest/json_type_helpers.rb
 - lib/rspec/rest/pagination_expectations.rb
+- lib/rspec/rest/path_composer.rb
 - lib/rspec/rest/request_builders.rb
 - lib/rspec/rest/response.rb
 - lib/rspec/rest/session.rb