kookaburra 0.18.3 → 0.20.0

data/lib/kookaburra.rb

@@ -1,5 +1,5 @@
 require 'kookaburra/exceptions'
-require 'kookaburra/test_data'
+require 'kookaburra/mental_model'
 require 'kookaburra/given_driver'
 require 'kookaburra/ui_driver'
 
@@ -29,33 +29,33 @@ class Kookaburra
   # Returns a new Kookaburra instance that wires together your application's
   # APIDriver, GivenDriver, and UIDriver.
   #
-  # @option options [Class] :api_driver_class Your application's
-  #   subclass of {Kookaburra::APIDriver}. At the moment, only the
-  #   {Kookaburra::JsonApiDriver} is implemented
   # @option options [Class] :given_driver_class Your
   #   application's subclass of {Kookaburra::GivenDriver}
   # @option options [Class] :ui_driver_class Your application's
   #   subclass of {Kookaburra::UIDriver}
-  # @option options [Capybara::Session] :browser (optional) The browser driver
+  # @option options [Capybara::Session] :browser The browser driver
   #   that Kookaburra will interact with to run the tests.
-  # @option options [#call] :rack_app (optional) The Rack application to test
-  #   against.
+  # @option options [String] :app_host The URL of your running application
+  #   server against which the tests will be run (e.g.
+  #   "http://my_app.example.com:12345")
+  # @option options [Proc] :server_error_detection A proc that will receive the
+  #   object passed in to the :browser option as an argument and must return
+  #   `true` if the server responded with an unexpected error or `false` if it
+  #   did not.
   def initialize(options = {})
-    @api_driver_class       = options[:api_driver_class]
     @given_driver_class     = options[:given_driver_class]
     @ui_driver_class        = options[:ui_driver_class]
     @browser                = options[:browser]
-    @rack_app               = options[:rack_app]
+    @app_host               = options[:app_host]
     @server_error_detection = options[:server_error_detection]
   end
 
   # Returns an instance of your GivenDriver class configured to share test
-  # fixture data with the UIDriver and to use your APIDriver class to
-  # communicate with your application
+  # fixture data with the UIDriver
   #
   # @return [Kookaburra::GivenDriver]
   def given
-    given_driver_class.new(:test_data => test_data, :api => api)
+    given_driver_class.new(:mental_model => mental_model, :app_host => @app_host)
   end
 
   # Returns an instance of your UIDriver class configured to share test fixture
@@ -64,18 +64,19 @@ class Kookaburra
   #
   # @return [Kookaburra::UIDriver]
   def ui
