rspec-rest 0.1.0

data/README.md

@@ -0,0 +1,447 @@
+# rspec-rest
+
+`rspec-rest` is a Ruby gem for behavior-first REST API specs built on top of
+RSpec and Rack::Test.
+
+It focuses on:
+
+- concise request DSL
+- JSON-first expectations
+- capture/reuse of response values
+- 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:
+
+```ruby
+# Gemfile
+gem "rspec-rest"
+```
+
+Until then, use GitHub:
+
+```ruby
+# Gemfile
+gem "rspec-rest", git: "https://github.com/llwebconsulting/rspec-rest.git"
+```
+
+Then:
+
+```bash
+bundle install
+```
+
+## Quick Start
+
+```ruby
+RSpec.describe "Users API" do
+  include RSpec::Rest
+
+  api do
+    app Rails.application
+    base_path "/v1"
+    base_headers "Accept" => "application/json"
+    default_format :json
+    base_url "http://localhost:3000" # used for failure-time curl reproduction
+  end
+
+  resource "/users" do
+    get "/" do
+      expect_status 200
+      expect_header "Content-Type", "application/json"
+      expect_json array_of(hash_including("id" => integer, "email" => string))
+    end
+
+    post "/" do
+      json "email" => "carl@example.com", "name" => "Carl"
+      expect_status 201
+      capture :user_id, "$.id"
+    end
+  end
+end
+```
+
+## Before and After (Rack::Test to rspec-rest)
+
+The example below shows the same behavior test written two ways.
+
+Before (`Rack::Test` + manual response parsing):
+
+```ruby
+RSpec.describe MyApp::V1::Posts, type: :request do
+  include Rack::Test::Methods
+
+  def app
+    MyApp::Base
+  end
+
+  let(:auth_token) { "test-token" }
+  let!(:posts) { create_list(:post, 3).sort_by(&:created_at).reverse }
+
+  before { header "Authorization", "Bearer #{auth_token}" }
+
+  it "returns posts page 1" do
+    get "/api/v1/posts", { page: 1, per_page: 10 }
+    payload = JSON.parse(last_response.body)
+
+    expect(last_response.status).to eq(200)
+    expect(payload.size).to eq(3)
+    expect(payload.first["id"]).to eq(posts.first.id)
+    expect(payload.first["author"]["id"]).to eq(posts.first.author.id)
+  end
+end
+```
+
+After (`rspec-rest` DSL):
+
+```ruby
+RSpec.describe "Posts API" do
+  include RSpec::Rest
+
+  let(:auth_token) { "test-token" }
+  let!(:posts) { create_list(:post, 3).sort_by(&:created_at).reverse }
+
+  api do
+    app MyApp::Base
+    base_path "/api/v1"
+    default_format :json
+  end
+
+  with_query locale: "en"
+  with_headers "X-Tenant-Id" => "tenant-123"
+  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
+
+      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_page_size 10
+      expect_max_page_size 20
+    end
+
+    get "/{id}" do
+      path_params id: 999_999
+      expect_error status: 404, message: "Post not found"
+    end
+  end
+
+  resource "/uploads" do
+    with_auth auth_token
+
+    post "/" do
+      multipart!
+      file :file, Rails.root.join("spec/fixtures/files/sample_upload.txt"), content_type: "text/plain"
+      expect_status 201
+      expect_json hash_including("filename" => "sample_upload.txt")
+    end
+  end
+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.
+
+```ruby
+api do
+  app Rails.application
+  base_path "/v1"
+  base_headers "Accept" => "application/json"
+  default_format :json
+  base_url "http://localhost:3000"
+  redact_headers ["Authorization", "Cookie", "Set-Cookie"]
+end
+```
+
+Supported config:
+
+- `app`: Rack app (required)
+- `base_path`: base request path prefix
+- `base_headers`: default headers merged into every request
+- `default_format`: set to `:json` to default `Accept: application/json`
+- `base_url`: used for generated curl commands (`http://example.org` default)
+- `redact_headers`: headers redacted in failure output and curl
+
+## Resources And Verbs
+
+- `resource "/users" do ... end`
+- `get`, `post`, `put`, `patch`, `delete`
+
+Resource paths are composable and support placeholders:
+
+```ruby
+resource "/users" do
+  resource "/{id}/posts" do
+    get "/" do
+      path_params id: 1
+      expect_status 404
+    end
+  end
+end
+```
+
+## Shared Request Presets
+
+Define shared request defaults at group/resource scope:
+
+- `with_headers(hash)`
+- `with_query(hash)`
+- `with_auth(token)` (sets `Authorization: Bearer <token>`)
+
+Use presets when your API requires repeated request context across many endpoints,
+for example auth headers, locale/tenant query params, client/app version headers,
+or other codebase-specific defaults.
+
+Nested resources inherit presets, and request-level builders (`header`, `query`, `bearer`) can override them.
+
+Typical pattern:
+- set broad defaults at top-level (`with_query`, `with_headers`)
+- narrow defaults at resource scope (`with_auth`, resource-specific headers)
+- override per request only when behavior differs
+
+```ruby
+with_query locale: "en"
+with_headers "X-Tenant-Id" => "tenant-123"
+
+resource "/posts" do
+  with_auth ENV.fetch("API_TOKEN", "token-123")
+  with_headers "X-Client" => "mobile"
+
+  get "/" do
+    query page: 2
+    expect_status 200
+  end
+
+  get "/admin" do
+    header "X-Client", "internal-tool" # request-level override
+    query locale: "fr"                 # request-level override
+    expect_status 200
+  end
+end
+```
+
+## Request Builders
+
+Inside verb blocks:
+
+- `header(key, value)`
+- `headers(hash)`
+- `bearer(token)`
+- `unauthenticated!`
+- `query(hash)`
+- `json(hash_or_string)`
+- `multipart!`
+- `file(param_key, file_or_path, content_type: nil, filename: nil)`
+- `path_params(hash)`
+
+Example:
+
+```ruby
+post "/" do
+  headers "X-Trace-Id" => "abc-123"
+  bearer "token-123"
+  query include_details: "true"
+  json "email" => "dev@example.com", "name" => "Dev"
+  expect_status 201
+end
+```
+
+Multipart upload example:
+
+```ruby
+post "/uploads" do
+  multipart!
+  file :file, Rails.root.join("spec/fixtures/files/sample_upload.txt"), content_type: "text/plain"
+  expect_status 201
+  expect_json hash_including("filename" => "sample_upload.txt")
+end
+```
+
+## Expectations
+
+Available expectation helpers:
+
+- `expect_status(code)`
+- `expect_header(key, value_or_regex)`
+- `expect_json(expected = nil, &block)`
+- `expect_json_contract(name)`
+- `expect_json_at(selector, 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: "$")`
+- `expect_ids_in_order(ids, selector: "$[*].id")`
+
+`expect_json` supports:
+
+- matcher mode:
+  - `expect_json hash_including("id" => integer)`
+- equality mode:
+  - `expect_json("id" => 1, "email" => "jane@example.com", "name" => "Jane")`
+- block mode:
+  - `expect_json { |payload| expect(payload["id"]).to integer }`
+
+`expect_json_at` supports the same matcher/equality/block modes against a selected path:
+
+- matcher mode:
+  - `expect_json_at "$.user.id", integer`
+- equality mode:
+  - `expect_json_at "$.user.email", "jane@example.com"`
+- block mode:
+  - `expect_json_at "$.items[0]" { |item| expect(item["id"]).to integer }`
+
+`expect_error` is a convenience helper for common API error payload assertions:
+
+```ruby
+get "/{id}" do
+  path_params id: 999
+  expect_error status: 404, message: "Post not found"
+end
+```
+
+Pagination helpers:
+
+```ruby
+get "/" do
+  query page: 2, per_page: 10
+  expect_status 200
+  expect_page_size 10
+  expect_max_page_size 20
+  expect_ids_in_order [30, 29, 28, 27, 26, 25, 24, 23, 22, 21]
+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`.
+
+```ruby
+contract :post_summary do
+  hash_including(
+    "id" => integer,
+    "title" => string,
+    "author" => hash_including("id" => integer)
+  )
+end
+
+get "/" do
+  expect_status 200
+  expect_json array_of(expect_json_contract(:post_summary))
+end
+```
+
+JSON type helpers:
+
+- `integer`
+- `string`
+- `boolean`
+- `array_of(matcher)`
+- `hash_including(...)`
+
+## Captures
+
+Capture response values and reuse them later in the same example:
+
+- `capture(:name, selector)`
+- `get(:name)`
+
+Selector syntax (minimal JSON selector):
+
+- `$.a.b`
+- `$.items[0].id`
+
+Example:
+
+```ruby
+post "/" do
+  json "email" => "flow@example.com", "name" => "Flow"
+  expect_status 201
+  capture :user_id, "$.id"
+end
+```
+
+## Failure Output and curl Reproduction
+
+When an expectation fails, output includes:
+
+- request method/path
+- request headers/body
+- response status/headers/body
+- generated `curl` command
+
+Sensitive headers are redacted by default and can be customized via
+`redact_headers`.
+
+## Contributing
+
+Contributions are welcome.
+
+Recommended workflow:
+
+1. Fork the repository on GitHub.
+2. Clone your fork locally.
+3. Create a feature branch from `main`.
+4. Make your changes with tests/docs as needed.
+5. Run quality checks locally:
+   - `bundle exec rspec`
+   - `bundle exec rubocop`
+6. Commit and push your branch to your fork.
+7. Open a Pull Request from your fork to this repository.
+
+Pull request guidelines:
+
+- Keep changes focused and include context in the PR description.
+- Add or update specs for behavior changes.
+- Update README/CHANGELOG when public behavior changes.
+- Ensure CI is green before requesting final review.
+
+Reporting issues and feature ideas:
+
+- Use GitHub Issues and choose the appropriate template:
+  - Bug report for incorrect behavior (include expected vs actual behavior and repro steps).
+  - Feature request for enhancement ideas.
+- Feature suggestions are appreciated and encouraged.
+- The fastest path to getting a feature implemented is to open a pull request with the proposed change and tests.
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## Namespace
+
+Gem name: `rspec-rest`  
+Ruby namespace: `RSpec::Rest`
+
+## Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md).
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/exe/rspec-rest

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "rspec/rest"
+
+# This executable is a placeholder for a future rspec-rest command-line interface.
+# It currently only loads the library and informs the user that the CLI
+# has not been implemented yet.
+
+if $PROGRAM_NAME == __FILE__
+  warn "rspec-rest: command-line interface is not yet implemented. This executable is a placeholder."
+end

