http_decoy 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 975527fe6fe58ce43dc77b5a0889d359d3cc55c120e04b5f93de51783e12d71d
-  data.tar.gz: 5d2bd7cc5c51adb9a65f3af5768c892b410b4973b9498d6b378f2efd261cd4f5
+  metadata.gz: 6c07411035e25bff04ba5ca53164ae73c6848e6431823f2e47332548c8214a7d
+  data.tar.gz: f1a9a1c4ee898db259bd4cafae877647d7a91f8066cee5e89378acdcb8e9866d
 SHA512:
-  metadata.gz: 8f12507d96e3dc4d2a2d54a2067cc06c7da17a20d1d2460dd89738d2d166efb8f470399d51a56c7980f154589aee9304f528b27e1d65331686cc44e79446032d
-  data.tar.gz: 613d2362f5fdaa48632fb90dafe49ed81172df3cb62d0f53b7fd8bc93dda10835fc08bba1c23d5ac2246ffb573606b352df292c695a988c3b98ec5069299c8bf
+  metadata.gz: 0f28725b5310aa60d176203562a2120aa9a3b115dcaa2acc86f5b25a1e4c3497dd37acc9b0e8b7a470c605f56edb6ab36e96f9c50d5fde52452b7871fc089066
+  data.tar.gz: 5480510e433a2c1719191c19fa275c6bd5fe476831eb7a578d19b782d85d363e93ea259faab4bf91f355078cc93f4957a5c5d5f07df322f4655e46712ae6fbac

data/CHANGELOG.md

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] — 2026-07-09
+
+### Added
+
+- `HttpDecoy::Minitest` — Minitest integration, parallel to `HttpDecoy::RSpec`:
+  - `include HttpDecoy::Minitest` + `fake_server(name) { ... }` class macro (inline pattern)
+  - `HttpDecoy.define(:name) { ... }.minitest_helpers` — suite-wide helper module, shared with RSpec via the same `Definition`
+  - `assert_received_request(server, method, path, times:, body:)` / `refute_received_request(server, method, path)` assertions
+  - `with_scenario(:name) { ... }` instance method, same semantics as the RSpec version
+  - `require "http_decoy/minitest"` never loads RSpec, and `require "http_decoy/rspec"` never loads Minitest
+- `respond(status, ..., after: seconds)` — delay a response by a real, measurable amount of time; useful for testing timeout thresholds and loading states against a wall clock rather than a raised exception. Works with `respond_sequence` entries too.
+- `raise_error(:timeout | :reset | :refused)` now actually terminates the TCP connection when the fake server is reached over a real socket (not via WebMock interception) — previously this path silently returned a normal `500` response instead of simulating a dropped connection, so code that specifically handles `Errno::ECONNRESET`/timeouts was never exercised unless WebMock was in the loop. Uses `SO_LINGER` to force a real RST rather than a clean EOF.
+
+### Fixed
+
+- `HttpDecoy.define(:name) { ... }.rspec_helpers` used standalone via `RSpec.configure { |c| c.include Foo.rspec_helpers }` (the primary documented usage) raised `NoMethodError` on `_http_decoy_register` unless the example group also separately did `include HttpDecoy::RSpec`. Ruby's `included` hook doesn't cascade through nested `include`s, so the generated helper module's `included` callback now explicitly extends `ClassMethods` onto the includer.
+
+### Changed
+
+- `HttpDecoy::Definition` moved to its own file (`definition.rb`) so `HttpDecoy.define` no longer force-loads RSpec — a Minitest-only project including `http_decoy/minitest` never pulls in `rspec/core`, and vice versa.
+- Deduplicated the request-body matcher shared by the RSpec `have_received_request(...).with(body:)` chain and the new Minitest `assert_received_request(..., body:)` into `HttpDecoy::BodyMatcher`.
+
 ## [0.1.0] — 2026-06-02
 
 ### Added
