RackBox

RackBox adds Merb-style blackbox testing to Rack apps (including Rails)

This currently only works with RSpec.

Screencast

Watch the 'Screencast'

Installation

$ sudo gem install remi-rackbox -s http://gems.github.com

NOTE: right now, RackBox requires thin. Soon, I'll likely remove thin as a dependency and will only require rack.

Rails (fast!)

$ sudo gem install rspec rspec-rails thin
$ sudo gem install remi-rackbox -s http://gems.github.com

$ rails new_app
$ cd new_app
$ ./script/generate rspec
$ ./script/generate blackbox_spec Home Page

$ rake spec

Rails (manual)

To write RackBox tests in Rails apps, make a blackbox directory under your spec directory and add this to the Spec configure block in your spec_helper.rb file:

config.use_blackbox = true

Also, add require 'rackbox' to the top of your spec_helper.rb

You can see a working example of blackbox testing a Rails application here: examples/rails

Rack

To write RackBox tests in Rack apps, I'm currently assuming that you have a config.ru rackup file. If so, your app should load, otherwise you can explicitly configure RackBox to read your Rack app:

RackBox.app = [your Rack app]

Basides that, the configuration is the same as Rails. Make a blackbox directory under your spec directory and add this to the Spec configure block in your spec_helper.rb file:

config.use_blackbox = true

Also, add require 'rackbox' to the top of your spec_helper.rb

You can see a working example of blackbox testing a Rack application here: examples/rack

NOTE: If you want to be able to use nice RSpec matchers like request('/').should have_tag('p') in your blackbox specs in your Rack apps, you should sudo gem install webrat and RackBox will include Webrat's helpers in your specs.

Usage

Ideally, the usage of RackBox should be identical to Merb-style blackbox testing. I need to find good documentation on how things work in Merb so I can duplicate any functionality I'm missing. For now, it's really simple!

describe Foo do

  it 'should have foxes on the home page' do
    request('/').body.should include('Foxes')
  end

  it 'should let me know that I was logged in' do
    response = request(login_path, :method => :post, :params => { 'user' => 'bob', :password => 'secret' })
    response.body.should include('Welcome bob, you were successfully logged in!')
  end

end

request gives you a Rack::Response which has body, headers, status methods (and more)

TODO

• recreate examples so they all follow a SIMPLE spec ... eg. they should all return request headers if you call /request_headers
• get rid of Thin as a dependency! use rails-rack-adapter
• get rid of including custom rpsec matchers, use rspec-custom-matchers
• make the spec module inclusion less magical! refactor the spec helpers out ... make it more explicit to include the spec helpers?
• add test/unit support (the above'll be helpful for this)
• bugfix: 'request' method makes spec helpers angry!
• request('/', :format => :json) # simple helpers for content type request accepts
• get usage documentation working for ./script/generate blackbox_spec
• refactor all specs ... an app should implement a simple API that we can spec against ... some URIs should return session vars, some request vars, etc
• add a rackbox script for helping to quickly run requests against apps!
• add a Rackbox Webrat backend so we can use the helpers to browse around and click buttons and whatnot? could be yummy!