WebMock
Ruby library for stubbing HTTP requests in tests — intercepts Net::HTTP, HTTParty, Faraday, RestClient, and other HTTP adapters to prevent real network calls and return controlled responses. WebMock: disables real HTTP connections by default in tests, stubs specific URLs with custom responses (stub_request(:post, 'https://api.openai.com/v1/chat/completions').to_return(body: '...')), verifies requests were made (have_requested(:get, /agent-api/)), and supports request body/header matching. Essential for testing agent services that call external APIs without making real API calls in unit/integration tests.
Score Breakdown
⚙ Agent Friendliness
🔒 Security
Testing library — no production security concerns. WebMock prevents agent tests from leaking real API keys to external services. Ensure WebMock is test-only dependency; production agent code must not stub HTTP calls.
⚡ Reliability
Best When
You're writing Ruby tests for agent services that make external HTTP calls (LLM APIs, tool APIs, webhooks) — WebMock prevents real API calls and gives you controlled responses for reliable agent test suites.
Avoid When
You need to test with real API calls (use VCR for record/replay), you're testing browser network requests, or you're using a non-Ruby HTTP stack.
Use Cases
- • Stub LLM API calls in agent unit tests — stub_request(:post, 'https://api.openai.com/v1/chat/completions').with(body: hash_including(model: 'gpt-4')).to_return(body: fixture('llm_response.json'), headers: {'Content-Type' => 'application/json'})
- • Test agent error handling — stub_request(:post, agent_api_url).to_return(status: 429, body: 'Rate limit exceeded') for testing agent retry logic without hitting real API rate limits
- • Verify agent makes expected API calls — after agent execution, assert_requested(:post, tool_api_url, times: 2) verifies agent called tool API exactly twice
- • Stub external agent tool APIs — stub MCP server HTTP calls, web scraping endpoints, or third-party service APIs that agent uses for tool calling
- • Test agent webhook handling — stub outbound webhook delivery confirmation calls; test that agent sends webhook to expected URL with correct payload
Not For
- • Integration tests against real APIs — WebMock blocks all HTTP by default; use VCR to record and replay real API responses for semi-integration agent tests
- • Non-Ruby HTTP testing — use nock (Node.js), responses (Python), or WireMock (Java) for HTTP mocking in other language agent services
- • System tests running in browser — WebMock stubs Ruby HTTP calls, not browser network requests; use Cypress intercept or Playwright route for browser-level agent UI network mocking
Interface
Authentication
HTTP mocking library — no auth concepts. Stubs intercept agent HTTP calls regardless of auth headers; test auth header presence with .with(headers: {}) matchers.
Pricing
WebMock is MIT licensed, maintained by Bartosz Blimke. Free for all use.
Agent Metadata
Known Gotchas
- ⚠ WebMock blocks all external HTTP by default — after require 'webmock/rspec', any unstubbed HTTP call raises WebMock::NetConnectNotAllowedError; test failures can look like agent logic errors; check for missing stub when agent test fails with network error
- ⚠ Stub URL must match exactly including query params — stub_request(:get, 'https://api.example.com/agents?status=active') only stubs that exact URL; missing query param or extra param causes real HTTP call (blocked); use URI template or regex matchers for flexible agent URL matching
- ⚠ Body matching with hash_including is partial — .with(body: hash_including(model: 'gpt-4')) matches any body containing {model: 'gpt-4'}; without hash_including, exact body match is required; use hash_including for agent request body matchers that allow extra fields
- ⚠ Stub resets between tests but not within — stub_request().to_return multiple times returns same response; .to_return multiple times raises WebMock::MultipleResponses for sequential responses (first call, second call different responses); use .to_return().then.to_return() for agent retry test sequences
- ⚠ WebMock must be configured before HTTP calls — require 'webmock/rspec' in spec_helper; require 'webmock' without /rspec integration doesn't auto-reset stubs between tests; manual WebMock.disable_net_connect! required without RSpec integration
- ⚠ allow_localhost: true for integration tests — WebMock.disable_net_connect!(allow_localhost: true) allows local agent service calls (test server, Capybara) while blocking external; missing allow_localhost blocks Rails system test HTTP calls to test server
Alternatives
Full Evaluation Report
Detailed scoring breakdown, competitive positioning, security analysis, and improvement recommendations for WebMock.
Scores are editorial opinions as of 2026-03-06.