kookaburra 0.18.3 → 0.20.0

data/Gemfile

@@ -5,7 +5,7 @@ gem 'basic_object' unless defined?(BasicObject)
 
 gem 'i18n'
 gem 'activesupport', '>= 3.0'
-gem 'rack-test'
+gem 'patron'
 
 # Add dependencies to develop your gem here.
 # Include everything needed to run rake, tests, features, etc.

data/Gemfile.lock

@@ -27,6 +27,7 @@ GEM
     mime-types (1.17.2)
     multi_json (1.1.0)
     nokogiri (1.5.0)
+    patron (0.4.18)
     rack (1.4.1)
     rack-protection (1.2.0)
       rack
@@ -79,7 +80,7 @@ DEPENDENCIES
   capybara
   i18n
   jeweler
-  rack-test
+  patron
   rcov
   redcarpet (~> 1.0)
   reek

data/README.markdown

@@ -3,20 +3,6 @@
 Kookaburra is a framework for implementing the [Window Driver] [Window Driver] pattern in
 order to keep acceptance tests maintainable.
 
-## WARNING: Significant Changes since 0.14.x ##
-
-As of 0.15.0, Kookaburra has been rewritten from the ground up. The original
-(up through 0.14.x) version was extracted from another project in which the
-testing library was being used. Unfortunately, this meant that the code in
-Kookaburra itself did not have very good test coverage, because it was being
-tested indirectly by the fact of its usage in the other project. What we've
-found is that a *lot* of complexity was sneaking into Kookaburra due to its
-having been developed without much focused TDD.
-
-Starting with 0.15.0, we are treating the previous versions as a spike. They
-were really useful for learning about the approach, but the code has enough
-design flaws that its best just to toss it.
-
 ## Installation ##
 
 Kookaburra is available as a Rubygem and [published on Rubygems.org] [Kookaburra Gem],
@@ -34,51 +20,45 @@ following:
 ## Setup ##
 
 Kookaburra abstracts some common patterns for implementing the Window Driver
