kookaburra 1.3.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5cadefaae85409b2b4db57ce339eea29091d9a87
-  data.tar.gz: 14ca8365ce3aecd80dbf5a78a8e7581d1461dac1
+  metadata.gz: 0096d882dd0e4a30ea2ff6f38744a307ca77b596
+  data.tar.gz: 97dd32061c90235865ed398517c59c356d0b3b38
 SHA512:
-  metadata.gz: b4ca6636a527e1a6de7af7b92ac9c87be2ca3ab507b5327ed4513635a522a3e794aff3930720cfbde751ad7dbb0236e52e9e5697f7a1f57569006a4ad6d7d355
-  data.tar.gz: a2badf5f817a513f45c4955bdb3ea0b9a8139a08fd4826fba07d43be6a8d11a0d9c8c07eb6a296904c562c22b556c834a1edba366953f2aa122a2af8240821d4
+  metadata.gz: 2022e2a53bef18d607ada46e5043d2f17c79f4699f4ee02b5d06c4b12c9d219727fee3bb2cee84e55383a35697d2918552a295b49e165d13bc0505a311c59097
+  data.tar.gz: 86883520f7835ebcd750f01448d39727ffa48c9f8c8d564b5b8ca42bd12e17468d6f7ee11aeb958a398f1facf939a09bb108f2c3e7bc6e9e68f67c246664d047

data/.travis.yml

@@ -2,8 +2,8 @@ before_install:
   - "export DISPLAY=:99.0"
   - "sh -e /etc/init.d/xvfb start"
 rvm:
+  - "2.1.2"
   - "2.0.0"
   - "1.9.3"
-  - "jruby-19mode"
 env:
   - "DISPLAY=:99.0"

data/README.markdown

@@ -37,7 +37,7 @@ running.
 
 The fact that Kookaburra runs against a remote server means that *it is not
 limited to testing only Ruby web applications*. As long as your application
-exposes a web-service API for use by the GivenDriver and an HTML user interface
+exposes a web-service API for use by the APIDriver and an HTML user interface
 for use by the UIDriver, you can use Kookaburra to test it. Also, as long as
 you're careful with both your application and test designs, you're not limited
 to running your tests only in an isolated testing environment; you could run
@@ -53,19 +53,19 @@ stopping your server for you. Examples of how to do so with a Rack application
 are presented below, but you should be able to take the same basic approach with
 other types of application servers.
 
-Although Capybara is capable of starting a Rack application server on its own,
-the default setup only starts the server up on-demand when you call a method
-that requires the browser to interact with the web application. Because the
-APIDriver layer does not use Capybara, it is necessary to manage the server
-process on your own. Otherwise the server would not be guaranteed to be running
-when you call the APIDriver methods (particularly as these often appear in
-"Given" statements that are run before you start interacting with the web
-browser.)
+Although Capybara is capable of starting a Rack application server on 
+its own, the default setup only starts the server up on-demand when you 
+call a method that requires the browser to interact with the web 
+application. Because the APIClient layer does not use Capybara, it is 
+necessary to manage the server process on your own. Otherwise the server 
+would not be guaranteed to be running when you call the APIClient 
+methods (particularly as these often appear in "Given" statements that 
+are run before you start interacting with the web browser.)
 
 Keep in mind that, even if your server is capable of being started up in another
 thread within the same Ruby process that is executing your test suite, you will
 want to avoid doing so unless you are using a Ruby interpreter that supports
-native threads. Otherwise, when the APIDriver makes an HTTP call to your
+native threads. Otherwise, when the APIClient makes an HTTP call to your
 application's API, it will block while waiting for a response, thus preventing
 your application from being able to respond to that request and resulting in a
 timeout error in your tests.
@@ -83,15 +83,15 @@ add the following to `spec/support/kookaburra_setup.rb`:
 
     require 'kookaburra/test_helpers'
 
-    # Change these to the files that define your custom GivenDriver and UIDriver
+    # Change these to the files that define your custom APIDriver and UIDriver
     # implementations.
