Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 390 lines (239 sloc) 12.986 kB
95e8298 Revert "WebMock module has to be included manually and is not include…
Bartosz Blimke authored
1 WebMock
2 =======
3
0016b13 Minor changes to README
Bartosz Blimke authored
4 Library for stubbing and setting expectations on HTTP requests in Ruby.
95e8298 Revert "WebMock module has to be included manually and is not include…
Bartosz Blimke authored
5
6 Features
7 --------
8
0016b13 Minor changes to README
Bartosz Blimke authored
9 * Stubbing HTTP requests at low http client lib level (no need to change tests when you change HTTP library)
95e8298 Revert "WebMock module has to be included manually and is not include…
Bartosz Blimke authored
10 * Setting and verifying expectations on HTTP requests
11 * Matching requests based on method, URI, headers and body
12 * Smart matching of the same URIs in different representations (also encoded and non encoded forms)
13 * Smart matching of the same headers in different representations.
14 * Support for Test::Unit and RSpec (and can be easily extended to other frameworks)
15 * Support for Net::HTTP and other http libraries based on Net::HTTP (i.e RightHttpConnection, rest-client, HTTParty)
32c653c Replaced google with example in README
Bartosz Blimke authored
16 * Support for HTTPClient library (both sync and async requests)
0016b13 Minor changes to README
Bartosz Blimke authored
17 * Easy to extend to other HTTP libraries
95e8298 Revert "WebMock module has to be included manually and is not include…
Bartosz Blimke authored
18
19 Installation
20 ------------
21
22 gem install webmock --source http://gemcutter.org
23
24 In your `test/test_helper.rb` add these two lines:
25
26 require 'webmock/test_unit'
27
28 include WebMock
29
30 or if you use RSpec add these lines to `spec/spec_helper`:
31
32 require 'webmock/rspec'
33
34 include WebMock
35
feb8ba5 Updated version to 0.7.3
Bartosz Blimke authored
36 You can also use WebMock without RSpec or Test::Unit support:
3ca443e WebMock module has to be included manually and is not included by RSp…
Bartosz Blimke authored
37
38 require 'webmock'
39
40 include WebMock
95e8298 Revert "WebMock module has to be included manually and is not include…
Bartosz Blimke authored
41
42 ## Examples
43
44
45
46 ## Stubbing
47
48
49 ### Stubbed request based on uri only and with the default response
50
32c653c Replaced google with example in README
Bartosz Blimke authored
51 stub_request(:any, "www.example.com")
95e8298 Revert "WebMock module has to be included manually and is not include…
Bartosz Blimke authored
52
32c653c Replaced google with example in README
Bartosz Blimke authored
53 Net::HTTP.get("www.example.com", "/") # ===> Success
95e8298 Revert "WebMock module has to be included manually and is not include…
Bartosz Blimke authored
54
55 ### Stubbing requests based on method, uri, body and headers
56
32c653c Replaced google with example in README
Bartosz Blimke authored
57 stub_request(:post, "www.example.com").with(:body => "abc", :headers => { 'Content-Length' => 3 })
95e8298 Revert "WebMock module has to be included manually and is not include…
Bartosz Blimke authored
58
32c653c Replaced google with example in README
Bartosz Blimke authored
59 uri = URI.parse("http://www.example.com/")
95e8298 Revert "WebMock module has to be included manually and is not include…
Bartosz Blimke authored
60 req = Net::HTTP::Post.new(uri.path)
61 req['Content-Length'] = 3
62 res = Net::HTTP.start(uri.host, uri.port) {|http|
63 http.request(req, "abc")
64 } # ===> Success
65
5313e02 Added version 0.9.0 features to CHANGELOG and README
Bartosz Blimke authored
66 ### Matching request body and headers against regular expressions
67
68 stub_request(:post, "www.example.com").
69 with(:body => /^.*world$/, :headers => {"Content-Type" => /image\/.+/}).to_return(:body => "abc")
70
71 uri = URI.parse('http://www.example.com/')
72 req = Net::HTTP::Post.new(uri.path)
73 req['Content-Type'] = 'image/png'
74 res = Net::HTTP.start(uri.host, uri.port) {|http|
75 http.request(req, 'hello world')
76 } # ===> Success
77
95e8298 Revert "WebMock module has to be included manually and is not include…
Bartosz Blimke authored
78 ### Matching custom request headers
79
0016b13 Minor changes to README
Bartosz Blimke authored
80 stub_request(:any, "www.example.com").with(:headers=>{ 'Header-Name' => 'Header-Value' })
95e8298 Revert "WebMock module has to be included manually and is not include…
Bartosz Blimke authored
81
32c653c Replaced google with example in README
Bartosz Blimke authored
82 uri = URI.parse('http://www.example.com/')
95e8298 Revert "WebMock module has to be included manually and is not include…
Bartosz Blimke authored
83 req = Net::HTTP::Post.new(uri.path)
84 req['Header-Name'] = 'Header-Value'
85 res = Net::HTTP.start(uri.host, uri.port) {|http|
86 http.request(req, 'abc')
87 } # ===> Success
88
5313e02 Added version 0.9.0 features to CHANGELOG and README
Bartosz Blimke authored
89 ### Matching requests against provided block
90
0016b13 Minor changes to README
Bartosz Blimke authored
91 stub_request(:post, "www.example.com").with { |request| request.body == "abc" }
92 RestClient.post('www.example.com', 'abc') # ===> Success
5313e02 Added version 0.9.0 features to CHANGELOG and README
Bartosz Blimke authored
93
94 ### Request with basic authentication
95
96 stub_request(:get, "user:pass@www.example.com")
97
98 Net::HTTP.start('www.example.com') {|http|
99 req = Net::HTTP::Get.new('/')
100 req.basic_auth 'user', 'pass'
101 http.request(req)
102 } # ===> Success
103
104 ### Matching uris using regular expressions
105
106 stub_request(:any, /.*example.*/)
107
108 Net::HTTP.get('www.example.com', '/') # ===> Success
109
95e8298 Revert "WebMock module has to be included manually and is not include…
Bartosz Blimke authored
110 ### Stubbing with custom response
111
32c653c Replaced google with example in README
Bartosz Blimke authored
112 stub_request(:any, "www.example.com").to_return(:body => "abc", :status => 200, :headers => { 'Content-Length' => 3 } )
95e8298 Revert "WebMock module has to be included manually and is not include…
Bartosz Blimke authored
113
32c653c Replaced google with example in README
Bartosz Blimke authored
114 Net::HTTP.get("www.example.com", '/') # ===> "abc"
95e8298 Revert "WebMock module has to be included manually and is not include…
Bartosz Blimke authored
115
0f3bb21 Updated README regarding dynamic responses
Bartosz Blimke authored
116 ### Response with body specified as IO object
95e8298 Revert "WebMock module has to be included manually and is not include…
Bartosz Blimke authored
117
118 File.open('/tmp/response_body.txt', 'w') { |f| f.puts 'abc' }
119
32c653c Replaced google with example in README
Bartosz Blimke authored
120 stub_request(:any, "www.example.com").to_return(:body => File.new('/tmp/response_body.txt'), :status => 200)
95e8298 Revert "WebMock module has to be included manually and is not include…
Bartosz Blimke authored
121
32c653c Replaced google with example in README
Bartosz Blimke authored
122 Net::HTTP.get('www.example.com', '/') # ===> "abc\n"
5313e02 Added version 0.9.0 features to CHANGELOG and README
Bartosz Blimke authored
123
3314aad Added support for status messages
Bartosz Blimke authored
124 ### Response with custom status message
125
126 stub_request(:any, "www.example.com").to_return(:status => [500, "Internal Server Error"])
127
128 req = Net::HTTP::Get.new("/")
129 Net::HTTP.start("www.example.com") { |http| http.request(req) }.message # ===> "Internal Server Error"
130
5313e02 Added version 0.9.0 features to CHANGELOG and README
Bartosz Blimke authored
131 ### Replaying raw responses recorded with `curl -is`
132
133 `curl -is www.example.com > /tmp/example_curl_-is_output.txt`
134 raw_response_file = File.new("/tmp/example_curl_-is_output.txt")
135
136 from file
137
138 stub_request(:get, "www.example.com").to_return(raw_response_file)
139
140 or string
141
142 stub_request(:get, "www.example.com").to_return(raw_response_file.read)
95e8298 Revert "WebMock module has to be included manually and is not include…
Bartosz Blimke authored
143
0f3bb21 Updated README regarding dynamic responses
Bartosz Blimke authored
144 ### Responses dynamically evaluated from block
145
4e0568a Added information about dynamic responses to README
Bartosz Blimke authored
146 stub_request(:any, 'www.example.net').
0f3bb21 Updated README regarding dynamic responses
Bartosz Blimke authored
147 to_return { |request| {:body => request.body} }
4e0568a Added information about dynamic responses to README
Bartosz Blimke authored
148
0f3bb21 Updated README regarding dynamic responses
Bartosz Blimke authored
149 RestClient.post('www.example.net', 'abc') # ===> "abc\n"
5b1c97b @tomafro Added complete dynamic request, where headers, body and status can al…
tomafro authored
150
0f3bb21 Updated README regarding dynamic responses
Bartosz Blimke authored
151 ### Responses dynamically evaluated from lambda
5b1c97b @tomafro Added complete dynamic request, where headers, body and status can al…
tomafro authored
152
153 stub_request(:any, 'www.example.net').
154 to_return(lambda { |request| {:body => request.body} })
155
156 RestClient.post('www.example.net', 'abc') # ===> "abc\n"
4e0568a Added information about dynamic responses to README
Bartosz Blimke authored
157
0f3bb21 Updated README regarding dynamic responses
Bartosz Blimke authored
158 ### Responses with dynamically evaluated parts
159
160 stub_request(:any, 'www.example.net').
161 to_return(:body => lambda { |request| request.body })
162
163 RestClient.post('www.example.net', 'abc') # ===> "abc\n"
164
5313e02 Added version 0.9.0 features to CHANGELOG and README
Bartosz Blimke authored
165 ### Multiple responses for repeated requests
95e8298 Revert "WebMock module has to be included manually and is not include…
Bartosz Blimke authored
166
5313e02 Added version 0.9.0 features to CHANGELOG and README
Bartosz Blimke authored
167 stub_request(:get, "www.example.com").to_return({:body => "abc"}, {:body => "def"})
168 Net::HTTP.get('www.example.com', '/') # ===> "abc\n"
169 Net::HTTP.get('www.example.com', '/') # ===> "def\n"
170
171 #after all responses are used the last response will be returned infinitely
172
173 Net::HTTP.get('www.example.com', '/') # ===> "def\n"
bb41263 Improved section about basic authentication support in readme.
Bartosz Blimke authored
174
5313e02 Added version 0.9.0 features to CHANGELOG and README
Bartosz Blimke authored
175 ### Multiple responses using chained `to_return()` or `to_raise()` declarations
95e8298 Revert "WebMock module has to be included manually and is not include…
Bartosz Blimke authored
176
5313e02 Added version 0.9.0 features to CHANGELOG and README
Bartosz Blimke authored
177 stub_request(:get, "www.example.com").
0f3bb21 Updated README regarding dynamic responses
Bartosz Blimke authored
178 to_return({:body => "abc"}).then. #then() is just a syntactic sugar
5313e02 Added version 0.9.0 features to CHANGELOG and README
Bartosz Blimke authored
179 to_return({:body => "def"}).then.
180 to_raise(MyException)
181 Net::HTTP.get('www.example.com', '/') # ===> "abc\n"
182 Net::HTTP.get('www.example.com', '/') # ===> "def\n"
183 Net::HTTP.get('www.example.com', '/') # ===> MyException raised
95e8298 Revert "WebMock module has to be included manually and is not include…
Bartosz Blimke authored
184
5313e02 Added version 0.9.0 features to CHANGELOG and README
Bartosz Blimke authored
185 ### Specifying number of times given response should be returned
186
187 stub_request(:get, "www.example.com").
188 to_return({:body => "abc"}).times(2).then.
189 to_return({:body => "def"})
190
191 Net::HTTP.get('www.example.com', '/') # ===> "abc\n"
192 Net::HTTP.get('www.example.com', '/') # ===> "abc\n"
193 Net::HTTP.get('www.example.com', '/') # ===> "def\n"
95e8298 Revert "WebMock module has to be included manually and is not include…
Bartosz Blimke authored
194
195
196 ### Real requests to network can be allowed or disabled
197
198 WebMock.allow_net_connect!
199
32c653c Replaced google with example in README
Bartosz Blimke authored
200 stub_request(:any, "www.example.com").to_return(:body => "abc")
95e8298 Revert "WebMock module has to be included manually and is not include…
Bartosz Blimke authored
201
32c653c Replaced google with example in README
Bartosz Blimke authored
202 Net::HTTP.get('www.example.com', '/') # ===> "abc"
95e8298 Revert "WebMock module has to be included manually and is not include…
Bartosz Blimke authored
203
204 Net::HTTP.get('www.something.com', '/') # ===> /.+Something.+/
205
206 WebMock.disable_net_connect!
207
208 Net::HTTP.get('www.something.com', '/') # ===> Failure
209
210
211 ## Setting Expectations
212
213 ### Setting expectations in Test::Unit
214 require 'webmock/test_unit'
215
32c653c Replaced google with example in README
Bartosz Blimke authored
216 stub_request(:any, "www.example.com")
95e8298 Revert "WebMock module has to be included manually and is not include…
Bartosz Blimke authored
217
32c653c Replaced google with example in README
Bartosz Blimke authored
218 uri = URI.parse('http://www.example.com/')
95e8298 Revert "WebMock module has to be included manually and is not include…
Bartosz Blimke authored
219 req = Net::HTTP::Post.new(uri.path)
220 req['Content-Length'] = 3
221 res = Net::HTTP.start(uri.host, uri.port) {|http|
222 http.request(req, 'abc')
223 }
224
32c653c Replaced google with example in README
Bartosz Blimke authored
225 assert_requested :post, "http://www.example.com",
95e8298 Revert "WebMock module has to be included manually and is not include…
Bartosz Blimke authored
226 :headers => {'Content-Length' => 3}, :body => "abc", :times => 1 # ===> Success
227
228 assert_not_requested :get, "http://www.something.com" # ===> Success
229
5313e02 Added version 0.9.0 features to CHANGELOG and README
Bartosz Blimke authored
230 assert_requested(:post, "http://www.example.com", :times => 1) { |req| req.body == "abc" }
231
95e8298 Revert "WebMock module has to be included manually and is not include…
Bartosz Blimke authored
232 ### Expecting real (not stubbed) requests
233
234 WebMock.allow_net_connect!
235
32c653c Replaced google with example in README
Bartosz Blimke authored
236 Net::HTTP.get('www.example.com', '/') # ===> Success
95e8298 Revert "WebMock module has to be included manually and is not include…
Bartosz Blimke authored
237
32c653c Replaced google with example in README
Bartosz Blimke authored
238 assert_requested :get, "http://www.example.com" # ===> Success
95e8298 Revert "WebMock module has to be included manually and is not include…
Bartosz Blimke authored
239
240
241 ### Setting expectations in RSpec
242 This style is borrowed from [fakeweb-matcher](http://github.com/freelancing-god/fakeweb-matcher)
243
244 require 'webmock/rspec'
245
32c653c Replaced google with example in README
Bartosz Blimke authored
246 WebMock.should have_requested(:get, "www.example.com").with(:body => "abc", :headers => {'Content-Length' => 3}).twice
95e8298 Revert "WebMock module has to be included manually and is not include…
Bartosz Blimke authored
247
248 WebMock.should_not have_requested(:get, "www.something.com")
5313e02 Added version 0.9.0 features to CHANGELOG and README
Bartosz Blimke authored
249
250 WebMock.should have_requested(:post, "www.example.com").with { |req| req.body == "abc" }
95e8298 Revert "WebMock module has to be included manually and is not include…
Bartosz Blimke authored
251
252 ### Different way of setting expectations in RSpec
253
32c653c Replaced google with example in README
Bartosz Blimke authored
254 request(:post, "www.example.com").with(:body => "abc", :headers => {'Content-Length' => 3}).should have_been_made.once
95e8298 Revert "WebMock module has to be included manually and is not include…
Bartosz Blimke authored
255
256 request(:post, "www.something.com").should have_been_made.times(3)
257
258 request(:any, "www.example.com").should_not have_been_made
259
5313e02 Added version 0.9.0 features to CHANGELOG and README
Bartosz Blimke authored
260 request(:post, "www.example.com").with { |req| req.body == "abc" }.should have_been_made
261
95e8298 Revert "WebMock module has to be included manually and is not include…
Bartosz Blimke authored
262 ## Clearing stubs and request history
263
264 If you want to reset all current stubs and history of requests use `WebMock.reset_webmock`
265
32c653c Replaced google with example in README
Bartosz Blimke authored
266 stub_request(:any, "www.example.com")
95e8298 Revert "WebMock module has to be included manually and is not include…
Bartosz Blimke authored
267
32c653c Replaced google with example in README
Bartosz Blimke authored
268 Net::HTTP.get('www.example.com', '/') # ===> Success
95e8298 Revert "WebMock module has to be included manually and is not include…
Bartosz Blimke authored
269
270 reset_webmock
271
32c653c Replaced google with example in README
Bartosz Blimke authored
272 Net::HTTP.get('www.example.com', '/') # ===> Failure
95e8298 Revert "WebMock module has to be included manually and is not include…
Bartosz Blimke authored
273
32c653c Replaced google with example in README
Bartosz Blimke authored
274 assert_not_requested :get, "www.example.com" # ===> Success
95e8298 Revert "WebMock module has to be included manually and is not include…
Bartosz Blimke authored
275
276
277 ## Matching requests
278
279 An executed request matches stubbed request if it passes following criteria:
280
4306efa Ability to register and expect requests with empty body.
Bartosz Blimke authored
281 When request URI matches stubbed request URI string or Regexp pattern<br/>
95e8298 Revert "WebMock module has to be included manually and is not include…
Bartosz Blimke authored
282 And request method is the same as stubbed request method or stubbed request method is :any<br/>
4306efa Ability to register and expect requests with empty body.
Bartosz Blimke authored
283 And request body is the same as stubbed request body or stubbed request body is not specified<br/>
0016b13 Minor changes to README
Bartosz Blimke authored
284 And request headers match stubbed request headers, or stubbed request headers match a subset of request headers, or stubbed request headers are not specified<br/>
285 And request matches provided block or block is not provided
95e8298 Revert "WebMock module has to be included manually and is not include…
Bartosz Blimke authored
286
287 ## Precedence of stubs
288
289 Always the last declared stub matching the request will be applied i.e:
290
32c653c Replaced google with example in README
Bartosz Blimke authored
291 stub_request(:get, "www.example.com").to_return(:body => "abc")
292 stub_request(:get, "www.example.com").to_return(:body => "def")
95e8298 Revert "WebMock module has to be included manually and is not include…
Bartosz Blimke authored
293
32c653c Replaced google with example in README
Bartosz Blimke authored
294 Net::HTTP.get('www.example.com', '/') # ====> "def"
95e8298 Revert "WebMock module has to be included manually and is not include…
Bartosz Blimke authored
295
296 ## Matching URIs
297
298 WebMock will match all different representations of the same URI.
299
300 I.e all the following representations of the URI are equal:
301
32c653c Replaced google with example in README
Bartosz Blimke authored
302 "www.example.com"
303 "www.example.com/"
304 "www.example.com:80"
305 "www.example.com:80/"
306 "http://www.example.com"
307 "http://www.example.com/"
308 "http://www.example.com:80"
309 "http://www.example.com:80/"
95e8298 Revert "WebMock module has to be included manually and is not include…
Bartosz Blimke authored
310
311 The following URIs with basic authentication are also equal for WebMock
312
32c653c Replaced google with example in README
Bartosz Blimke authored
313 "a b:pass@www.example.com"
314 "a b:pass@www.example.com/"
315 "a b:pass@www.example.com:80"
316 "a b:pass@www.example.com:80/"
317 "http://a b:pass@www.example.com"
318 "http://a b:pass@www.example.com/"
319 "http://a b:pass@www.example.com:80"
320 "http://a b:pass@www.example.com:80/"
321 "a%20b:pass@www.example.com"
322 "a%20b:pass@www.example.com/"
323 "a%20b:pass@www.example.com:80"
324 "a%20b:pass@www.example.com:80/"
325 "http://a%20b:pass@www.example.com"
326 "http://a%20b:pass@www.example.com/"
327 "http://a%20b:pass@www.example.com:80"
328 "http://a%20b:pass@www.example.com:80/"
95e8298 Revert "WebMock module has to be included manually and is not include…
Bartosz Blimke authored
329
330 or these
331
78414b7 Improved examples with equality of URIs with the same parameters
Bartosz Blimke authored
332 "www.example.com/my path/?a=my param&b=c"
333 "www.example.com/my%20path/?a=my%20param&b=c"
334 "www.example.com:80/my path/?a=my param&b=c"
335 "www.example.com:80/my%20path/?a=my%20param&b=c"
336 "http://www.example.com/my path/?a=my param&b=c"
337 "http://www.example.com/my%20path/?a=my%20param&b=c"
338 "http://www.example.com:80/my path/?a=my param&b=c"
339 "http://www.example.com:80/my%20path/?a=my%20param&b=c"
95e8298 Revert "WebMock module has to be included manually and is not include…
Bartosz Blimke authored
340
341
342 If you provide Regexp to match URI, WebMock will try to match it against every valid form of the same url.
343
78414b7 Improved examples with equality of URIs with the same parameters
Bartosz Blimke authored
344 I.e `/.*my param.*/` will match `www.example.com/my%20path` because it is equivalent of `www.example.com/my path`
95e8298 Revert "WebMock module has to be included manually and is not include…
Bartosz Blimke authored
345
346
347 ## Matching headers
348
349 WebMock will match request headers against stubbed request headers in the following situations:
350
351 1. Stubbed request has headers specified and request headers are the same as stubbed headers <br/>
352 i.e stubbed headers: `{ 'Header1' => 'Value1', 'Header1' => 'Value1' }`, requested: `{ 'Header1' => 'Value1', 'Header1' => 'Value1' }`
353
354 2. Stubbed request has headers specified and stubbed request headers are a subset of request headers <br/>
355 i.e stubbed headers: `{ 'Header1' => 'Value1' }`, requested: `{ 'Header1' => 'Value1', 'Header1' => 'Value1' }`
356
357 3. Stubbed request has no headers <br/>
358 i.e stubbed headers: `nil`, requested: `{ 'Header1' => 'Value1', 'Header1' => 'Value1' }`
359
360 WebMock normalises headers and treats all forms of same headers as equal:
361 i.e the following two sets of headers are equal:
362
363 `{ "Header1" => "value1", :content_length => 123, :X_CuStOm_hEAder => :value }`
364
365 `{ :header1 => "value1", "Content-Length" => 123, "x-cuSTOM-HeAder" => "value" }`
366
367
368 ## Bugs and Issues
369
370 Please submit them here [http://github.com/bblimke/webmock/issues](http://github.com/bblimke/webmock/issues)
371
372 ## Suggestions
373
374 If you have any suggestions on how to improve WebMock please send an email to the mailing list [groups.google.com/group/webmock-users](http://groups.google.com/group/webmock-users)
375
376 I'm particularly interested in how the DSL could be improved.
377
378 ## Credits
379
380 Thanks to my fellow [Bambinos](http://new-bamboo.co.uk/) for all the great suggestions!
381
382 Thank you Fakeweb! This library was inspired by [FakeWeb](fakeweb.rubyforge.org).
383 I took couple of solutions from that project. I also copied some code i.e Net:HTTP adapter.
384 Fakeweb architecture unfortunately didn't allow me to extend it easily with the features I needed.
385 I also preferred some things to work differently i.e request stub precedence.
386
387 ## Copyright
388
0016b13 Minor changes to README
Bartosz Blimke authored
389 Copyright 2009-2010 Bartosz Blimke. See LICENSE for details.
Something went wrong with that request. Please try again.