README.rdoc in chrisk-fakeweb-1.1.2.6 vs README.rdoc in chrisk-fakeweb-1.1.2.7
- old
+ new
@@ -1,100 +1,127 @@
= FakeWeb
FakeWeb is a helper for faking web requests in Ruby. It works at a global
level, without modifying code or writing extensive stubs.
-= Installation
+== Installation
+
This fork of Blaine Cook's original code has lots of fixes, stability
-improvements, and a few new features. To get it, install the latest gem
-directly from GitHub (currently 1.1.2.6):
+improvements, and a few new features. It also has new support for Ruby 1.9.1
+and JRuby. To get it, install the latest gem directly from GitHub (currently
+1.1.2.7):
sudo gem install chrisk-fakeweb --source http://gems.github.com
-= Examples
+== Help and discussion
+
+There's a brand new mailing list at http://groups.google.com/group/fakeweb-users.
+
+
+== Development Notes
+
+We're currently considering how the API should change to add support for
+request bodies (see Known Issues below). Your input would be really helpful:
+see http://groups.google.com/group/fakeweb-users/browse_thread/thread/44d190a6b12e4273
+for a discussion of some different options. Thanks!
+
+
+== Examples
+
Start by requiring FakeWeb:
require 'rubygems'
require 'fake_web'
-== Registering basic string responses
+=== Registering basic string responses
- FakeWeb.register_uri("http://example.com/test1", :string => "Hello World!")
+ FakeWeb.register_uri(:get, "http://example.com/test1", :string => "Hello World!")
- Net::HTTP.get(URI.parse('http://example.com/test1'))
+ Net::HTTP.get(URI.parse("http://example.com/test1"))
=> "Hello World!"
- Net::HTTP.get(URI.parse('http://example.com/test2'))
+ Net::HTTP.get(URI.parse("http://example.com/test2"))
=> FakeWeb is bypassed and the response from a real request is returned
-== Replaying a recorded response
+=== Replaying a recorded response
page = `curl -is http://www.google.com/`
- FakeWeb.register_uri('http://www.google.com/', :response => page)
+ FakeWeb.register_uri(:get, "http://www.google.com/", :response => page)
- Net::HTTP.get(URI.parse('http://www.google.com/'))
+ Net::HTTP.get(URI.parse("http://www.google.com/"))
# => Full response, including headers
-== Adding a custom status to the response
+=== Adding a custom status to the response
- FakeWeb.register_uri('http://example.com/', :string => "Nothing to be found 'round here",
- :status => ["404", "Not Found"])
+ FakeWeb.register_uri(:get, "http://example.com/", :string => "Nothing to be found 'round here",
+ :status => ["404", "Not Found"])
- Net::HTTP.start('example.com') do |req|
- response = req.get('/')
+ Net::HTTP.start("example.com") do |req|
+ response = req.get("/")
response.code # => "404"
response.message # => "Not Found"
response.body # => "Nothing to be found 'round here"
end
-== Rotating responses
+=== Responding to any HTTP method
+ FakeWeb.register_uri(:any, "http://example.com", :string => "response for any HTTP method")
+
+If you use the <tt>:any</tt> symbol, the URI you specify will be completely
+stubbed out (regardless of the HTTP method of the request). This can be useful
+for RPC-like services, where the HTTP method isn't significant. (Older
+versions of FakeWeb always behaved like this, and didn't accept the first
++method+ argument above; this syntax is still supported, for
+backwards-compatibility, but it will probably be deprecated at some point.)
+
+=== Rotating responses
+
You can optionally call FakeWeb.register_uri with an array of options hashes;
these are used, in order, to respond to repeated requests. Once you run out of
responses, further requests always receive the last response. (You can also send
a response more than once before rotating, by specifying a <tt>:times</tt>
option for that response.)
- FakeWeb.register_uri('http://example.com/posts/1',
+ FakeWeb.register_uri(:delete, "http://example.com/posts/1",
[{:string => "Post 1 deleted.", :status => ["200", "OK"]},
{:string => "Post not found", :status => ["404", "Not Found"]}])
- Net::HTTP.start('example.com') do |req|
- req.delete('/posts/1').body # => "Post 1 deleted"
- req.delete('/posts/1').body # => "Post not found"
- req.delete('/posts/1').body # => "Post not found"
+ Net::HTTP.start("example.com") do |req|
+ req.delete("/posts/1").body # => "Post 1 deleted"
+ req.delete("/posts/1").body # => "Post not found"
+ req.delete("/posts/1").body # => "Post not found"
end
-== Clearing registered URIs
+=== Clearing registered URIs
The FakeWeb registry is a singleton that lasts for the duration of your
program, maintaining every fake response you register. If needed, you
can clean out the registry and remove all registered URIs:
FakeWeb.clean_registry
-== Blocking all real requests
+=== Blocking all real requests
When you're using FakeWeb to replace _all_ of your requests, it's useful to
catch when requests are made for unregistered URIs (unlike the default
behavior, which is to pass those requests through to Net::HTTP as usual).
FakeWeb.allow_net_connect = false
- Net::HTTP.get(URI.parse('http://example.com/'))
+ Net::HTTP.get(URI.parse("http://example.com/"))
=> raises FakeWeb::NetConnectNotAllowedError
FakeWeb.allow_net_connect = true
- Net::HTTP.get(URI.parse('http://example.com/'))
+ Net::HTTP.get(URI.parse("http://example.com/"))
=> FakeWeb is bypassed and the response from a real request is returned
This is handy when you want to make sure your tests are self-contained, or you
want to catch the scenario when a URI is changed in implementation code
without a corresponding test change.
-= More info
+== More info
FakeWeb lets you decouple your test environment from live services without
modifying code or writing extensive stubs.
In addition to the conceptual advantage of having idempotent request
@@ -105,34 +132,34 @@
FakeWeb works with anything based on Net::HTTP--both higher-level wrappers,
like OpenURI, as well as a ton of libraries for popular web services.
-= Known Issues
+== Known Issues
-* Requests are only stubbed at the URI level, with no respect to HTTP method.
+* Request bodies are ignored, including PUT and POST parameters. If you need
+ different responses for different request bodies, you need to request
+ different URLs, and register different responses for each. (Query strings
+ are fully supported, though.)
-* Similarly, request bodies are ignored, including PUT and POST parameters. If
- you need different responses for different request bodies, you need to
- request different URLs, and register different responses for each. (Query
- strings are fully supported, though.)
+== Copyright
-= Copyright
-
Copyright 2006-2007 Blaine Cook
-Copyright 2008 various contributors
+Copyright 2008-2009 various contributors
-FakeWeb is free software; you can redistribute it and/or modify
-it under the terms of the GNU General Public License as published by
-the Free Software Foundation; either version 2 of the License, or
-(at your option) any later version.
+ FakeWeb is free software; you can redistribute it and/or modify it under the
+ terms of the GNU General Public License as published by the Free Software
+ Foundation; either version 2 of the License, or (at your option) any later
+ version.
-FakeWeb is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-GNU General Public License for more details.
+ FakeWeb is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+ FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
+ details.
-You should have received a copy of the GNU General Public License
-along with FakeWeb; if not, write to the Free Software
-Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
+ You should have received a copy of the GNU General Public License along
+ with FakeWeb; if not, write to the Free Software Foundation, Inc., 51
+ Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
+
+See <tt>LICENSE.txt</tt> for the full terms.
\ No newline at end of file