@@ -35,5 +57,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Ruby 3.1+ support
 - 92% test coverage (SimpleCov), 66 examples
 
-[Unreleased]: https://github.com/jibranusman/http_decoy/compare/v0.1.0...HEAD
-[0.1.0]: https://github.com/jibranusman/http_decoy/releases/tag/v0.1.0
+[Unreleased]: https://github.com/jibranusman95/http_decoy/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/jibranusman95/http_decoy/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/jibranusman95/http_decoy/releases/tag/v0.1.0

data/CONTRIBUTING.md

@@ -1,67 +1,39 @@
 # Contributing to http_decoy
 
-Thanks for taking the time. Bug reports, documentation improvements, and feature proposals are all welcome.
+First: thank you. It genuinely means a lot.
 
-## Setup
+## Quick start
 
 ```bash
-git clone https://github.com/jibranusman/http_decoy
+git clone https://github.com/jibranusman95/http_decoy
 cd http_decoy
 bundle install
+bundle exec rspec     # RSpec suite — make sure everything is green before you start
+bundle exec rake test # Minitest suite
+bundle exec rubocop   # no existing offenses to inherit
 ```
 
-## Running the tests
+## How to contribute
 
-```bash
-bundle exec rspec          # full suite
-bundle exec rspec spec/http_decoy/server_spec.rb   # single file
-```
-
-## Linting
-
-```bash
-bundle exec rubocop        # check
-bundle exec rubocop -a     # autocorrect safe offenses
-```
-
-Both must be green before a PR can be merged. CI enforces this on every push.
-
-## Submitting a pull request
-
-1. Fork the repo and create a branch from `main`
-2. Write a failing test that describes the bug or feature
-3. Make it pass
-4. Run `bundle exec rspec` and `bundle exec rubocop` — both must be clean
-5. Update `CHANGELOG.md` under `[Unreleased]`
-6. Open a PR with a clear description of what and why
-
-## What we're looking for
+**Found a bug?** Open an issue. Include a minimal reproduction if you can — it'll get fixed faster.
 
