kookaburra 0.27.0 → 1.0.0

data/Gemfile

@@ -1,17 +1,18 @@
 source 'http://rubygems.org'
 
-gem 'patron'
-gem 'json_pure'
+gem 'rest-client'
 
 # Add dependencies to develop your gem here.
 # Include everything needed to run rake, tests, features, etc.
 group :development do
+  gem 'jruby-openssl', :platforms => :jruby
   gem 'rspec'
   gem 'capybara'
   gem 'yard'
-  gem 'redcarpet', '~> 1.0' # used to format documentation
+  gem 'kramdown' # used by yard to format documentation, but not a dependency as far as the yard gem is concerned
   gem 'jeweler'
   gem 'reek'
   gem 'sinatra'
-  gem 'find_a_port', '>= 1.0.1'
+  gem 'find_a_port'
+  gem 'json'
 end

data/Gemfile.lock

@@ -2,6 +2,7 @@ GEM
   remote: http://rubygems.org/
   specs:
     addressable (2.3.2)
+    bouncy-castle-java (1.5.0146.1)
     capybara (1.1.2)
       mime-types (>= 1.16)
       nokogiri (>= 1.3.3)
@@ -9,10 +10,11 @@ GEM
       rack-test (>= 0.5.4)
       selenium-webdriver (~> 2.0)
       xpath (~> 0.1.4)
-    childprocess (0.3.4)
+    childprocess (0.3.5)
       ffi (~> 1.0, >= 1.0.6)
     diff-lcs (1.1.3)
-    ffi (1.1.0)
+    ffi (1.1.5)
+    ffi (1.1.5-java)
     find_a_port (1.0.1)
     git (1.2.5)
     jeweler (1.8.4)
@@ -20,28 +22,32 @@ GEM
       git (>= 1.2.5)
       rake
       rdoc
-    json (1.7.4)
-    json_pure (1.7.4)
+    jruby-openssl (0.7.7)
+      bouncy-castle-java (>= 1.5.0146.1)
+    json (1.7.5)
+    json (1.7.5-java)
+    kramdown (0.14.0)
     libwebsocket (0.1.5)
       addressable
     mime-types (1.19)
     multi_json (1.3.6)
     nokogiri (1.5.5)
-    patron (0.4.18)
+    nokogiri (1.5.5-java)
     rack (1.4.1)
     rack-protection (1.2.0)
       rack
-    rack-test (0.6.1)
+    rack-test (0.6.2)
       rack (>= 1.0)
     rake (0.9.2.2)
     rdoc (3.12)
       json (~> 1.4)
-    redcarpet (1.17.2)
     reek (1.2.12)
       ripper_ruby_parser (~> 0.0.7)
       ruby2ruby (~> 1.2.5)
       ruby_parser (~> 2.0)
       sexp_processor (~> 3.0)
+    rest-client (1.6.7)
+      mime-types (>= 1.16)
     ripper_ruby_parser (0.0.8)
       sexp_processor (~> 3.0)
     rspec (2.11.0)
@@ -49,9 +55,9 @@ GEM
       rspec-expectations (~> 2.11.0)
       rspec-mocks (~> 2.11.0)
     rspec-core (2.11.1)
-    rspec-expectations (2.11.2)
+    rspec-expectations (2.11.3)
       diff-lcs (~> 1.1.3)
-    rspec-mocks (2.11.1)
+    rspec-mocks (2.11.3)
     ruby2ruby (1.2.5)
       ruby_parser (~> 2.0)
       sexp_processor (~> 3.0)
@@ -64,7 +70,7 @@ GEM
       multi_json (~> 1.0)
       rubyzip
     sexp_processor (3.2.0)
-    sinatra (1.3.2)
+    sinatra (1.3.3)
       rack (~> 1.3, >= 1.3.6)
       rack-protection (~> 1.2)
       tilt (~> 1.3, >= 1.3.3)
@@ -74,16 +80,18 @@ GEM
     yard (0.8.2.1)
 
 PLATFORMS
+  java
   ruby
 
 DEPENDENCIES
   capybara
-  find_a_port (>= 1.0.1)
+  find_a_port
   jeweler
-  json_pure
-  patron
-  redcarpet (~> 1.0)
+  jruby-openssl
+  json
+  kramdown
   reek
+  rest-client
   rspec
   sinatra
   yard

data/README.markdown

@@ -3,6 +3,11 @@
 Kookaburra is a framework for implementing the [Window Driver] [Window Driver] pattern in
 order to keep acceptance tests maintainable.
 
+## Requirements ##
+
+Requires Ruby 1.9. Tested with both MRI and JRUBY (not that you must run
+JRuby in 1.9 compatability mode.)
+
 ## Installation ##
 
 Kookaburra is available as a Rubygem and [published on Rubygems.org] [Kookaburra Gem],
@@ -111,13 +116,14 @@ and shut down a Rack application server. Just add the following to
 
     require 'kookaburra/test_helpers'
     require 'thwait'
+    require 'find_a_port' # from the find_a_port gem
 
     # Change these to the files that define your custom GivenDriver and UIDriver
     # implementations.
     require 'my_app/kookaburra/given_driver'
     require 'my_app/kookaburra/ui_driver'
 
-    APP_PORT = ENV['APP_PORT'] || 3009
+    APP_PORT = FindAPort.available_port
 
     # c.app_host below should be set to whatever the root URL of your running
     # application is.
@@ -141,6 +147,10 @@ and shut down a Rack application server. Just add the following to
       c.before(:all, :type => :request) do
         # Run the server process in a forked process, and get a handle on that
         # process, so that it can be shut down after the tests run.