data/lib/rspec/rest/captures.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "json_selector"
+
+module RSpec
+  module Rest
+    module Captures
+      def capture(name, selector)
+        captures[name.to_sym] = JsonSelector.extract(rest_response.json, selector)
+      end
+
+      def get(name)
+        key = name.to_sym
+        return captures[key] if captures.key?(key)
+
+        raise MissingCaptureError, "No captured value found for #{key.inspect} in this example."
+      end
+
+      private
+
+      def captures
+        @captures ||= {}
+      end
+    end
+  end
+end

data/lib/rspec/rest/class_level_contracts.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module RSpec
+  module Rest
+    module ClassLevelContracts
+      def contract(name, &definition)
+        raise ArgumentError, "contract requires a block definition" unless block_given?
+
+        rest_contracts_local[normalize_contract_name!(name)] = definition
+      end
+
+      def rest_contract_definition(name)
+        rest_contracts[name.to_sym]
+      end
+
+      private
+
+      def normalize_contract_name!(name)
+        raise ArgumentError, "contract name cannot be nil" if name.nil?
+        return name.to_sym if name.respond_to?(:to_sym)
+
+        raise ArgumentError,
+              "contract name must respond to #to_sym, got #{name.inspect} (#{name.class})"
+      end
+
+      def rest_contracts_local
+        @rest_contracts_local ||= {}
+      end
+
+      def rest_contracts
+        inherited = if superclass.respond_to?(:rest_contracts, true)
+                      superclass.send(:rest_contracts)
+                    else
+                      {}
+                    end
+        inherited.merge(rest_contracts_local)
+      end
+    end
+  end
+end

