rspec-rest 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d00a1ef08b51bc62ee1b737217eb5f441ee625ca3cbd848d0db1cbacff619f2
-  data.tar.gz: 6507ec718a8f8a0ecf5de375e2efba9f3d686cc577258baf89a05d9ccc47d64d
+  metadata.gz: 47e2dfd9b5b01a159c9d81dffc650b0a807d6491669100f3e4c0939b9012eb3e
+  data.tar.gz: 0b5f6d62d08a5139fa60ce2d2a193d92949193767a08378f5212e576bc762f50
 SHA512:
-  metadata.gz: 742d99b9ceecc699b920038a11476f304a657b1023599d819fc69fd17f19154387745ceffeabda7cc98b36ccf065ba6c164f2eb3c618c34822e68ecd9e4f50b6
-  data.tar.gz: 6c80fa3a4b6f088172aa9b795ff8fc48e82cc7f64052bdf3b0028e3741983d6c73088bb72a29be44f9575da1ecc57c70b97d4a8f428b96f4385a5aded4805e81
+  metadata.gz: ca75926bef46af5c64380a992281242afada213a4e4975ef41f0e1e8c525395c41a88618fd04accec24613cb13b107a8a0ae04b25a4e32cb4ded5464e6093760
+  data.tar.gz: f9762615e58277d690c7cdc7b7426dac3818e3f1fe7f12eb6e3e753d9cf0e19d366a7eae198911b5f33d7911ef72ded6826dabe63dd5b66bde19f98c7954fd87

data/CHANGELOG.md

@@ -9,6 +9,36 @@ 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

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    rspec-rest (0.2.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 "/", "returns first page of posts for authenticated user" do
-      query page: 1
 
+    get "/" do
+      query page: 1, per_page: 10
       expect_status 200
-      expect_json array_of(expect_json_contract(:post_summary))
-      expect_json_first hash_including("id" => posts.first.id)
-      expect_json_item(0) { |item| expect(item["author"]["id"]).to eq(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,7 +206,9 @@ Supported config:
 
 - `resource "/users" do ... end`
 - `get`, `post`, `put`, `patch`, `delete`
-  - optional form: `get(path, description = nil) { ... }`
+  - 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:
 
@@ -207,7 +227,7 @@ Example with an explicit behavior name:
 
 ```ruby
 resource "/users" do
-  get "/", "returns public users for authenticated client" do
+  get "/", description: "returns public users for authenticated client" do
     expect_status 200
   end
 end
@@ -217,6 +237,45 @@ RSpec example output uses the composed full route (including `base_path`) and ap
 - `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:
@@ -301,7 +360,8 @@ 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)`
@@ -365,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
@@ -378,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
 ```
 
@@ -424,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

@@ -56,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)
@@ -78,14 +141,15 @@ module RSpec
         end
 
         HTTP_METHODS.each do |method|
-          define_method(method) do |path, description = nil, &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)
             example_name = build_example_name(
               method: method,
               path: path,
               resource_path: resource_path,
-              description: description
+              description: description_options[:description]
             )
             it(example_name) do
               start_rest_request(
@@ -95,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
@@ -116,35 +181,19 @@ module RSpec
 
         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?
+        def emit_positional_description_warning(method, description_options)
+          return unless description_options[:using_positional_description]
 
-          "#{base} - #{normalized_description}"
+          send(:warn_on_deprecated_positional_description, method)
         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
+        def resolve_verb_description_options(method, positional_description, description)
+          resolve_description_options(
+            method: method,
+            positional_description: positional_description,
+            keyword_description: description
           )
         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 InstanceMethods

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/version.rb

@@ -2,6 +2,6 @@
 
 module RSpec
   module Rest
-    VERSION = "0.2.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.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Carl
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-03-08 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