= FakeWeb

FakeWeb is a helper for faking web requests. It works at a global level, without
modifying code or writing extensive stubs.

= Examples

== Using a string response

  FakeWeb.register_uri("http://example.com/test1", :string => "Hello World!")

  Net::HTTP.get(URI.parse('http://example.com/test1'))
  => "Hello World!"

  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

  page = `curl -is http://www.google.com/`
  FakeWeb.register_uri('http://www.google.com/', :response => page)

  Net::HTTP.get(URI.parse('http://www.google.com/'))
  # => Full response, including headers

== Adding a custom status to the response

  FakeWeb.register_uri('http://example.com/', :string => "Nothing to be found 'round here",
                                              :status => ["404", "Not Found"])

  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

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',
                       [{: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"
  end

== Requesting with OpenURI

  FakeWeb.register_uri('http://example.com/', :string => "Hello, World!")

  open('http://example.com/').string
  => "Hello, World!"

== Clearing registered URIs

The FakeWeb registry is a singleton that lasts for the duration of your
program, maintaining every fake responses you register. If needed, you
can clean out the registry and remove all registered URIs:

  FakeWeb.clean_registry


= Description

FakeWeb is a helper for faking web requests. This makes testing easier,
because you can decouple your test environment from live services without
modifying code. It allows for a range of request behaviour, from simple
stubbing of HTTP responses to re-playing complete recorded responses.

In addition to the conceptual advantage of having idempotent request behaviour, 
FakeWeb makes tests run faster than if they were made to remote (or even local)
web servers. It also makes it possible to run tests without a network
connection or in situations where the server is behind a firewall or has
host based access controls.

FakeWeb is tested with
Net::HTTP[http://www.ruby-doc.org/stdlib/libdoc/net/http/rdoc/index.html] and
OpenURI[http://www.ruby-doc.org/stdlib/libdoc/open-uri/rdoc/]. It should work
with any web client library that uses Net::HTTP for its underlying requests
(e.g., Flickr.rb[http://redgreenblu.com/flickr/],
Ruby/Amazon[http://www.caliban.org/ruby/ruby-amazon.shtml],
soap4r[http://dev.ctor.org/soap4r/], etc.)

= Known Issues

* 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.

= Copyright

FakeWeb - Ruby Helper for Faking Web Requests
Copyright 2006 Blaine Cook <romeda@gmail.com>.

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.

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