Library for stubbing and setting expectations on HTTP requests in Ruby.
I'm not able to maintain WebMock until end of June 2011. If anyone is interested in maintaining it in the meantime (at least handling pull requests and creating patch releases), please get in touch.
- 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
- Net::HTTP and libraries based on Net::HTTP (i.e RightHttpConnection, REST Client, HTTParty)
- HTTPClient
- Patron
- EM-HTTP-Request
- Curb (currently only Curb::Easy)
##Installation
gem install webmock --source http://gemcutter.org
git clone http://github.com/bblimke/webmock.git
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
stub_request(:any, "www.example.com")
Net::HTTP.get("www.example.com", "/") # ===> Success
stub_request(:post, "www.example.com").with(:body => "abc", :headers => { 'Content-Length' => 3 })
uri = URI.parse("http://www.example.com/")
req = Net::HTTP::Post.new(uri.path)
req['Content-Length'] = 3
res = Net::HTTP.start(uri.host, uri.port) {|http|
http.request(req, "abc")
} # ===> Success
stub_request(:post, "www.example.com").
with(:body => /^.*world$/, :headers => {"Content-Type" => /image\/.+/}).to_return(:body => "abc")
uri = URI.parse('http://www.example.com/')
req = Net::HTTP::Post.new(uri.path)
req['Content-Type'] = 'image/png'
res = Net::HTTP.start(uri.host, uri.port) {|http|
http.request(req, 'hello world')
} # ===> Success
stub_http_request(:post, "www.example.com").
with(:body => {:data => {:a => '1', :b => 'five'}})
RestClient.post('www.example.com', "data[a]=1&data[b]=five",
:content_type => 'application/x-www-form-urlencoded') # ===> Success
RestClient.post('www.example.com', '{"data":{"a":"1","b":"five"}}',
:content_type => 'application/json') # ===> Success
RestClient.post('www.example.com', '<data a="1" b="five" />',
:content_type => 'application/xml' ) # ===> Success
stub_request(:any, "www.example.com").with(:headers=>{ 'Header-Name' => 'Header-Value' })
uri = URI.parse('http://www.example.com/')
req = Net::HTTP::Post.new(uri.path)
req['Header-Name'] = 'Header-Value'
res = Net::HTTP.start(uri.host, uri.port) {|http|
http.request(req, 'abc')
} # ===> Success
stub_http_request(:get, 'www.example.com').with(:headers => {'Accept' => ['image/jpeg', 'image/png'] })
req = Net::HTTP::Get.new("/")
req['Accept'] = ['image/png']
req.add_field('Accept', 'image/jpeg')
Net::HTTP.start("www.example.com") {|http| http.request(req) } # ===> Success
stub_request(:post, "www.example.com").with { |request| request.body == "abc" }
RestClient.post('www.example.com', 'abc') # ===> Success
stub_request(:get, "user:[email protected]")
Net::HTTP.start('www.example.com') {|http|
req = Net::HTTP::Get.new('/')
req.basic_auth 'user', 'pass'
http.request(req)
} # ===> Success
stub_request(:any, /.*example.*/)
Net::HTTP.get('www.example.com', '/') # ===> Success
stub_http_request(:get, "www.example.com").with(:query => {"a" => ["b", "c"]})
RestClient.get("http://www.example.com/?a[]=b&a[]=c") # ===> Success
stub_request(:any, "www.example.com").to_return(:body => "abc", :status => 200, :headers => { 'Content-Length' => 3 } )
Net::HTTP.get("www.example.com", '/') # ===> "abc"
File.open('/tmp/response_body.txt', 'w') { |f| f.puts 'abc' }
stub_request(:any, "www.example.com").to_return(:body => File.new('/tmp/response_body.txt'), :status => 200)
Net::HTTP.get('www.example.com', '/') # ===> "abc\n"
stub_request(:any, "www.example.com").to_return(:status => [500, "Internal Server Error"])
req = Net::HTTP::Get.new("/")
Net::HTTP.start("www.example.com") { |http| http.request(req) }.message # ===> "Internal Server Error"
`curl -is www.example.com > /tmp/example_curl_-is_output.txt`
raw_response_file = File.new("/tmp/example_curl_-is_output.txt")
from file
stub_request(:get, "www.example.com").to_return(raw_response_file)
or string
stub_request(:get, "www.example.com").to_return(raw_response_file.read)
stub_request(:any, 'www.example.net').
to_return { |request| {:body => request.body} }
RestClient.post('www.example.net', 'abc') # ===> "abc\n"
stub_request(:any, 'www.example.net').
to_return(lambda { |request| {:body => request.body} })
RestClient.post('www.example.net', 'abc') # ===> "abc\n"
`curl -is www.example.com > /tmp/www.example.com.txt`
stub_request(:get, "www.example.com").to_return(lambda { |request| File.new("/tmp/#{request.uri.host.to_s}.txt" }))
stub_request(:any, 'www.example.net').
to_return(:body => lambda { |request| request.body })
RestClient.post('www.example.net', 'abc') # ===> "abc\n"
stub_request(:any, 'www.example.net').to_raise(StandardError)
RestClient.post('www.example.net', 'abc') # ===> StandardError
stub_request(:any, 'www.example.net').to_raise(StandardError.new("some error"))
stub_request(:any, 'www.example.net').to_raise("some error")
stub_request(:any, 'www.example.net').to_timeout
RestClient.post('www.example.net', 'abc') # ===> RestClient::RequestTimeout
stub_request(:get, "www.example.com").to_return({:body => "abc"}, {:body => "def"})
Net::HTTP.get('www.example.com', '/') # ===> "abc\n"
Net::HTTP.get('www.example.com', '/') # ===> "def\n"
#after all responses are used the last response will be returned infinitely
Net::HTTP.get('www.example.com', '/') # ===> "def\n"
stub_request(:get, "www.example.com").
to_return({:body => "abc"}).then. #then() is just a syntactic sugar
to_return({:body => "def"}).then.
to_raise(MyException)
Net::HTTP.get('www.example.com', '/') # ===> "abc\n"
Net::HTTP.get('www.example.com', '/') # ===> "def\n"
Net::HTTP.get('www.example.com', '/') # ===> MyException raised
stub_request(:get, "www.example.com").
to_return({:body => "abc"}).times(2).then.
to_return({:body => "def"})
Net::HTTP.get('www.example.com', '/') # ===> "abc\n"
Net::HTTP.get('www.example.com', '/') # ===> "abc\n"
Net::HTTP.get('www.example.com', '/') # ===> "def\n"
WebMock.allow_net_connect!
stub_request(:any, "www.example.com").to_return(:body => "abc")
Net::HTTP.get('www.example.com', '/') # ===> "abc"
Net::HTTP.get('www.something.com', '/') # ===> /.+Something.+/
WebMock.disable_net_connect!
Net::HTTP.get('www.something.com', '/') # ===> Failure
WebMock.disable_net_connect!(:allow_localhost => true)
Net::HTTP.get('www.something.com', '/') # ===> Failure
Net::HTTP.get('localhost:9887', '/') # ===> Allowed. Perhaps to Selenium?
WebMock.disable_net_connect!(:allow => "www.example.org")
Net::HTTP.get('www.something.com', '/') # ===> Failure
Net::HTTP.get('www.example.org', '/') # ===> Allowed.
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
.
require 'webmock/test_unit'
stub_request(:any, "www.example.com")
uri = URI.parse('http://www.example.com/')
req = Net::HTTP::Post.new(uri.path)
req['Content-Length'] = 3
res = Net::HTTP.start(uri.host, uri.port) {|http|
http.request(req, 'abc')
}
assert_requested :post, "http://www.example.com",
:headers => {'Content-Length' => 3}, :body => "abc", :times => 1 # ===> Success
assert_not_requested :get, "http://www.something.com" # ===> Success
assert_requested(:post, "http://www.example.com", :times => 1) { |req| req.body == "abc" }
WebMock.allow_net_connect!
Net::HTTP.get('www.example.com', '/') # ===> Success
assert_requested :get, "http://www.example.com" # ===> Success
This style is borrowed from fakeweb-matcher
require 'webmock/rspec'
WebMock.should have_requested(:get, "www.example.com").with(:body => "abc", :headers => {'Content-Length' => 3}).twice
WebMock.should_not have_requested(:get, "www.something.com")
WebMock.should have_requested(:post, "www.example.com").with { |req| req.body == "abc" }
WebMock.should have_requested(:get, "www.example.com").with(:query => {"a" => ["b", "c"]})
WebMock.should have_requested(:get, "www.example.com").
with(:body => {"a" => ["b", "c"]}, :headers => {'Content-Type' => 'application/json'})
a_request(:post, "www.example.com").with(:body => "abc", :headers => {'Content-Length' => 3}).should have_been_made.once
a_request(:post, "www.something.com").should have_been_made.times(3)
a_request(:any, "www.example.com").should_not have_been_made
a_request(:post, "www.example.com").with { |req| req.body == "abc" }.should have_been_made
a_request(:get, "www.example.com").with(:query => {"a" => ["b", "c"]}).should have_been_made
a_request(:post, "www.example.com").
with(:body => {"a" => ["b", "c"]}, :headers => {'Content-Type' => 'application/json'}).should have_been_made
If you want to reset all current stubs and history of requests use WebMock.reset!
stub_request(:any, "www.example.com")
Net::HTTP.get('www.example.com', '/') # ===> Success
WebMock.reset!
Net::HTTP.get('www.example.com', '/') # ===> Failure
assert_not_requested :get, "www.example.com" # ===> Success
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
Always the last declared stub matching the request will be applied i.e:
stub_request(:get, "www.example.com").to_return(:body => "abc")
stub_request(:get, "www.example.com").to_return(:body => "def")
Net::HTTP.get('www.example.com', '/') # ====> "def"
WebMock will match all different representations of the same URI.
I.e all the following representations of the URI are equal:
"www.example.com"
"www.example.com/"
"www.example.com:80"
"www.example.com:80/"
"http://www.example.com"
"http://www.example.com/"
"http://www.example.com:80"
"http://www.example.com:80/"
The following URIs with basic authentication are also equal for WebMock
"a b:[email protected]"
"a b:[email protected]/"
"a b:[email protected]:80"
"a b:[email protected]:80/"
"http://a b:[email protected]"
"http://a b:[email protected]/"
"http://a b:[email protected]:80"
"http://a b:[email protected]:80/"
"a%20b:[email protected]"
"a%20b:[email protected]/"
"a%20b:[email protected]:80"
"a%20b:[email protected]:80/"
"http://a%20b:[email protected]"
"http://a%20b:[email protected]/"
"http://a%20b:[email protected]:80"
"http://a%20b:[email protected]:80/"
or these
"www.example.com/my path/?a=my param&b=c"
"www.example.com/my%20path/?a=my%20param&b=c"
"www.example.com:80/my path/?a=my param&b=c"
"www.example.com:80/my%20path/?a=my%20param&b=c"
"http://www.example.com/my path/?a=my param&b=c"
"http://www.example.com/my%20path/?a=my%20param&b=c"
"http://www.example.com:80/my path/?a=my param&b=c"
"http://www.example.com:80/my%20path/?a=my%20param&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 www.example.com/my%20path
because it is equivalent of www.example.com/my path
WebMock will match request headers against stubbed request headers in the following situations:
-
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' }
-
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' }
-
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" }
To record your application's real HTTP interactions and replay them later in tests you can use VCR with WebMock.
####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"
end
WebMock.after_request(:except => [:patron], :real_requests_only => true) do |request_signature, response|
puts "Request #{request_signature} was made and #{response} was returned"
end
Please submit them here http://github.com/bblimke/webmock/issues
If you have any suggestions on how to improve WebMock please send an email to the mailing list groups.google.com/group/webmock-users
I'm particularly interested in how the DSL could be improved.
In order to work on Webmock you first need to fork and clone the repo. Please do any work on a dedicated branch and rebase against master before sending a pull request.
We use RVM in order to test WebMock against 1.8.6, REE, 1.8.7, 1.9.2 and
jRuby. You can get RVM setup for WebMock development using the
following commands (if you don't have these version of Ruby installed
use rvm install
to install each of them).
rvm use --create 1.8.6@webmock
gem install jeweler bundler
bundle install
rvm use --create ree@webmock
gem install jeweler bundler
bundle install
rvm use --create 1.8.7@webmock
gem install jeweler bundler
bundle install
rvm use --create 1.9.2@webmock
gem install jeweler bundler
bundle install
rvm use --create jruby@webmock
gem install jeweler bundler
bundle install
These commands will create a gemset named WebMock for each of the
supported versions of Ruby and bundle install
all dependencies.
With the supported versions of Ruby installed RVM will run specs across all version with just one command.
bundle exec rvm 1.8.6@webmock,ree@webmock,1.8.7@webmock,1.9.2@webmock,jruby@webmock rspec spec/**/*_spec.rb
This command is wrapped up in to a rake task and can be invoked like so:
rake spec:rubies
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
- Sam Stokes
- Eugene Bolshakov
For a full list of contributors you can visit the contributors page.
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.