-    ui_driver_class.new(:test_data => test_data,
+    ui_driver_class.new(:mental_model => mental_model,
                         :browser => browser,
+                        :app_host => @app_host,
                         :server_error_detection => @server_error_detection)
   end
 
-  # Returns a frozen copy of the specified test fixture data collection.
+  # Returns a frozen copy of the specified {MentalModel::Collection}.
   # However, this is neither a deep copy nor a deep freeze, so it is possible
   # that you could modify data outside of your GivenDriver or UIDriver. Just
   # don't do that. Trust me.
   #
-  # This access is provided so that you can reference the current fixture data
-  # within your test implementation in order to make assertions about the state
+  # This access is provided so that you can reference the current mental model
+  # within your test implementation and make assertions about the state
   # of your application's interface.
   #
   # @example
@@ -83,28 +84,18 @@ class Kookaburra
   #   ui.create_a_new_widget(:bar)
   #   ui.widget_list.widgets.should == k.get_data(:widgets).slice(:foo, :bar)
   #
-  # @return [Kookaburra::TestData::Collection]
+  # @return [Kookaburra::MentalModel::Collection]
   def get_data(collection_name)
-    test_data.send(collection_name).dup.freeze
+    mental_model.send(collection_name).dup.freeze
   end
 
   private
 
   extend DependencyAccessor
-  dependency_accessor :given_driver_class, :api_driver_class, :ui_driver_class
+  dependency_accessor :given_driver_class, :ui_driver_class
 
-  def api
-    api_driver_class.new(application_driver)
-  end
-
-  def application_driver
-    unless @rack_app.nil?
-      RackDriver.new(@rack_app)
-    end
-  end
-
-  def test_data
-    @test_data ||= TestData.new
+  def mental_model
+    @mental_model ||= MentalModel.new
   end
 
   def browser

data/lib/kookaburra/api_driver.rb

@@ -1,16 +1,100 @@
+require 'kookaburra/exceptions'
+require 'delegate'
+require 'patron'
+
 class Kookaburra
-  # This class currently exists only so that, in documentation, we can refer to
-  # the generic APIDriver rather than the specific {Kookaburra::JsonApiDriver},
-  # which is currently the only implementation. Once another APIDriver
-  # implementation is added to Kookaburra, anything it has in common with
-  # {Kookaburra::JsonApiDriver} should be factored up into this class.
-  #
-  # @abstract Subclass and provide an API client implementation
-  class APIDriver
-    # Returns a new APIDriver.
+  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.
     #
-    # @param args Not actually used, but takes any arguments
-    def initialize(*args)
+    # @option options [String] :app_host The root URL of your running
+    #   application (e.g. "http://my_app.example.com:12345")
+    # @option options [Patron::Session] :http_client (Patron::Session.new) The
+    #   object responsible for actually making HTTP calls to your application.
+    def initialize(options = {})
+      http_client = options[:http_client] || Patron::Session.new
+      http_client.base_url = options[:app_host] if options.has_key?(:app_host)
+      super(http_client)
+    end
+
+    # Makes a POST request via the `:http_client`
+    #
+    # @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)
+    end
+
+    # Makes a PUT request via the `:http_client`
+    #
+    # @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)
+    end
+
+    # Makes a GET request via the `:http_client`
+    #
+    # @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)
+    end
+
+    # Makes a DELETE request via the `:http_client`
+    #
+    # @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)
+    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).
+      args = [type, path, data, options].compact
+      response = __getobj__.send(*args)
+
+      check_response_status!(type, response, options)
+      response.body
+    end
+
+    def check_response_status!(request_type, response, options)
+      verb, default_status = verb_map[request_type]
+      expected_status = options[:expected_response_status] || default_status
+      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
+    end
+
+    def verb_map 
+      {
+        :get => ['GET', 200],
+        :post => ['POST', 201],
+        :put => ['PUT', 200],
+        :delete => ['DELETE', 200]
+      }
     end
   end
 end

data/lib/kookaburra/given_driver.rb

@@ -7,12 +7,17 @@ class Kookaburra
   # comprised of several distinct API calls as well as access to Kookaburra's
   # test data store.
   #
-  # @abstract Subclass and implement your Given DSL
+  # @abstract Subclass and implement your Given DSL. You must also provide an
+  #   implementation of #api that returns an instance of your APIDriver.
   #
   # @example GivenDriver subclass
   #   module MyApp
   #     module Kookaburra
   #       class GivenDriver < ::Kookaburra::GivenDriver
+  #         def api
+  #           @api ||= APIDriver.new(:app_host => initialization_options[:app_host])
+  #         end
+  #
   #         def a_widget(name, attributes = {})
   #           # Set up the data that will be passed to the API by merging any
   #           # passed attributes into the default data.
@@ -21,9 +26,9 @@ class Kookaburra
   #           # Call the API method and get the resulting response as Ruby data.
   #           result = api.create_widget(data)
   #
-  #           # Store the resulting widget data in the TestData object, so that
+  #           # Store the resulting widget data in the MentalModel object, so that
   #           # it can be referenced in other operations.
-  #           test_data.widgets[name] = result
+  #           mental_model.widgets[name] = result
   #         end
   #       end
   #     end
@@ -34,27 +39,38 @@ class Kookaburra
     # It is unlikely that you would call #initialize yourself; your GivenDriver
     # object is instantiated for you by {Kookaburra#given}.
     #
