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

The latest release of FakeWeb is once again available from your friendly RubyForge mirror. Just install the gem:

sudo gem install fakeweb

Note: the gem was previously available as FakeWeb (capital letters), but now all versions are simply registered as fakeweb. If you have any old FakeWeb gems lying around, remove them: sudo gem uninstall FakeWeb

Help and discussion

RDocs for the current release are available at fakeweb.rubyforge.org.

There’s a mailing list for questions and discussion at groups.google.com/group/fakeweb-users.

The main source repository is github.com/chrisk/fakeweb.

Examples

Start by requiring FakeWeb:

require 'rubygems'
require 'fakeweb'

Registering basic string responses

FakeWeb.register_uri(:get, "http://example.com/test1", :body => "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

You can also call register_uri with a regular expression, to match more than one URI.

Replaying a recorded response

page = `curl -is http://www.google.com/`
FakeWeb.register_uri(:get, "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(:get, "http://example.com/", :body => "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

Responding to any HTTP method

FakeWeb.register_uri(:any, "http://example.com", :body => "response for any HTTP method")

If you use the :any 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 now deprecated.)

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 :times option for that response.)

FakeWeb.register_uri(:delete, "http://example.com/posts/1",
                     [{:body => "Post 1 deleted.", :status => ["200", "OK"]},
                      {:body => "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

Using HTTP basic authentication

You can stub requests that use basic authentication with userinfo strings in the URIs:

FakeWeb.register_uri(:get, "http://example.com/secret", :body => "Unauthorized", :status => ["401", "Unauthorized"])
FakeWeb.register_uri(:get, "http://user:[email protected]/secret", :body => "Authorized")

Net::HTTP.start("example.com") do |http|
  req = Net::HTTP::Get.new("/secret")
  http.request(req)  # => "Unauthorized"
  req.basic_auth("user", "pass")
  http.request(req)  # => "Authorized"
end

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

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/"))
=> raises FakeWeb::NetConnectNotAllowedError

FakeWeb.allow_net_connect = true
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.

Specifying HTTP response headers

When you register a response using the :body option, you’re only setting the body of the response. If you want to add headers to these responses, simply add the header as an option to register_uri:

FakeWeb.register_uri(:get, "http://example.com/hello.txt", :body => "Hello", :content_type => "text/plain")

This sets the “Content-Type” header in the response.

Automatically saving responses as fixtures

If your test suite makes many requests it can become tedious registering a uri for every request. You can put FakeWeb into fixture generation mode where every request made will save a fixture to the provided path. After generating fixtures for all of your requests you can tell FakeWeb to load your fixtures and it will register all of your requests to the appropriate response.

FakeWeb.generate_fixture("spec/web_fixtures") # save responses as a fixture
FakeWeb.register_fixture("spec/web_fixtures") # FakeWeb.register each fixture

Add this to your spec/spec_helper to help generate and load fixtures:

FakeWeb.generate_fixtures 'spec/web_fixtures' if ENV['FAKEWEB_FIXTURES']

unless FakeWeb.generate_fixtures?
  FakeWeb.register_fixtures 'spec/web_fixtures'
  FakeWeb.allow_net_connect = false
end

Then run this in the console to generate fixtures:

rake spec FAKEWEB_FIXTURES=true

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

  • 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.) We’re currently considering how the API should change to add support for request bodies in 1.3.0. Your input would be really helpful: see groups.google.com/group/fakeweb-users/browse_thread/thread/44d190a6b12e4273 for a discussion of some different options. Thanks!

Copyright 2006-2007 Blaine Cook

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

See LICENSE.txt for the full terms.