Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 204 lines (134 sloc) 7.693 kB
02e3a0d @chrisk Copy the examples to the README, since a few rdoc renderers don't see…
authored
1 = FakeWeb
7a1a3d5 @blaine Initial Import
blaine authored
2
1f6d378 @chrisk Lots of README cleanup: add installation section, remove OpenURI exam…
authored
3 FakeWeb is a helper for faking web requests in Ruby. It works at a global
4 level, without modifying code or writing extensive stubs.
5
442597c @chrisk Add links to the new Google Group, instead of the Lighthouse project
authored
6
82f5c4e @chrisk Play with rdoc header levels a bit
authored
7 == Installation
1f6d378 @chrisk Lots of README cleanup: add installation section, remove OpenURI exam…
authored
8
dfe50fe @chrisk Add Bundler/RubyGems installation instructions
authored
9 * You can install the latest release from RubyGems:
7a1a3d5 @blaine Initial Import
blaine authored
10
dfe50fe @chrisk Add Bundler/RubyGems installation instructions
authored
11 gem install fakeweb
12
13 Note that the gem was previously registered as +FakeWeb+, switching
14 to +fakeweb+ in 2009. All releases are available under the new name.
15
16 * If your application uses Bundler, add a line like this to your Gemfile:
17
18 gem "fakeweb", "~> 1.3"
19
20 You may want to specify <tt>:group => :test</tt> and/or
21 <tt>:require => false</tt>, depending on how you use Bundler.
22
23 * If you're developing a gem, add a line like this to your gemspec:
24
25 spec.add_development_dependency "fakeweb", ["~> 1.3"]
3a143bc @chrisk Add note to README about gems named "FakeWeb" vs. "fakeweb"
authored
26
442597c @chrisk Add links to the new Google Group, instead of the Lighthouse project
authored
27
28 == Help and discussion
29
7365a38 @chrisk Prepare docs for 1.2.0 release
authored
30 RDocs for the current release are available at http://fakeweb.rubyforge.org.
442597c @chrisk Add links to the new Google Group, instead of the Lighthouse project
authored
31
7365a38 @chrisk Prepare docs for 1.2.0 release
authored
32 There's a mailing list for questions and discussion at
6442d5d @chrisk Update a few links in docs, the gemspec, etc.
authored
33 https://groups.google.com/d/forum/fakeweb-users.
6b0bdf9 @chrisk Add link to the ticket on Lighthouse for discussing some API changes
authored
34
6442d5d @chrisk Update a few links in docs, the gemspec, etc.
authored
35 The main source repository is https://github.com/chrisk/fakeweb.
4cbafc5 @chrisk Pushing the README, hoping it will render as rdoc again
authored
36
7f40f29 @chrisk Fix image alignment in README using proper CSS
authored
37 {<img src="https://travis-ci.org/chrisk/fakeweb.png?branch=master" alt="Build Status" style="vertical-align: text-top" />}[https://travis-ci.org/chrisk/fakeweb] FakeWeb's tests run at https://travis-ci.org/chrisk/fakeweb.
4ab05d6 @chrisk Add the Travis CI build status badge to the README
authored
38
82f5c4e @chrisk Play with rdoc header levels a bit
authored
39 == Examples
02e3a0d @chrisk Copy the examples to the README, since a few rdoc renderers don't see…
authored
40
e8aed07 @chrisk Add new README sections: how to require the library, and FakeWeb.allo…
authored
41 Start by requiring FakeWeb:
42
7365a38 @chrisk Prepare docs for 1.2.0 release
authored
43 require 'fakeweb'
e8aed07 @chrisk Add new README sections: how to require the library, and FakeWeb.allo…
authored
44
82f5c4e @chrisk Play with rdoc header levels a bit
authored
45 === Registering basic string responses
571854b @chrisk Make README a little friendlier by splitting up examples
authored
46
92075e0 @chrisk Deprecate FakeWeb.register_uri's :string and :file options in favor o…
authored
47 FakeWeb.register_uri(:get, "http://example.com/test1", :body => "Hello World!")
571854b @chrisk Make README a little friendlier by splitting up examples
authored
48
26b7c6c @chrisk Update the README to reflect new HTTP method support
authored
49 Net::HTTP.get(URI.parse("http://example.com/test1"))
571854b @chrisk Make README a little friendlier by splitting up examples
authored
50 => "Hello World!"
51
26b7c6c @chrisk Update the README to reflect new HTTP method support
authored
52 Net::HTTP.get(URI.parse("http://example.com/test2"))
571854b @chrisk Make README a little friendlier by splitting up examples
authored
53 => FakeWeb is bypassed and the response from a real request is returned
54
16d74d3 @chrisk Further doc updates for regex support; remove repetitive section in R…
authored
55 You can also call <tt>register_uri</tt> with a regular expression, to match
56 more than one URI.
57
49bcdf8 @chrisk Escape a period in a regex in the README for clarity
authored
58 FakeWeb.register_uri(:get, %r|http://example\.com/|, :body => "Hello World!")
d6076cf @akahn Add regular expression example to README.
akahn authored
59
60 Net::HTTP.get(URI.parse("http://example.com/test3"))
61 => "Hello World!"
62
82f5c4e @chrisk Play with rdoc header levels a bit
authored
63 === Replaying a recorded response
571854b @chrisk Make README a little friendlier by splitting up examples
authored
64
65 page = `curl -is http://www.google.com/`
26b7c6c @chrisk Update the README to reflect new HTTP method support
authored
66 FakeWeb.register_uri(:get, "http://www.google.com/", :response => page)
571854b @chrisk Make README a little friendlier by splitting up examples
authored
67
26b7c6c @chrisk Update the README to reflect new HTTP method support
authored
68 Net::HTTP.get(URI.parse("http://www.google.com/"))
571854b @chrisk Make README a little friendlier by splitting up examples
authored
69 # => Full response, including headers
70
82f5c4e @chrisk Play with rdoc header levels a bit
authored
71 === Adding a custom status to the response
571854b @chrisk Make README a little friendlier by splitting up examples
authored
72
92075e0 @chrisk Deprecate FakeWeb.register_uri's :string and :file options in favor o…
authored
73 FakeWeb.register_uri(:get, "http://example.com/", :body => "Nothing to be found 'round here",
26b7c6c @chrisk Update the README to reflect new HTTP method support
authored
74 :status => ["404", "Not Found"])
571854b @chrisk Make README a little friendlier by splitting up examples
authored
75
26b7c6c @chrisk Update the README to reflect new HTTP method support
authored
76 Net::HTTP.start("example.com") do |req|
77 response = req.get("/")
571854b @chrisk Make README a little friendlier by splitting up examples
authored
78 response.code # => "404"
79 response.message # => "Not Found"
80 response.body # => "Nothing to be found 'round here"
02e3a0d @chrisk Copy the examples to the README, since a few rdoc renderers don't see…
authored
81 end
7a1a3d5 @blaine Initial Import
blaine authored
82
26b7c6c @chrisk Update the README to reflect new HTTP method support
authored
83 === Responding to any HTTP method
84
92075e0 @chrisk Deprecate FakeWeb.register_uri's :string and :file options in favor o…
authored
85 FakeWeb.register_uri(:any, "http://example.com", :body => "response for any HTTP method")
26b7c6c @chrisk Update the README to reflect new HTTP method support
authored
86
87 If you use the <tt>:any</tt> symbol, the URI you specify will be completely
88 stubbed out (regardless of the HTTP method of the request). This can be useful
d431cb5 @chrisk Docs: minor edits to the README
authored
89 for RPC-style services, where the HTTP method isn't significant. (Older
26b7c6c @chrisk Update the README to reflect new HTTP method support
authored
90 versions of FakeWeb always behaved like this, and didn't accept the first
0142d47 @chrisk Deprecate the implicit :any HTTP method
authored
91 +method+ argument above; this syntax is now deprecated.)
26b7c6c @chrisk Update the README to reflect new HTTP method support
authored
92
82f5c4e @chrisk Play with rdoc header levels a bit
authored
93 === Rotating responses
7d41f8d @chrisk Add a README section for response rotation
authored
94
d431cb5 @chrisk Docs: minor edits to the README
authored
95 You can optionally call <tt>FakeWeb.register_uri</tt> with an array of options
96 hashes; these are used, in order, to respond to repeated requests. Once you run
97 out of responses, further requests always receive the last response. (You can
98 also send a response more than once before rotating, by specifying a
99 <tt>:times</tt> option for that response.)
7d41f8d @chrisk Add a README section for response rotation
authored
100
26b7c6c @chrisk Update the README to reflect new HTTP method support
authored
101 FakeWeb.register_uri(:delete, "http://example.com/posts/1",
92075e0 @chrisk Deprecate FakeWeb.register_uri's :string and :file options in favor o…
authored
102 [{:body => "Post 1 deleted.", :status => ["200", "OK"]},
103 {:body => "Post not found", :status => ["404", "Not Found"]}])
7d41f8d @chrisk Add a README section for response rotation
authored
104
26b7c6c @chrisk Update the README to reflect new HTTP method support
authored
105 Net::HTTP.start("example.com") do |req|
106 req.delete("/posts/1").body # => "Post 1 deleted"
107 req.delete("/posts/1").body # => "Post not found"
108 req.delete("/posts/1").body # => "Post not found"
7d41f8d @chrisk Add a README section for response rotation
authored
109 end
110
d762cee @chrisk Clean up docs for basic auth a bit
authored
111 === Using HTTP basic authentication
da225c4 Updated README for HTTP basic authentication
Michael Bleigh authored
112
d431cb5 @chrisk Docs: minor edits to the README
authored
113 You can fake requests that use basic authentication by adding +userinfo+ strings
114 to your URIs:
da225c4 Updated README for HTTP basic authentication
Michael Bleigh authored
115
92075e0 @chrisk Deprecate FakeWeb.register_uri's :string and :file options in favor o…
authored
116 FakeWeb.register_uri(:get, "http://example.com/secret", :body => "Unauthorized", :status => ["401", "Unauthorized"])
117 FakeWeb.register_uri(:get, "http://user:pass@example.com/secret", :body => "Authorized")
da225c4 Updated README for HTTP basic authentication
Michael Bleigh authored
118
d762cee @chrisk Clean up docs for basic auth a bit
authored
119 Net::HTTP.start("example.com") do |http|
120 req = Net::HTTP::Get.new("/secret")
121 http.request(req) # => "Unauthorized"
122 req.basic_auth("user", "pass")
123 http.request(req) # => "Authorized"
124 end
da225c4 Updated README for HTTP basic authentication
Michael Bleigh authored
125
82f5c4e @chrisk Play with rdoc header levels a bit
authored
126 === Clearing registered URIs
ec20d18 Add a section to the README on FakeWeb.clean_registry
Chris Kampmeier authored
127
d431cb5 @chrisk Docs: minor edits to the README
authored
128 The FakeWeb registry is a singleton that lasts for the duration of your program,
129 maintaining every fake response you register. If needed, you can clean out the
130 registry and remove all registered URIs:
ec20d18 Add a section to the README on FakeWeb.clean_registry
Chris Kampmeier authored
131
132 FakeWeb.clean_registry
133
82f5c4e @chrisk Play with rdoc header levels a bit
authored
134 === Blocking all real requests
e8aed07 @chrisk Add new README sections: how to require the library, and FakeWeb.allo…
authored
135
136 When you're using FakeWeb to replace _all_ of your requests, it's useful to
137 catch when requests are made for unregistered URIs (unlike the default
138 behavior, which is to pass those requests through to Net::HTTP as usual).
139
140 FakeWeb.allow_net_connect = false
26b7c6c @chrisk Update the README to reflect new HTTP method support
authored
141 Net::HTTP.get(URI.parse("http://example.com/"))
e8aed07 @chrisk Add new README sections: how to require the library, and FakeWeb.allo…
authored
142 => raises FakeWeb::NetConnectNotAllowedError
143
144 FakeWeb.allow_net_connect = true
26b7c6c @chrisk Update the README to reflect new HTTP method support
authored
145 Net::HTTP.get(URI.parse("http://example.com/"))
e8aed07 @chrisk Add new README sections: how to require the library, and FakeWeb.allo…
authored
146 => FakeWeb is bypassed and the response from a real request is returned
147
93b890f @chrisk Fix up docs for #allow_net_connect= and add it to the README
authored
148 It's recommended that you set <tt>FakeWeb.allow_net_connect = false</tt> in the
149 setup for your tests.
150
151 ==== Allowing requests to a specific server
152
153 If you want to prevent your tests from hitting the internet while allowing
154 access to a specific server for integration testing, you can assign a URI or
155 +Regexp+ to be used as a whitelist for outbound requests:
156
157 FakeWeb.allow_net_connect = %r[^https?://localhost]
158 Net::HTTP.get(URI.parse("http://localhost/path")) # => allowed
159 Net::HTTP.get(URI.parse("http://example.com/")) # => raises FakeWeb::NetConnectNotAllowedError
7a1a3d5 @blaine Initial Import
blaine authored
160
b8fbab4 @chrisk Add support for specifying HTTP headers as options to FakeWeb.registe…
authored
161 === Specifying HTTP response headers
162
92075e0 @chrisk Deprecate FakeWeb.register_uri's :string and :file options in favor o…
authored
163 When you register a response using the <tt>:body</tt> option, you're only
164 setting the body of the response. If you want to add headers to these responses,
165 simply add the header as an option to +register_uri+:
b8fbab4 @chrisk Add support for specifying HTTP headers as options to FakeWeb.registe…
authored
166
92075e0 @chrisk Deprecate FakeWeb.register_uri's :string and :file options in favor o…
authored
167 FakeWeb.register_uri(:get, "http://example.com/hello.txt", :body => "Hello", :content_type => "text/plain")
b8fbab4 @chrisk Add support for specifying HTTP headers as options to FakeWeb.registe…
authored
168
169 This sets the "Content-Type" header in the response.
7365a38 @chrisk Prepare docs for 1.2.0 release
authored
170
06a41c3 @chrisk Add FakeWeb.last_request to the README
authored
171 === Checking the last request
172
173 It's often useful to retrieve the last request made by your code, so you can
174 write tests for its content. FakeWeb keeps track of the last request, whether it
175 was stubbed or not:
176
177 Net::HTTP.get(URI.parse("http://example.com"))
178 FakeWeb.last_request # => Net::HTTP::Get request object
179
82f5c4e @chrisk Play with rdoc header levels a bit
authored
180 == More info
1f6d378 @chrisk Lots of README cleanup: add installation section, remove OpenURI exam…
authored
181
182 FakeWeb lets you decouple your test environment from live services without
183 modifying code or writing extensive stubs.
7a1a3d5 @blaine Initial Import
blaine authored
184
1f6d378 @chrisk Lots of README cleanup: add installation section, remove OpenURI exam…
authored
185 In addition to the conceptual advantage of having idempotent request
186 behaviour, FakeWeb makes tests run faster than if they were made to remote (or
187 even local) web servers. It also makes it possible to run tests without a
188 network connection or in situations where the server is behind a firewall or
189 has host-based access controls.
7a1a3d5 @blaine Initial Import
blaine authored
190
1f6d378 @chrisk Lots of README cleanup: add installation section, remove OpenURI exam…
authored
191 FakeWeb works with anything based on Net::HTTP--both higher-level wrappers,
192 like OpenURI, as well as a ton of libraries for popular web services.
7a1a3d5 @blaine Initial Import
blaine authored
193
194
82f5c4e @chrisk Play with rdoc header levels a bit
authored
195 == Known Issues
7a1a3d5 @blaine Initial Import
blaine authored
196
26b7c6c @chrisk Update the README to reflect new HTTP method support
authored
197 * Request bodies are ignored, including PUT and POST parameters. If you need
198 different responses for different request bodies, you need to request
7365a38 @chrisk Prepare docs for 1.2.0 release
authored
199 different URLs, and register different responses for each. (Query strings are
200 fully supported, though.) We're currently considering how the API should
201 change to add support for request bodies in 1.3.0. Your input would be really
6442d5d @chrisk Update a few links in docs, the gemspec, etc.
authored
202 helpful: see https://groups.google.com/d/msg/fakeweb-users/RNGQprEuQnM/ryCiMeBD91YJ
7365a38 @chrisk Prepare docs for 1.2.0 release
authored
203 for a discussion of some different options. Thanks!
Something went wrong with that request. Please try again.