-pattern for tests of Ruby web applications built on [Rack] [Rack]. You will need
-to tell Kookaburra which classes contain the specific Domain Driver
-implementations for your application as well as which driver to use for running
-the tests (currently only tested with [Capybara] [Capybara]).
-
-### ActiveRecord and Database Transactions ###
-
-Kookaburra currently uses Rack::Test as the underlying implementation for its
-APIDriver classes. This poses a problem when you want to run your UI tests via a
-driver other than Rack::Test such as Selenium, because the APIDriver sets up
-your test data using a different database connection than the process that runs
-the server against which Selenium executes, and they do not have access to the
-same transaction.
-
-One way to handle this problem is to force ActiveRecord to use the same
-connection in both the main thread and the thread that is spun up by Capybara to
-run the application for Selenium testing. You can do so by requiring
-`kookaburra/utils/active_record_shared_connection` within your Kookaburra setup.
-
-In the near future, we plan to change Kookaburra to execute *both* its APIDriver
-and UIDriver against an actual server and ditch Rack::Test. Not only will this
-help avoid this specific problem, but it will move towards the goal of being
-able to (optionally) run these tests on a completely different machine than the
-running application.
+testing pattern for web applications. You will need to tell Kookaburra which
+classes contain the specific Domain Driver implementations for your application
+as well as which driver to use for running the tests (currently only tested with
+[Capybara] [Capybara]).
+
+Kookaburra is designed to run tests agains a remote web server (although that
+server could be running on the same machine, it doesn't need to be), and it is
+the responsibility of the test implementation to ensure that the server is
+running. Take a look at Kookaburra's own integration specs for one example of
+how to achieve this for a [Rack-based] [Rack] application. (Note that you cannot
+easily start the application server in a seperate thread. Because Ruby uses
+green threads, the HTTP library used in the APIDriver will block while making
+its requests and prevent the application server thread from responding.)
+
+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
+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 the
+same test suite you use for development against your production systems and even
+repurpose your Kookaburra-based tests for load-testing and similar applications.
 
 ### RSpec ###
 
 For [RSpec] [RSpec] integration tests, just add the following to
 `spec/support/kookaburra_setup.rb`:
 
-    # only if using ActiveRecord and a browser driver other than Rack::Test for
-    # UI testing
-    require 'kookaburra/utils/active_record_shared_connection'
-
     require 'kookaburra/test_helpers'
-    require 'my_app/kookaburra/api_driver'
     require 'my_app/kookaburra/given_driver'
     require 'my_app/kookaburra/ui_driver'
 
+    # :app_host below should be set to whatever the root URL of your running
+    # application is.
     Kookaburra.configuration = {
-      :api_driver_class => MyApp::Kookaburra::APIDriver,
       :given_driver_class => MyApp::Kookaburra::GivenDriver,
       :ui_driver_class => MyApp::Kookaburra::UIDriver,
+      :app_host => 'http://my_app.example.com:1234',
       :browser => Capybara,
-      :rack_app => Capybara.app,
       :server_error_detection => { |browser|
         browser.has_css?('head title', :text => 'Internal Server Error')
       }
@@ -92,21 +72,17 @@ For [RSpec] [RSpec] integration tests, just add the following to
 
 For [Cucumber] [Cucumber], add the following to `features/support/kookaburra_setup.rb`:
 
-    # only if using ActiveRecord and a browser driver other than Rack::Test for
-    # UI testing
-    require 'kookaburra/utils/active_record_shared_connection'
-
     require 'kookaburra/test_helpers'
-    require 'my_app/kookaburra/api_driver'
     require 'my_app/kookaburra/given_driver'
     require 'my_app/kookaburra/ui_driver'
 
+    # :app_host below should be set to whatever the root URL of your running
+    # application is.
     Kookaburra.configuration = {
-      :api_driver_class => MyApp::Kookaburra::APIDriver,
       :given_driver_class => MyApp::Kookaburra::GivenDriver,
       :ui_driver_class => MyApp::Kookaburra::UIDriver,
+      :app_host => 'http://my_app.example.com:1234',
       :browser => Capybara,
-      :rack_app => Capybara.app,
       :server_error_detection => { |browser|
         browser.has_css?('head title', :text => 'Internal Server Error')
       }
@@ -119,10 +95,10 @@ Cucumber step definitions.
 
 ## Defining Your Testing DSL ##
 
-Kookaburra attempts to extract some common patterns that make it easier to use
-the Window Driver pattern along with various Ruby testing frameworks, but you
-still need to define your own testing DSL. An acceptance testing stack using
-Kookaburra has the following layers:
+Kookaburra extracts some common patterns that make it easier to use the Window
+Driver pattern along with various Ruby testing frameworks, but you still need to
+define your own testing DSL. An acceptance testing stack using Kookaburra has
+the following layers:
 
 1. The **Business Specification Language** (Cucumber scenarios or other
    spcification documents)
@@ -130,7 +106,7 @@ Kookaburra has the following layers:
    etc.)
 3. The **Domain Driver** (Kookaburra::GivenDriver and Kookaburra::UIDriver)
 4. The **Window Driver** (Kookaburra::UIDriver::UIComponent)
-5. The **Application Driver** (Capybara and Kookaburra::RackDriver)
+5. The **Application Driver** (Capybara and Kookaburra::APIDriver)
 
 ### The Business Specification Language ###
 
@@ -163,7 +139,9 @@ Note that the scenario is focused on business concepts versus interface details,
 i.e. you "choose to check out" rather than "click on the checkout button". If
 for some reason your e-commerce system was going to be a terminal application
 rather than a web application, you would not need to change this scenario at
-all, because the actual business concepts described would not change.
+all, because the actual business concepts described would not change (and
+although Kookaburra's focus is on testing web applications, it could likely be
+adapted to other environments.)
 
 ### The Test Implementation ###
 
@@ -173,19 +151,19 @@ definitions, RSpec example blocks, Test::Unit tests, etc. At this layer, your
 code orchestrates calls into the Domain Driver to mimic user interactions under
 various conditions and make assertions about the results.
 
-**Test assertions always belong within the test implementation layer.** Some testing
-frameworks such as RSpec add methods like `#should` to `Object`, which has the
-effect of poisoning the entire Ruby namespace with these methods---if you are
-using RSpec, you can call `#should` anywhere in your code and it will work when
-RSpec is loaded. Do not be tempted to call a testing library's Object decorators
-anywhere outside of your test implementation (such as within `UIDriver` or
-`UIComponent` subclasses.) Doing so will tightly couple your Domain Driver
-and/or Window Driver implementation to a specific testing library.
+**Test assertions always belong within the test implementation layer.** Some
+testing frameworks such as RSpec add methods like `#should` to `Object`, which
+has the effect of poisoning the entire Ruby namespace with these methods---if
+you are using RSpec, you can call `#should` anywhere in your code and it will
+work when RSpec is loaded. Do not be tempted to call a testing library's Object
+decorators anywhere outside of your test implementation (such as within
+`UIDriver` or `UIComponent` subclasses.) Doing so will tightly couple your
+Domain Driver and/or Window Driver implementation to a specific testing library.
 
-`Kookaburra::UIDriver::UIComponent` does provide an `#assert` method for use
-inside your own UIComponents. This method exists to verify preconditions and
-provide more informative error messages; it is not intended to be used to make
-test verifications.
+`Kookaburra::UIDriver::UIComponent` provides an `#assert` method for use inside
+your own UIComponents. This method exists to verify preconditions and provide
+more informative error messages; it is not intended to be used for test
+verifications.
 
 Given the Cucumber scenario above, here is how the test implementation layer
 might look:
@@ -287,60 +265,36 @@ top-level drivers: the `GivenDriver` (available via `#given`) 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.
 
-#### Test Data ####
+#### Mental Model ####
 
-`Kookaburra::TestData` is the component via which the `GivenDriver` and the
-`UIDriver` share information. For instance, if you create a user account via the
-`GivenDriver`, you would store the login credentials for that account in the
-`TestData` 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::MentalModel` is the component via which the `GivenDriver` 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
+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 share
-a `TestData` instance, which is available to both of them via their `#test_data`
-method.
+Kookaburra automatically configures your `GivenDriver` and your `UIDriver` to
+share a `MentalModel` instance, which is available to both of them via their
+`#mental_model` method.
 
-The `TestData` instance will return a `TestData::Collection` for any method
-called on the object. The `TestData::Collection` object behaves like a `Hash`
+The `MentalModel` instance will return a `MentalModel::Collection` for any method
+called on the object. The `MentalModel::Collection` object behaves like a `Hash`
 for the most part, however it will raise a `Kookaburra::UnknownKeyError` if you
 try to access a key that has not yet been assigned a value.
 
-Here's a quick example of TestData behavor:
+Here's a quick example of MentalModel behavor:
 
-    test_data = TestData.new
+    mental_model = MentalModel.new
 
-    test_data.widgets[:widget_a] = {'name' => 'Widget A'}
+    mental_model.widgets[:widget_a] = {'name' => 'Widget A'}
 
-    test_data.widgets[:widget_a]
+    mental_model.widgets[:widget_a]
     #=> {'name' => 'Widget A'}
     
     # this will raise a Kookaburra::UnknownKeyError
-    test_data.widgets[:widget_b]
-
-#### 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`:
-
-    # lib/my_app/kookaburra/api_driver.rb
-
-    class MyApp::Kookaburra::APIDriver < Kookaburra::JsonApiDriver
-      def create_account(account_data)
-        post '/api/v1/accounts', account_data
-      end
-    end
-
-Regardless of the type of APIDriver subclass, the contents 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`, `#head`, 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.
+    mental_model.widgets[:widget_b]
 
 #### Given Driver ####
 
@@ -353,6 +307,11 @@ for your application:
     # lib/my_app/kookaburra/given_driver.rb
 
     class MyApp::Kookaburra::GivenDriver < Kookaburra::GivenDriver
+      # Specify the APIDriver to use
+      def api
+        @api ||= MyApp::Kookaburra::APIDriver.new(:app_host => initialization_options[:app_host])
+      end
+
       def existing_account(nickname)
         account_data = {'display_name' => 'John Doe', 'password' => 'a password'}
         account_data['username'] = "test-user-#{`uuidgen`.strip}"
@@ -361,34 +320,52 @@ for your application:
         result = api.create_account(account_data)
 
         # merge in the password, since API (hopefully!) doesn't return it, and
-        # store details in the TestData instance
+        # store details in the MentalModel instance
         result.merge!('password' => account_data['password'])
-        test_data.accounts[nickname] = account_details
+        mental_model.accounts[nickname] = account_details
+      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 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`:
+
+    # lib/my_app/kookaburra/api_driver.rb
+
+    class MyApp::Kookaburra::APIDriver < Kookaburra::JsonApiDriver
+      def create_account(account_data)
+        post '/api/v1/accounts', account_data
+      end
+
+      def get_account(id)
+        get '/api/v1/accounts/%d' % id
       end
     end
 
-Although there is nothing that actually *prevents* you from either interacting
-with the UI or directly manipulating your application via calls into the model
-from the `GivenDriver`, both should be avoided. In the first case, 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.
-
-In the second case, by avoiding the manipulation of your applications's state at the
-code level and instead doing so via an external API, it is much less likely that
-you will create a state that your application can't actually get into in a
-production environment. Additionally, this opens up the possibility of running
-your tests against a "remote" server where you would not have access to the
-application internals. ("Remote" in the sense that it is not in the same Ruby
-process as your running tests, although it may or may not be on the same
-machine. Note that this is not currently possible with Kookaburra due to our
-reliance on Rack::Test.)
+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.
 
 #### UI Driver ####
 
 `Kookaburra::UIDriver` provides the necessary tools for driving your
-application's user interface using the Window Driver pattern. You will subclass
+application's user interface with the Window Driver pattern. You will subclass
 `Kookaburra::UIDriver` for your application and implement your testing DSL
 within your subclass:
 
@@ -464,9 +441,10 @@ You describe the various user interface components by sub-classing
 `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
-`Kookaburra::RackDriver` 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.
+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.
 
 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
@@ -502,3 +480,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"

data/VERSION

@@ -1 +1 @@
-0.18.3
+0.20.0

data/kookaburra.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = "kookaburra"
-  s.version = "0.18.3"
+  s.version = "0.20.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-03-18"
+  s.date = "2012-03-22"
   s.description = "Cucumber + Capybara = Kookaburra? It made sense at the time."
   s.email = "johnwilger@gmail.com"
   s.extra_rdoc_files = [
@@ -34,18 +34,16 @@ Gem::Specification.new do |s|
     "lib/kookaburra/exceptions.rb",
     "lib/kookaburra/given_driver.rb",
     "lib/kookaburra/json_api_driver.rb",
+    "lib/kookaburra/mental_model.rb",
     "lib/kookaburra/null_browser.rb",
-    "lib/kookaburra/rack_driver.rb",
-    "lib/kookaburra/test_data.rb",
     "lib/kookaburra/test_helpers.rb",
     "lib/kookaburra/ui_driver.rb",
     "lib/kookaburra/ui_driver/ui_component.rb",
-    "lib/kookaburra/utils/active_record_shared_connection.rb",
     "spec/integration/test_a_rack_application_spec.rb",
+    "spec/kookaburra/api_driver_spec.rb",
     "spec/kookaburra/json_api_driver_spec.rb",
+    "spec/kookaburra/mental_model_spec.rb",
     "spec/kookaburra/null_browser_spec.rb",
-    "spec/kookaburra/rack_driver_spec.rb",
-    "spec/kookaburra/test_data_spec.rb",
     "spec/kookaburra/test_helpers_spec.rb",
     "spec/kookaburra/ui_driver/ui_component_spec.rb",
     "spec/kookaburra/ui_driver_spec.rb",
@@ -65,7 +63,7 @@ Gem::Specification.new do |s|
       s.add_runtime_dependency(%q<basic_object>, [">= 0"])
       s.add_runtime_dependency(%q<i18n>, [">= 0"])
       s.add_runtime_dependency(%q<activesupport>, [">= 3.0"])
-      s.add_runtime_dependency(%q<rack-test>, [">= 0"])
+      s.add_runtime_dependency(%q<patron>, [">= 0"])
       s.add_development_dependency(%q<rspec>, [">= 0"])
       s.add_development_dependency(%q<capybara>, [">= 0"])
       s.add_development_dependency(%q<yard>, [">= 0"])
@@ -78,7 +76,7 @@ Gem::Specification.new do |s|
       s.add_dependency(%q<basic_object>, [">= 0"])
       s.add_dependency(%q<i18n>, [">= 0"])
       s.add_dependency(%q<activesupport>, [">= 3.0"])
-      s.add_dependency(%q<rack-test>, [">= 0"])
+      s.add_dependency(%q<patron>, [">= 0"])
       s.add_dependency(%q<rspec>, [">= 0"])
       s.add_dependency(%q<capybara>, [">= 0"])
       s.add_dependency(%q<yard>, [">= 0"])
@@ -92,7 +90,7 @@ Gem::Specification.new do |s|
     s.add_dependency(%q<basic_object>, [">= 0"])
     s.add_dependency(%q<i18n>, [">= 0"])
     s.add_dependency(%q<activesupport>, [">= 3.0"])
-    s.add_dependency(%q<rack-test>, [">= 0"])
+    s.add_dependency(%q<patron>, [">= 0"])
     s.add_dependency(%q<rspec>, [">= 0"])
     s.add_dependency(%q<capybara>, [">= 0"])
     s.add_dependency(%q<yard>, [">= 0"])