-    # @option options [Kookaburra::TestData] the test data store
-    # @option options [Kookaburra::APIDriver] the APIDriver subclass to be used
+    # @option options [Kookaburra::MentalModel] :mental_model the MentalModel
+    #   instance used by your tests
+    # @option options [String] :app_host The root URL of your running
+    #   application (e.g. "http://my_app.example.com:12345")
     def initialize(options = {})
-      @test_data = options[:test_data]
-      @api       = options[:api]
+      @initialization_options = options
+      @mental_model = options[:mental_model]
     end
 
     protected
 
-    # A reference to the {Kookaburra::TestData} object that this GivenDriver
-    # instance was created with.
+    # Used to access your APIDriver in your own GivenDriver implementation
     #
-    # @attribute [r]
-    # @return [Kookaburra::TestData]
-    dependency_accessor :test_data
+    # @abstract
+    # @return [Kookaburra::APIDriver]
+    # @raise [Kookaburra::ConfigurationError] raised if you do not provide an
+    #   implementation.
+    def api
+      raise ConfigurationError, "You must implement #api in your subclass."
+    end
 
-    # A reference to the {Kookaburra::APIDriver} that this GivenDriver instance
-    # was created with.
+    # The full set of options passed in to {#initialize}
+    #
+    # Access is provided so that you can use these when instantiating your
+    # {APIDriver} in your {#api} implementation.
+    attr_reader :initialization_options
+
+    # A reference to the {Kookaburra::MentalModel} object that this GivenDriver
+    # instance was created with.
     #
     # @attribute [r]
-    # @return [Kookaburra::APIDriver]
-    dependency_accessor :api
+    # @return [Kookaburra::MentalModel]
+    dependency_accessor :mental_model
   end
 end

data/lib/kookaburra/json_api_driver.rb

@@ -1,90 +1,63 @@
-require 'kookaburra/dependency_accessor'
-require 'kookaburra/rack_driver'
 require 'kookaburra/api_driver'
+require 'delegate'
 require 'active_support/json'
 
 class Kookaburra
-  # Use this for your APIDriver base class if your application implements a JSON
-  # webservice API. The JsonApiDriver abstracts away the details of translating
-  # JSON <-> Ruby and setting the necessary request headers.
+  # Delegates all methods (by default) to and instance of
+  # {Kookaburra::APIDriver}.
   #
-  # @example Create a widget via API
-  #   module MyApp
-  #     module Kookaburra
-  #       class APIDriver < ::Kookaburra::JsonApiDriver
-  #         def create_widget(data)
-  #           post '/widgets', data
-  #         end
-  #       end
-  #     end
-  #   end
-  #
-  # @note This implementation uses `ActiveSupport::JSON` to handle JSON
-  #   translation.
-  class JsonApiDriver < APIDriver
-    # @private
-    J = ActiveSupport::JSON
-
-    # @param [Kookaburra::RackDriver] app_driver
-    def initialize(app_driver)
-      @app_driver = app_driver
+  # 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".
+    #
+    # @option options [Kookaburra::APIDriver] :api_driver (Kookaburra::APIDriver.new)
+    #   The APIDriver instance to be delegated to. Changing this is probably
+    #   only useful for testing.
+    def initialize(options = {})
+      api_driver = options[:api_driver] || APIDriver.new(:app_host => options[:app_host])
+      api_driver.headers.merge!(
+        'Content-Type' => 'application/json',
+        'Accept' => 'application/json'
+      )
+      super(api_driver)
     end
 
-    protected
+    def post(path, data, *args)
+      request(:post, path, data, *args)
+    end
 
-    # Sets headers for HTTP Basic authentication if your application requires
-    # it.
-    #
-    # @example
-    #   def create_widget(data)
-    #     authorize('api_user', 'api_password')
-    #     post '/widgets', data
-    #   end
-    #
-    # @param [String] username
-    # @param [String] password
-    def authorize(username, password)
-      @app_driver.authorize(username, password)
+    def put(path, data, *args)
+      request(:put, path, data, *args)
     end
 