data/lib/rspec/rest/class_level_presets.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module RSpec
+  module Rest
+    module ClassLevelPresets
+      DEFAULT_PRESETS = {
+        headers: {},
+        query: {}
+      }.freeze
+
+      def with_headers(value)
+        current_preset_scope[:headers].merge!(value)
+      end
+
+      def with_query(value)
+        current_preset_scope[:query] ||= {}
+        current_preset_scope[:query].merge!(value)
+      end
+
+      def with_auth(token)
+        with_headers("Authorization" => "Bearer #{token}")
+      end
+
+      private
+
+      def blank_presets
+        deep_dup_presets(DEFAULT_PRESETS)
+      end
+
+      def rest_root_presets
+        @rest_root_presets ||= blank_presets
+      end
+
+      def current_preset_scope
+        stack = @rest_preset_stack || []
+        return stack.last unless stack.empty?
+
+        rest_root_presets
+      end
+
+      def current_request_presets
+        presets = inherited_root_presets
+        merge_presets!(presets, rest_root_presets)
+        (@rest_preset_stack || []).each do |scope|
+          merge_presets!(presets, scope)
+        end
+        presets
+      end
+
+      def inherited_root_presets
+        return blank_presets unless superclass.respond_to?(:rest_root_presets, true)
+
+        deep_dup_presets(superclass.send(:rest_root_presets))
+      end
+
+      def merge_presets!(base, override)
+        base[:headers].merge!(override[:headers] || {})
+        if override[:query] && !override[:query].empty?
+          base[:query] ||= {}
+          base[:query].merge!(override[:query])
+        end
+        base
+      end
+
+      def deep_dup(value)
+        case value
+        when Hash
+          value.transform_values do |v|
+            deep_dup(v)
+          end
+        when Array
+          value.map { |v| deep_dup(v) }
+        else
+          begin
+            value.dup
+          rescue TypeError
+            value
+          end
+        end
+      end
+
+      def deep_dup_presets(presets)
+        {
+          headers: deep_dup(presets[:headers] || {}),
+          query: deep_dup(presets[:query] || {})
+        }
+      end
+    end
+  end
+end