-- Bug fixes with a reproducing spec
-- New DSL features (propose in an issue first if it's non-trivial)
-- Additional body content-type support
-- Better error messages
-- Real-world usage examples in the README
+**Want a feature?** Open an issue first so we can align before you build. Nothing worse than putting work into something that doesn't fit.
 
-## Good first issues
+**Have a fix ready?** Just open a PR. One thing per PR. Include a failing test if the change is non-trivial.
 
-Check the [`good first issue`](https://github.com/jibranusman/http_decoy/issues?q=label%3A%22good+first+issue%22) label for beginner-friendly tasks.
+**Docs or README improvements?** Also very welcome — just send the PR directly.
 
-## Code style
+## Before you submit
 
-- `frozen_string_literal: true` on every file
-- Follow the existing RuboCop config (`.rubocop.yml`)
-- Keep handler blocks and DSL methods small and focused
-- No clever metaprogramming without a comment explaining why
+- `bundle exec rspec` — all green
+- `bundle exec rake test` — all green (Minitest suite)
+- `bundle exec rubocop` — no new offenses
+- Focused scope — one fix or feature per PR
 
-## Reporting bugs
+## What happens next
 
-Open a GitHub issue with:
-- Ruby version (`ruby --version`)
-- http_decoy version
-- Minimal reproduction case (ideally a failing RSpec example)
-- What you expected vs what happened
+I review promptly — usually within a day or two, often faster. I'll either merge it, ask for changes with clear reasoning, or explain why it doesn't fit. No ghosting.
 
-## Security issues
+## License
 
-Do not open a public issue for security vulnerabilities. Email the maintainer directly (address in the gemspec).
+By contributing, you agree your changes are released under the same [MIT License](LICENSE) as this project.

data/README.md

@@ -2,7 +2,7 @@
 
 **A real fake HTTP server. For real tests.**
 
-[![CI](https://github.com/jibranusman/http_decoy/actions/workflows/ci.yml/badge.svg)](https://github.com/jibranusman/http_decoy/actions)
+[![CI](https://github.com/jibranusman95/http_decoy/actions/workflows/ci.yml/badge.svg)](https://github.com/jibranusman95/http_decoy/actions)
 [![Gem Version](https://badge.fury.io/rb/http_decoy.svg)](https://badge.fury.io/rb/http_decoy)
 [![Downloads](https://img.shields.io/gem/dt/http_decoy)](https://rubygems.org/gems/http_decoy)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
@@ -279,6 +279,25 @@ end
 
 Available transport errors: `:timeout`, `:reset`, `:refused`.
 
+How the client observes this depends on how the request reached http_decoy:
+
+- **Through WebMock's interception** (the default, whenever `base_url` is declared) — the exact matching Ruby exception (`Timeout::Error`, `Errno::ECONNRESET`, `Errno::ECONNREFUSED`) is raised directly at your HTTP client's call site, so `rescue Errno::ECONNRESET` in your code sees a real instance of that class.
+- **Hitting the server directly over a real socket** (`server.base_url` with no WebMock in between — e.g. an SDK-under-test that owns its own connection) — there's no HTTP status code for "the connection died," so http_decoy actually terminates the TCP connection (via `SO_LINGER`, which forces the kernel to send RST) rather than returning a response. Your client sees a genuine connection failure, not a 500.
+
+Either way, an unhandled exception from your *own* handler code (a real bug, not `raise_error`) still returns a normal `500` with the error message in the body — that path is unchanged.
+
+### Simulating latency
+
+`respond` accepts `after:` (seconds) to delay the response — useful for testing timeout thresholds, loading states, or spinners against a real clock instead of a raised exception:
+
+```ruby
+get "/slow-report" do
+  respond 200, json: { status: "ready" }, after: 2.5
+end
+```
+
+Works with `respond_sequence` too — set `after:` per entry to simulate a service that degrades over successive calls.
+
 ### Stateful sequences
 
 ```ruby
@@ -340,6 +359,45 @@ end
 
 ---
 
+## Minitest integration
+
+Same DSL, same `HttpDecoy.define` definitions — `require "http_decoy/minitest"` never loads RSpec, and vice versa.
+
+Suite-wide (recommended) — same `FakeStripe` definition as above, shared across both frameworks:
+
+```ruby
+class ChargeTest < Minitest::Test
+  include FakeStripe.minitest_helpers
+
+  def test_charges_the_card
+    StripeService.charge(500)
+    assert_received_request fake_server(:stripe), :post, "/v1/charges"
+  end
+end
+```
+
+Inline per test class:
+
+```ruby
+class DegradedUpstreamTest < Minitest::Test
+  include HttpDecoy::Minitest
+
+  fake_server(:api) do
+    get "/status" do
+      respond 503, json: { status: "degraded" }
+    end
+  end
+
+  def test_handles_it_gracefully
+    assert_equal :degraded, MyApp.health_check
+  end
+end
+```
+
+Assertions: `assert_received_request(server, method, path, times:, body:)` and `refute_received_request(server, method, path)` mirror the RSpec `have_received_request` matcher's chains.
+
+---
+
 ## Configuration
 
 ```ruby
@@ -355,15 +413,15 @@ end
 
 | | WebMock | VCR | **http_decoy** |
 |---|---|---|---|
-| Real server | No | No | **Yes** |
-| Request contract validation | No | No | **Yes** |
-| Dynamic responses | No | No | **Yes** |
+| Real server | optional | No | **Yes** |
+| Request contract validation | possible | No | **Yes** |
+| Dynamic responses | yes | No | **Yes** |
 | Failure scenario testing | Verbose | Very hard | **One line** |
 | Works offline | Yes | First run: No | **Yes** |
 | Secrets in version control | No | **Risk** | No |
 | Cassettes to maintain | No | **Yes** | No |
 | Define once, use everywhere | Requires setup | Yes | **Yes** |
-| Catches API drift | No | No | **Yes** |
+| Catches API drift | possible | No | **Yes** |
 
 http_decoy uses WebMock internally to intercept requests — complementary, not a replacement.
 
@@ -452,23 +510,57 @@ end
 - Ruby 3.1+
 - Runtime dependencies: `webrick`, `rack` (both lightweight)
 - Optional: `webmock` for URL interception
+- Works with RSpec or Minitest — neither is a runtime dependency; only the integration you `require` gets loaded
+
+---
+
+## Further Reading
+
+- [Why WebMock Stubs Lie (And What To Do About It)](https://dev.to/jibranusman95/why-webmock-stubs-lie-and-what-to-do-about-it-4990) — the problem http_decoy was built to solve, with examples
 
 ---
 
 ## Contributing
 
+I built this myself — which means it works great for the cases I thought of, and probably has rough edges for the ones I didn't. If you hit something weird, **open an issue**. I read them all and respond fast.
+
+Want to fix something or add a feature? **Send a PR.** No CLA, no process overhead, no committee review. If the tests pass and the change makes sense, it's getting merged. I'm one person and I genuinely appreciate the help — you can take this further than I can alone.
+
+Not sure where to start? Look for [`good first issue`](https://github.com/jibranusman95/http_decoy/issues?q=label%3A%22good+first+issue%22) labels, or just open an issue and ask.
+
 ```bash
-git clone https://github.com/jibranusman/http_decoy
+git clone https://github.com/jibranusman95/http_decoy
 cd http_decoy
 bundle install
-bundle exec rspec      # run all tests
-bundle exec rubocop    # lint
+bundle exec rspec    # RSpec suite
+bundle exec rake test # Minitest suite
+bundle exec rubocop  # no new offenses
 ```
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for full guidelines. Good first issues are labeled [`good first issue`](https://github.com/jibranusman/http_decoy/issues?q=label%3A%22good+first+issue%22).
+See [CONTRIBUTING.md](CONTRIBUTING.md) for full guidelines.
+
+### Contributors
+
+Everyone who's made this better:
+
+<a href="https://github.com/jibranusman95/http_decoy/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=jibranusman95/http_decoy" />
+</a>
 
 ---
 
+## From the same author
+
+Small, sharp Ruby gems built to the same standard — 100% test coverage, zero dependencies beyond what's needed.
+
+| Gem | What it does |
+|-----|-------------|
+| [llm_cassette](https://github.com/jibranusman95/llm_cassette) | VCR for LLMs — streaming-aware cassette recorder for OpenAI and Anthropic |
+| [turbo_presence](https://github.com/jibranusman95/turbo_presence) | Figma-style live cursors, avatar stacks, and typing indicators for Rails/Hotwire |
+| [promptscrub](https://github.com/jibranusman95/promptscrub) | PII redaction middleware for LLM calls — strip sensitive data from prompts, rehydrate in responses |
+| [webhook_inbox](https://github.com/jibranusman95/webhook_inbox) | Transactional inbox for Rails webhook receivers — deduplication, async processing, replay, dashboard |
+| [agent_jail](https://github.com/jibranusman95/agent_jail) | Fork-based sandbox for LLM tool calls — timeout, memory limit, and filesystem restrictions |
+
 ## License
 
 MIT. See [LICENSE](LICENSE).

data/Rakefile

@@ -2,7 +2,16 @@
 
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
+require "rake/testtask"
 
 RSpec::Core::RakeTask.new(:spec)
 
-task default: :spec
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test" << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+  # Default -w flag surfaces a harmless "circular require" warning from
+  # webmock/minitest loading against minitest's own loader — not our bug.
+  t.warning = false
+end
+
+task default: %i[spec test]

data/lib/http_decoy/body_matcher.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module HttpDecoy
+  # Shared by the RSpec `have_received_request(...).with(body:)` chain and the
+  # Minitest `assert_received_request(..., body:)` keyword — matches a logged
+  # request body against either an exact Hash of expected key/value matchers
+  # (each value tested via `===`, so RSpec matchers, classes, and regexes all
+  # work) or a single matcher applied to the whole body.
+  module BodyMatcher
+    module_function
+
+    # rubocop:disable Style/CaseEquality -- `===` is the point: callers pass
+    # RSpec matchers, Regexp, Class, or plain values as `matcher`/`v`.
+    def matches?(actual, matcher)
+      case matcher
+      when Hash
+        actual.is_a?(Hash) && matcher.all? do |k, v|
+          actual_val = actual[k] || actual[k.to_s]
+          v === actual_val
+        end
+      else
+        matcher === actual
+      end
+    end
+    # rubocop:enable Style/CaseEquality
+  end
+end

data/lib/http_decoy/definition.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module HttpDecoy
+  # Wraps a named RouteMap so it can be shared across multiple test files
+  # and reused across test frameworks.
+  #
+  # Framework-specific helper methods are added by whichever integration
+  # file is loaded: `require "http_decoy/rspec"` adds #rspec_helpers,
+  # `require "http_decoy/minitest"` adds #minitest_helpers.
+  class Definition
+    attr_reader :name, :route_map
+
+    def initialize(name, route_map)
+      @name      = name
+      @route_map = route_map
+    end
+  end
+end

data/lib/http_decoy/handler_context.rb

@@ -42,7 +42,11 @@ module HttpDecoy
     end
 
     # Build and store the response tuple for this request.
-    def respond(status, json: nil, text: nil, headers: {})
+    # `after:` delays the response by the given number of seconds — useful
+    # for testing timeout thresholds and loading states against a real clock,
+    # not just a raised exception.
+    def respond(status, json: nil, text: nil, headers: {}, after: nil)
+      sleep(after) if after&.positive?
       body_str     = json ? JSON.generate(resolve(json)) : text.to_s
       content_type = json ? "application/json" : "text/plain"
       @_response   = [status.to_i, { "Content-Type" => content_type }.merge(headers), [body_str]]

data/lib/http_decoy/minitest.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require_relative "route_map"
+require_relative "server"
+require_relative "webmock_integration"
+require_relative "definition"
+require_relative "body_matcher"
+
+module HttpDecoy
+  # Minitest integration. Same server lifecycle and semantics as
+  # HttpDecoy::RSpec (fresh Server per test, WebMock stub scoped to that
+  # server, teardown never calls WebMock.reset!) hooked into Minitest's
+  # setup/teardown instead of RSpec's before/after.
+  #
+  # Pattern A — inline (per test class):
+  #
+  #   class ChargeTest < Minitest::Test
+  #     include HttpDecoy::Minitest
+  #
+  #     fake_server(:payments) do
+  #       post "/charges" do
+  #         respond 201, json: { id: "ch_abc" }
+  #       end
+  #     end
+  #
+  #     def test_creates_a_charge
+  #       MyService.charge(100)
+  #       assert_received_request fake_server(:payments), :post, "/charges"
+  #     end
+  #   end
+  #
+  # Pattern B — suite-wide definition (shared with RSpec):
+  #
+  #   FakeStripe = HttpDecoy.define(:stripe) do
+  #     base_url "https://api.stripe.com"
+  #     post "/v1/charges" do
+  #       respond 200, json: { id: "ch_123" }
+  #     end
+  #   end
+  #
+  #   class ChargeTest < Minitest::Test
+  #     include FakeStripe.minitest_helpers
+  #
+  #     def test_charges_the_card
+  #       StripeService.charge(500)
+  #       assert_received_request fake_server(:stripe), :post, "/v1/charges"
+  #     end
+  #   end
+  module Minitest
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.include(Assertions)
+    end
+
+    module ClassMethods
+      # Class-level macro. Evaluates the block into a RouteMap once at class-load
+      # time, then registers it for the shared setup/teardown hooks.
+      def fake_server(name, &)
+        route_map = RouteMap.new
+        route_map.instance_eval(&)
+        _http_decoy_register(name, route_map)
+      end
+
+      # Internal: register a pre-built RouteMap and install setup/teardown
+      # (once per class) that start/stop every registered server.
+      # Called by both the fake_server macro and Definition#minitest_helpers.
+      def _http_decoy_register(name, route_map)
+        _http_decoy_route_maps[name] = route_map
+        _http_decoy_install_hooks
+      end
+
+      def _http_decoy_route_maps
+        @_http_decoy_route_maps ||= {}
+      end
+
+      def _http_decoy_install_hooks
+        return if @_http_decoy_hooks_installed
+
+        @_http_decoy_hooks_installed = true
+
+        define_method(:setup) do
+          super()
+          @_http_decoy_servers       = {}
+          @_http_decoy_webmock_stubs = {}
+
+          self.class._http_decoy_route_maps.each do |server_name, route_map|
+            server = Server.new(route_map)
+            server.start
+            stub = WebMockIntegration.setup(server)
+            @_http_decoy_servers[server_name] = server
+            @_http_decoy_webmock_stubs[server_name] = stub
+          end
+        end
+
+        define_method(:teardown) do
+          (@_http_decoy_servers || {}).each_key do |server_name|
+            server = @_http_decoy_servers[server_name]
+            stub   = @_http_decoy_webmock_stubs[server_name]
+            WebMockIntegration.teardown(stub)
+            server&.stop
+          end
+          super()
+        end
+      end
+    end
+
+    # Instance-level accessor — returns the live Server for this test.
+    def fake_server(name)
+      @_http_decoy_servers[name]
+    end
+
+    # Run a block with a named scenario active.
+    # server_name defaults to the only server if exactly one is registered.
+    def with_scenario(scenario_name, server_name = nil, &)
+      name = server_name || begin
+        servers = @_http_decoy_servers || {}
+        raise ArgumentError, "server_name required when multiple fake servers are active" if servers.size > 1
+        raise ArgumentError, "No fake servers are active" if servers.empty?
+
+        servers.keys.first
+      end
+
+      server = @_http_decoy_servers[name]
+      raise ArgumentError, "No fake server named #{name.inspect}" unless server
+
+      server.with_scenario(scenario_name, &)
+    end
+
+    # ---------------------------------------------------------------------------
+    # Minitest assertions
+    # ---------------------------------------------------------------------------
+    module Assertions
+      def assert_received_request(server, method, path, times: nil, body: nil)
+        entries     = server.request_log.for(method, path)
+        description = "#{method.to_s.upcase} #{path}"
+
+        if times
+          assert_equal times, entries.count,
+                       "expected #{description} to have been received #{times} time(s), " \
+                       "but it was received #{entries.count} time(s)"
+        else
+          assert entries.any?, "expected #{description} to have been received, but it was never called"
+        end
+
+        return unless body
+
+        assert entries.any? { |e| HttpDecoy::BodyMatcher.matches?(e.body, body) },
+               "expected #{description} body to match #{body.inspect}, but received: #{entries.map(&:body).inspect}"
+      end
+
+      def refute_received_request(server, method, path)
+        entries = server.request_log.for(method, path)
+        assert entries.empty?, "expected #{method.to_s.upcase} #{path} not to have been received"
+      end
+    end
+  end
+
+  # Reopens Definition (see definition.rb) to add the Minitest-specific helper.
+  class Definition
+    # Returns an anonymous module. Include it in a Minitest::Test subclass to
+    # register the server lifecycle for every test in that class.
+    #
+    #   include FakeStripe.minitest_helpers
+    #
+    def minitest_helpers
+      definition = self
+
+      Module.new do
+        include HttpDecoy::Minitest
+
+        # See the matching comment in rspec.rb — the explicit `extend` is
+        # required because Ruby's `included` hook does not cascade through
+        # nested includes.
+        define_singleton_method(:included) do |base|
+          super(base)
+          base.extend(HttpDecoy::Minitest::ClassMethods)
+          base.include(HttpDecoy::Minitest::Assertions)
+          base._http_decoy_register(definition.name, definition.route_map)
+        end
+
+        define_method(:_http_decoy_definition) { definition }
+      end
+    end
+  end
+end

data/lib/http_decoy/rspec.rb

@@ -4,6 +4,8 @@ require "rspec/core"
 require_relative "route_map"
 require_relative "server"
 require_relative "webmock_integration"
+require_relative "definition"
+require_relative "body_matcher"
 
 module HttpDecoy
   # RSpec integration.
@@ -112,7 +114,7 @@ module HttpDecoy
       entries = server.request_log.for(method, path)
       next false if entries.empty?
       next false if @times && entries.count != @times
-      next false if @body_matcher && entries.none? { |e| body_matches?(e.body, @body_matcher) }
+      next false if @body_matcher && entries.none? { |e| HttpDecoy::BodyMatcher.matches?(e.body, @body_matcher) }
 
       true
     end
@@ -154,33 +156,14 @@ module HttpDecoy
       desc += " with body matching #{@body_matcher.inspect}" if @body_matcher
       desc
     end
-
-    def body_matches?(actual, matcher)
-      case matcher
-      when Hash
-        actual.is_a?(Hash) && matcher.all? do |k, v|
-          actual_val = actual[k] || actual[k.to_s]
-          v === actual_val
-        end
-      else
-        matcher === actual
-      end
-    end
   end
 
   # ---------------------------------------------------------------------------
   # Definition — returned by HttpDecoy.define
   # ---------------------------------------------------------------------------
 
-  # Wraps a named RouteMap and generates an anonymous RSpec helper module.
+  # Reopens Definition (see definition.rb) to add the RSpec-specific helper.
   class Definition
-    attr_reader :name, :route_map
-
-    def initialize(name, route_map)
-      @name      = name
-      @route_map = route_map
-    end
-
     # Returns an anonymous module. Include it in RSpec.configure to register
     # the server lifecycle for every example group in the suite.
     #
@@ -194,8 +177,15 @@ module HttpDecoy
 
         # define_singleton_method closes over `definition` from the outer scope.
         # `def self.included` would NOT — def never captures outer locals.
+        #
+        # `extend` is required here: `include HttpDecoy::RSpec` above only ran
+        # HttpDecoy::RSpec.included against *this anonymous module*, not against
+        # `base` — Ruby's included hook does not cascade through nested includes.
+        # Without this line, `RSpec.configure { |c| c.include Foo.rspec_helpers }`
+        # used on its own raises NoMethodError on `_http_decoy_register`.
         define_singleton_method(:included) do |base|
           super(base)
+          base.extend(HttpDecoy::RSpec::ClassMethods)
           base._http_decoy_register(definition.name, definition.route_map)
         end
 

data/lib/http_decoy/server.rb

@@ -2,6 +2,7 @@
 
 require "webrick"
 require "rack"
+require "socket"
 require "stringio"
 require "json"
 require_relative "request_log"
@@ -44,6 +45,13 @@ module HttpDecoy
         res.status = status.to_i
         headers.each { |k, v| res[k] = v }
         res.body = Array(body).join
+      rescue Timeout::Error, Errno::ECONNRESET, Errno::ECONNREFUSED
+        # raise_error(:timeout/:reset/:refused): over a real socket there's no
+        # response that means "the connection died" — the only faithful
+        # simulation is to actually kill the connection. (Over WebMock's
+        # to_rack interception this same exception instead propagates directly
+        # to the caller, which is the more common path and needs no help here.)
+        drop_connection(req)
       rescue StandardError => e
         res.status = 500
         res["Content-Type"] = "application/json"
@@ -162,5 +170,31 @@ module HttpDecoy
     def json_response(status, payload)
       [status.to_i, { "Content-Type" => "application/json" }, [JSON.generate(payload)]]
     end
+
+    # Forcibly terminate the underlying TCP connection instead of sending a
+    # response. WEBrick::HTTPRequest stores the raw socket in @socket once
+    # #parse has run (it's not exposed through the public API) — reaching in
+    # is the only way to make a "connection reset" simulation actually reset
+    # the connection rather than returning a normal 500 response.
+    #
+    # SO_LINGER 0 makes the kernel send RST on close instead of a graceful
+    # FIN, so the client observes a real ECONNRESET (or equivalent) rather
+    # than a clean EOF. Any failure here (unsupported socket, already closed)
+    # is swallowed — the surrounding WEBrick request loop still tries to
+    # write a response to the now-closed socket and fails safely on its own.
+    def drop_connection(req)
+      sock = req.instance_variable_get(:@socket)
+      return unless sock
+
+      begin
+        sock.setsockopt(Socket::SOL_SOCKET, Socket::SO_LINGER, [1, 0].pack("ii"))
+      rescue StandardError
+        nil
+      end
+
+      sock.close
+    rescue StandardError
+      nil
+    end
   end
 end

data/lib/http_decoy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module HttpDecoy
-  VERSION = "0.1.1"
+  VERSION = "0.2.0"
 end

data/lib/http_decoy.rb

@@ -9,6 +9,7 @@ require_relative "http_decoy/request_log"
 require_relative "http_decoy/handler_context"
 require_relative "http_decoy/server"
 require_relative "http_decoy/webmock_integration"
+require_relative "http_decoy/definition"
 
 module HttpDecoy
   class << self
@@ -25,7 +26,7 @@ module HttpDecoy
       @configuration ||= Configuration.new
     end
 
-    # Define a named fake service.
+    # Define a named fake service, reusable across RSpec and Minitest.
     #
     #   FakeStripe = HttpDecoy.define(:stripe) do
     #     base_url "https://api.stripe.com"
@@ -37,9 +38,13 @@ module HttpDecoy
     #   end
     #
     #   RSpec.configure { |c| c.include FakeStripe.rspec_helpers }
+    #   # or, in a Minitest::Test subclass:
+    #   include FakeStripe.minitest_helpers
     #
+    # #rspec_helpers requires "http_decoy/rspec" to be loaded; #minitest_helpers
+    # requires "http_decoy/minitest" — this method itself pulls in neither, so
+    # a Minitest-only project never loads RSpec (and vice versa).
     def define(name = :default, &)
-      require_relative "http_decoy/rspec"
       route_map = RouteMap.new
       route_map.instance_eval(&)
       Definition.new(name, route_map)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: http_decoy
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Jibran Usman
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-02 00:00:00.000000000 Z
+date: 2026-07-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -54,8 +54,11 @@ files:
 - README.md
 - Rakefile
 - lib/http_decoy.rb
+- lib/http_decoy/body_matcher.rb
 - lib/http_decoy/configuration.rb
+- lib/http_decoy/definition.rb
 - lib/http_decoy/handler_context.rb
+- lib/http_decoy/minitest.rb
 - lib/http_decoy/request_log.rb
 - lib/http_decoy/route.rb
 - lib/http_decoy/route_map.rb
@@ -91,6 +94,6 @@ requirements: []
 rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
-summary: Declarative fake HTTP servers for RSpec. Real server. Real requests. Zero
-  cassettes.
+summary: Declarative fake HTTP servers for RSpec/Minitest. Real server. Real requests.
+  Zero cassettes.
 test_files: []