-    # Make a JSON post request to the server
-    #
-    # @param [String] path The path portion of the URI that should be requested
-    # @param [Hash] data The data that should be translated into a JSON post
-    #   body for the request.
-    #
-    # @return [Hash] The decoded response from the server
-    #
-    # @example
-    #   # in your JsonApiDriver subclass
-    #   def create_widget(data)
-    #     post '/widgets', data
-    #   end
-    #
-    #   # in a method within your GivenDriver
-    #   api.create_widget(:name => 'Foo')
-    #   #=> {:id => 1, :name => 'Foo', :description => ''}
-    def post(path, data)
-      do_json_request(:post, path, data)
+    def get(path, *args)
+      request(:get, path, nil, *args)
     end
 
-    def put(path, data)
-      do_json_request(:put, path, data)
+    def delete(path, *args)
+      request(:delete, path, nil, *args)
     end
 
-    def get(path, data)
-      do_json_request(:get, path, data)
+    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].flatten.compact
+      output = __getobj__.send(type, *args)
+
+      decode(output)
     end
 
-  private
+    def encode(data)
+      ActiveSupport::JSON.encode(data) unless data.nil?
+    end
 
-    def do_json_request(method, path, data)
-      json_request_headers = {
-        'Content-Type' => 'application/json',
-        'Accept' => 'application/json'
-      }
-      response = @app_driver.send(method.to_sym, path, J.encode(data), json_request_headers)
-      J.decode(response)
+    def decode(data)
+      ActiveSupport::JSON.decode(data)
     end
   end
 end

data/lib/kookaburra/{test_data.rb → mental_model.rb}

@@ -1,37 +1,43 @@
 require 'delegate'
 
 class Kookaburra
-  # Each instance of {Kookaburra} has its own instance of TestData. This object
+  # Each instance of {Kookaburra} has its own instance of MentalModel. This object
   # is used to maintain a shared understanding of the application state between
   # your {GivenDriver} and your {UIDriver}. You can access the various test data
   # collections in your test implementations via {Kookaburra#get_data}.
-  class TestData
+  #
+  # The mental model is not intended to represent a copy of all of the data
+  # within your application. Rather it is meant to represent the mental image of
+  # the data that a user of your application might have while working with your
+  # system. Certainly you *can* store whatever you want in it, but thinking
+  # about it in these terms can help you design better, more robust tests.
+  class MentalModel
     def initialize
       @data = {}
     end
 
-    # TestData instances will respond to any message that has an arity of 0 by
-    # returning either a new or existing {TestData::Collection} having the name
+    # MentalModel instances will respond to any message that has an arity of 0 by
+    # returning either a new or existing {MentalModel::Collection} having the name
     # of the method.
     def method_missing(name, *args)
       return super unless args.empty?
       @data[name] ||= Collection.new(name)
     end
 
-    # TestData instances respond to everything.
+    # MentalModel instances respond to everything.
     #
     # @see #method_missing
     def respond_to?
       true
     end
 
-    # A TestData::Collection behaves much like a `Hash` object, with the
+    # A MentalModel::Collection behaves much like a `Hash` object, with the
     # exception that it will raise an {UnknownKeyError} rather than return nil
     # if you attempt to access a key that has not been set. The exception
     # attempts to provide a more helpful error message.
     #
     # @example
-    #   widgets = Kookaburra::TestData::Collection.new('widgets')
+    #   widgets = Kookaburra::MentalModel::Collection.new('widgets')
     #
     #   widgets[:foo] = :a_foo
     #   
@@ -39,14 +45,14 @@ class Kookaburra
     #   #=> :a_foo
     #
     #   # Raises an UnknownKeyError
-    #   test_data.widgets[:bar]
+    #   mental_model.widgets[:bar]
     class Collection < SimpleDelegator
       # @param [String] name The name of the collection. Used to provide
       #   helpful error messages when unknown keys are accessed.
       def initialize(name)
         @name = name
         data = Hash.new do |hash, key|
-          raise UnknownKeyError, "Can't find test_data.#{@name}[#{key.inspect}]. Did you forget to set it?"
+          raise UnknownKeyError, "Can't find mental_model.#{@name}[#{key.inspect}]. Did you forget to set it?"
         end
         super(data)
       end