rspec-rest 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 47e2dfd9b5b01a159c9d81dffc650b0a807d6491669100f3e4c0939b9012eb3e
-  data.tar.gz: 0b5f6d62d08a5139fa60ce2d2a193d92949193767a08378f5212e576bc762f50
+  metadata.gz: e72f8991e5d53bdb5bd0ccfa7524a42fcf5c99afead0caba45bb8876ef66bf8c
+  data.tar.gz: c33cdc064fc0d12c76f42f036b1490732ecbd6aaa1c6c8213bfaef6260e99d03
 SHA512:
-  metadata.gz: ca75926bef46af5c64380a992281242afada213a4e4975ef41f0e1e8c525395c41a88618fd04accec24613cb13b107a8a0ae04b25a4e32cb4ded5464e6093760
-  data.tar.gz: f9762615e58277d690c7cdc7b7426dac3818e3f1fe7f12eb6e3e753d9cf0e19d366a7eae198911b5f33d7911ef72ded6826dabe63dd5b66bde19f98c7954fd87
+  metadata.gz: 240876e213f49ac41ddc68015bd1d91744df3af41454e53f4cd561a10042f839544fae0ac7537dd3eee68f4c76727e9f1ff07136b8a1e060fcbc068e401aca69
+  data.tar.gz: d9c09b903fe84ef94c2290633b1770fd0d05263a909ffa4a9d2aeec6c8aa26e8a7e26dbff6622073d6bf99b8d24b988898a5040a12b7dc4b19a09981c78b02fd

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,18 @@ Semantic Versioning.
 
 ## [Unreleased]
 
-No changes yet.
+## [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.4.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
@@ -404,7 +404,7 @@ expect_json_last { |item| expect(item["id"]).to integer }
 `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 +413,7 @@ end
 Pagination helpers:
 
 ```ruby
-get "/" do
+get path: "/" do
   query page: 2, per_page: 10
   expect_status 200
   expect_page_size 10
@@ -436,7 +436,7 @@ contract :post_summary do
   )
 end
 
-get "/" do
+get path: "/" do
   expect_status 200
   expect_json array_of(contract(:post_summary))
 end
@@ -465,7 +465,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/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/version.rb

@@ -2,6 +2,6 @@
 
 module RSpec
   module Rest
-    VERSION = "0.3.0"
+    VERSION = "0.4.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.4.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