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


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


  • Stubbing HTTP requests at low http client lib level (no need to change tests when you change HTTP library)
  • Setting and verifying expectations on HTTP requests
  • Matching requests based on method, URI, headers and body
  • Smart matching of the same URIs in different representations (also encoded and non encoded forms)
  • Smart matching of the same headers in different representations.
  • Support for Test::Unit
  • Support for RSpec 1.x and RSpec 2.x

Supported HTTP libraries

  • Net::HTTP and libraries based on Net::HTTP (i.e RightHttpConnection, REST Client, HTTParty)
  • HTTPClient
  • Patron
  • EM-HTTP-Request
  • Curb (currently only Curb::Easy)


gem install webmock --source

or to install the latest development version from github master

git clone
cd webmock
rake install


Add the following code to test/test_helper.rb

require 'webmock/test_unit'


Add the following code to spec/spec_helper:

require 'webmock/rspec'


Add the following code to features/support/env.rb

require 'webmock/cucumber'

You can also use WebMock outside a test framework:

require 'webmock'
include WebMock::API



Stubbed request based on uri only and with the default response

 stub_request(:any, "")

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

Stubbing requests based on method, uri, body and headers

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

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

Matching request body and headers against regular expressions

stub_request(:post, "").
  with(:body => /^.*world$/, :headers => {"Content-Type" => /image\/.+/}).to_return(:body => "abc")

uri = URI.parse('')
req =
req['Content-Type'] = 'image/png'
res = Net::HTTP.start(, uri.port) {|http|
  http.request(req, 'hello world')
}    # ===> Success

Matching request body against a hash. Body can be URL-Encoded, JSON or XML.

stub_http_request(:post, "").
	with(:body => {:data => {:a => '1', :b => 'five'}})'', "data[a]=1&data[b]=five", 
  :content_type => 'application/x-www-form-urlencoded')    # ===> Success'', '{"data":{"a":"1","b":"five"}}', 
  :content_type => 'application/json')    # ===> Success'', '<data a="1" b="five" />', 
  :content_type => 'application/xml' )    # ===> Success

Matching custom request headers

stub_request(:any, "").with(:headers=>{ 'Header-Name' => 'Header-Value' })

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

Matching multiple headers with the same name

stub_http_request(:get, '').with(:headers => {'Accept' => ['image/jpeg', 'image/png'] })

req ="/")  
req['Accept'] = ['image/png']
req.add_field('Accept', 'image/jpeg')
Net::HTTP.start("") {|http|  http.request(req) } # ===> Success

Matching requests against provided block

stub_request(:post, "").with { |request| request.body == "abc" }'', 'abc')    # ===> Success

Request with basic authentication

stub_request(:get, "")

Net::HTTP.start('') {|http|
  req ='/')
  req.basic_auth 'user', 'pass'
}  # ===> Success

Matching uris using regular expressions

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

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

Matching query params using hash

 stub_http_request(:get, "").with(:query => {"a" => ["b", "c"]})
 RestClient.get("[]=b&a[]=c") # ===> Success	

Stubbing with custom response

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

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

Response with body specified as IO object'/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"

Response with custom status message

stub_request(:any, "").to_return(:status => [500, "Internal Server Error"])

req ="/")
Net::HTTP.start("") { |http| http.request(req) }.message # ===> "Internal Server Error"

Replaying raw responses recorded with curl -is

`curl -is > /tmp/example_curl_-is_output.txt`
raw_response_file ="/tmp/example_curl_-is_output.txt")

from file

stub_request(:get, "").to_return(raw_response_file)

or string

stub_request(:get, "").to_return(

Responses dynamically evaluated from block

stub_request(:any, '').
  to_return { |request| {:body => request.body} }'', 'abc')    # ===> "abc\n"

Responses dynamically evaluated from lambda

stub_request(:any, '').
  to_return(lambda { |request| {:body => request.body} })'', 'abc')    # ===> "abc\n"	       

Dynamically evaluated raw responses recorded with curl -is

`curl -is > /tmp/`
stub_request(:get, "").to_return(lambda { |request|"/tmp/#{}.txt" }))

Responses with dynamically evaluated parts

stub_request(:any, '').
  to_return(:body => lambda { |request| request.body })'', 'abc')    # ===> "abc\n"	

Raising errors

Exception declared by class

stub_request(:any, '').to_raise(StandardError)'', 'abc')    # ===> StandardError

or by exception instance

stub_request(:any, '').to_raise("some error"))

or by string

stub_request(:any, '').to_raise("some error")

Raising timeout errors

stub_request(:any, '').to_timeout'', 'abc')    # ===> RestClient::RequestTimeout	

Multiple responses for repeated requests

stub_request(:get, "").to_return({:body => "abc"}, {:body => "def"})
Net::HTTP.get('', '/')    # ===> "abc\n"
Net::HTTP.get('', '/')    # ===> "def\n"

#after all responses are used the last response will be returned infinitely

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

Multiple responses using chained to_return(), to_raise() or to_timeout declarations

stub_request(:get, "").
	to_return({:body => "abc"}).then.  #then() is just a syntactic sugar
	to_return({:body => "def"}).then.
Net::HTTP.get('', '/')    # ===> "abc\n"
Net::HTTP.get('', '/')    # ===> "def\n"
Net::HTTP.get('', '/')    # ===> MyException raised

Specifying number of times given response should be returned

stub_request(:get, "").
	to_return({:body => "abc"}).times(2).then.
	to_return({:body => "def"})

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

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

External requests can be disabled while allowing localhost

WebMock.disable_net_connect!(:allow_localhost => true)

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

Net::HTTP.get('localhost:9887', '/')      # ===> Allowed. Perhaps to Selenium?

