remi-rackbox 1.1.0 → 1.1.1

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2009 ryan "remi" Taylor
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

data/RDOC_README.rdoc

@@ -0,0 +1,88 @@
+= RackBox
+
+RackBox adds Merb-style blackbox testing]blackbox] to Rack apps (including Rails)
+
+This currently only works with RSpec.
+
+== Screencast
+
+Watch the Screencast[http://remi.org/2009/01/29/introducing-rackbox_merb-esque-blackbox-testing-for-rack-and-rails-apps.html]
+
+== 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](http://github.com/remi/rackbox/tree/master/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](http://github.com/remi/rackbox/tree/master/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`](http://rack.rubyforge.org/doc/classes/Rack/Response.html) which has 
+`body`, `headers`, `status` methods (and more](http://rack.rubyforge.org/doc/classes/Rack/Response.html))
+
+== TODO
+
+* request('/', :data => 'some XML or something')
+* request('/', :format => :json)          # simple helpers for content type request accepts
+* request('/', 'Content-Length' => 'x')   # anything passed in that we don't handle, throw into the request ENV ... but :content_length should work too?
+* get usage documentation working for `./script/generate blackbox_spec`

data/README.markdown

@@ -1,17 +1,39 @@
 RackBox
 =======
 
-[RackBox][] adds [Merb][]-style blackbox testing to [Rack][] apps (including [Rails][])
+[RackBox][] adds [Merb][]-style [blackbox testing][blackbox] to [Rack][] apps (including [Rails][])
 
 This currently only works with [RSpec][].
 
+Screencast
+----------
+
+[Watch the 'Screencast'][screencast]
+
 Installation
 ------------
 
     $ sudo gem install remi-rackbox -s http://gems.github.com
 
-Rails
------
+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:
@@ -39,6 +61,10 @@ 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](http://github.com/remi/rackbox/tree/master/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
 -----
 
@@ -64,13 +90,19 @@ on how things work in [Merb][] so I can duplicate any functionality I'm missing.
 TODO
 ----
 
-Before I make a screencast and post it to my blog, I wanna finish these ...
+ - request('/', :format => :json)          # simple helpers for content type request accepts
+ - get usage documentation working for `./script/generate blackbox_spec`
 
- - add a rails generator so you can install the gem and then ./script/generate blackbox\_spec
 
 
-[rackbox]:  http://github.com/remi/rackbox
-[merb]:     http://merbivore.com
-[rack]:     http://rack.rubyforge.org
-[rails]:    http://rubyonrails.org
-[rspec]:    http://rspec.info
+[rackbox]:    http://github.com/remi/rackbox
+[merb]:       http://merbivore.com
+[rack]:       http://rack.rubyforge.org
+[rails]:      http://rubyonrails.org
+[rspec]:      http://rspec.info
+[webrat]:     http://github.com/brynary/webrat
+[thin]:       http://code.macournoyer.com/thin
+[screencast]: http://remi.org/2009/01/29/introducing-rackbox_merb-esque-blackbox-testing-for-rack-and-rails-apps.html
+[rubygem]:    http://www.rubygems.org
+[blackbox]:   http://en.wikipedia.org/wiki/Black_box_testing
+[sinatra]:    http://sinatra.github.com

data/Rakefile

@@ -34,7 +34,7 @@ Rake::RDocTask.new do |rdoc|
   rdoc.rdoc_dir = 'rdoc'
   rdoc.title    = 'rackbox'
   rdoc.options << '--line-numbers' << '--inline-source'
-  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('RDOC_README.rdoc')
   rdoc.rdoc_files.include('lib/**/*.rb')
 end
 

data/VERSION.yml

@@ -1,4 +1,4 @@
 --- 
 :major: 1
 :minor: 1
-:patch: 0
+:patch: 1

data/lib/rackbox.rb

@@ -14,6 +14,7 @@ require 'rackbox/rack/sticky_sessions'
 require 'rackbox/rack/extensions_for_rspec'
 
 require 'rackbox/rackbox'
+require 'rackbox/app'
 
 require 'rspec/custom_matcher'
 require 'rackbox/matchers'

data/lib/rackbox/app.rb

@@ -0,0 +1,30 @@
+class RackBox
+
+  # represents a rack appliction
+  #
+  # gives us some helpers on a rack app 
+  # like the ability to use the #request 
+  # method on it easily
+  #
+  class App
+    attr_accessor :rack_app, :mock_request
+
+    def initialize rack_app
+      @rack_app = rack_app
+      reset_request
+    end
+
+    def reset_request
+      @mock_request = Rack::MockRequest.new @rack_app
+    end
+    alias reset reset_request
+
+    # sessions are sticky!
+    #
+    # to reset, @rackbox_app.reset
+    def request url, options = {}
+      RackBox.request @mock_request, url, options
+    end
+  end
+
+end

data/lib/rackbox/matchers.rb

@@ -1,24 +1,30 @@
-# Custom RSpec matchers
-module RackBox::Matchers
-  def self.included base
-    
-    # this should really just be matcher(:foo){ ... }
-    # but there's a bit of other meta logic to deal with here
-    Object.send :remove_const, :RedirectTo if defined? RedirectTo
-    undef redirect_to if defined? redirect_to
+class RackBox
 
-    # the actual matcher logic
-    matcher(:redirect_to, base) do |response, url|
-      return false unless response['Location']
-      if url =~ /^\//
-        # looking for a relative match, eg. should redirect_to('/login')
-        relative_location = response['Location'].sub(/^https?:\/\//,'').sub(/^[^\/]*/,'')
-        # ^ there's probably a helper on Rack or CGI to do this
-        relative_location.downcase == url.downcase
-      else
-        response['Location'].downcase == url.downcase
+  # Custom RSpec matchers
+  module Matchers
+
+    def self.included base
+      
+      # this should really just be matcher(:foo){ ... }
+      # but there's a bit of other meta logic to deal with here
+      Object.send :remove_const, :RedirectTo if defined? RedirectTo
+      undef redirect_to if defined? redirect_to
+
+      # the actual matcher logic
+      matcher(:redirect_to, base) do |response, url|
+        return false unless response['Location']
+        if url =~ /^\//
+          # looking for a relative match, eg. should redirect_to('/login')
+          relative_location = response['Location'].sub(/^https?:\/\//,'').sub(/^[^\/]*/,'')
+          # ^ there's probably a helper on Rack or CGI to do this
+          relative_location.downcase == url.downcase
+        else
+          response['Location'].downcase == url.downcase
+        end
       end
+
     end
 
   end
+
 end

data/lib/rackbox/rackbox.rb

@@ -1,3 +1,4 @@
+
 # To add blackbox testing to a Rails app,
 # in your spec_helper.rb
 #
@@ -8,7 +9,76 @@
 #   end
 #
 class RackBox
+
+  # i am an rdoc comment on RackBox's eigenclass
   class << self
+
+    # to turn on some verbosity / logging, set:
+    #   RackBox.verbose = true
+    attr_accessor :verbose
+
+    # A port of Merb's request() method, used in tests
+    #
+    # At the moment, we're using #req instead because #request conflicts 
+    # with an existing RSpec-Rails method
+    #
+    # Usage:
+    #   
+    #   req '/'
+    #   req login_path
+    #   req url_for(:controller => 'login')
+    #
+    #   req '/', :method => :post, :params => { 'chunky' => 'bacon' }
+    #
+    #   req '/', :data => "some XML data to POST"
+    #
+    # TODO take any additional options and pass them along to the environment, so we can say 
+    #      req '/', :user_agent => 'some custom user agent'
+    #
+    def req app_or_request, url, options = {}
+      puts "RackBox#request url:#{ url.inspect }, options:#{ options.inspect }" if RackBox.verbose
+
+      # need to find the request or app
+      mock_request = nil
+      if app_or_request.is_a? Rack::MockRequest
+        mock_request = app_or_request
+      elsif app_or_request.nil?
+        if RackBox.app.nil?
+          raise "Not sure howto to execute a request against app or request: #{ app_or_request.inspect }"
+        else
+          mock_request = Rack::MockRequest.new(RackBox.app) # default to RackBox.app if nil
+        end
+      elsif app_or_request.respond_to? :call
+        mock_request = Rack::MockRequest.new(app_or_request)
+      else
+        raise "Not sure howto to execute a request against app or request: #{ app_or_request.inspect }"
+      end
+
+      options[:method] ||= ( options[:params] || options[:data] ) ? :post : :get # if params, default to POST, else default to GET
+      options[:params] ||= { }
+
+      if options[:data]
+        # input should be the data we're likely POSTing ... this overrides any params
+        input = options[:data]
+      else
+        # input should be params, if any
+        input = RackBox.build_query options[:params]
+      end
+
+      headers = options.dup
+      headers.delete :data   if headers[:data]
+      headers.delete :params if headers[:params]
+      headers.delete :method if headers[:method]
+      
+      # merge input
+      headers[:input] = input
+      
+      puts "  requesting #{ options[:method].to_s.upcase } #{ url.inspect } #{ headers.inspect }" if RackBox.verbose
+      mock_request.send options[:method], url, headers
+    end
+
+    alias request req unless defined? request
+
     # the Rack appliction to do 'Black Box' testing against
     #
     # To set, in your spec_helper.rb or someplace:

data/lib/rackbox/spec/helpers.rb

@@ -1,34 +1,23 @@
-# Helper methods to include in specs that want to use blackbox testing
-#
-# This module has the RackBox::SpecHelpers#request method, which is 
-# the main method used by RackBox blackbox tests
-#
-module RackBox::SpecHelpers
+class RackBox
 
-  # A port of Merb's request() method, used in tests
+  # Helper methods to include in specs that want to use blackbox testing
   #
-  # At the moment, we're using #req instead because #request conflicts 
-  # with an existing RSpec-Rails method
+  # TODO For backwards compatibility, I would like to keep a SpecHelpers
+  #      module, but this needs to be renamed because this isn't spec 
+  #      specific at all!  it needs to be easy to RackBox::App.new(rack_app).request
+  #      or something like that (something generic)
   #
-  # Usage:
-  #   
-  #   req '/'
-  #   req login_path
-  #   req url_for(:controller => 'login')
+  # This module has the RackBox::SpecHelpers#request method, which is 
+  # the main method used by RackBox blackbox tests
   #
-  #   req '/', :method => :post, :params => { 'chunky' => 'bacon' }
-  #
-  # TODO support inner hashes, so { :foo => { :chunky => :bacon } } becomes 'foo[chunky]=bacon'
-  #
-  # TODO take any additional options and pass them along to the environment, so we can say 
-  #      req '/', :user_agent => 'some custom user agent'
-  #
-  def req url, options = {}
-    options[:method] ||= (options[:params]) ? :post : :get # if params, default to POST, else default to GET
-    options[:params] ||= { }
-    @rackbox_request.send options[:method], url, :input => RackBox.build_query(options[:params])
-  end
+  module SpecHelpers
+
+    # moved logic into RackBox#request, where it can easily be re-used
+    def req url, options = {}
+      RackBox.request @rackbox_request, url, options
+    end
 
-  alias request req unless defined? request
+    alias request req unless defined? request
 
+  end
 end

data/spec/custom_request_header_specs.rb

@@ -0,0 +1,14 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe RackBox, 'custom request headers' do
+
+  before do
+    @rack_app = lambda {|env| [ 200, { }, env.inspect ] }
+  end
+
+  it "#request should take any non-special options and assume they're request headers" do
+    RackBox.request(@rack_app, '/').body.should_not include('"HTTP_ACCEPT"=>"application/json"')
+    RackBox.request(@rack_app, '/', 'HTTP_ACCEPT' => 'application/json').body.should include('"HTTP_ACCEPT"=>"application/json"')
+  end
+
+end

data/spec/posting_data_spec.rb

@@ -0,0 +1,33 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe RackBox, 'POSTing data' do
+
+  before do
+    @rack_app1 = lambda {|env| [ 200, { }, "you POSTed data: #{ env['rack.input'].read }" ] }  
+    @rack_app2 = lambda {|env| 
+      req = Rack::Request.new env
+      [ 200, { }, "you POSTed data: #{ req.body.read }" ]
+    }  
+    @method_app = lambda {|env| [ 200, { }, "method: #{ env['REQUEST_METHOD'] }" ] }
+  end
+
+  it 'should make it easy to POST data, eg. curl -D "XML"' do
+    RackBox.request(@rack_app1, '/', :data => 'hi there').body.should include('you POSTed data: hi there')
+    RackBox.request(@rack_app2, '/', :data => 'hi there').body.should include('you POSTed data: hi there')
+  end
+
+  it "should default to POST if method isn't explicitly set and we set :data" do
+    RackBox.request(@method_app, '/').body.should include('method: GET')
+    RackBox.request(@method_app, '/', :method => :put).body.should include('method: PUT')
+    RackBox.request(@method_app, '/', :data => 'hi').body.should include('method: POST')
+    RackBox.request(@method_app, '/', :data => 'hi', :method => :put).body.should include('method: PUT')
+  end
+
+  it "should default to POST if method isn't explicitly set and we set :params" do
+    RackBox.request(@method_app, '/').body.should include('method: GET')
+    RackBox.request(@method_app, '/', :method => :put).body.should include('method: PUT')
+    RackBox.request(@method_app, '/', :params => { :x => 5 }).body.should include('method: POST')
+    RackBox.request(@method_app, '/', :params => { :x => 5 }, :method => :put).body.should include('method: PUT')
+  end
+
+end

data/spec/request_method_spec.rb

@@ -0,0 +1,17 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe RackBox, '#request' do
+
+  before do
+    @rack_app = lambda {|env| [ 200, { }, "you requested path #{ env['PATH_INFO'] }" ] }  
+  end
+
+  it 'should be easy to run the #request method against any Rack app' do
+    RackBox::App.new(@rack_app).request('/hello').body.should include('you requested path /hello')
+  end
+
+  it 'should be even easier to run the #request method against any Rack app' do
+    RackBox.request(@rack_app, '/hello').body.should include('you requested path /hello')
+  end
+
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: remi-rackbox
 version: !ruby/object:Gem::Version 
-  version: 1.1.0
+  version: 1.1.1
 platform: ruby
 authors: 
 - remi
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-01-29 00:00:00 -08:00
+date: 2009-02-09 00:00:00 -08:00
 default_executable: 
 dependencies: []
 
@@ -25,6 +25,8 @@ files:
 - Rakefile
 - VERSION.yml
 - README.markdown
+- LICENSE
+- RDOC_README.rdoc
 - lib/rackbox.rb
 - lib/rspec
 - lib/rspec/custom_matcher.rb
@@ -36,9 +38,13 @@ files:
 - lib/rackbox/spec
 - lib/rackbox/spec/configuration.rb
 - lib/rackbox/spec/helpers.rb
+- lib/rackbox/app.rb
 - lib/rackbox/rackbox.rb
 - lib/rackbox/matchers.rb
-- spec/rackbox_spec.rb
+- spec/request_method_spec.rb
+- spec/posting_data_spec.rb
+- spec/rackbox_build_query_spec.rb
+- spec/custom_request_header_specs.rb
 - spec/spec_helper.rb
 - examples/sinatra
 - examples/sinatra/run-specs