-    require 'my_app/kookaburra/given_driver'
+    require 'my_app/kookaburra/api_driver'
     require 'my_app/kookaburra/ui_driver'
 
     # c.app_host below should be set to whatever the root URL of your running
     # application is.
     Kookaburra.configure do |c|
-      c.given_driver_class = MyApp::Kookaburra::GivenDriver
+      c.api_driver_class = MyApp::Kookaburra::APIDriver
       c.ui_driver_class = MyApp::Kookaburra::UIDriver
       c.app_host = 'http://my_app.example.com:1234'
       c.browser = Capybara::Session.new(:selenium)
@@ -101,7 +101,7 @@ add the following to `spec/support/kookaburra_setup.rb`:
     end
 
     RSpec.configure do |c|
-      # Makes the #k, #given and #ui methods available to your specs
+      # Makes the #k, #api and #ui methods available to your specs
       # (See section on test implementation below)
       c.include(Kookaburra::TestHelpers, :type => :request)
     end
@@ -117,9 +117,9 @@ and shut down a Rack application server. Just add the following to
     require 'kookaburra/test_helpers'
     require 'kookaburra/rack_app_server'
 
-    # Change these to the files that define your custom GivenDriver and UIDriver
+    # Change these to the files that define your custom APIDriver and UIDriver
     # implementations.
-    require 'my_app/kookaburra/given_driver'
+    require 'my_app/kookaburra/api_driver'
     require 'my_app/kookaburra/ui_driver'
 
     # `MyApplication` below should be replaced with the object that
@@ -134,7 +134,7 @@ and shut down a Rack application server. Just add the following to
     # c.app_host below should be set to whatever the root URL of your
     # running application is.
     Kookaburra.configure do |c|
-      c.given_driver_class = MyApp::Kookaburra::GivenDriver
+      c.api_driver_class = MyApp::Kookaburra::APIDriver
       c.ui_driver_class = MyApp::Kookaburra::UIDriver
       c.app_host = 'http://localhost:%d' % app_server.port
       c.browser = Capybara::Session.new(:selenium)
@@ -168,15 +168,15 @@ add the following to `features/support/kookaburra_setup.rb`:
 
     require 'kookaburra/test_helpers'
 
-    # Change these to the files that define your custom GivenDriver and UIDriver
+    # Change these to the files that define your custom APIDriver and UIDriver
     # implementations.
-    require 'my_app/kookaburra/given_driver'
+    require 'my_app/kookaburra/api_driver'
     require 'my_app/kookaburra/ui_driver'
 
     # c.app_host below should be set to whatever the root URL of your running
     # application is.
     Kookaburra.configure do |c|
-      c.given_driver_class = MyApp::Kookaburra::GivenDriver
+      c.api_driver_class = MyApp::Kookaburra::APIDriver
       c.ui_driver_class = MyApp::Kookaburra::UIDriver
       c.app_host = 'http://my_app.example.com:1234'
       c.browser = Capybara::Session.new(:selenium)
@@ -198,9 +198,9 @@ and shut down a Rack application server. Just add the following to
     require 'kookaburra/test_helpers'
     require 'kookaburra/rack_app_server'
 
-    # Change these to the files that define your custom GivenDriver and UIDriver
+    # Change these to the files that define your custom APIDriver and UIDriver
     # implementations.
-    require 'my_app/kookaburra/given_driver'
+    require 'my_app/kookaburra/api_driver'
     require 'my_app/kookaburra/ui_driver'
 
     # `MyApplication` below should be replaced with the object that
@@ -215,7 +215,7 @@ and shut down a Rack application server. Just add the following to
     # c.app_host below should be set to whatever the root URL of your
     # running application is.
     Kookaburra.configure do |c|
-      c.given_driver_class = MyApp::Kookaburra::GivenDriver
+      c.api_driver_class = MyApp::Kookaburra::APIDriver
       c.ui_driver_class = MyApp::Kookaburra::UIDriver
       c.app_host = 'http://localhost:%d' % app_server.port
       c.browser = Capybara::Session.new(:selenium)
