kookaburra 0.0.4 → 0.1.0

data/VERSION

@@ -1 +1 @@
-0.0.4
+0.1.0

data/kookaburra.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = "kookaburra"
-  s.version = "0.0.4"
+  s.version = "0.1.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-15"
+  s.date = "2012-01-16"
   s.description = "Cucumber + Capybara = Kookaburra? It made sense at the time."
   s.email = "devteam@renewfund.com"
   s.extra_rdoc_files = [
@@ -38,9 +38,9 @@ Gem::Specification.new do |s|
     "lib/kookaburra/ui_driver/mixins/has_subcomponents.rb",
     "lib/kookaburra/ui_driver/mixins/has_ui_component.rb",
     "lib/kookaburra/ui_driver/ui_component.rb",
-    "lib/kookaburra/world_setup.rb",
     "lib/requires.rb",
-    "test/helper.rb"
+    "test/helper.rb",
+    "test/kookaburra_test.rb"
   ]
   s.homepage = "http://github.com/projectdx/kookaburra"
   s.licenses = ["MIT"]

data/lib/kookaburra.rb

@@ -1,19 +1,120 @@
 require File.join(File.dirname(__FILE__), *%w[requires])
 
+# Kookaburra is a framework for implementing the WindowDriver pattern 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.)
 module Kookaburra
-  def self.drivers
-    test_data = Kookaburra::TestData.new
-    api_driver = Kookaburra::APIDriver.new({
-      :app       => Capybara.app,
-      :test_data => test_data,
-    })
-    given_driver = Kookaburra::GivenDriver.new({
-      :api_driver => api_driver,
-    })
-    ui_driver = Kookaburra::UIDriver.new({
-      :browser   => Capybara.current_session,
-      :test_data => test_data,
-    })
-    { :api_driver => api_driver, :given_driver => given_driver, :ui_driver => ui_driver }
+  class << self
+    # Provides the default adapter for the Kookaburra library. In most cases,
+    # this will probably be the `Capybara` class:
+    #
+    #   Kookaburra.adapter = Capybara
+    #
+    # We allow this to be passed in, so that we can avoid a hard-coded
+    # dependency on Capybara in this gem.
+    attr_accessor :adapter
+  end
+
+  # Whatever was set in `Kookaburra.adapter can be overriden in the mixin
+  # context. For example, in an RSpec example:
+  #
+  #   describe "Something" do
+  #     it "does something" do
+  #       self.kookaburra_adapter = CapybaraLikeThing
+  #       ...
+  #     end
+  #   end
+  #
+  attr_accessor :kookaburra_adapter
+
+  def kookaburra_adapter #:nodoc:
+    @kookaburra_adapter ||= Kookaburra.adapter
+  end
+
+  # Returns a configured instance of the `Kookaburra::APIDriver`
+  def api
+    kookaburra_drivers[:api] ||= Kookaburra::APIDriver.new(
+      :app => kookaburra_adapter.app,
+      :test_data => kookaburra_test_data)
+  end
+
+  # Returns a configured instance of the `Kookaburra::GivenDriver`
+  def given
+    kookaburra_drivers[:given] ||= Kookaburra::GivenDriver.new(:api_driver => api)
+  end
+
+  # Returns a configured instance of the `Kookaburra::UIDriver`
+  def ui
+    kookaburra_drivers[:ui] ||= Kookaburra::UIDriver.new(
+      :browser => kookaburra_adapter.current_session,
+      :test_data => kookaburra_test_data)
+  end
+
+  # 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.:
+  #
+  #   Before do
+  #     kookaburra_reset!
+  #   end
+  def kookaburra_reset!
+    @kookaburra_drivers = {}
+  end
+
+  private
+
+  # The Kookaburra::TestData instance should not be used directly, 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
+  # instance of the including class.
+  def kookaburra_drivers
+    @kookaburra_drivers ||= {}
   end
 end

data/lib/kookaburra/api_driver.rb

@@ -1,3 +1,5 @@
+require 'rack/test'
+
 module Kookaburra
   # Pattern:
   # - Get some data from test_data.factory

data/lib/kookaburra/test_data.rb

@@ -1,3 +1,5 @@
+require 'active_support/hash_with_indifferent_access'
+
 # This is the mechanism for sharing state between Cucumber steps.
 # If you're using instance variables, YOU'RE DOING IT WRONG.
 module Kookaburra

data/lib/kookaburra/ui_driver/mixins/has_strategies.rb

@@ -1,3 +1,5 @@
+require 'active_support/core_ext/class/attribute'
+
 module Kookaburra
   class UIDriver
     module HasStrategies

data/lib/requires.rb

@@ -1,5 +1,3 @@
-require 'active_support/hash_with_indifferent_access'
-
 def kookaburra_require_glob(path_glob)
   Dir.glob(path_glob).each do |file|
     require file

