Rack::Test

Code: https://github.com/rack/rack-test

Description

Rack::Test is a small, simple testing API for Rack apps. It can be used on its own or as a reusable starting point for Web frameworks and testing libraries to build on.

Features

• Allows for submitting requests and testing responses
• Maintains a cookie jar across requests
• Supports request headers used for subsequent requests
• Follow redirects when requested

Examples

These examples use test/unit but it's equally possible to use rack-test with other testing frameworks such as minitest or rspec.

require "test/unit"
require "rack/test"
require "json"

class HomepageTest < Test::Unit::TestCase
  include Rack::Test::Methods

  def app
    lambda { |env| [200, {'content-type' => 'text/plain'}, ['All responses are OK']] }
  end

  def test_response_is_ok
    # Optionally set headers used for all requests in this spec:
    #header 'accept-charset', 'utf-8'

    # First argument is treated as the path
    get '/'

    assert last_response.ok?
    assert_equal 'All responses are OK', last_response.body
  end

  def delete_with_url_params_and_body
    # First argument can have a query string
    #
    # Second argument is used as the parameters for the request, which will be
    # included in the request body for non-GET requests.
    delete '/?foo=bar', JSON.generate('baz' => 'zot')
  end

  def post_with_json
    # Third argument is the rack environment to use for the request.  The following
    # entries in the submitted rack environment are treated specially (in addition
    # to options supported by `Rack::MockRequest#env_for`:
    #
    # :cookie : Set a cookie for the current session before submitting the request.
    #
    # :query_params : Set parameters for the query string (as opposed to the body).
    #                 Value should be a hash of parameters.
    #
    # :xhr : Set HTTP_X_REQUESTED_WITH env key to XMLHttpRequest.
    post(uri, JSON.generate('baz' => 'zot'), 'CONTENT_TYPE' => 'application/json')
  end
end

rack-test will test the app returned by the app method. If you are loading middleware in a config.ru file, and want to test that, you should load the Rack app created from the config.ru file:

OUTER_APP = Rack::Builder.parse_file("config.ru").first

class TestApp < Test::Unit::TestCase
  include Rack::Test::Methods

  def app
    OUTER_APP
  end

  def test_root
    get "/"
    assert last_response.ok?
  end
end

If your application does not automatically use the Rack::Lint middleware in test mode, and you want to test that requests to and responses from your application are compliant with the Rack specification, you should manually use the Rack::Lint middleware:

class TestApp < Test::Unit::TestCase
  include Rack::Test::Methods

  APP = Rack::Lint.new(YOUR_APP)

  def app
    APP
  end
end

Install

To install the latest release as a gem:

gem install rack-test

Or add to your Gemfile:

gem 'rack-test'

Contribution

Contributions are welcome. Please make sure to:

• Use a regular forking workflow
• Write tests for the new or changed behaviour
• Provide an explanation/motivation in your commit message / PR message
• Ensure History.md is updated

Authors

• Contributions from Bryan Helmkamp, Jeremy Evans, Simon Rozet, and others
• Much of the original code was extracted from Merb 1.0's request helper

License

rack-test is released under the MIT License.

Supported platforms

• Ruby 2.0+
• JRuby 9.1+

Releasing

• Bump VERSION in lib/rack/test/version.rb
• Ensure History.md is up-to-date, including correct version and date
• git commit . -m 'Release $VERSION'
• git push
• git tag -a -m 'Tag the $VERSION release' $VERSION
• git push --tags
• gem build rack-test.gemspec
• gem push rack-test-$VERSION.gem
• Add a discussion post for the release