@@ -243,9 +243,9 @@ the following layers:
    spcification documents)
 2. The **Test Implementation** (Cucumber step definitions, RSpec example blocks,
    etc.)
-3. The **Domain Driver** (Kookaburra::GivenDriver and Kookaburra::UIDriver)
+3. The **Domain Driver** (Kookaburra::APIDriver and Kookaburra::UIDriver)
 4. The **Window Driver** (Kookaburra::UIDriver::UIComponent)
-5. The **Application Driver** (Capybara and Kookaburra::APIDriver)
+5. The **Application Driver** (Capybara and Kookaburra::APIClient)
 
 ### The Business Specification Language ###
 
@@ -315,19 +315,19 @@ might look:
     # step_definitions/various_steps.rb
 
     Given "I have an existing account" do
-      given.existing_account
+      api.existing_account
     end
 
     Given "I have previously specified default payment options" do
-      given.default_payment_options_specified
+      api.default_payment_options_specified
     end
 
     Given "I have previously specified default shipping options" do
-      given.default_shipping_options_specified
+      api.default_shipping_options_specified
     end
 
     Given "I have an item in my shopping cart" do
-      given.an_item_in_my_shopping_cart
+      api.an_item_in_my_shopping_cart
     end
 
     When "I sign in to my account" do
@@ -389,10 +389,10 @@ Using RSpec, the test implementation would be as follows:
     
     describe "Purchase Items in Cart" do
       example "Using Existing Billing and Shipping Information" do
-        given.existing_account(:my_account)
-        given.default_payment_options_specified_for(:my_account)
-        given.default_shipping_options_specified_for(:my_account)
-        given.an_item_in_my_shopping_cart(:my_account)
+        api.existing_account(:my_account)
+        api.default_payment_options_specified_for(:my_account)
+        api.default_shipping_options_specified_for(:my_account)
+        api.an_item_in_my_shopping_cart(:my_account)
 
         ui.sign_in(:my_account)
         ui.choose_to_check_out
@@ -407,21 +407,21 @@ Using RSpec, the test implementation would be as follows:
 
 The Domain Driver layer is where you build up an internal DSL that describes the
 business concepts of your application at a fairly high level. It consists of two
-top-level drivers: the `GivenDriver` (available via `#given`) used to set up
+top-level drivers: the `APIDriver` (available via `#api`) used to set up
 state for your tests and the UIDriver (available via `#ui`) for describing the
 tasks that a user can accomplish with the application.
 
 #### Mental Model ####
 
-`Kookaburra::MentalModel` is the component via which the `GivenDriver` and the
+`Kookaburra::MentalModel` is the component via which the `APIDriver` and the
 `UIDriver` share information, and it is intended to represent your application
 user's mental picture of the data they are working with. For instance, if you
-create a user account via the `GivenDriver`, you would store the login
+create a user account via the `APIDriver`, you would store the login
 credentials for that account in the `MentalModel` instance, so the `UIDriver`
 knows what to use when you tell it to `#sign_in`. This is what allows the
 Cucumber step definitions to remain free from explicitly shared state.
 
-Kookaburra automatically configures your `GivenDriver` and your `UIDriver` to
+Kookaburra automatically configures your `APIDriver` and your `UIDriver` to
 share a `MentalModel` instance, which is available to both of them via their
 `#mental_model` method.
 
@@ -459,20 +459,20 @@ Here's an example of MentalModel behavior:
     mental_model.widgets.deleted[:widget_a]
     #=> {'name' => 'Widget A'}
 
-#### Given Driver ####
+#### API Driver ####
 
-The `Kookaburra::GivenDriver` is used to create a particular "preexisting" state
+The `Kookaburra::APIDriver` is used to create a particular "preexisting" state
 within your application's data and ensure you have a handle to that data (when
 needed) prior to interacting with the UI. You will create a subclass of
-`Kookaburra::GivenDriver` in which you will create part of the Domain Driver DSL
+`Kookaburra::APIDriver` in which you will create part of the Domain Driver DSL
 for your application:
 
