kookaburra 0.7.2 → 0.8.0

data/.yardopts

@@ -0,0 +1 @@
+--markup=markdown

data/Gemfile

@@ -7,11 +7,11 @@ gem 'rack-test'
 # Add dependencies to develop your gem here.
 # Include everything needed to run rake, tests, features, etc.
 group :development do
-  gem 'minitest', '>= 0'
-  gem 'bluecloth'
-  gem 'yard', '~> 0.6.0'
-  gem 'bundler', '~> 1.0.0'
-  gem 'jeweler', '~> 1.6.4'
-  gem 'rcov', '>= 0'
-  gem 'reek', '~> 1.2.8'
+  gem 'minitest'
+  gem 'yard'
+  gem 'redcarpet', '~> 1.0' # used to format documentation
+  gem 'bundler'
+  gem 'jeweler'
+  gem 'rcov'
+  gem 'reek'
 end

data/Gemfile.lock

@@ -1,22 +1,23 @@
 GEM
   remote: http://rubygems.org/
   specs:
-    activesupport (3.1.3)
+    activesupport (3.2.0)
+      i18n (~> 0.6)
       multi_json (~> 1.0)
-    bluecloth (2.2.0)
     git (1.2.5)
     i18n (0.6.0)
     jeweler (1.6.4)
       bundler (~> 1.0)
       git (>= 1.2.5)
       rake
-    minitest (2.9.0)
+    minitest (2.10.1)
     multi_json (1.0.4)
-    rack (1.3.5)
+    rack (1.4.0)
     rack-test (0.6.1)
       rack (>= 1.0)
     rake (0.9.2.2)
-    rcov (0.9.11)
+    rcov (1.0.0)
+    redcarpet (1.17.2)
     reek (1.2.8)
       ruby2ruby (~> 1.2)
       ruby_parser (~> 2.0)
@@ -26,20 +27,20 @@ GEM
       sexp_processor (~> 3.0)
     ruby_parser (2.3.1)
       sexp_processor (~> 3.0)
-    sexp_processor (3.0.9)
-    yard (0.6.8)
+    sexp_processor (3.0.10)
+    yard (0.7.4)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
   activesupport (>= 3.0)
-  bluecloth
-  bundler (~> 1.0.0)
+  bundler
   i18n
-  jeweler (~> 1.6.4)
+  jeweler
   minitest
   rack-test
   rcov
-  reek (~> 1.2.8)
-  yard (~> 0.6.0)
+  redcarpet (~> 1.0)
+  reek
+  yard

data/README.markdown

@@ -1,15 +1,29 @@
 # Kookaburra #
 
-Kookaburra is a framework for implementing the [Window Driver] [1] pattern in
+Kookaburra is a framework for implementing the [Window Driver] [Window Driver] pattern in
 order to keep acceptance tests maintainable.
 
+## Installation ##
+
+Kookaburra is available as a Rubygem and [published on Rubygems.org] [Kookaburra
+Gem], so installation is trivial:
+
+    gem install kookaburra
+
+If you're using [Bundler](http://gembundler.com/) for your project, just add the
+following:
+
+    group :development, :test do
+      gem 'kookaburra'
+    end
+
 ## Setup ##
 
 Kookaburra itself abstracts some common patterns for implementing the Window
