Bryan Helmkamp

Today I’m happy to announce the first release of a new library I’ve been cooking up: Rack::Test. It’s a simple API for issuing fake requests to any Rack app (e.g. Rails, Sinatra, Merb, etc.) similar to what you might be familiar with in Rails’ integration tests or Merb’s request specs. Basically, I extracted Merb’s request helper code into a small, reusable, framework agnostic library. Here’s an example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

require "rack/test"

class HomepageTest < Test::Unit::TestCase
  include Rack::Test::Methods
  
  def app
    MyApp.new
  end
  
  def test_redirect_logged_in_users_to_dashboard
    authorize "bryan", "secret"
    get "/"
    follow_redirect!
    
    assert_equal "http://example.org/redirected", last_request.url
    assert last_response.ok?
  end
end

While developing Webrat, I started to realize all of the Ruby web frameworks were reinventing boilerplate code to create a test environment for issuing fake requests. They all have to:

• Convert params hashes into encoded strings (something the browser handles for normal requests)
• Maintain a simulated cooke jar to enable sessions
• Generate multipart requests (to support test file uploads)

Through discussions with Josh Knowles and Yehuda Katz, it became apparent that an abstracted layer for these concerns would be valuable.

With Rack::Test, we hope to make it easy for frameworks to encourage their users to write tests by making it trivial to provide a testing environment. We’d like to foster compatibility between Ruby web app testing environments (especially important as ideas like multi-framework apps become more prominent). The philosophy is the library should stay small and extendable so frameworks can layer on additional functionality they want to offer without modifying Rack::Test’s core behavior or resorting to monkeypatching.

The Rack::Test API

The full RDoc is available on gitrdoc, but I’ve reproduced some of it below. It should feel familiar if you’re used to Rails integration testing or Merb request specs:

Rack::Test.initialize(app) — Initialize a new session for the given Rack app

#get(uri, params = {}, env = {}) — Issue a GET request for the given URI with the given params and Rack environment. Stores the issues request object in #last_request and the app’s response in #last_response. Yield #last_response to a block if given.

#post, #put, #delete, and #head — Behave like #get but specifying a different HTTP method

#request(uri, env = {}) — Issue a request to the Rack app for the given URI and optional Rack environment. Stores the issues request object in #last_request and the app’s response in #last_response. Yield #last_response to a block if given.

#follow_redirect! — Rack::Test does not follow any redirects automatically. This method will follow the redirect returned in the last response. If the last response was not a redirect, an error will be raised.

#header(name, value) — Set a header to be included on all subsequent requests through the session. Use a value of nil to remove a previously configured header.

#authorize(username, password)— Set the username and password for HTTP Basic authorization, to be included in subsequent requests in the HTTP_AUTHORIZATION header.

#last_request — Return the last request issued in the session. Raises an error if no requests have been sent yet.

#last_response — Return the last response received in the session. Raises an error if no requests have been sent yet.

Note: Thanks to the people who helped get Rack::Test off the ground: The Merb Team for their request helper code; Yehuda Katz and Josh Knowles for guidance, encouragement and support; Simon Rozet and Pat Nakajima for early code contributions.