data/lib/rspec/rest/config.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module RSpec
+  module Rest
+    class Config
+      DEFAULT_REDACT_HEADERS = %w[
+        Authorization
+        Proxy-Authorization
+        Cookie
+        Set-Cookie
+        X-Api-Key
+        X-Auth-Token
+      ].freeze
+
+      attr_accessor :app, :base_path, :base_headers, :default_format, :redact_headers, :base_url
+
+      def initialize(**options)
+        @app = options[:app]
+        @base_path = options[:base_path] || ""
+        @base_headers = (options[:base_headers] || {}).dup
+        @default_format = options[:default_format]
+        @redact_headers = (options[:redact_headers] || DEFAULT_REDACT_HEADERS).dup
+        @base_url = options[:base_url] || "http://example.org"
+      end
+    end
+  end
+end

data/lib/rspec/rest/contract_expectations.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "contract_matcher"
+
+module RSpec
+  module Rest
+    module ContractExpectations
+      def expect_json_contract(name)
+        contract_name = normalize_contract_name(name)
+        return unknown_contract_matcher(name_error_message(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?
+
+        available = self.class.send(:rest_contracts).keys.map(&:inspect).sort
+        message = "Unknown contract #{contract_name.inspect}. Available contracts: [#{available.join(', ')}]"
+        unknown_contract_matcher(message)
+      end
+
+      private
+
+      def normalize_contract_name(name)
+        return nil if name.nil? || !name.respond_to?(:to_sym)
+
+        name.to_sym
+      end
+
+      def unknown_contract_matcher(message)
+        UnknownContractMatcher.new(message)
+      end
+
+      def name_error_message(name)
+        "Invalid contract name #{name.inspect} (#{name.class}). " \
+          "expect_json_contract requires a contract name that responds to #to_sym."
+      end
+    end
+  end
+end