+        #
+        # Note that you cannot fork under JRuby and will need to use a thread.
+        # See `spec/integration/test_a_rack_application_spec.rb` for an
+        # example.
         @rack_server_pid = fork do
           Capybara.server_port = APP_PORT
           Capybara::Server.new(MyApplication).boot
@@ -205,13 +215,14 @@ and shut down a Rack application server. Just add the following to
 
     require 'kookaburra/test_helpers'
     require 'thwait'
+    require 'find_a_port' # from the find_a_port gem
 
     # Change these to the files that define your custom GivenDriver and UIDriver
     # implementations.
     require 'my_app/kookaburra/given_driver'
     require 'my_app/kookaburra/ui_driver'
 
-    APP_PORT = ENV['APP_PORT'] || 3009
+    APP_PORT = FindAPort.available_port
 
     # c.app_host below should be set to whatever the root URL of your running
     # application is.
@@ -227,12 +238,16 @@ and shut down a Rack application server. Just add the following to
 
     World(Kookaburra::TestHelpers)
 
-    # Start the application server prior to running a group of integration
-    # specs. `MyApplication` below should be replaced with the object that
+    # Start the application server prior to running the tests.
+    # `MyApplication` below should be replaced with the object that
     # implements the Rack `#call` interface for your application. For a Rails
     # app, this would be along the lines of `MyAppName::Application`.
     # Runs the server process in a forked process, and get a handle on that
     # process, so that it can be shut down after the tests run.
+    #
+    # Note that you cannot fork under JRuby and will need to use a thread.
+    # See `spec/integration/test_a_rack_application_spec.rb` for an
+    # example.
     @rack_server_pid = fork do
       Capybara.server_port = APP_PORT
       Capybara::Server.new(MyApplication).boot
@@ -519,32 +534,32 @@ rather than driving a web browser.
 
 #### API Driver ####
 
-The `Kookaburra::APIDriver` is used to interact with an application's external
-web services API. You tell Kookaburra about your API by creating a subclass of
-`Kookaburra::APIDriver` for your application. Because different applications may
-implement different types of APIs, Kookaburra will provide more than one base
-APIDriver class. At the moment, only a JSON API is supported via
-`Kookaburra::JsonApiDriver`:
+The `Kookaburra::APIDriver` is used to interact with an application's
+external web services API. You tell Kookaburra about your API by
+creating a subclass of `Kookaburra::APIDriver` for your application,
+specifying how requests should be encoded and decoded, and specifying
+any headers that should be present on every request.
 
     # lib/my_app/kookaburra/api_driver.rb
 
-    class MyApp::Kookaburra::APIDriver < Kookaburra::JsonApiDriver
+    class MyApp::Kookaburra::APIDriver < Kookaburra::APIDriver
+      encode_with { |data| JSON.dump(data) }
+      decode_with { |data| JSON.parse(data) }
+      header 'Content-Type', 'application/json'
+      header 'Accept', 'application/json'
+
       def create_account(account_data)
-        post '/api/v1/accounts', account_data
+        post '/api/accounts', account_data
       end
 
       def get_account(id)
-        get '/api/v1/accounts/%d' % id
+        get '/api/accounts/%d' % id
       end
     end
 
-Regardless of the type of APIDriver, the content of your application's APIDriver
-should consist mainly of mappings between discrete actions and HTTP requests to
-the specified URL paths. Each driver will implement `#post`, `#get`, `#put` and
-`#delete` in such a way that any Ruby data structure provided as parameters will
-be appropriately translated to the API's required data format, and any response
-body from the API request will be translated into a Ruby data structure and
-returned.
+The content of your application's APIDriver should consist mainly of
+mappings between discrete actions and HTTP requests to the specified URL
+paths.
 
 #### UI Driver ####
 
@@ -623,12 +638,13 @@ You describe the various user interface components by sub-classing
 ### The Application Driver Layer ###
 
 `Kookaburra::APIDriver`, `Kookaburra::UIDriver` and
-`Kookaburra::UIDriver::UIComponent` rely on the Application Driver layer to
-interact with your application. In the case of the `APIDriver`, Kookaburra uses
-the [Patron] [Patron] library to send HTTP requests to your application. The
-`UIDriver` and `UIComponent` rely on whatever is passed to `Kookaburra.new` as
-the `:browser` option. Presently, we have only used Capybara as the application
-driver for Kookaburra.
+`Kookaburra::UIDriver::UIComponent` rely on the Application Driver layer
+to interact with your application. In the case of the `APIDriver`,
+Kookaburra uses the [RestClient] [RestClient] library to send HTTP
+requests to your application. The `UIDriver` and `UIComponent` rely on
+whatever is passed to `Kookaburra.new` as the `:browser` option.
+Presently, we have only used Capybara as the application driver for
+Kookaburra.
 
 It's possible that something other than Capybara could be passed in, as long as
 that something presented the same API. In reality, using something other than
@@ -664,4 +680,4 @@ further details.
 [RSpec]: http://rspec.info "RSpec.info: home"
 [Cucumber]: http://cukes.info/ "Cucumber - Making BDD fun"
 [Pull Request]: https://github.com/projectdx/kookaburra/pull/new/master "Send a pull request - GitHub"
-[Patron]: https://github.com/toland/patron "toland/patron"
+[RestClient]: https://github.com/archiloque/rest-client "archiloque/rest-client -GitHub"

data/Rakefile