data/test/helper.rb

@@ -8,6 +8,7 @@ rescue Bundler::BundlerError => e
   exit e.status_code
 end
 require 'minitest/unit'
+require 'minitest/autorun'
 
 $LOAD_PATH.unshift(File.dirname(__FILE__))
 $LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))

data/test/kookaburra_test.rb

@@ -0,0 +1,111 @@
+require 'helper'
+
+describe Kookaburra do
+  describe 'as a mixin' do
+    let(:mixer_class) do
+      Class.new do
+        include Kookaburra
+      end
+    end
+
+    let(:mixer) do
+      mixer_class.new.tap do |m|
+        m.kookaburra_adapter = adapter
+      end
+    end
+
+    let(:mixer2) do
+      mixer_class.new.tap do |m|
+        m.kookaburra_adapter = adapter
+      end
+    end
+
+    let(:adapter) do
+      capybara_like_thing = Class.new do
+        def app
+          :an_application
+        end
+
+        def current_session
+          :a_current_session
+        end
+      end
+
+      capybara_like_thing.new
+    end
+
+    describe '#kookaburra_adapter' do
+      it 'is a read/write attribute' do
+        mixer = mixer_class.new
+        assert_nil mixer.kookaburra_adapter
+        mixer.kookaburra_adapter = :probably_Capybara
+        assert_equal :probably_Capybara, mixer.kookaburra_adapter
+      end
+    end
+
+    describe '#api' do
+      it 'is an instance of Kookaburra::APIDriver' do
+        assert_kind_of(Kookaburra::APIDriver, mixer.api)
+      end
+
+      it 'only creates a new one once for an instance of the including class' do
+        assert_same(mixer.api, mixer.api)
+      end
+
+      it 'is a different instance of APIDriver for each instance of the including class' do
+        refute_same mixer.api, mixer2.api
+      end
+    end
+
+    describe '#given' do
+      it 'is an instance of Kookaburra::GivenDriver' do
+        assert_kind_of(Kookaburra::GivenDriver, mixer.given)
+      end
+
+      it 'only creates a new one once for an instance of the including class' do
+        assert_same(mixer.given, mixer.given)
+      end
+
+      it 'is a different instance of GivenDriver for each instance of the including class' do
+        refute_same mixer.given, mixer2.given
+      end
+    end
+
+    describe '#ui' do
+      it 'is an instance of Kookaburra::UIDriver' do
+        assert_kind_of(Kookaburra::UIDriver, mixer.ui)
+      end
+
+      it 'only creates a new one once for an instance of the including class' do
+        assert_same(mixer.ui, mixer.ui)
+      end
+
+      it 'is a different instance of UIDriver for each instance of the including class' do
+        refute_same mixer.ui, mixer2.ui
+      end
+    end
+
+    describe '#kookaburra_reset!' do
+      it 'resets the api driver' do
+        api = mixer.api
+        mixer.kookaburra_reset!
+        api2 = mixer.api
+        refute_same api, api2
+      end
+
+      it 'resets the given driver' do
+        given = mixer.given
+        mixer.kookaburra_reset!
+        given2 = mixer.given
+        refute_same given, given2
+      end
+
+      it 'resets the ui driver' do
+        ui = mixer.ui
+        mixer.kookaburra_reset!
+        ui2 = mixer.ui
+        refute_same ui, ui2
+      end
+    end
+  end
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: kookaburra
 version: !ruby/object:Gem::Version 
-  hash: 23
+  hash: 27
   prerelease: 
   segments: 
   - 0
+  - 1
   - 0
-  - 4
-  version: 0.0.4
+  version: 0.1.0
 platform: ruby
 authors: 
 - Renewable Funding, LLC
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-01-15 00:00:00 Z
+date: 2012-01-16 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   version_requirements: &id001 !ruby/object:Gem::Requirement 
@@ -183,9 +183,9 @@ files:
 - lib/kookaburra/ui_driver/mixins/has_subcomponents.rb
 - lib/kookaburra/ui_driver/mixins/has_ui_component.rb
 - lib/kookaburra/ui_driver/ui_component.rb
-- lib/kookaburra/world_setup.rb
 - lib/requires.rb
 - test/helper.rb
+- test/kookaburra_test.rb
 homepage: http://github.com/projectdx/kookaburra
 licenses: 
 - MIT

data/lib/kookaburra/world_setup.rb

@@ -1,12 +0,0 @@
-# Can't use a custom World class, because cucumber-rails is already doing that
-module Kookaburra
-  module WorldSetup
-    def ui;    @drivers[:ui_driver   ]; end
-    def api;   @drivers[:api_driver  ]; end
-    def given; @drivers[:given_driver]; end
-
-    def kookaburra_world_setup
-      @drivers = Kookaburra.drivers
-    end
-  end
-end