-Driver pattern for tests of Ruby web applications built on [Rack] [2]. You will need
+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] [3]). The details of setting up your
+the tests (currently only tested with [Capybara] [Capybara]). The details of setting up your
 Domain Driver layer are discussed below, but in general you will need the
 following in a locations such as `lib/my_application/kookaburra.rb` (replace
 `MyApplication` with a module name suitable to your actual application:
@@ -33,7 +47,7 @@ following in a locations such as `lib/my_application/kookaburra.rb` (replace
 
 ### RSpec ###
 
-For [RSpec] [4] integration tests, just add the following to
+For [RSpec] [RSpec] integration tests, just add the following to
 `spec/support/kookaburra_setup.rb`:
 
     require 'my_application/kookaburra'
@@ -44,7 +58,7 @@ For [RSpec] [4] integration tests, just add the following to
 
 ### Cucumber ###
 
-For Cucumber, add the following to `features/support/kookaburra_setup.rb`:
+For [Cucumber] [Cucumber], add the following to `features/support/kookaburra_setup.rb`:
 
     require 'my_application/kookaburra'
 
@@ -64,12 +78,15 @@ Cucumber step definitions.
 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 four layers:
+Kookaburra has the following layers:
 
-1. The **Business Specification Language** (Cucumber scenarios and step definitions)
-2. The **Domain Driver** (Kookaburra::GivenDriver and Kookaburra::UIDriver)
-3. The **Window Driver** (Kookaburra::UIDriver::UIComponent)
-4. The **Application Driver** (Capybara and Rack::Test)
+1. The **Business Specification Language** (Cucumber scenarios or other
+   spcification documents)
+2. The **Test Implementation** (Cucumber step definitions, RSpec example blocks,
+   etc.)
+3. The **Domain Driver** (Kookaburra::GivenDriver and Kookaburra::UIDriver)
+4. The **Window Driver** (Kookaburra::UIDriver::UIComponent)
+5. The **Application Driver** (Capybara and Rack::Test)
 
 ### The Business Specification Language ###
 
@@ -104,18 +121,28 @@ 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.
 
-### The Domain Driver ###
-
-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
-three top-level drivers: the `APIDriver` (available via `#api`) for interacting
-with your application's external API, the `GivenDriver` (available via `#given`)
-which really just wraps the `APIDriver` and is used to set up state for your
-tests, and the UIDriver (available via `#given`) for describing the tasks that a
-user can accomplish with the application.
-
-Given the Cucumber scenario above, the step definitions call into the Domain
-Driver layer to interact with your application:
+### The Test Implementation ###
+
+The Test Implementation layer exists as the line in between the Business
+Specification Language and the Domain Driver, and it includes Cucumber step
+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.
+
+**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. If you must
+make some type of assertion within the Domain Driver layer, a better approach is
+to simply raise an exception with an informative error message when some desired
+condition is not met.
+
+Given the Cucumber scenario above, here is how the test implementation layer
+might look:
 
     # step_definitions/various_steps.rb
 
@@ -158,6 +185,7 @@ Driver layer to interact with your application:
 The step definitions contain neither explicitly shared state (instance
 variables) nor any logic branches; they are simply wrappers around calls into
 the Domain Driver layer. There are a couple of advantages to this approach.
+
 First, because step definitions are so simple, it isn't necessary to force *Very
 Specific Wording* on the business analyst/product owner who is writing the
 specs. For instance, if she writes "I see a summary of my order" in another
@@ -183,8 +211,9 @@ The second advantage is that by pushing all of the complexity down into the
 Domain Driver, it's now trivial to reuse the exact same code in
 developer-centric integration tests. This ensures you have parity between the
 way the automated acceptance tests run and any additional testing that the
-development team needs to add in. You could write the same test using just
-RSpec as follows:
+development team needs to add in.
+
+Using RSpec, the test implementation would be as follows:
 
     # spec/integration/purchase_items_in_cart_spec.rb
     
@@ -204,10 +233,17 @@ RSpec as follows:
       end
     end
 
-Whether in Cucumber step definitions or developer integration tests, you will
-usually interact only with the GivenDriver and the UIDriver.
+### The Domain Driver ###
 
-#### TestData ####
+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
+three top-level drivers: the `APIDriver` (available via `#api`) for interacting
+with your application's external API, the `GivenDriver` (available via `#given`)
+which really just wraps the `APIDriver` and is 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 ####
 
 `Kookaburra::TestData` is the component via which the `GivenDriver` and the
 `UIDriver` share information. For instance, if you create a user account via the
@@ -258,7 +294,7 @@ access default data:
       end
     end
 
-#### APIDriver ####
+#### 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
@@ -273,7 +309,7 @@ web services API. You tell Kookaburra about your API by creating a subclass of
       end
     end
 
-#### GivenDriver ####
+#### Given Driver ####
 
 The `Kookaburra::GivenDriver` is used to create a particular "preexisting"
 state within your application's data and ensure you have a handle to that data
@@ -301,7 +337,24 @@ the Domain Driver DSL for your application:
       end
     end
 
-#### UIDriver ####
+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 things 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 generally be much, much faster if you
+are able to create this state via API calls rather than driving a web browser.
+
+In the second case, by avoiding manipulating your applications's state at the
+code level and instead doing so via an external API, it is much less likely that
+you will be creating 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.)
+
+#### UI Driver ####
 
 `Kookaburra::UIDriver` provides the necessary tools for driving your
 application's user interface using the Window Driver pattern. You will subclass
@@ -325,13 +378,14 @@ within your subclass:
 ### The Window Driver Layer ###
 
 While your `GivenDriver` and `UIDriver` provide a DSL that represents actions
-your users can perform in your application, the [Window Driver] [1] layer describes
-the individual user interface components that the user interacts with to perform
-these tasks. By describing each interface component using an OOP approach, it is
-much easier to maintain your acceptance/integration tests, because the
-implementation details of each component are captured in a single place. If/when
-that implementation changes, you can---for example---fix every single test that
-needs to log a user into the system just by updating the SignInScreen class.
+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
+approach, it is much easier to maintain your acceptance/integration tests,
+because the implementation details of each component are captured in a single
+place. If/when that implementation changes, you can---for example---fix every
+single test that needs to log a user into the system just by updating the
+SignInScreen class.
 
 You describe the various user interface components by sub-classing
 `Kookaburra::UIDriver::UIComponent`:
@@ -370,22 +424,48 @@ You describe the various user interface components by sub-classing
       end
     end
 
+### 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
+`Rack::Test` to send HTTP requests to your application. The `UIDriver` and
+`UIComponent` rely on whatever is configured as `Kookaburra.adapter`. Presently,
+we have only used Capybara as the application driver for Kookaburra:
+
+    Kookaburra.adapter = Capybara
+
+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
+Capybara is likely to require some changes to Kookaburra itself. If you have a
+particular interest in making this work, please feel free to fork the project
+and send us a [GitHub pull request] [Pull Request] with your changes.
+
 ## Contributing to kookaburra ##
  
-* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
-* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
+* Check out the latest master to make sure the feature hasn't been implemented
+  or the bug hasn't been fixed yet
+* Check out the issue tracker to make sure someone already hasn't requested it
+  and/or contributed it
 * Fork the project
 * Start a feature/bugfix branch
 * Commit and push until you are happy with your contribution
-* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
-* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+* Make sure to add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to
+  have your own version, or is otherwise necessary, that is fine, but please
+  isolate to its own commit so I can cherry-pick around it.
+* Send us a [pull request] [Pull Request]
 
 ## Copyright ##
 
 Copyright © 2011 Renewable Funding, LLC. See LICENSE.txt for
 further details.
 
-[1]: http://martinfowler.com/eaaDev/WindowDriver.html "Window Driver - Martin Fowler"
-[2]: http://rack.rubyforge.org/ "Rack: a Ruby Webserver Interface"
-[3]: https://github.com/jnicklas/capybara "jnicklas/capybara - GitHub"
-[4]: http://rspec.info "RSpec.info: home"
+[Window Driver]: http://martinfowler.com/eaaDev/WindowDriver.html "Window Driver - Martin Fowler"
+[Kookaburra Gem]: https://rubygems.org/gems/kookaburra "kookaburra | RubyGems.org | your community gem host"
+[Rack]: http://rack.rubyforge.org/ "Rack: a Ruby Webserver Interface"
+[Capybara]: https://github.com/jnicklas/capybara "jnicklas/capybara - GitHub"
+[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"

data/VERSION

@@ -1 +1 @@
-0.7.2
+0.8.0

data/kookaburra.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = "kookaburra"
-  s.version = "0.7.2"
+  s.version = "0.8.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Renewable Funding, LLC"]
-  s.date = "2012-01-23"
+  s.date = "2012-01-24"
   s.description = "Cucumber + Capybara = Kookaburra? It made sense at the time."
   s.email = "devteam@renewfund.com"
   s.extra_rdoc_files = [
@@ -19,6 +19,7 @@ Gem::Specification.new do |s|
   s.files = [
     ".document",
     ".rvmrc",
+    ".yardopts",
     "Gemfile",
     "Gemfile.lock",
     "LICENSE.txt",
@@ -55,35 +56,35 @@ Gem::Specification.new do |s|
       s.add_runtime_dependency(%q<activesupport>, [">= 3.0"])
       s.add_runtime_dependency(%q<rack-test>, [">= 0"])
       s.add_development_dependency(%q<minitest>, [">= 0"])
-      s.add_development_dependency(%q<bluecloth>, [">= 0"])
-      s.add_development_dependency(%q<yard>, ["~> 0.6.0"])
-      s.add_development_dependency(%q<bundler>, ["~> 1.0.0"])
-      s.add_development_dependency(%q<jeweler>, ["~> 1.6.4"])
+      s.add_development_dependency(%q<yard>, [">= 0"])
+      s.add_development_dependency(%q<redcarpet>, ["~> 1.0"])
+      s.add_development_dependency(%q<bundler>, [">= 0"])
+      s.add_development_dependency(%q<jeweler>, [">= 0"])
       s.add_development_dependency(%q<rcov>, [">= 0"])
-      s.add_development_dependency(%q<reek>, ["~> 1.2.8"])
+      s.add_development_dependency(%q<reek>, [">= 0"])
     else
       s.add_dependency(%q<i18n>, [">= 0"])
       s.add_dependency(%q<activesupport>, [">= 3.0"])
       s.add_dependency(%q<rack-test>, [">= 0"])
       s.add_dependency(%q<minitest>, [">= 0"])
-      s.add_dependency(%q<bluecloth>, [">= 0"])
-      s.add_dependency(%q<yard>, ["~> 0.6.0"])
-      s.add_dependency(%q<bundler>, ["~> 1.0.0"])
-      s.add_dependency(%q<jeweler>, ["~> 1.6.4"])
+      s.add_dependency(%q<yard>, [">= 0"])
+      s.add_dependency(%q<redcarpet>, ["~> 1.0"])
+      s.add_dependency(%q<bundler>, [">= 0"])
+      s.add_dependency(%q<jeweler>, [">= 0"])
       s.add_dependency(%q<rcov>, [">= 0"])
-      s.add_dependency(%q<reek>, ["~> 1.2.8"])
+      s.add_dependency(%q<reek>, [">= 0"])
     end
   else
     s.add_dependency(%q<i18n>, [">= 0"])
     s.add_dependency(%q<activesupport>, [">= 3.0"])
     s.add_dependency(%q<rack-test>, [">= 0"])
     s.add_dependency(%q<minitest>, [">= 0"])
-    s.add_dependency(%q<bluecloth>, [">= 0"])
-    s.add_dependency(%q<yard>, ["~> 0.6.0"])
-    s.add_dependency(%q<bundler>, ["~> 1.0.0"])
-    s.add_dependency(%q<jeweler>, ["~> 1.6.4"])
+    s.add_dependency(%q<yard>, [">= 0"])
+    s.add_dependency(%q<redcarpet>, ["~> 1.0"])
+    s.add_dependency(%q<bundler>, [">= 0"])
+    s.add_dependency(%q<jeweler>, [">= 0"])
     s.add_dependency(%q<rcov>, [">= 0"])
-    s.add_dependency(%q<reek>, ["~> 1.2.8"])
+    s.add_dependency(%q<reek>, [">= 0"])
   end
 end
 

data/lib/kookaburra/api_driver.rb

@@ -1,21 +1,16 @@
 require 'rack/test'
 
 module Kookaburra
-  # Pattern:
-  # - Get some data from test_data.factory
-  # - Post it to the API
-  # - Remember the response in test_data
   class APIDriver
-    include Rack::Test::Methods
-    attr_reader :app, :test_data
-    protected :app, :test_data
-
     def initialize(opts)
-      @app       = opts.fetch(:app)
-      @test_data = opts.fetch(:test_data)
+      @app = opts.fetch(:app)
     end
 
-  protected
+    protected
+
+    include Rack::Test::Methods
+
+    attr_reader :app
 
     def raise_unless_status(expected_status, short_description)
       message = "%s failed (#{last_response.status})\n#{last_response.body}" % short_description
@@ -25,21 +20,30 @@ module Kookaburra
     ##### JSON Tools #####
 
     def post_as_json(short_description, path, data = {}, options = {})
-      header 'Content-Type', 'application/json'
-      header 'Accept', 'application/json'
+      set_json_request_headers
       post path, data.to_json
       raise_unless_status options[:expected_status] || 201, short_description
     end
 
     def put_as_json(short_description, path, data = {}, options = {})
-      header 'Content-Type', 'application/json'
-      header 'Accept', 'application/json'
+      set_json_request_headers
       put path, data.to_json
       raise_unless_status options[:expected_status] || 201, short_description
     end
 
+    def get_as_json(short_description, path, data = {}, options = {})
+      set_json_request_headers
+      get path, data
+      raise_unless_status options[:expected_status] || 200, short_description
+    end
+
     def hash_from_response_json
       HashWithIndifferentAccess.new( JSON.parse(last_response.body) )
     end
+
+    def set_json_request_headers
+      header 'Content-Type', 'application/json'
+      header 'Accept', 'application/json'
+    end
   end
 end

data/lib/kookaburra.rb

@@ -3,136 +3,134 @@ require 'kookaburra/api_driver'
 require 'kookaburra/given_driver'
 require 'kookaburra/ui_driver'
 
-# Kookaburra is a framework for implementing the Window Driver pattern[1] in
-# order to keep acceptance tests maintainable.
-#
-# For RSpec integration tests, just add the following to
-# `spec/support/kookaburra.rb`:
-# 
-#   RSpec.configure do |c|
-#     c.include(Kookaburra, :type => :request)
-#   end
-#
-# That will make #given, #api and #ui entry-points available to your examples,
-# e.g.:
-#
-#   describe "Widget Management" do
-#     describe "viewing a list of widgets" do
-#       example "when there are no widgets" do
-#         given.there_is_a_user(:bob)
-#         given.user_has_no_widgets(:bob)
-#
-#         ui.log_in_as(:bob)
-#         ui.navigate_to(:list_of_widgets)
-#
-#         ui.list_of_widgets.should be_visible
-#         ui.list_of_widgets.should be_empty
-#       end
-#     end
-#   end
-#
-# For Cucumber, add the following to `features/support/kookaburra_setup.rb`:
-#
-#   Kookaburra.adapter = Capybara
-#   World(Kookaburra)
-#
-#   Before do
-#     kookaburra_reset!
-#   end
-#
-# After doing to, the #api, #given and #ui methods will be available in your
-# Cucumber step definitions.
-#
-# (Obviously, the specific methods on #given and #ui are something that will be
-# unique to your application's domain.)
-#
-# [1] http://martinfowler.com/eaaDev/WindowDriver.html
+# This module contains the methods for Kookaburra configuration as well as
+# accessors to the `GivenDriver`, `APIDriver` and `UIDriver`. See
+# {file:README.markdown README} for more information on setting up Kookaburra
+# for your project.
 module Kookaburra
   class << self
-    # Provides the default adapter for the Kookaburra library. In most cases,
-    # this will probably be the `Capybara` class:
+    # Provides the default adapter for the Kookaburra library.
     #
-    #   Kookaburra.adapter = Capybara
+    # If not using Capybara, the Object must respond to `#app` and return a Rack
+    # application; and it must respond to `#current_session` and return an
+    # object that provides the same interface as `Capybara::Session`
     #
-    # We allow this to be passed in, so that we can avoid a hard-coded
-    # dependency on Capybara in this gem.
+    # @example using Capybara
+    #     Kookaburra.adapter = Capybara
     attr_accessor :adapter
 
-    # The API Driver that will be used by Kookaburra, typically a subclass of
-    # Kookaburra::APIDriver containing the testing DSL for your app. The default
-    # is an instance of Kookaburra::APIDriver.
+    # A reference to your application's subclass of `Kookaburra::APIDriver`
+    #
+    # @example setting your APIDriver
+    #     Kookaburra.api_driver = MyApplication::Kookaburra::APIDriver
     attr_accessor :api_driver
 
-    def api_driver
-      @api_driver ||= Kookaburra::APIDriver
-    end
-
-    # The Given Driver that will be used by Kookaburra, typically a subclass of
-    # Kookaburra::GivenDriver containing the testing DSL for your app. The default
-    # is an instance of Kookaburra::GivenDriver.
+    # A reference to your application's subclass of `Kookaburra::GivenDriver`
+    #
+    # @example setting your GivenDriver
+    #     Kookaburra.api_driver = MyApplication::Kookaburra::GivenDriver
     attr_accessor :given_driver
 
-    def given_driver
-      @given_driver ||= Kookaburra::GivenDriver
-    end
-
-    # The UI Driver that will be used by Kookaburra, typically a subclass of
-    # Kookaburra::UIDriver containing the testing DSL for your app. The default
-    # is an instance of Kookaburra::UIDriver.
+    # A reference to your application's subclass of `Kookaburra::UIDriver`
+    #
+    # @example setting your UIDriver
+    #     Kookaburra.api_driver = MyApplication::Kookaburra::UIDriver
     attr_accessor :ui_driver
 
-    def ui_driver
-      @ui_driver ||= Kookaburra::UIDriver
-    end
-
+    # Configure the test data collections and default data for your tests
+    #
+    # The passed block is evaluated in the context of the `Kookaburra::TestData`
+    # class and therefore has access to the
+    # `Kookaburra::TestData.provide_collection` and
+    # `Kookaburra::TestData.default` methods. Anything else in the block will
+    # also be evaluated in the context of the class, allowing you to further
+    # augment the TestData class.
+    #
+    # @param [Proc] blk the TestData configuration code
+    #
+    # @example creating a collection
+    #     Kookaburra.test_data_setup do
+    #       provide_collection :users
+    #     end
+    #
+    # @example specifying default values for use in tests
+    #     Kookaburra.test_data_setup do
+    #       default :user,
+    #         :first_name => 'Bob',
+    #         :last_name  => 'Jones',
+    #         :password   => 'bob_jones_password'
+    #       end
+    #     end
+    #
+    # @example otherwise extending TestData
+    #     Kookaburra.test_data_setup do
+    #       include MyApplication::Kookaburra::TestDataExtensions
+    #     end
+    #
+    # @see Kookaburra::TestData.provide_collection
+    # @see Kookaburra::TestData.default
     def test_data_setup(&blk)
       Kookaburra::TestData.class_eval(&blk)
     end
   end
 
-  # Whatever was set in `Kookaburra.adapter can be overriden in the mixin
-  # context. For example, in an RSpec example:
+  # Used to override Kookaburra.adapter in Kookaburra's own tests.
   #
-  #   describe "Something" do
-  #     it "does something" do
-  #       self.kookaburra_adapter = CapybaraLikeThing
-  #       ...
-  #     end
-  #   end
+  # This method should not be used by applications using Kookaburra.
   #
+  # @private
   attr_accessor :kookaburra_adapter
 
   def kookaburra_adapter
     @kookaburra_adapter ||= Kookaburra.adapter
   end
 
-  # Returns a configured instance of the `Kookaburra::APIDriver`
+  # The configured instance of the `Kookaburra::APIDriver` subclass for your
+  # application.
+  #
+  # Can be used in the Test Implementation layer to access the application's API
+  # directly, however you should probably only call this within your
+  # `GivenDriver`.
+  #
+  # @return [Kookaburra::APIDriver]
   def api
-    kookaburra_drivers[:api] ||= Kookaburra.api_driver.new(
-      :app => kookaburra_adapter.app,
-      :test_data => kookaburra_test_data)
+    kookaburra_drivers[:api] ||= Kookaburra.api_driver.new(:app => kookaburra_adapter.app)
   end
 
-  # Returns a configured instance of the `Kookaburra::GivenDriver`
+  # The configured instance of the `Kookaburra::GivenDriver` subclass for your
+  # application.
+  #
+  # Use #given inside your test implementation to call methods from your
+  # `GivenDriver` subclass.
+  #
+  # @return [Kookaburra::GivenDriver]
   def given
     kookaburra_drivers[:given] ||= \
       Kookaburra.given_driver.new(:api_driver => api, :test_data => kookaburra_test_data)
   end
 
-  # Returns a configured instance of the `Kookaburra::UIDriver`
+  # The configured instance of the `Kookaburra::UIDriver` subclass for your
+  # application.
+  #
+  # Use #given inside your test implementation to call methods from your
+  # `UIDriver` subclass.
+  #
+  # @return [Kookaburra::UIDriver]
   def ui
     kookaburra_drivers[:ui] ||= Kookaburra.ui_driver.new(
       :browser => kookaburra_adapter.current_session,
       :test_data => kookaburra_test_data)
   end
 
+  # Reset the Kookaburra drivers to clear state between Cucumber scenarios
+  #
   # This method causes new instances of all the Kookaburra drivers to be created
   # the next time they are used, and, in particular, resets the state of any
   # test data that is shared between the various drivers. This is necessary when
   # Kookaburra is mixed in to Cucumber's World, because World does not get a new
-  # instance for each scenario. Instead, just be sure to call this method from a
-  # `Before` block in your cucumber setup, i.e.:
+  # instance for each scenario.
   #
+  # @example add this to `features/support/kookaburra_setup.rb`
   #   Before do
   #     kookaburra_reset!
   #   end
@@ -142,14 +140,15 @@ module Kookaburra
 
   private
 
-  # The Kookaburra::TestData instance should not be used directly, but all of
-  # the drivers should reference the same instance.
+  # The Kookaburra::TestData instance should not be accesed directly in the test
+  # implementation layer, but all of the drivers should reference the same
+  # instance.
   def kookaburra_test_data
     kookaburra_drivers[:test_data] ||= Kookaburra::TestData.new
   end
 
   # Holds references to all drivers in a single hash, so that
-  # Kookaburra#kookaburra_reset! can easily clear all Kookaburra state on the
+  # `Kookaburra#kookaburra_reset!` can clear all Kookaburra state on the
   # instance of the including class.
   def kookaburra_drivers
     @kookaburra_drivers ||= {}

data/test/kookaburra_test.rb

@@ -1,6 +1,12 @@
 require 'helper'
 
 describe Kookaburra do
+  before(:each) do
+    Kookaburra.api_driver = Kookaburra::APIDriver
+    Kookaburra.given_driver = Kookaburra::GivenDriver
+    Kookaburra.ui_driver = Kookaburra::UIDriver
+  end
+
   describe 'as a mixin' do
     let(:mixer_class) do
       Class.new do
@@ -138,11 +144,6 @@ describe Kookaburra do
         Kookaburra.api_driver = :an_api_driver
         assert_equal :an_api_driver, Kookaburra.api_driver
       end
-
-      it 'defaults to Kookaburra::APIDriver' do
-        Kookaburra.api_driver = nil
-        assert_equal Kookaburra::APIDriver, Kookaburra.api_driver
-      end
     end
 
     describe '#given_driver' do
@@ -150,11 +151,6 @@ describe Kookaburra do
         Kookaburra.given_driver = :a_given_driver
         assert_equal :a_given_driver, Kookaburra.given_driver
       end
-
-      it 'defaults to Kookaburra::GivenDriver' do
-        Kookaburra.given_driver = nil
-        assert_equal Kookaburra::GivenDriver, Kookaburra.given_driver
-      end
     end
 
     describe '#ui_driver' do
@@ -162,11 +158,6 @@ describe Kookaburra do
         Kookaburra.ui_driver = :a_ui_driver
         assert_equal :a_ui_driver, Kookaburra.ui_driver
       end
-
-      it 'defaults to Kookaburra::UIDriver' do
-        Kookaburra.ui_driver = nil
-        assert_equal Kookaburra::UIDriver, Kookaburra.ui_driver
-      end
     end
 
     describe '.test_data_setup' do

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: kookaburra
 version: !ruby/object:Gem::Version 
-  hash: 7
+  hash: 63
   prerelease: 
   segments: 
   - 0
-  - 7
-  - 2
-  version: 0.7.2
+  - 8
+  - 0
+  version: 0.8.0
 platform: ruby
 authors: 
 - Renewable Funding, LLC
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-01-23 00:00:00 Z
+date: 2012-01-24 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   version_requirements: &id001 !ruby/object:Gem::Requirement 
@@ -84,7 +84,7 @@ dependencies:
         segments: 
         - 0
         version: "0"
-  name: bluecloth
+  name: yard
   prerelease: false
   type: :development
   requirement: *id005
@@ -94,13 +94,12 @@ dependencies:
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
-        hash: 7
+        hash: 15
         segments: 
+        - 1
         - 0
-        - 6
-        - 0
-        version: 0.6.0
-  name: yard
+        version: "1.0"
+  name: redcarpet
   prerelease: false
   type: :development
   requirement: *id006
@@ -108,14 +107,12 @@ dependencies:
   version_requirements: &id007 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
-    - - ~>
+    - - ">="
       - !ruby/object:Gem::Version 
-        hash: 23
+        hash: 3
         segments: 
-        - 1
         - 0
-        - 0
-        version: 1.0.0
+        version: "0"
   name: bundler
   prerelease: false
   type: :development
@@ -124,14 +121,12 @@ dependencies:
   version_requirements: &id008 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
-    - - ~>
+    - - ">="
       - !ruby/object:Gem::Version 
-        hash: 7
+        hash: 3
         segments: 
-        - 1
-        - 6
-        - 4
-        version: 1.6.4
+        - 0
+        version: "0"
   name: jeweler
   prerelease: false
   type: :development
@@ -154,14 +149,12 @@ dependencies:
   version_requirements: &id010 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
-    - - ~>
+    - - ">="
       - !ruby/object:Gem::Version 
-        hash: 15
+        hash: 3
         segments: 
-        - 1
-        - 2
-        - 8
-        version: 1.2.8
+        - 0
+        version: "0"
   name: reek
   prerelease: false
   type: :development
@@ -178,6 +171,7 @@ extra_rdoc_files:
 files: 
 - .document
 - .rvmrc
+- .yardopts
 - Gemfile
 - Gemfile.lock
 - LICENSE.txt