rack-test-rest 0.1.0

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/Gemfile

@@ -0,0 +1,13 @@
+source "http://rubygems.org"
+# Add dependencies required to use your gem here.
+# Example:
+#   gem "activesupport", ">= 2.3.5"
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem "shoulda", ">= 0"
+  gem "bundler", "~> 1.0.0"
+  gem "jeweler", "~> 1.5.2"
+  gem "rcov", ">= 0"
+end

data/Gemfile.lock

@@ -0,0 +1,20 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    git (1.2.5)
+    jeweler (1.5.2)
+      bundler (~> 1.0.0)
+      git (>= 1.2.5)
+      rake
+    rake (0.8.7)
+    rcov (0.9.9)
+    shoulda (2.11.3)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.0.0)
+  jeweler (~> 1.5.2)
+  rcov
+  shoulda

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2011 Joseph Ruscio
+ 
+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/README.md

@@ -0,0 +1,127 @@
+`rack-test-rest` is an extension to `rack-test` that when combined with
+`Test::Unit` simplifies the process of unit testing properly
+designed RESTful API's.
+
+# Installation
+    $ gem install rack-test-rest
+
+# Use
+
+`rack-test-rest` extends `rack-test` with a set of higher-level methods that
+perform _CRUD_ operations against resources through a RESTful API that conforms
+to best practices and validates that they respond correctly.
+It's designed to be mixed into a subclass of `Test::Unit::Testcase`
+that is testing a specific resource e.g.:
+
+      class GaugeTest < Test::Unit::TestCase
+        include Rack::Test::Methods
+        include Rack::Test::Rest
+
+        def setup
+          @rack_test_rest = {
+            #:debug => true,
+            :root_uri => "/v1/metrics",
+            :resource => "gauges"
+          }
+        end
+
+        def test_create
+          create_resource(:name => "foo")
+          create_resource(:code => 422, :name => "foo")
+        end
+
+        def test_read
+          create_resource(:name => "foo")
+
+          gauge = read_resource(:id => name)
+          assert gauge['name'] == name
+        end
+
+        def test_update
+          create_resource(:name => "foo", :description => "bar")
+
+          update_resource(:id => "foo", :description => "baz")
+
+          gauge = read_resource(:id => name)
+          assert gauge['description'] == "baz"
+        end
+
+        def test_delete
+          create_resource(:name => "foo")
+          delete_resource(:id => "foo")
+          read_resource(:code => 404, :id => name)
+        end
+
+`rack-test-rest` exploits _convention over configuration_ to minimize the amount of work
+required to test any particular resource. You need only specify `:root_uri` and `:resource`
+in your test setup (through the `@rack_test_rest` instance variable). These are combined
+to create either the URI for creating/indexing resources or the URI for a particular resource:
+
+    :root_uri + '/' + :resource + '.json'
+    :root_uri + '/' + :resource + '/' + params[:id].to_s + '.json'
+
+## `create_resource(params={})`
+
+Performs a POST to with any specified parameters to `:root_uri/:resource.json`
+and ensures that it returns `201`. Returns the string value found in the response's
+`Location` header.
+
+## `read_resource(params={})`
+
+Performs a GET with any specified parameters and validates that it returns `200`.
+If `:id` is specified the GET is performed against a singular resource i.e.
+`:root_uri/:resource/:id.json`. In the absence of `:id` the GET is performed
+as an index operation against `:root_uri/:resource.json`. Returns parsed
+JSON of the response body on a `200`.
+
+## `update_resource(params={})`
+
+Requires an :id parameter. Performs a PUT against `:root_uri/:resource/:id.json`
+with any other specified parameters and asserts that it returns `204`.
+
+## `delete_resource(params={})`
+
+Requires an :id parameter. Performs a DELETE against `:root_uri/:resource/:id.json`
+and asserts that it returns `204`.
+
+## Testing invalid input
+
+Any of the CRUD operations can be altered to check that invalid input is properly
+detected and returns the correct error code by specifying `:code` as a parameter
+e.g.
+    create_resource(:code => 422, :name => duplicate_name)
+    read_resource(:code => 404, :id => invalid_id)
+
+## Debugging
+The point of unit tests is to surface and fix defects and/or regressions in your code
+in the lab rather than than in production. When your tests fail you can include
+:debug => true` to instruct `rack-rest-test` to verbosely log to STDOUT the individual
+HTTP requests it's performing and the results of each.
+
+## Pagination
+`rack-test-rest` also supports randomized tests for paginated resources assuming you follow
+the [standard pagination scheme](http://dev.librato.com/v1/pagination). All you need supply it
+with is a block it can use to generate unique parameters for populating the resources prior
+to pagination tests. You can specify `:count` to control how many records are created and
+paginated through (defaults to 512) and `:length` to specify the maximum number of resources
+that a single index operation may return (defaults to 100).
+
+    def test_gauge_pagination
+      @db.run("DELETE FROM gauges")
+      paginate_resource(){ |id| {:name => "foo_#{id}", :description => "gauge #{id}"} }
+    end
+
+# Contributions
+
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
+* Fork the project
+* Start a feature/bugfix branch
+* Commit and push until you are happy with your contribution
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+* Submit a pull request!
+
+# Copyright
+
+Copyright (c) 2011 Joseph Ruscio. See LICENSE.txt for
+further details.

data/Rakefile

@@ -0,0 +1,53 @@
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "rack-test-rest"
+  gem.homepage = "http://github.com/josephruscio/rack-test-rest"
+  gem.license = "MIT"
+  gem.summary = %Q{Abstractions for testing RESTful API's with rack-test and Test::Unit.}
+  gem.description = %Q{rack-test-rest is an extension to rack-test that when combined with Test::Unit simplifies the process of unit testing properly designed RESTful API's.}
+  gem.email = "joe@ruscio.org"
+  gem.authors = ["Joseph Ruscio"]
+  # Include your dependencies below. Runtime dependencies are required when using your gem,
+  # and development dependencies are only needed for development (ie running rake tasks, tests, etc)
+  #  gem.add_runtime_dependency 'jabber4r', '> 0.1'
+  #  gem.add_development_dependency 'rspec', '> 1.2.3'
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+require 'rcov/rcovtask'
+Rcov::RcovTask.new do |test|
+  test.libs << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "rack-test-rest #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/rack-test-rest.rb

@@ -0,0 +1,134 @@
+module Rack
+  module Test
+    module Rest
+
+      def resource_uri
+	"#{@rack_test_rest[:root_uri]}/#{@rack_test_rest[:resource]}"
+      end
+
+      def create_resource(params={})
+        expected_code = params[:code]
+        params.delete :code
+
+        puts "Posting to: '#{resource_uri}.json'" if @rack_test_rest[:debug]
+        post "#{resource_uri}.json", params
+
+        if expected_code
+          assert last_response.status == expected_code
+        else
+	  if @rack_test_rest[:debug]
+            puts "#{last_response.status}: #{last_response.body}"
+            puts last_response.original_headers["Location"]
+	  end
+          assert last_response.status == 201
+          if @rack_test_rest[:location]
+            assert last_response.original_headers["Location"] =~ @rack_test_rest[:location]
+          end
+        end
+
+        last_response.original_headers["Location"]
+      end
+
+      def read_resource(params={})
+        expected_code = params[:code]
+        params.delete :code
+
+	if params[:id]
+          id = params[:id]
+          params.delete(:id)
+	  uri = resource_uri + "/#{id}.json"
+	else
+	  uri = resource_uri + ".json"
+	end
+
+        puts "GET #{uri} #{params}" if @rack_test_rest[:debug]
+        get uri, params
+
+        if @rack_test_rest[:debug]
+          puts "Code: #{last_response.status}"
+          puts "Body: #{last_response.body}"
+	end
+
+        if expected_code
+          assert last_response.status == expected_code
+          return nil
+        else
+          assert last_response.status == 200
+          return JSON.parse(last_response.body)
+        end
+      end
+
+      def update_resource(params={})
+        expected_code = params[:code]
+        params.delete :code
+
+        id = params[:id]
+        params.delete(:id)
+
+        puts "Attempting to update #{id} with #{params}" if @rack_test_rest[:debug]
+
+        put "#{resource_uri}/#{id}.json", params
+
+        puts "#{last_response.status}: #{last_response.body}" if @rack_test_rest[:debug]
+
+        if expected_code
+          assert last_response.status == expected_code
+        else
+          assert last_response.status == 204
+        end
+      end
+
+      def delete_resource(params={})
+        delete "#{resource_uri}/#{params[:id]}.json"
+
+        if params[:code]
+          assert last_response.status == params[:code]
+        else
+          assert last_response.status == 204
+        end
+      end
+
+      def paginate_resource(params={})
+
+        count = params[:count] ? params[:count] : 512
+        max = params[:max_length] ? params[:max_length] : 100
+
+        #populate the DB
+        0.upto(count - 1) do |id|
+          create_resource(yield(id))
+        end
+
+        retrieved = 0
+        offset = 0
+
+        while retrieved < count
+          # Get a random number from 1-100
+          length = rand(max - 1) + 1
+
+          expected_length = (length > (count - retrieved)) ? (count - retrieved) : length
+
+          if @rack_test_rest[:debug]
+            puts "Requesting offset='#{offset}', length='#{length}'"
+            puts "Expecting '#{expected_length}'"
+          end
+
+	  pg_resp = read_resource(:offset => offset, :length => length)
+
+          puts "Received #{pg_resp[@rack_test_rest[:resource]].count} records" if @rack_test_rest[:debug]
+          assert pg_resp[@rack_test_rest[:resource]].count == expected_length
+
+          puts "Found #{pg_resp["query"]["found"]} records" if @rack_test_rest[:debug]
+          assert pg_resp["query"]["found"] == count
+
+          assert pg_resp["query"]["total"] == count
+          assert pg_resp["query"]["length"] == expected_length
+          assert pg_resp["query"]["offset"] == offset
+
+          retrieved += expected_length
+          offset = retrieved
+        end
+      end
+
+    end
+  end
+end

data/test/helper.rb

@@ -0,0 +1,18 @@
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'test/unit'
+require 'shoulda'
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'rack-test-rest'
+
+class Test::Unit::TestCase
+end

data/test/test_rack-test-rest.rb

@@ -0,0 +1,7 @@
+require 'helper'
+
+class TestRackTestRest < Test::Unit::TestCase
+  should "probably rename this file and start testing for real" do
+    flunk "hey buddy, you should probably rename this file and start testing for real"
+  end
+end

metadata

@@ -0,0 +1,137 @@
+--- !ruby/object:Gem::Specification 
+name: rack-test-rest
+version: !ruby/object:Gem::Version 
+  hash: 27
+  prerelease: 
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Joseph Ruscio
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-04-10 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  type: :development
+  version_requirements: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  requirement: *id001
+  prerelease: false
+  name: shoulda
+- !ruby/object:Gem::Dependency 
+  type: :development
+  version_requirements: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 23
+        segments: 
+        - 1
+        - 0
+        - 0
+        version: 1.0.0
+  requirement: *id002
+  prerelease: false
+  name: bundler
+- !ruby/object:Gem::Dependency 
+  type: :development
+  version_requirements: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 7
+        segments: 
+        - 1
+        - 5
+        - 2
+        version: 1.5.2
+  requirement: *id003
+  prerelease: false
+  name: jeweler
+- !ruby/object:Gem::Dependency 
+  type: :development
+  version_requirements: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  requirement: *id004
+  prerelease: false
+  name: rcov
+description: rack-test-rest is an extension to rack-test that when combined with Test::Unit simplifies the process of unit testing properly designed RESTful API's.
+email: joe@ruscio.org
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE.txt
+- README.md
+files: 
+- .document
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- VERSION
+- lib/rack-test-rest.rb
+- test/helper.rb
+- test/test_rack-test-rest.rb
+has_rdoc: true
+homepage: http://github.com/josephruscio/rack-test-rest
+licenses: 
+- MIT
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.4.2
+signing_key: 
+specification_version: 3
+summary: Abstractions for testing RESTful API's with rack-test and Test::Unit.
+test_files: 
+- test/helper.rb
+- test/test_rack-test-rest.rb