-    # lib/my_app/kookaburra/given_driver.rb
+    # lib/my_app/kookaburra/api_driver.rb
 
-    class MyApp::Kookaburra::GivenDriver < Kookaburra::GivenDriver
-      # Specify the APIDriver to use
+    class MyApp::Kookaburra::APIDriver < Kookaburra::APIDriver
+      # Specify the APIClient to use
       def api
-        @api ||= MyApp::Kookaburra::APIDriver.new(configuration)
+        @api ||= MyApp::Kookaburra::APIClient.new(configuration)
       end
 
       def existing_account(nickname)
@@ -489,24 +489,17 @@ for your application:
       end
     end
 
-Although there is nothing that actually *prevents* you from interacting with the
-UI in the `GivenDriver`, you should avoid doing so. The `GivenDriver`'s purpose
-is to describe state that exists *before* the user interaction that is being
-tested. Although this state may be the result of a previous user interaction,
-your tests will be much, much faster if you create this state via API calls
-rather than driving a web browser.
+#### API Client ####
 
-#### API Driver ####
-
-The `Kookaburra::APIDriver` is used to interact with an application's
+The `Kookaburra::APIClient` 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,
+creating a subclass of `Kookaburra::APIClient` 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::APIDriver
+    class MyApp::Kookaburra::APIClient < Kookaburra::APIClient
       encode_with { |data| JSON.dump(data) }
       decode_with { |data| JSON.parse(data) }
       header 'Content-Type', 'application/json'
@@ -521,7 +514,7 @@ any headers that should be present on every request.
       end
     end
 
-The content of your application's APIDriver should consist mainly of
+The content of your application's APIClient should consist mainly of
 mappings between discrete actions and HTTP requests to the specified URL
 paths.
 
@@ -548,7 +541,7 @@ within your subclass:
 
 ### The Window Driver Layer ###
 
-While your `GivenDriver` and `UIDriver` provide a DSL that represents actions
+While your `APIDriver` and `UIDriver` provide a DSL that represents actions
 your users can perform in your application, the [Window Driver] [Window Driver]
 layer describes the individual user interface components that the user interacts
 with to perform these tasks. By describing each interface component using an OOP
@@ -601,9 +594,9 @@ You describe the various user interface components by sub-classing
 
 ### The Application Driver Layer ###
 
-`Kookaburra::APIDriver`, `Kookaburra::UIDriver` and
+`Kookaburra::APIClient`, `Kookaburra::UIDriver` and
 `Kookaburra::UIDriver::UIComponent` rely on the Application Driver layer
-to interact with your application. In the case of the `APIDriver`,
+to interact with your application. In the case of the `APIClient`,
 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.

data/lib/kookaburra.rb

@@ -1,13 +1,13 @@
 require 'kookaburra/exceptions'
 require 'kookaburra/mental_model'
-require 'kookaburra/given_driver'
+require 'kookaburra/api_driver'
 require 'kookaburra/ui_driver'
 require 'kookaburra/configuration'
 
 # Kookaburra provides the top-level API that you will access in your test
-# implementation, namely the {#given}, {#ui}, and the {#get_data} methods.
+# implementation, namely the {#api}, {#ui}, and the {#get_data} methods.
 #
-# The Kookaburra object ensures that your GivenDriver and UIDriver share the
+# The Kookaburra object ensures that your APIDriver and UIDriver share the
 # same state with regard to any {Kookaburra::MentalModel} data that is created
 # during your test run. As such, it is important to ensure that a new instance
 # of Kookaburra is created for each individual test, otherwise you may wind up
@@ -35,26 +35,26 @@ class Kookaburra
   end
 
   # Returns a new Kookaburra instance that wires together your application's
-  # GivenDriver and UIDriver with a shared {Kookaburra::MentalModel}.
+  # APIDriver and UIDriver with a shared {Kookaburra::MentalModel}.
   #
   # @param [Kookaburra::Configuration] configuration (Kookaburra.configuration)
   def initialize(configuration = Kookaburra.configuration)
     @configuration = configuration
     @configuration.mental_model = MentalModel.new
