Skip to content
Library for stubbing and setting expectations on HTTP requests in Ruby.
Pull request Compare This branch is 1205 commits behind bblimke:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Library for stubbing HTTP requests in Ruby.


  • Stubbing requests and setting requests expectations
  • Matching requests based on method, url, headers and body
  • Matching not escaped and escaped urls
  • Support for Test::Unit and RSpec (and can be easily extended to other frameworks)
  • Support for Net::Http and other http libraries based on Net::Http
  • Adding other http library adapters is easy


gem install webmock --source

In your test/test_helper.rb or spec/spec_helper.rb include the following lines

require 'webmock'

include WebMock

Now you are ready to write your tests/specs with stubbed HTTP calls.


Stubbed request based on url only and with the default response

 stub_request(:any, "")

 Net::HTTP.get('', '/')    # ===> Success

Stubbing requests based on method, url, body and headers

stub_request(:post, "").with(:body => "abc", :headers => { 'Content-Length' => 3 })

url = URI.parse('')
req =
req['Content-Length'] = 3
res = Net::HTTP.start(, url.port) {|http|
  http.request(req, 'abc')
}    # ===> Success

Matching custom request headers

stub_request(:any, "").with(:headers=>{'Header-Name'=>"Header-Value"}).to_return(:body => "abc", :status => 200)

url = URI.parse('')
req =
req['Header-Name'] = "Header-Value"
res = Net::HTTP.start(, url.port) {|http|
  http.request(req, 'abc')
}    # ===> Success

Custom response

stub_request(:any, "").to_return(:body => "abc", :status => 200,  :headers => { 'Content-Length' => 3 })

Net::HTTP.get('', '/')    # ===> "abc"

Custom response with body as file path'/tmp/response_body.txt', 'w') { |f| f.puts 'abc' }

stub_request(:any, "").to_return(:body => "/tmp/response_body.txt", :status => 200)

Net::HTTP.get('', '/')    # ===> "abc\n"

Request with basic authentication

stub_request(:any, "")

Net::HTTP.get(URI.parse(''))    # ===> Success

Matching urls using regular expressions

 stub_request(:any, /.*google.*/)

 Net::HTTP.get('', '/') # ===> Success

Real requests to network can be allowed or disabled


stub_request(:any, "").to_return(:body => "abc")

Net::HTTP.get('', '/')    # ===> "abc"

Net::HTTP.get('', '/') # ===> /.+Something.+/


Net::HTTP.get('', '/')    # ===> Failure

Clearing stubs

stub_request(:any, "")

Net::HTTP.get('', '/')    # ===> Success


Net::HTTP.get('', '/')    # ===> Failure

Test/Unit style assertions (they actually work everywhere, in RSpec too)

stub_request(:any, "")

url = URI.parse('')
req =
req['Content-Length'] = 3
res = Net::HTTP.start(, url.port) {|http|
  http.request(req, 'abc')

assert_requested :post, "", :headers => {'Content-Length' => 3}, :body => "abc", :times => 1    # ===> Success

assert_not_requested :get, ""    # ===> Success

Expecting real (not stubbed) requests


Net::HTTP.get('', '/')    # ===> Success

assert_requested :get, ""    # ===> Success

RSpec matchers 1

request(:post, "").with(:body => "abc", :headers => {'Content-Length' => 3}).should have_been_made.once

request(:post, "").should have_been_made.times(3)

request(:any, "").should_not have_been_made

RSpec matchers 2 (fakeweb-matcher style)

WebMock.should have_requested(:get, "").with(:body => "abc", :headers => {'Content-Length' => 3}).twice

WebMock.should_not have_requested(:get, "")


Matching requests

Here are the criteria of matching requests:

  • request url matches stubbed request url pattern
  • and request method is the same as stubbed request method or stubbed request method is :any
  • and request body is the same as stubbed request body or stubbed request body is not set (is nil)
  • and request headers are the same as stubbed request headers or stubbed request headers are a subset of request headers or stubbed request headers are not set

Precedence of stubs

Always the last declared stub matching the request will be applied. i.e

stub_request(:get, "").to_return(:body => "abc")
stub_request(:get, "").to_return(:body => "def")

Net::HTTP.get('', '/')   # ====> "def"

Bugs and Issues

Please submit them here


If you have any suggestions on how to improve WebMock please send an email to the mailing list

I'm particularly interested in how the DSL could be improved.


  • Add EventMachine::Protocols::HttpClient adapter


Thank you Fakeweb! This library is based on the idea taken from FakeWeb. I took couple of solutions from that project. I also copied some code i.e Net:Http adapter. Fakeweb architecture unfortunately didn't allow me to extend it easily with the features I needed. I also preferred some things to work differently i.e request stub precedence.


Copyright 2009 Bartosz Blimke. See LICENSE for details.

Something went wrong with that request. Please try again.