@@ -29,8 +29,25 @@ require 'rspec/core/rake_task'
 
 task :default => :spec
 
-desc 'Run specs'
-RSpec::Core::RakeTask.new
+# TODO: figure out how to get rake task working under JRuby and rbenv
+if defined?(JRUBY_VERSION) && ENV['RBENV_VERSION']
+  desc 'Run specs'
+  task :spec do
+    msg = <<-EOM
+    ********************************************************************************
+    * You appear to be running under JRuby and using rbenv.
+    *
+    * For some reason the `rake spec` command isn't working correctly in
+    * these circumstances. However, you should be able to just run the
+    * `rspec` command directly.
+    ********************************************************************************
+    EOM
+    raise msg
+  end
+else
+  desc 'Run specs'
+  RSpec::Core::RakeTask.new
+end
 
 require 'reek/rake/task'
 Reek::Rake::Task.new do |t|

data/VERSION

@@ -1 +1 @@
-0.27.0
+1.0.0

data/kookaburra.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = "kookaburra"
-  s.version = "0.27.0"
+  s.version = "1.0.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["John Wilger", "Sam Livingston-Gray", "Ravi Gadad"]
-  s.date = "2012-08-21"
+  s.date = "2012-10-14"
   s.description = "Cucumber + Capybara = Kookaburra? It made sense at the time."
   s.email = "johnwilger@gmail.com"
   s.extra_rdoc_files = [
@@ -35,7 +35,6 @@ Gem::Specification.new do |s|
     "lib/kookaburra/dependency_accessor.rb",
     "lib/kookaburra/exceptions.rb",
     "lib/kookaburra/given_driver.rb",
-    "lib/kookaburra/json_api_driver.rb",
     "lib/kookaburra/mental_model.rb",
     "lib/kookaburra/mental_model_matcher.rb",
     "lib/kookaburra/test_helpers.rb",
@@ -47,7 +46,6 @@ Gem::Specification.new do |s|
     "spec/integration/test_a_rack_application_spec.rb",
     "spec/kookaburra/api_driver_spec.rb",
     "spec/kookaburra/configuration_spec.rb",
-    "spec/kookaburra/json_api_driver_spec.rb",
     "spec/kookaburra/mental_model_matcher_spec.rb",
     "spec/kookaburra/mental_model_spec.rb",
     "spec/kookaburra/test_helpers_spec.rb",
@@ -70,39 +68,42 @@ Gem::Specification.new do |s|
     s.specification_version = 3
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
-      s.add_runtime_dependency(%q<patron>, [">= 0"])
-      s.add_runtime_dependency(%q<json_pure>, [">= 0"])
+      s.add_runtime_dependency(%q<rest-client>, [">= 0"])
+      s.add_development_dependency(%q<jruby-openssl>, [">= 0"])
       s.add_development_dependency(%q<rspec>, [">= 0"])
       s.add_development_dependency(%q<capybara>, [">= 0"])
       s.add_development_dependency(%q<yard>, [">= 0"])
-      s.add_development_dependency(%q<redcarpet>, ["~> 1.0"])
+      s.add_development_dependency(%q<kramdown>, [">= 0"])
       s.add_development_dependency(%q<jeweler>, [">= 0"])
       s.add_development_dependency(%q<reek>, [">= 0"])
       s.add_development_dependency(%q<sinatra>, [">= 0"])
-      s.add_development_dependency(%q<find_a_port>, [">= 1.0.1"])
+      s.add_development_dependency(%q<find_a_port>, [">= 0"])
+      s.add_development_dependency(%q<json>, [">= 0"])
     else
-      s.add_dependency(%q<patron>, [">= 0"])
-      s.add_dependency(%q<json_pure>, [">= 0"])
+      s.add_dependency(%q<rest-client>, [">= 0"])
+      s.add_dependency(%q<jruby-openssl>, [">= 0"])
       s.add_dependency(%q<rspec>, [">= 0"])
       s.add_dependency(%q<capybara>, [">= 0"])
       s.add_dependency(%q<yard>, [">= 0"])
-      s.add_dependency(%q<redcarpet>, ["~> 1.0"])
+      s.add_dependency(%q<kramdown>, [">= 0"])
       s.add_dependency(%q<jeweler>, [">= 0"])
       s.add_dependency(%q<reek>, [">= 0"])
       s.add_dependency(%q<sinatra>, [">= 0"])
-      s.add_dependency(%q<find_a_port>, [">= 1.0.1"])
+      s.add_dependency(%q<find_a_port>, [">= 0"])
+      s.add_dependency(%q<json>, [">= 0"])
     end
   else
-    s.add_dependency(%q<patron>, [">= 0"])
-    s.add_dependency(%q<json_pure>, [">= 0"])
+    s.add_dependency(%q<rest-client>, [">= 0"])
+    s.add_dependency(%q<jruby-openssl>, [">= 0"])
     s.add_dependency(%q<rspec>, [">= 0"])
     s.add_dependency(%q<capybara>, [">= 0"])
     s.add_dependency(%q<yard>, [">= 0"])
-    s.add_dependency(%q<redcarpet>, ["~> 1.0"])
+    s.add_dependency(%q<kramdown>, [">= 0"])
     s.add_dependency(%q<jeweler>, [">= 0"])
     s.add_dependency(%q<reek>, [">= 0"])
     s.add_dependency(%q<sinatra>, [">= 0"])
-    s.add_dependency(%q<find_a_port>, [">= 1.0.1"])
+    s.add_dependency(%q<find_a_port>, [">= 0"])
+    s.add_dependency(%q<json>, [">= 0"])
   end
 end
 

data/lib/kookaburra/api_driver.rb

@@ -1,91 +1,205 @@
+require 'restclient'
 require 'kookaburra/exceptions'
-require 'delegate'
-require 'patron'
 
 class Kookaburra
-  class APIDriver < SimpleDelegator
-    # Wraps `http_client` in a `SimpleDelegator` that causes request methods to
-    # either return the response body or raise an exception on an unexpected
-    # response status code.
+  # Communicate with a Web Services API
+  #
+  # You will create a subclass of `APIDriver` in your testing
+  # implementation to be used with you subclass of
+  # `Kookaburra::GivenDriver`. While the `GivenDriver` implements the
+  # "business domain" DSL for setting up your application state, the
+  # `APIDriver` maps discreet operations to your application's web
+  # service API and can (optionally) handle encoding input data and
+  # decoding response bodies to and from your preferred serialization
+  # format.
+  class APIDriver
+    class << self
+      # Serializes input data
+      #
+      # If specified, any input data provided to `APIDriver#post`,
+      # `APIDriver#put` or `APIDriver#request` will be processed through
+      # this function prior to being sent to the HTTP server.
+      #
+      # @yieldparam data [Object] The data parameter that was passed to
+      #             the request method
+      # @yieldreturn [String] The text to be used as the request body
+      #
+      # @example
+      #   class MyAPIDriver < Kookaburra::APIDriver
+      #     encode_with { |data| JSON.dump(data) }
+      #     # ...
+      #   end
+      def encode_with(&block)
+        define_method(:encode) do |data|
+          return if data.nil?
+          block.call(data)
+        end
+      end
+
+      # Deserialize response body
+      #
+      # If specified, the response bodies of all requests made using
+      # this `APIDriver` will be processed through this function prior
+      # to being returned.
+      #
+      # @yieldparam data [String] The response body sent by the HTTP
+      #             server
+      #
+      # @yieldreturn [Object] The result of parsing the response body
+      #              through this function
+      #
+      # @example
+      #   class MyAPIDriver < Kookaburra::APIDriver
+      #     decode_with { |data| JSON.parse(data) }
+      #     # ...
+      #   end
+      def decode_with(&block)
+        define_method(:decode) do |data|
+          block.call(data)
+        end
+      end
+
+      # Set custom HTTP headers
+      #
+      # Can be called multiple times to set HTTP headers that will be
+      # provided with every request made by the `APIDriver`.
+      #
+      # @param [String] name The name of the header, e.g. 'Content-Type'
+      # @param [String] value The value to which the header is set
+      #
+      # @example
+      #   class MyAPIDriver < Kookaburra::APIDriver
+      #     header 'Content-Type', 'application/json'
+      #     header 'Accept', 'application/json'
+      #     # ...
+      #   end
+      def header(name, value)
+        headers[name] = value
+      end
+
+      # Used to retrieve the list of headers within the instance. Not
+      # intended to be used elsewhere.
+      #
+      # @private
+      def headers
+        @headers ||= {}
+      end
+    end
+
+    # Create a new `APIDriver` instance
     #
     # @param [Kookaburra::Configuration] configuration
-    # @param [Patron::Session] http_client
-    def initialize(configuration, http_client = Patron::Session.new)
-      http_client.base_url = configuration.app_host
-      super(http_client)
+    # @param [RestClient] http_client (optional) Generally only
+    #        overriden when testing Kookaburra itself
+    def initialize(configuration, http_client = RestClient)
+      @configuration = configuration
+      @http_client = http_client
     end
 
-    # Makes a POST request via the `:http_client`
+    # Convenience method to make a POST request
     #
-    # @param [String] path The path to request (e.g. "/foo")
-    # @param [Hash, String] data The post data. If a Hash is provided, it will
-    #   be converted to an 'application/x-www-form-urlencoded' post body.
-    # @option options [Integer] :expected_response_status (201) The HTTP status
-    #   code that you expect the server to respond with.
-    # @raise [Kookaburra::UnexpectedResponse] raised if the HTTP status of the
-    #   response does not match the `:expected_response_status`
-    def post(path, data, options = {})
-      request(:post, path, options, data)
+    # @see APIDriver#request
+    def post(path, data)
+      request(:post, path, data)
     end
 
-    # Makes a PUT request via the `:http_client`
+    # Convenience method to make a PUT request
     #
-    # @param [String] path The path to request (e.g. "/foo")
-    # @param [Hash, String] data The post data. If a Hash is provided, it will
-    #   be converted to an 'application/x-www-form-urlencoded' post body.
-    # @option options [Integer] :expected_response_status (201) The HTTP status
-    #   code that you expect the server to respond with.
-    # @raise [Kookaburra::UnexpectedResponse] raised if the HTTP status of the
-    #   response does not match the `:expected_response_status`
-    def put(path, data, options = {})
-      request(:put, path, options, data)
+    # @see APIDriver#request
+    def put(path, data)
+      request(:put, path, data)
     end
 
-    # Makes a GET request via the `:http_client`
+    # Convenience method to make a GET request
     #
-    # @param [String] path The path to request (e.g. "/foo")
-    # @option options [Integer] :expected_response_status (201) The HTTP status
-    #   code that you expect the server to respond with.
-    # @raise [Kookaburra::UnexpectedResponse] raised if the HTTP status of the
-    #   response does not match the `:expected_response_status`
-    def get(path, options = {})
-      request(:get, path, options)
+    # @see APIDriver#request
+    def get(path)
+      request(:get, path)
     end
 
-    # Makes a DELETE request via the `:http_client`
+    # Convenience method to make a DELETE request
+    #
+    # @see APIDriver#request
+    def delete(path)
+      request(:delete, path)
+    end
+
+    # Make an HTTP request
+    #
+    # If you need to make a request other than the typical GET, POST,
+    # PUT and DELETE, you can use this method directly.
+    #
+    # This *will* follow redirects when the server's response code is in
+    # the 3XX range. If the response is a 303, the request will be
+    # transformed into a GET request.
     #
-    # @param [String] path The path to request (e.g. "/foo")
-    # @option options [Integer] :expected_response_status (201) The HTTP status
-    #   code that you expect the server to respond with.
-    # @raise [Kookaburra::UnexpectedResponse] raised if the HTTP status of the
-    #   response does not match the `:expected_response_status`
-    def delete(path, options = {})
-      request(:delete, path, options)
+    # @see APIDriver.encode_with
+    # @see APIDriver.decode_with
+    # @see APIDriver.header
+    # @see APIDriver#get
+    # @see APIDriver#post
+    # @see APIDriver#put
+    # @see APIDriver#delete
+    #
+    # @param [Symbol] method The HTTP verb to use with the request
+    # @param [String] path The path to request. Will be joined with the
+    #        `Kookaburra::Configuration#app_host` setting to build the
+    #        URL unless a full URL is specified here.
+    # @param [Object] data The data to be posted in the request body. If
+    #        an encoder was specified, this can be any type of object as
+    #        long as the encoder can serialize it into a String. If no
+    #        encoder was specified, then this can be one of:
+    #
+    #        * a String - will be passed as is
+    #        * a Hash - will be encoded as normal HTTP form params
+    #        * a Hash containing references to one or more Files - will
+    #          set the content type to multipart/form-data
+    #
+    # @return [Object] The response body returned by the server. If a
+    #         decoder was specified, this will return the result of
+    #         parsing the response body through the decoder function.
+    #
+    # @raise [Kookaburra::UnexpectedResponse] Raised if the HTTP
+    #        response received is not in the 2XX-3XX range.
+    def request(method, path, data = nil)
+      data = encode(data)
+      response = @http_client.send(method, url_for(path), *[data, headers].compact)
+      decode(response.body)
+    rescue RestClient::Exception => e
+      raise_unexpected_response(e)
     end
 
     private
 
-    def request(type, path, options = {}, data = nil)
-      # don't send a data argument if it's not passed in, because some methods
-      # on target object may not have the proper arity (i.e. #get and #delete).
-      if path.nil?
-        raise ArgumentError, "You must specify a request URL, but it was nil."
-      end
-      args = [type, path, data, options].compact
-      response = __getobj__.send(*args)
+    def headers
+      self.class.headers
+    end
 
-      check_response_status!(type, response, options)
-      response.body
+    def url_for(path)
+      URI.join(base_url, path).to_s
     end
 
-    def check_response_status!(request_type, response, options)
-      verb = request_type.to_s.upcase
-      expected_status = options[:expected_response_status] || (200..299)
-      unless expected_status === response.status
-        raise UnexpectedResponse, "#{verb} to #{response.url} responded with " \
-          + "#{response.status} status, not #{expected_status} as expected\n\n" \
-          + response.body
-      end
+    def base_url
+      @configuration.app_host
+    end
+
+    def encode(data)
+      data
+    end
+
+    def decode(data)
+      data
+    end
+
+    def raise_unexpected_response(exception)
+      message = <<-END
+      Unexpected response from server: #{exception.message}
+
+      #{exception.http_body}
+      END
+      new_exception = UnexpectedResponse.new(message)
+      new_exception.set_backtrace(exception.backtrace)
+      raise new_exception
     end
   end
 end

data/lib/kookaburra/given_driver.rb

@@ -5,7 +5,7 @@ class Kookaburra
   # test preconditions. Unlike {Kookaburra::APIDriver}, which is meant to be a
   # simple mapping to your application's API, a method in the GivenDriver may be
   # comprised of several distinct API calls as well as access to Kookaburra's
-  # test data store.
+  # test data store via `#mental_model`.
   #
   # @abstract Subclass and implement your Given DSL.
   #

data/spec/integration/test_a_rack_application_spec.rb

@@ -1,5 +1,5 @@
 require 'kookaburra/test_helpers'
-require 'kookaburra/json_api_driver'
+require 'kookaburra/api_driver'
 require 'capybara'
 require 'thwait'
 require 'find_a_port'
@@ -182,7 +182,12 @@ describe "testing a Rack application with Kookaburra" do
         end
       end
 
-      class MyAPIDriver < Kookaburra::JsonApiDriver
+      class MyAPIDriver < Kookaburra::APIDriver
+        encode_with { |data| JSON.dump(data) }
+        decode_with { |data| JSON.parse(data) }
+        header 'Content-Type', 'application/json'
+        header 'Accept', 'application/json'
+
         def create_user(user_data)
           post '/users', user_data
         end
@@ -315,17 +320,29 @@ describe "testing a Rack application with Kookaburra" do
       end
 
       before(:all) do
-        @rack_server_pid = fork do
+        start_server = lambda {
           Capybara.server_port = APP_PORT
           Capybara::Server.new(JsonApiApp.new).boot
           ThreadsWait.all_waits(Thread.list)
+        }
+        if defined?(JRUBY_VERSION)
+          # Can't `fork` in JRuby. This doesn't provide the state
+          # isolation that you get with forking (AFAIK, I'm no JVM
+          # expert, though), but it lets the tests run and pass.
+          Thread.new { start_server.call }
+        else
+          @rack_server_pid = fork do
+            start_server.call
+          end
         end
         sleep 1 # Give the server a chance to start up.
       end
 
       after(:all) do
-        Process.kill(9, @rack_server_pid)
-        Process.wait
+        unless defined?(JRUBY_VERSION)
+          Process.kill(9, @rack_server_pid)
+          Process.wait
+        end
       end
 
       it "runs the tests against the app" do

data/spec/kookaburra/api_driver_spec.rb

@@ -1,159 +1,102 @@
 require 'kookaburra/api_driver'
 
 describe Kookaburra::APIDriver do
+  def url_for(uri)
+    URI.join('http://example.com', uri).to_s
+  end
+
   let(:configuration) { stub('Configuration', :app_host => 'http://example.com') }
 
   let(:api) { Kookaburra::APIDriver.new(configuration, client) }
 
-  let(:response) {
-    stub('Patron::Response', :body => 'foo', :status => 200, :url => '/foo')
-  }
+  let(:response) { stub('RestClient::Response', body: 'foo', code: 200) }
 
-  let(:client) {
-         mock('Patron::Session', :post => response, :get => response,
-         :put => response, :delete => response, :base_url= => nil)
-  }
-
-  describe '#initialize' do
-    it 'instantiates a new http client if no :http_client option is passed' do
-      Patron::Session.should_receive(:new).and_return(stub.as_null_object)
-      Kookaburra::APIDriver.new(configuration)
-    end
+  let(:client) { stub('RestClient') }
 
-    it 'does not instantiate a new http client if an :http_client option is passed' do
-      Patron::Session.should_receive(:new).never
-      Kookaburra::APIDriver.new(configuration, client)
-    end
+  it 'sends POST requests to the server and returns the response body' do
+    client.should_receive(:post).with(url_for('/foo'), 'bar', {}) \
+      .and_return(response)
+    api.post('/foo', 'bar').should == 'foo'
   end
 
-  describe '#post' do
-    before(:each) do
-      response.stub!(:status => 201)
-    end
-
-    it 'delegates to the http client' do
-      client.should_receive(:post).with('/foo', 'bar', {}) \
-        .and_return(response)
-      api.post('/foo', 'bar')
-    end
-
-    it 'returns the response body' do
-      api.post('/foo', 'bar').should == 'foo'
-    end
-
-    it 'does not raise an UnexpectedResponse if the response status matches the specified expectation' do
-      response.stub!(:status => 666)
-      lambda { api.post('/foo', 'bar', :expected_response_status => 666) } \
-        .should_not raise_error
-    end
-
-    it 'raises an UnexpectedResponse if the response status is not the specified status' do
-      lambda { api.post('/foo', 'bar', :expected_response_status => 666) } \
-        .should raise_error(Kookaburra::UnexpectedResponse,
-                            "POST to /foo responded with 201 status, not 666 as expected\n\nfoo")
-    end
-
-    it 'is OK by default with a response status of 201' do
-      lambda { api.post('/foo', 'bar') } \
-        .should_not raise_error(Kookaburra::UnexpectedResponse)
-    end
-
-    it 'is OK by default with a response status of 200' do
-      response.stub!(:status => 200)
-      lambda { api.post('/foo', 'bar') } \
-        .should_not raise_error(Kookaburra::UnexpectedResponse)
-    end
-
-    it 'raises an ArgumentError with a useful message if no request path is specified' do
-      lambda { api.post(nil, 'bar') } \
-        .should raise_error(ArgumentError, "You must specify a request URL, but it was nil.")
-    end
+  it 'sends PUT requests to the server and returns the response body' do
+    client.should_receive(:put).with(url_for('/foo'), 'bar', {}) \
+      .and_return(response)
+    api.put('/foo', 'bar').should == 'foo'
   end
 
-  describe '#put' do
-    it 'delegates to the http client' do
-      client.should_receive(:put).with('/foo', 'bar', {}) \
-        .and_return(response)
-      api.put('/foo', 'bar')
-    end
-
-    it 'returns the response body' do
-      api.put('/foo', 'bar').should == 'foo'
-    end
-
-    it 'does not raise an UnexpectedResponse if the response status matches the specified expectation' do
-      response.stub!(:status => 666)
-      lambda { api.put('/foo', 'bar', :expected_response_status => 666) } \
-        .should_not raise_error
-    end
-
-    it 'raises an UnexpectedResponse if the response status is not the specified status' do
-      lambda { api.put('/foo', 'bar', :expected_response_status => 666) } \
-        .should raise_error(Kookaburra::UnexpectedResponse,
-                            "PUT to /foo responded with 200 status, not 666 as expected\n\nfoo")
-    end
-
-    it 'raises an ArgumentError with a useful message if no request path is specified' do
-      lambda { api.put(nil, 'bar') } \
-        .should raise_error(ArgumentError, "You must specify a request URL, but it was nil.")
-    end
+  it 'sends GET requests to the server and returns the response body' do
+    client.should_receive(:get).with(url_for('/foo'), {}) \
+      .and_return(response)
+    api.get('/foo').should == 'foo'
   end
 
-  describe '#get' do
-    it 'delegates to the http client' do
-      client.should_receive(:get).with('/foo', {}) \
-        .and_return(response)
-      api.get('/foo')
-    end
-
-    it 'returns the response body' do
-      api.get('/foo').should == 'foo'
-    end
-
-    it 'does not raise an UnexpectedResponse if the response status matches the specified expectation' do
-      response.stub!(:status => 666)
-      lambda { api.get('/foo', :expected_response_status => 666) } \
-        .should_not raise_error
-    end
-
-    it 'raises an UnexpectedResponse if the response status is not the specified status' do
-      lambda { api.get('/foo', :expected_response_status => 666) } \
-        .should raise_error(Kookaburra::UnexpectedResponse,
-                            "GET to /foo responded with 200 status, not 666 as expected\n\nfoo")
-    end
-
-    it 'raises an ArgumentError with a useful message if no request path is specified' do
-      lambda { api.get(nil) } \
-        .should raise_error(ArgumentError, "You must specify a request URL, but it was nil.")
-    end
+  it 'sends DELETE requests to the server and returns the response body' do
+    client.should_receive(:delete).with(url_for('/foo'), {}) \
+      .and_return(response)
+    api.delete('/foo').should == 'foo'
   end
 
-  describe '#delete' do
-    it 'delegates to the http client' do
-      client.should_receive(:delete).with('/foo', {}) \
-        .and_return(response)
-      api.delete('/foo')
+  describe 'any type of HTTP request' do
+    before(:each) do
+      client.stub!(:http_verb => response)
     end
 
     it 'returns the response body' do
-      api.delete('/foo').should == 'foo'
-    end
-
-    it 'does not raise an UnexpectedResponse if the response status matches the specified expectation' do
-      response.stub!(:status => 666)
-      lambda { api.delete('/foo', :expected_response_status => 666) } \
-        .should_not raise_error
-    end
-
-    it 'raises an UnexpectedResponse if the response status is not the specified status' do
-      lambda { api.delete('/foo', :expected_response_status => 666) } \
-        .should raise_error(Kookaburra::UnexpectedResponse,
-                            "DELETE to /foo responded with 200 status, not 666 as expected\n\nfoo")
-    end
-
-    it 'raises an ArgumentError with a useful message if no request path is specified' do
-      lambda { api.delete(nil) } \
-        .should raise_error(ArgumentError, "You must specify a request URL, but it was nil.")
+      api.request(:http_verb, '/foo', 'bar').should == 'foo'
+    end
+
+    it 'raises an UnexpectedResponse if the request is not successful' do
+      response.stub!(code: 500)
+      client.stub!(:http_verb).and_raise(RestClient::Exception.new(response))
+      lambda { api.request(:http_verb, '/foo') } \
+        .should raise_error(Kookaburra::UnexpectedResponse)
+    end
+
+    context 'when custom headers are specified' do
+      let(:api) {
+        klass = Class.new(Kookaburra::APIDriver) do
+          header 'Header-Foo', 'Baz'
+          header 'Header-Bar', 'Bam'
+        end
+        klass.new(configuration, client)
+      }
+
+      it "sets headers on requests" do
+        client.should_receive(:http_verb).with(url_for('/foo'), {}, 'Header-Foo' => 'Baz', 'Header-Bar' => 'Bam')
+        api.request(:http_verb, '/foo', {})
+      end
+    end
+
+    context 'when a custom encoder is specified' do
+      let(:api) {
+        klass = Class.new(Kookaburra::APIDriver) do
+          encode_with { |data| :some_encoded_data }
+        end
+        klass.new(configuration, client)
+      }
+
+      it "encodes input to requests" do
+        client.should_receive(:http_verb) do |_, data, _|
+          data.should == :some_encoded_data
+          response
+        end
+
+        api.request(:http_verb, '/foo', :ruby_data)
+      end
+    end
+
+    context 'when a custom decoder is specified' do
+      let(:api) {
+        klass = Class.new(Kookaburra::APIDriver) do
+        decode_with { |data| :some_decoded_data }
+        end
+        klass.new(configuration, client)
+      }
+
+      it "decodes response bodies from requests" do
+        api.request(:http_verb, '/foo').should == :some_decoded_data
+      end
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kookaburra
 version: !ruby/object:Gem::Version
-  version: 0.27.0
+  version: 1.0.0
   prerelease: 
 platform: ruby
 authors:
@@ -11,10 +11,10 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-08-21 00:00:00.000000000 Z
+date: 2012-10-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: patron
+  name: rest-client
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
@@ -30,14 +30,14 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: json_pure
+  name: jruby-openssl
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
-  type: :runtime
+  type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     none: false
@@ -94,21 +94,21 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: redcarpet
+  name: kramdown
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ~>
+    - - ! '>='
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ~>
+    - - ! '>='
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: jeweler
   requirement: !ruby/object:Gem::Requirement
@@ -164,7 +164,7 @@ dependencies:
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: 1.0.1
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -172,7 +172,23 @@ dependencies:
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: 1.0.1
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Cucumber + Capybara = Kookaburra? It made sense at the time.
 email: johnwilger@gmail.com
 executables: []
@@ -199,7 +215,6 @@ files:
 - lib/kookaburra/dependency_accessor.rb
 - lib/kookaburra/exceptions.rb
 - lib/kookaburra/given_driver.rb
-- lib/kookaburra/json_api_driver.rb
 - lib/kookaburra/mental_model.rb
 - lib/kookaburra/mental_model_matcher.rb
 - lib/kookaburra/test_helpers.rb
@@ -211,7 +226,6 @@ files:
 - spec/integration/test_a_rack_application_spec.rb
 - spec/kookaburra/api_driver_spec.rb
 - spec/kookaburra/configuration_spec.rb
-- spec/kookaburra/json_api_driver_spec.rb
 - spec/kookaburra/mental_model_matcher_spec.rb
 - spec/kookaburra/mental_model_spec.rb
 - spec/kookaburra/test_helpers_spec.rb
@@ -238,7 +252,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -3018150638405994021
+      hash: -1361909781639378810
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:

data/lib/kookaburra/json_api_driver.rb

@@ -1,65 +0,0 @@
-require 'delegate'
-require 'json'
-require 'kookaburra/api_driver'
-
-class Kookaburra
-  # Delegates all methods (by default) to and instance of
-  # {Kookaburra::APIDriver}.
-  #
-  # Expects the application's API to accept and respond with JSON formatted
-  # data. All methods will decode the response body using
-  # `ActiveSupport::JSON.decode`. Methods that take input data ({#post} and
-  # {#put}) will encode the post data using `ActiveSupport::JSON.encode`.
-  class JsonApiDriver < SimpleDelegator
-    #
-    # Sets both the "Content-Type" and "Accept" headers to "application/json".
-    #
-    # @param [Kookaburra::Configuration] configuration
-    # @param [Kookaburra::APIDriver] api_driver (Kookaburra::APIDriver.new)
-    #   The APIDriver instance to be delegated to. Changing this is probably
-    #   only useful for testing Kookaburra itself.
-    def initialize(configuration, api_driver = nil)
-      api_driver = api_driver || APIDriver.new(configuration)
-      api_driver.headers.merge!(
-        'Content-Type' => 'application/json',
-        'Accept' => 'application/json'
-      )
-      super(api_driver)
-    end
-
-    def post(path, data, *args)
-      request(:post, path, data, *args)
-    end
-
-    def put(path, data, *args)
-      request(:put, path, data, *args)
-    end
-
-    def get(path, *args)
-      request(:get, path, nil, *args)
-    end
-
-    def delete(path, *args)
-      request(:delete, path, nil, *args)
-    end
-
-    private
-
-    def request(type, path, data = nil, *args)
-      # don't want to send data to methods that don't accept it
-      args = [path, *([encode(data), args].reject(&:nil?))].flatten
-
-      output = __getobj__.send(type, *args)
-
-      decode(output)
-    end
-
-    def encode(data)
-      JSON.dump(data) unless data.nil?
-    end
-
-    def decode(data)
-      JSON.parse(data)
-    end
-  end
-end

data/spec/kookaburra/json_api_driver_spec.rb

@@ -1,95 +0,0 @@
-require 'kookaburra/json_api_driver'
-
-describe Kookaburra::JsonApiDriver do
-  let(:response) { '{"foo":"bar"}' }
-
-  let(:api) {
-    stub('APIDriver', :get => response, :post => response, :put => response,
-         :delete => response, :headers => {})
-  }
-
-  let(:configuration) {
-    stub('Configuration')
-  }
-
-  let(:json) { Kookaburra::JsonApiDriver.new(stub('Configuration'), api) }
-
-  describe '#initialize' do
-    it 'instantiates a new APIDriver if no :api_driver option is passed' do
-      Kookaburra::APIDriver.should_receive(:new) \
-        .with(configuration) \
-        .and_return(api)
-      Kookaburra::JsonApiDriver.new(configuration)
-    end
-
-    it 'does not instantiate a new APIDriver if an :api_driver option is passed' do
-      Kookaburra::APIDriver.should_receive(:new).never
-      Kookaburra::JsonApiDriver.new(configuration, api)
-    end
-
-    it 'sets appropriate headers for a JSON API request' do
-      Kookaburra::JsonApiDriver.new(configuration, api)
-      api.headers.should == {
-        'Content-Type' => 'application/json',
-        'Accept' => 'application/json'
-      }
-    end
-  end
-
-  it 'delegates to a Kookaburra::APIDriver by default' do
-    api.stub!(:foo => :bar)
-    json.foo.should == :bar
-  end
-
-  describe '#post' do
-    it 'delegates to the api driver as a JSON request' do
-      api.should_receive(:post) \
-        .with('/foo', '{"foo":"bar"}') \
-        .and_return('{"baz":"bam"}')
-      json.post('/foo', 'foo' => 'bar')
-    end
-
-    it 'returns the JSON-decoded response body' do
-      json.post('/foo', :bar => :baz).should == {'foo' => 'bar'}
-    end
-  end
-
-  describe '#put' do
-    it 'delegates to the api driver as a JSON request' do
-      api.should_receive(:put) \
-        .with('/foo', '{"foo":"bar"}') \
-        .and_return('{"baz":"bam"}')
-      json.put('/foo', 'foo' => 'bar')
-    end
-
-    it 'returns the JSON-decoded response body' do
-      json.put('/foo', :bar => :baz).should == {'foo' => 'bar'}
-    end
-  end
-
-  describe '#get' do
-    it 'delegates to the api driver as a JSON request' do
-      api.should_receive(:get) \
-        .with('/foo') \
-        .and_return('{"baz":"bam"}')
-      json.get('/foo')
-    end
-
-    it 'returns the JSON-decoded response body' do
-      json.get('/foo').should == {'foo' => 'bar'}
-    end
-  end
-
-  describe '#delete' do
-    it 'delegates to the api driver as a JSON request' do
-      api.should_receive(:delete) \
-        .with('/foo') \
-        .and_return('{"baz":"bam"}')
-      json.delete('/foo')
-    end
-
-    it 'returns the JSON-decoded response body' do
-      json.delete('/foo').should == {'foo' => 'bar'}
-    end
-  end
-end