-    @given_driver_class = configuration.given_driver_class
+    @api_driver_class = configuration.api_driver_class
     @ui_driver_class = configuration.ui_driver_class
   end
 
-  # Returns an instance of your GivenDriver class configured to share test
+  # Returns an instance of your APIDriver class configured to share test
   # fixture data with the UIDriver
   #
-  # @return [Kookaburra::GivenDriver]
-  def given
-    @given ||= @given_driver_class.new(@configuration)
+  # @return [Kookaburra::APIDriver]
+  def api
+    @api ||= @api_driver_class.new(@configuration)
   end
 
   # Returns an instance of your UIDriver class configured to share test fixture
-  # data with the GivenDriver and to use the browser driver you specified in
+  # data with the APIDriver and to use the browser driver you specified in
   # {#initialize}
   #
   # @return [Kookaburra::UIDriver]
@@ -69,7 +69,7 @@ class Kookaburra
   # of your application's interface.
   #
   # @example
-  #   given.a_widget(:foo)
+  #   api.create_widget(:foo)
   #   ui.create_a_new_widget(:bar)
   #   ui.widget_list.widgets.should == k.get_data(:widgets).values_at(:foo, :bar)
   #
@@ -77,10 +77,4 @@ class Kookaburra
   def get_data(collection_name)
     @configuration.mental_model.send(collection_name).dup
   end
-
-  private
-
-  def __mental_model__
-    @configuration.mental_model
-  end
 end

data/lib/kookaburra/api_client.rb

@@ -0,0 +1,214 @@
+require 'restclient'
+require 'core_ext/object/to_query'
+require 'kookaburra/exceptions'
+
+class Kookaburra
+  # Communicate with a Web Services API
+  #
+  # You will create a subclass of {APIClient} in your testing
+  # implementation to be used with you subclass of
+  # {Kookaburra::APIDriver}. While the {GivenDriver} implements the
+  # "business domain" DSL for setting up your application state, the
+  # {APIClient} 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 APIClient
+    class << self
+      # Serializes input data
+      #
+      # If specified, any input data provided to {APIClient#post},
+      # {APIClient#put} or {APIClient#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 MyAPIClient < Kookaburra::APIClient
+      #     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 {APIClient} 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 MyAPIClient < Kookaburra::APIClient
+      #     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 {APIClient}.
+      #
+      # @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 MyAPIClient < Kookaburra::APIClient
+      #     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 {APIClient} instance
+    #
+    # @param [Kookaburra::Configuration] configuration
+    # @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
+
+    # Convenience method to make a POST request
+    #
+    # @see APIClient#request
+    def post(path, data = nil, headers = {})
+      request(:post, path, data, headers)
+    end
+
+    # Convenience method to make a PUT request
+    #
+    # @see APIClient#request
+    def put(path, data = nil, headers = {})
+      request(:put, path, data, headers)
+    end
+
+    # Convenience method to make a GET request
+    #
+    # @see APIClient#request
+    def get(path, data = nil, headers = {})
+      path = add_querystring_to_path(path, data)
+      request(:get, path, nil, headers)
+    end
+
+    # Convenience method to make a DELETE request
+    #
+    # @see APIClient#request
+    def delete(path, data = nil, headers = {})
+      path = add_querystring_to_path(path, data)
+      request(:delete, path, nil, headers)
+    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.
+    #
+    # @see APIClient.encode_with
+    # @see APIClient.decode_with
+    # @see APIClient.header
+    # @see APIClient#get
+    # @see APIClient#post
+    # @see APIClient#put
+    # @see APIClient#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, headers)
+      data = encode(data)
+      headers = global_headers.merge(headers)
+      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 add_querystring_to_path(path, data)
+      return path if data.nil? || data == {}
+      "#{path}?#{data.to_query}"
+    end
+
+    def global_headers
+      self.class.headers
+    end
+
+    def url_for(path)
+      URI.join(base_url, path).to_s
+    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