External requests can be disabled while allowing any hostname

WebMock.disable_net_connect!(:allow => "")

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

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

Connecting on Net::HTTP.start

HTTP protocol has 3 steps: connect, request and response (or 4 with close). Most Ruby HTTP client libraries treat connect as a part of request step, with the exception of Net::HTTP which allows opening connection to the server separately to the request, by using Net::HTTP.start.

WebMock API was also designed with connect being part of request step, and it only allows stubbing requests, not connections. When Net::HTTP.start is called, WebMock doesn't know yet whether a request is stubbed or not. WebMock by default delays a connection until the request is invoked, so when there is no request, Net::HTTP.start doesn't do anything. This means that WebMock breaks the Net::HTTP behaviour by default!

To workaround this issue, WebMock offers :net_http_connect_on_start option, which can be passed to WebMock.allow_net_connect! and WebMock#disable_net_connect! methods, i.e.

WebMock.allow_net_connect!(:net_http_connect_on_start => true)

This forces WebMock Net::HTTP adapter to always connect on Net::HTTP.start.

Setting Expectations

Setting expectations in Test::Unit

require 'webmock/test_unit'

stub_request(:any, "")

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

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

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

assert_requested(:post, "", :times => 1) { |req| req.body == "abc" }

Expecting real (not stubbed) requests


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

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

Setting expectations in RSpec

This style is borrowed from fakeweb-matcher

require 'webmock/rspec'

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

WebMock.should_not have_requested(:get, "")

WebMock.should have_requested(:post, "").with { |req| req.body == "abc" }

WebMock.should have_requested(:get, "").with(:query => {"a" => ["b", "c"]}) 

WebMock.should have_requested(:get, "").
  with(:body => {"a" => ["b", "c"]}, :headers => 'Content-Type' => 'application/json')

Different way of setting expectations in RSpec

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

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

a_request(:any, "").should_not have_been_made

a_request(:post, "").with { |req| req.body == "abc" }.should have_been_made

a_request(:get, "").with(:query => {"a" => ["b", "c"]}).should have_been_made

a_request(:post, "").
  with(:body => {"a" => ["b", "c"]}, :headers => 'Content-Type' => 'application/json').should have_been_made

Clearing stubs and request history

If you want to reset all current stubs and history of requests use WebMock.reset!

stub_request(:any, "")

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


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

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

Matching requests

An executed request matches stubbed request if it passes following criteria:

When request URI matches stubbed request URI string or Regexp 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 specified
And request headers match stubbed request headers, or stubbed request headers match a subset of request headers, or stubbed request headers are not specified
And request matches provided block or block is not provided

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"

Matching URIs

WebMock will match all different representations of the same URI.

I.e all the following representations of the URI are equal:


The following URIs with basic authentication are also equal for WebMock


or these

" path/?a=my param&b=c"
" path/?a=my param&b=c"
" path/?a=my param&b=c"
" path/?a=my param&b=c"

If you provide Regexp to match URI, WebMock will try to match it against every valid form of the same url.

I.e /.*my param.*/ will match because it is equivalent of path

Matching headers

WebMock will match request headers against stubbed request headers in the following situations:

  1. Stubbed request has headers specified and request headers are the same as stubbed headers
    i.e stubbed headers: { 'Header1' => 'Value1', 'Header1' => 'Value1' }, requested: { 'Header1' => 'Value1', 'Header1' => 'Value1' }

  2. Stubbed request has headers specified and stubbed request headers are a subset of request headers
    i.e stubbed headers: { 'Header1' => 'Value1' }, requested: { 'Header1' => 'Value1', 'Header1' => 'Value1' }

  3. Stubbed request has no headers
    i.e stubbed headers: nil, requested: { 'Header1' => 'Value1', 'Header1' => 'Value1' }

WebMock normalises headers and treats all forms of same headers as equal: i.e the following two sets of headers are equal:

{ "Header1" => "value1", :content_length => 123, :X_CuStOm_hEAder => :value }

{ :header1 => "value1", "Content-Length" => 123, "x-cuSTOM-HeAder" => "value" }

Recording real requests and responses and replaying them later

To record your application's real HTTP interactions and replay them later in tests you can use VCR with WebMock.

Request callbacks

####WebMock can invoke callbacks stubbed or real requests:

WebMock.after_request do |request_signature, response|
  puts "Request #{request_signature} was made and #{response} was returned"

invoke callbacks for real requests only and except requests made with Patron

WebMock.after_request(:except => [:patron], :real_requests_only => true)  do |request_signature, response|
  puts "Request #{request_signature} was made and #{response} was returned"

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.


The initial lines of this project were written during New Bamboo Hack Day Thanks to my fellow Bambinos for all the great suggestions!

People who submitted patches and new features or suggested improvements. Many thanks to these people:

  • Ben Pickles
  • Mark Evans
  • Ivan Vega
  • Piotr Usewicz
  • Nick Plante
  • Nick Quaranto
  • Diego E. "Flameeyes" Pettenò
  • Niels Meersschaert
  • Mack Earnhardt
  • Arvicco
  • Sergio Gil
  • Jeffrey Jones
  • Tekin Suleyman
  • Tom Ward
  • Nadim Bitar
  • Myron Marston
  • Sam Phillips
  • Jose Angel Cortinas
  • Razic
  • Steve Tooke
  • Nathaniel Bibler
  • Martyn Loughran
  • Muness Alrubaie
  • Charles Li
  • Ryan Bigg
  • Pete Higgins
  • Hans de Graaff
  • Alastair Brunton


Thank you Fakeweb! This library was inspired by FakeWeb. I imported some solutions from that project to WebMock. 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 (c) 2009-2010 Bartosz Blimke. See LICENSE for details.