rspec-rest 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 93914e31c974ea40630915bca0148c886b24608cca438d627f58b7ae83a3c4b5
-  data.tar.gz: d31e2d01339e37c1d432dc8b36333ba8e707d2e2ebff5637c7ebbce94093ba9b
+  metadata.gz: 6d00a1ef08b51bc62ee1b737217eb5f441ee625ca3cbd848d0db1cbacff619f2
+  data.tar.gz: 6507ec718a8f8a0ecf5de375e2efba9f3d686cc577258baf89a05d9ccc47d64d
 SHA512:
-  metadata.gz: 908e78cda54bbd8dc33be4001429e6d9ca36e0111fcd8da1aa54bded587a27225828663bcbf19c2a130c4c1d634af3f68d8d7eab270dbb2d5769459861b7d5cc
-  data.tar.gz: 8aed0d1c0d77ce8381169b1ed4babb90ed9f02b9b9749fe12f0f7f7724d6bc73cd9fb4fbb2ad46d75b2eeb2254c29fd7b1ea72fc3642b8ac92d2f9bd0269bdc3
+  metadata.gz: 742d99b9ceecc699b920038a11476f304a657b1023599d819fc69fd17f19154387745ceffeabda7cc98b36ccf065ba6c164f2eb3c618c34822e68ecd9e4f50b6
+  data.tar.gz: 6c80fa3a4b6f088172aa9b795ff8fc48e82cc7f64052bdf3b0028e3741983d6c73088bb72a29be44f9575da1ecc57c70b97d4a8f428b96f4385a5aded4805e81

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,28 @@ Semantic Versioning.
 
 No changes yet.
 
+## [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.2.0)
       rack-test (~> 2.1)
 
 GEM

data/README.md

@@ -123,13 +123,13 @@ RSpec.describe "Posts API" do
     with_auth auth_token
     with_query per_page: 10
 
-    get "/" do
+    get "/", "returns first page of posts for authenticated user" do
       query page: 1
 
       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_first hash_including("id" => posts.first.id)
+      expect_json_item(0) { |item| expect(item["author"]["id"]).to eq(posts.first.author.id) }
       expect_page_size 10
       expect_max_page_size 20
     end
@@ -188,6 +188,7 @@ Supported config:
 
 - `resource "/users" do ... end`
 - `get`, `post`, `put`, `patch`, `delete`
+  - optional form: `get(path, description = nil) { ... }`
 
 Resource paths are composable and support placeholders:
 
@@ -202,6 +203,20 @@ resource "/users" do
 end
 ```
 
+Example with an explicit behavior name:
+
+```ruby
+resource "/users" do
+  get "/", "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.
 ## Shared Request Presets
 
 Define shared request defaults at group/resource scope:
@@ -288,6 +303,9 @@ Available expectation helpers:
 - `expect_json(expected = nil, &block)`
 - `expect_json_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 +329,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

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
@@ -77,10 +78,16 @@ module RSpec
         end
 
         HTTP_METHODS.each do |method|
-          define_method(method) do |path, &block|
+          define_method(method) do |path, description = nil, &block|
             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
+            )
+            it(example_name) do
               start_rest_request(
                 method: method,
                 path: path,
@@ -109,6 +116,23 @@ 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?
+
+          "#{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?

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/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.2.0"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rspec-rest
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Carl
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-03-07 00:00:00.000000000 Z
+date: 2026-03-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack-test
@@ -119,9 +119,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