Library for stubbing and setting expectations on HTTP requests in Ruby.
gem install webmock
or alternatively:
# add to your Gemfile
group :test do
gem "webmock"
end
git clone http://github.com/bblimke/webmock.git
cd webmock
rake install
WebMock 2.x has changed somewhat since version 1.x. Changes are listed in CHANGELOG.md
Create a file features/support/webmock.rb with the following contents:
require 'webmock/cucumber'
Add the following code to test/test_helper:
require 'webmock/minitest'
Add the following code to spec/spec_helper:
require 'webmock/rspec'
Add the following code to test/test_helper.rb
require 'webmock/test_unit'
You can also use WebMock outside a test framework:
require 'webmock'
include WebMock::API
WebMock.enable!
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) do |http|
http.request(req, "abc")
end # ===> 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) do |http|
http.request(req, 'hello world')
end # ===> Success
stub_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(:post, "www.example.com").
with(body: hash_including({data: {a: '1', b: 'five'}}))
RestClient.post('www.example.com', "data[a]=1&data[b]=five&x=1",
:content_type => 'application/x-www-form-urlencoded') # ===> 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) do |http|
http.request(req, 'abc')
end # ===> Success
stub_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, "www.example.com").with(basic_auth: ['user', 'pass'])
# or
# stub_request(:get, "www.example.com").
# with(headers: {'Authorization' => "Basic #{ Base64.strict_encode64('user:pass').chomp}"})
Net::HTTP.start('www.example.com') do |http|
req = Net::HTTP::Get.new('/')
req.basic_auth 'user', 'pass'
http.request(req)
end # ===> Success
stub_request(:get, "user:pass@www.example.com") does not match a request with credentials provided in the Authorization header.stub_request(:get, "user:pass@www.example.com")
RestClient.get('user:pass@www.example.com') # ===> Success
stub_request(:any, /example/)
Net::HTTP.get('www.example.com', '/') # ===> Success
stub_request(:any, ->(uri) { true })
uri_template = Addressable::Template.new "www.example.com/{id}/"
stub_request(:any, uri_template)
Net::HTTP.get('www.example.com', '/webmock/') # ===> Success
uri_template =
Addressable::Template.new "www.example.com/thing/{id}.json{?x,y,z}{&other*}"
stub_request(:any, uri_template)
Net::HTTP.get('www.example.com',
'/thing/5.json?x=1&y=2&z=3&anyParam=4') # ===> Success
stub_request(:get, "www.example.com").with(query: {"a" => ["b", "c"]})
RestClient.get("http://www.example.com/?a[]=b&a[]=c") # ===> Success
stub_request(:get, "www.example.com").
with(query: hash_including({"a" => ["b", "c"]}))
RestClient.get("http://www.example.com/?a[]=b&a[]=c&x=1") # ===> Success
stub_request(:get, "www.example.com").
with(query: hash_excluding({"a" => "b"}))
RestClient.get("http://www.example.com/?a=b") # ===> Failure
RestClient.get("http://www.example.com/?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"
Set appropriate Content-Type for HTTParty's parsed_response.
stub_request(:any, "www.example.com").to_return body: '{}', headers: {content_type: 'application/json'}
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_json(body: {foo: "bar"})
Net::HTTP.get('www.example.com', '/') # ===> "{\"foo\": \"bar\"}"
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 -iscurl -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 -iscurl -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"
class MyRackApp
def self.call(env)
[200, {}, ["Hello"]]
end
end
stub_request(:get, "www.example.com").to_rack(MyRackApp)
RestClient.post('www.example.com') # ===> "Hello"
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"
to_return(), to_raise() or to_timeout declarationsstub_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"
stub_get = stub_request(:get, "www.example.com")
remove_request_stub(stub_get)
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?
Allowed requests can be specified in a number of ways.
With a String specifying a host name:
WebMock.disable_net_connect!(allow: 'www.example.org')
RestClient.get('www.something.com', '/') # ===> Failure
RestClient.get('www.example.org', '/') # ===> Allowed
RestClient.get('www.example.org:8080', '/') # ===> Allowed
With a String specifying a host name and a port:
WebMock.disable_net_connect!(allow: 'www.example.org:8080')
RestClient.get('www.something.com', '/') # ===> Failure
RestClient.get('www.example.org', '/') # ===> Failure
RestClient.get('www.example.org:8080', '/') # ===> Allowed
With a Regexp matching the URI:
WebMock.disable_net_connect!(allow: %r{ample\.org/foo})
RestClient.get('www.example.org', '/foo/bar') # ===> Allowed
RestClient.get('sample.org', '/foo') # ===> Allowed
RestClient.get('sample.org', '/bar') # ===> Failure
With an object that responds to #call, receiving a URI object and returning a boolean:
denylist = ['google.com', 'facebook.com', 'apple.com']
allowed_sites = lambda{|uri|
denylist.none?{|site| uri.host.include?(site) }
}
WebMock.disable_net_connect!(allow: allowed_sites)
RestClient.get('www.example.org', '/') # ===> Allowed
RestClient.get('www.facebook.com', '/') # ===> Failure
RestClient.get('apple.com', '/') # ===> Failure
With an Array of any of the above:
WebMock.disable_net_connect!(allow: [
lambda{|uri| uri.host.length % 2 == 0 },
/ample.org/,
'bbc.co.uk',
])
RestClient.get('www.example.org', '/') # ===> Allowed
RestClient.get('bbc.co.uk', '/') # ===> Allowed
RestClient.get('bbc.com', '/') # ===> Allowed
RestClient.get('www.bbc.com', '/') # ===> Failure
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. At the time of connection being made there is no information about the request or URL yet, therefore WebMock is not able to decide whether to stub a request or not and all connections are allowed. To enable connections only to a specific domain (e.g. your test server) use:
WebMock.allow_net_connect!(net_http_connect_on_start: "www.example.com")
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) do |http|
http.request(req, 'abc')
end
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
stub_get = stub_request(:get, "www.example.com")
stub_post = stub_request(:post, "www.example.com")
Net::HTTP.get('www.example.com', '/')
assert_requested(stub_get)
assert_not_requested(stub_post)
WebMock moduleThis style is borrowed from fakeweb-matcher
require 'webmock/rspec'
expect(WebMock).to have_requested(:get, "www.example.com").
with(body: "abc", headers: {'Content-Length' => 3}).twice
expect(WebMock).not_to have_requested(:get, "www.something.com")
expect(WebMock).to have_requested(:post, "www.example.com").
with { |req| req.body == "abc" }
# Note that the block with `do ... end` instead of curly brackets won't work!
# Why? See this comment https://github.com/bblimke/webmock/issues/174#issuecomment-34908908
expect(WebMock).to have_requested(:get, "www.example.com").
with(query: {"a" => ["b", "c"]})
expect(WebMock).to have_requested(:get, "www.example.com").
with(query: hash_including({"a" => ["b", "c"]}))
expect(WebMock).to have_requested(:get, "www.example.com").
with(body: {"a" => ["b", "c"]},
headers: {'Content-Type' => 'application/json'})
a_requestexpect(a_request(:post, "www.example.com").
with(body: "abc", headers: {'Content-Length' => 3})).
to have_been_made.once
expect(a_request(:post, "www.something.com")).to have_been_made.times(3)
expect(a_request(:post, "www.something.com")).to have_been_made.at_least_once
expect(a_request(:post, "www.something.com")).
to have_been_made.at_least_times(3)
expect(a_request(:post, "www.something.com")).to have_been_made.at_most_twice
expect(a_request(:post, "www.something.com")).to have_been_made.at_most_times(3)
expect(a_request(:any, "www.example.com")).not_to have_been_made
expect(a_request(:post, "www.example.com").with { |req| req.body == "abc" }).
to have_been_made
expect(a_request(:get, "www.example.com").with(query: {"a" => ["b", "c"]})).
to have_been_made
expect(a_request(:get, "www.example.com").
with(query: hash_including({"a" => ["b", "c"]}))).to have_been_made
expect(a_request(:post, "www.example.com").
with(body: {"a" => ["b", "c"]},
headers: {'Content-Type' => 'application/json'})).to have_been_made
stub = stub_request(:get, "www.example.com")
# ... make requests ...
expect(stub).to have_been_requested
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
If you want to reset only the counters of the executed requests use WebMock.reset_executed_requests!
stub = stub_request(:get, "www.example.com")
stub2 = stub_request(:get, "www.example2.com")
Net::HTTP.get('www.example.com', '/')
Net::HTTP.get('www.example.com', '/')
Net::HTTP.get('www.example2.com', '/')
expect(stub).to have_been_requested.times(2)
expect(stub2).to have_been_requested.times(1)
WebMock.reset_executed_requests!
expect(stub).not_to have_been_requested
expect(stub2).not_to have_been_requested
# Disable WebMock (all adapters)
WebMock.disable!
# Disable WebMock for all libs except Net::HTTP
WebMock.disable!(except: [:net_http])
# Enable WebMock (all adapters)
WebMock.enable!
# Enable WebMock for all libs except Patron
WebMock.enable!(except: [:patron])
An executed request matches stubbed request if it passes following criteria:
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 userinfo are also equal for WebMock
"a b:pass@www.example.com"
"a b:pass@www.example.com/"
"a b:pass@www.example.com:80"
"a b:pass@www.example.com:80/"
"http://a b:pass@www.example.com"
"http://a b:pass@www.example.com/"
"http://a b:pass@www.example.com:80"
"http://a b:pass@www.example.com:80/"
"a%20b:pass@www.example.com"
"a%20b:pass@www.example.com/"
"a%20b:pass@www.example.com:80"
"a%20b:pass@www.example.com:80/"
"http://a%20b:pass@www.example.com"
"http://a%20b:pass@www.example.com/"
"http://a%20b:pass@www.example.com:80"
"http://a%20b:pass@www.example.com: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 path/ will match www.example.com/my%20path because it is equivalent of www.example.com/my path
If you use Addressable::Template for matching, then WebMock will defer the matching rules to Addressable, which complies with RFC 6570.
If you use any of the WebMock methods for matching query params, then Addressable will be used to match the base URI and WebMock will match the query params. If you do not, then WebMock will let Addressable match the full URI.
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', 'Header2' => 'Value2' }, requested: { 'Header1' => 'Value1', 'Header2' => 'Value2' }
Stubbed request has headers specified and stubbed request headers are a subset of request headers
i.e stubbed headers: { 'Header1' => 'Value1' }, requested: { 'Header1' => 'Value1', 'Header2' => 'Value2' }
Stubbed request has no headers
i.e stubbed headers: nil, requested: { 'Header1' => 'Value1', 'Header2' => 'Value2' }
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.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 |req_signature, response|
puts "Request #{req_signature} was made and #{response} was returned"
end
Please submit them here http://github.com/bblimke/webmock/issues
You can contribute by triaging issues which may include reproducing bug reports or asking for vital information, such as version numbers or reproduction instructions. If you would like to start triaging issues, one easy way to get started is to subscribe to webmock on CodeTriage.
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.
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:
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.
FAQs
Unknown package
We found that webmock demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.
Research
Security News
A threat actor's playbook for exploiting the npm ecosystem was exposed on the dark web, detailing how to build a blockchain-powered botnet.
Security News
NVD’s backlog surpasses 20,000 CVEs as analysis slows and NIST announces new system updates to address ongoing delays.