How to stub a JSON API response with WebMock?

Use to_return with a JSON body and set the Content-Type header to 'application/json'. For example, stub_request(:get, 'api.example.com').to_return(body: '{"key":"value"}', headers: {'Content-Type' => 'application/json'}). WebMock also provides a shorthand to_return_json for convenience.

WebMock or VCR for mocking HTTP requests in Ruby?

WebMock is better for fine-grained control over request/response stubbing and verification, while VCR excels at recording and replaying real interactions. Use WebMock for deterministic unit tests and VCR for integration tests that need realistic data.

How to allow real connections to specific domains in WebMock?

Use WebMock.disable_net_connect! with the allow option, passing a string, regex, or lambda. For example, WebMock.disable_net_connect!(allow: /example\.com/) permits requests to example.com while blocking others, as shown in the network control examples.

Why isn't WebMock intercepting my HTTP request?

Check if your HTTP client is supported in the README's list. Also, ensure WebMock is enabled and stubs are correctly matched; mismatched URIs or headers can cause failures. Verify with WebMock.allow_net_connect! to test real requests.

How to assert that a request was made with specific query params in RSpec?

Use have_requested with the query option. For instance, expect(WebMock).to have_requested(:get, 'www.example.com').with(query: {'a' => 'b'}). WebMock supports hash_including for partial matches, as detailed in the expectations section.

Can WebMock handle HTTP basic authentication in URLs?

Yes, but note that since version 2.0.0, WebMock treats URL-based auth and header-based auth separately. Stub with user:pass@example.com for URL auth or with(basic_auth: ['user', 'pass']) for headers, as explained in the examples.

Open-Awesome

WebMock

MITRubyv3.26.2

A Ruby library for stubbing and setting expectations on HTTP requests in tests.

GitHub

4.1k stars577 forks0 contributors

What is WebMock?

WebMock is a Ruby library for stubbing and setting expectations on HTTP requests in tests. It intercepts HTTP requests at the client library level, allowing developers to simulate external API responses, control network behavior, and verify that their code makes the expected HTTP calls without relying on live services.

Target Audience

Ruby developers writing tests for applications that make HTTP requests, especially those using RSpec, MiniTest, or Test::Unit and needing reliable, fast, and deterministic test suites.

Value Proposition

Developers choose WebMock for its deep integration with Ruby HTTP clients, flexible request matching, and seamless support for major testing frameworks, making it the go-to solution for mocking HTTP interactions in Ruby tests.

Overview

Library for stubbing and setting expectations on HTTP requests in Ruby.

Use Cases

Best For

Testing Ruby applications that consume external APIs
Mocking HTTP requests in RSpec, MiniTest, or Test::Unit test suites
Simulating API failures, timeouts, or specific response codes
Verifying that your code makes the correct HTTP calls with expected parameters
Isolating tests from network dependencies for faster and more reliable test runs
Stubbing third-party service interactions in development or CI environments

Not Ideal For

Projects requiring real HTTP integrations with live servers for end-to-end testing
Applications using HTTP clients not listed in WebMock's supported libraries (e.g., newer or niche gems)
Testing scenarios involving HTTP/2, WebSockets, or other protocols beyond basic HTTP/1.1
High-performance test suites where the overhead of request interception is unacceptable

Pros & Cons

Pros

Extensive HTTP Library Coverage

Supports over 10 popular Ruby HTTP clients including Net::HTTP, HTTParty, and Excon, as listed in the README, ensuring broad compatibility without switching libraries.

Granular Request Matching

Matches requests by method, URI (with regex and RFC 6570 templates), headers, and body (JSON, XML, etc.), demonstrated in examples like stubbing with partial hashes or lambda blocks.

Seamless Test Framework Integration

Out-of-the-box support for RSpec, MiniTest, and Test::Unit with simple require statements, as shown in setup instructions for each framework.

Powerful Response Control

Allows custom responses, errors, timeouts, and Rack app delegation, with features like chained responses and dynamic evaluation from blocks or lambdas.

Cons

Net::HTTP Connection Quirks

The README warns that WebMock breaks Net::HTTP's default behavior by not connecting on start, requiring manual :net_http_connect_on_start configuration, which adds complexity.

Dependent on Supported Clients

Only works with the explicitly listed HTTP libraries; if a project uses an unsupported client, WebMock cannot intercept requests, forcing workarounds or alternative tools.

Stub Management Overhead

Managing stub precedence and clearing history requires careful setup (e.g., using WebMock.reset!), as the last declared stub wins and stale stubs can cause test pollution.

Frequently Asked Questions

Related Projects

faker

A library for generating fake data such as names, addresses, and phone numbers.

Acceptance test framework for web applications

Stars10,153

Forks1,469

Last commit5 days ago

factory_bot

A library for setting up Ruby objects as test data.

Stars8,192

Forks2,568

Last commit7 days ago

VCR

Record your test suite's HTTP interactions and replay them during future test runs for fast, deterministic, accurate tests.

Stars6,045

Forks507

Last commit1 month ago

Community-curated · Updated weekly · 100% open source

Found a gem we're missing?

Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.

Submit a project Star on GitHub