kookaburra 0.21.1 → 0.22.0

data/Gemfile

@@ -1,8 +1,5 @@
 source 'http://rubygems.org'
 
-# Only need this gem for Ruby < 1.9.2
-gem 'basic_object' unless defined?(BasicObject)
-
 gem 'i18n'
 gem 'activesupport', '>= 3.0'
 gem 'patron'

data/Gemfile.lock

@@ -4,7 +4,6 @@ GEM
     activesupport (3.2.2)
       i18n (~> 0.6)
       multi_json (~> 1.0)
-    basic_object (0.0.1)
     capybara (1.1.2)
       mime-types (>= 1.16)
       nokogiri (>= 1.3.3)
@@ -76,7 +75,6 @@ PLATFORMS
 
 DEPENDENCIES
   activesupport (>= 3.0)
-  basic_object
   capybara
   i18n
   jeweler

data/README.markdown

@@ -52,17 +52,17 @@ For [RSpec] [RSpec] integration tests, just add the following to
     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
+    # c.app_host below should be set to whatever the root URL of your running
     # application is.
-    Kookaburra.configuration = {
-      :given_driver_class => MyApp::Kookaburra::GivenDriver,
-      :ui_driver_class => MyApp::Kookaburra::UIDriver,
-      :app_host => 'http://my_app.example.com:1234',
-      :browser => Capybara,
-      :server_error_detection => { |browser|
+    Kookaburra.configure do |c|
+      c.given_driver_class = MyApp::Kookaburra::GivenDriver
+      c.ui_driver_class = MyApp::Kookaburra::UIDriver
+      c.app_host = 'http://my_app.example.com:1234'
+      c.browser = Capybara
+      c.server_error_detection { |browser|
         browser.has_css?('head title', :text => 'Internal Server Error')
       }
-    }
+    end
 
     RSpec.configure do |c|
       c.include(Kookaburra::TestHelpers, :type => :request)
@@ -76,17 +76,17 @@ For [Cucumber] [Cucumber], add the following to `features/support/kookaburra_set
     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
+    # c.app_host below should be set to whatever the root URL of your running
     # application is.
-    Kookaburra.configuration = {
-      :given_driver_class => MyApp::Kookaburra::GivenDriver,
-      :ui_driver_class => MyApp::Kookaburra::UIDriver,
-      :app_host => 'http://my_app.example.com:1234',
-      :browser => Capybara,
-      :server_error_detection => { |browser|
+    Kookaburra.configure do |c|
+      c.given_driver_class = MyApp::Kookaburra::GivenDriver
+      c.ui_driver_class = MyApp::Kookaburra::UIDriver
+      c.app_host = 'http://my_app.example.com:1234'
+      c.browser = Capybara
+      c.server_error_detection { |browser|
         browser.has_css?('head title', :text => 'Internal Server Error')
       }
-    }
+    end
 
     World(Kookaburra::TestHelpers)
 
@@ -326,7 +326,7 @@ for your application:
     class MyApp::Kookaburra::GivenDriver < Kookaburra::GivenDriver
       # Specify the APIDriver to use
       def api
-        @api ||= MyApp::Kookaburra::APIDriver.new(:app_host => initialization_options[:app_host])
+        @api ||= MyApp::Kookaburra::APIDriver.new(configuration)
       end
 
       def existing_account(nickname)
@@ -394,8 +394,8 @@ within your subclass:
       ui_component :sign_in_screen, SignInScreen
 
       def sign_in(account_nickname)
-        account = test_data.accounts[account_nickname]
-        sign_in_screen.show
+        account = mental_model.accounts[account_nickname]
+        address_bar.go_to(sign_in_screen)
         sign_in_screen.submit_login(account['username'], account['password'])
       end
     end

data/VERSION

@@ -1 +1 @@
-0.21.1
+0.22.0

data/kookaburra.gemspec

@@ -5,7 +5,7 @@
 
 Gem::Specification.new do |s|
   s.name = "kookaburra"
-  s.version = "0.21.1"
+  s.version = "0.22.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"]
@@ -30,24 +30,27 @@ Gem::Specification.new do |s|
     "kookaburra.gemspec",
     "lib/kookaburra.rb",
     "lib/kookaburra/api_driver.rb",
+    "lib/kookaburra/assertion.rb",
+    "lib/kookaburra/configuration.rb",
     "lib/kookaburra/dependency_accessor.rb",
     "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/test_helpers.rb",
     "lib/kookaburra/ui_driver.rb",
     "lib/kookaburra/ui_driver/ui_component.rb",
+    "lib/kookaburra/ui_driver/ui_component/address_bar.rb",
     "spec/integration/test_a_rack_application_spec.rb",
     "spec/kookaburra/api_driver_spec.rb",
+    "spec/kookaburra/configuration_spec.rb",
     "spec/kookaburra/json_api_driver_spec.rb",
     "spec/kookaburra/mental_model_spec.rb",
-    "spec/kookaburra/null_browser_spec.rb",
-    "spec/kookaburra/test_helpers_spec.rb",
+    "spec/kookaburra/ui_driver/ui_component/address_bar_spec.rb",
     "spec/kookaburra/ui_driver/ui_component_spec.rb",
     "spec/kookaburra/ui_driver_spec.rb",
     "spec/kookaburra_spec.rb",
+    "spec/support/shared_examples/it_can_make_assertions.rb",
     "spec/support/shared_examples/it_has_a_dependency_accessor.rb"
   ]
   s.homepage = "http://github.com/projectdx/kookaburra"
@@ -60,7 +63,6 @@ Gem::Specification.new do |s|
     s.specification_version = 3
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
-      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<patron>, [">= 0"])
@@ -73,7 +75,6 @@ Gem::Specification.new do |s|
       s.add_development_dependency(%q<reek>, [">= 0"])
       s.add_development_dependency(%q<sinatra>, [">= 0"])
     else
-      s.add_dependency(%q<basic_object>, [">= 0"])
       s.add_dependency(%q<i18n>, [">= 0"])
       s.add_dependency(%q<activesupport>, [">= 3.0"])
       s.add_dependency(%q<patron>, [">= 0"])
@@ -87,7 +88,6 @@ Gem::Specification.new do |s|
       s.add_dependency(%q<sinatra>, [">= 0"])
     end
   else
-    s.add_dependency(%q<basic_object>, [">= 0"])
     s.add_dependency(%q<i18n>, [">= 0"])
     s.add_dependency(%q<activesupport>, [">= 3.0"])
     s.add_dependency(%q<patron>, [">= 0"])

data/lib/kookaburra/api_driver.rb

@@ -4,17 +4,14 @@ require 'patron'
 
 class Kookaburra
   class APIDriver < SimpleDelegator
-    # Wraps `:http_client` in a `SimpleDelegator` that causes request methods to
+    # Wraps `http_client` in a `SimpleDelegator` that causes request methods to
     # either return the response body or raise an exception on an unexpected
     # response status code.
     #
-    # @option options [String] :app_host The root URL of your running
-    #   application (e.g. "http://my_app.example.com:12345")
-    # @option options [Patron::Session] :http_client (Patron::Session.new) The
-    #   object responsible for actually making HTTP calls to your application.
-    def initialize(options = {})
-      http_client = options[:http_client] || Patron::Session.new
-      http_client.base_url = options[:app_host] if options.has_key?(:app_host)
+    # @param [Kookaburra::Configuration] configuration
+    # @param [Patron::Session] http_client
+    def initialize(configuration, http_client = Patron::Session.new)
+      http_client.base_url = configuration.app_host
       super(http_client)
     end
 

data/lib/kookaburra/assertion.rb

@@ -0,0 +1,24 @@
+require 'kookaburra/exceptions'
+
+class Kookaburra
+  # Include this module wherever you need to be able to make a quick,
+  # low-ceremony assertion.
+  module Assertion
+    protected
+
+    # Provides a mechanism to make assertions about the state of your
+    # UIComponent without relying on a specific testing framework. A good
+    # reason to use this would be to provide a more informative error message
+    # when a pre-condition is not met, rather than waiting on an operation
+    # further down the line to fail.
+    #
+    # @param [boolean expression] test an expression that will be evaluated in a boolean context
+    # @param [String] message the exception message that will be used if
+    #   test is false
+    #
+    # @raise [Kookaburra::AssertionFailed] raised if test evaluates to false
+    def assert(test, message = "You might want to provide a better message, eh?")
+      test or raise AssertionFailed, message
+    end
+  end
+end

data/lib/kookaburra/configuration.rb

@@ -0,0 +1,70 @@
+require 'ostruct'
+require 'delegate'
+require 'kookaburra/dependency_accessor'
+
+class Kookaburra
+  # Provides access to the configuration data used throughout Kookaburra
+  class Configuration
+    extend DependencyAccessor
+
+    # The class to use as your GivenDriver
+    #
+    # @attribute [rw] given_driver_class
+    # @raise [Kookaburra::ConfigurationError] if you try to read this attribute
+    #   without it having been set
+    dependency_accessor :given_driver_class
+
+    # The class to use as your UIDriver
+    #
+    # @attribute [rw] ui_driver_class
+    # @raise [Kookaburra::ConfigurationError] if you try to read this attribute
+    #   without it having been set
+    dependency_accessor :ui_driver_class
+
+    # This object is used by {Kookaburra::UIDriver::UIComponent} to interface
+    # with the web browser. Typically it should be an instance of
+    # `Capybara::Session`
+    #
+    # @attribute [rw] browser
+    # @raise [Kookaburra::ConfigurationError] if you try to read this attribute
+    #   without it having been set
+    dependency_accessor :browser
+
+    # This is the root URL of your running application, including the port
+    # number if necessary. (e.g. "http://my.example.com:12345")
+    #
+    # @attribute [rw] app_host
+    # @raise [Kookaburra::ConfigurationError] if you try to read this attribute
+    #   without it having been set
+    dependency_accessor :app_host
+
+    # This is the {Kookaburra::MentalModel} that is shared between your
+    # GivenDriver and your UIDriver. This attribute is managed by {Kookaburra},
+    # so you shouldn't need to change it yourself.
+    #
+    # @attribute [rw] mental_model
+    # @raise [Kookaburra::ConfigurationError] if you try to read this attribute
+    #   without it having been set
+    dependency_accessor :mental_model
+
+    # Specify a function that can be used to determine if a server error has
+    # occured within your application.
+    #
+    # If the function returns `true`, then Kookaburra will assume that the
+    # application has responded with an error.
+    #
+    # @yield whichever object was assigned to {#browser}
+    #
+    # @example If the page title is "Internal Server Error"
+    #   config.server_error_detection { |browser|
+    #     browser.has_css?('head title', :text => 'Internal Server Error')
+    #   }
+    def server_error_detection(&blk)
+      if block_given?
+        @server_error_detection = blk
+      else
+        @server_error_detection
+      end
+    end
+  end
+end

data/lib/kookaburra/dependency_accessor.rb

@@ -18,7 +18,10 @@ class Kookaburra
         instance_variable_get("@#{name}") or raise "No %s object was set on %s initialization." \
           % [name, [self.class.name, 'an Anonymous Class!!!'].reject(&:blank?).first]
       end
-      private name
+
+      define_method("#{name}=") do |value|
+        instance_variable_set("@#{name}", value)
+      end
     end
   end
 end

data/lib/kookaburra/given_driver.rb

@@ -1,4 +1,4 @@
-require 'kookaburra/dependency_accessor'
+require 'active_support/core_ext/module/delegation'
 
 class Kookaburra
   # Your GivenDriver subclass is used to define your testing DSL for setting up
@@ -7,15 +7,14 @@ class Kookaburra
   # comprised of several distinct API calls as well as access to Kookaburra's
   # test data store.
   #
-  # @abstract Subclass and implement your Given DSL. You must also provide an
-  #   implementation of #api that returns an instance of your APIDriver.
+  # @abstract Subclass and implement your Given DSL.
   #
   # @example GivenDriver subclass
   #   module MyApp
   #     module Kookaburra
   #       class GivenDriver < ::Kookaburra::GivenDriver
   #         def api
-  #           @api ||= APIDriver.new(:app_host => initialization_options[:app_host])
+  #           @api ||= APIDriver.new(configuration)
   #         end
   #
   #         def a_widget(name, attributes = {})
@@ -34,22 +33,23 @@ class Kookaburra
   #     end
   #   end
   class GivenDriver
-    extend DependencyAccessor
-
     # It is unlikely that you would call #initialize yourself; your GivenDriver
     # object is instantiated for you by {Kookaburra#given}.
     #
-    # @option options [Kookaburra::MentalModel] :mental_model the MentalModel
-    #   instance used by your tests
-    # @option options [String] :app_host The root URL of your running
-    #   application (e.g. "http://my_app.example.com:12345")
-    def initialize(options = {})
-      @initialization_options = options
-      @mental_model = options[:mental_model]
+    # @param [Kookaburra::Configuration] configuration
+    def initialize(configuration)
+      @configuration = configuration
     end
 
     protected
 
+    attr_reader :configuration
+
+    # Access to the shared {Kookaburra::MentalModel} instance
+    #
+    # @attribute [rw] mental_model
+    delegate :mental_model, :to => :configuration
+
     # Used to access your APIDriver in your own GivenDriver implementation
     #
     # @abstract
@@ -59,18 +59,5 @@ class Kookaburra
     def api
       raise ConfigurationError, "You must implement #api in your subclass."
     end
-
-    # The full set of options passed in to {#initialize}
-    #
-    # Access is provided so that you can use these when instantiating your
-    # {APIDriver} in your {#api} implementation.
-    attr_reader :initialization_options
-
-    # A reference to the {Kookaburra::MentalModel} object that this GivenDriver
-    # instance was created with.
-    #
-    # @attribute [r]
-    # @return [Kookaburra::MentalModel]
-    dependency_accessor :mental_model
   end
 end

data/lib/kookaburra/json_api_driver.rb

@@ -14,11 +14,12 @@ class Kookaburra
     #
     # Sets both the "Content-Type" and "Accept" headers to "application/json".
     #
-    # @option options [Kookaburra::APIDriver] :api_driver (Kookaburra::APIDriver.new)
+    # @param [Kookaburra::Configuration] configuration
+    # @param [Kookaburra::APIDriver] api_driver (Kookaburra::APIDriver.new)
     #   The APIDriver instance to be delegated to. Changing this is probably
-    #   only useful for testing.
-    def initialize(options = {})
-      api_driver = options[:api_driver] || APIDriver.new(:app_host => options[:app_host])
+    #   only useful for testing Kookaburra itself.
+    def initialize(configuration, api_driver = nil)
+      api_driver = api_driver || APIDriver.new(configuration)
       api_driver.headers.merge!(
         'Content-Type' => 'application/json',
         'Accept' => 'application/json'

data/lib/kookaburra/test_helpers.rb

@@ -1,4 +1,5 @@
 require 'kookaburra'
+require 'active_support/core_ext/module/delegation'
 
 class Kookaburra
   # This module is intended to be mixed in to your testing context to provide
@@ -12,15 +13,15 @@ class Kookaburra
   #   require 'my_app/kookaburra/given_driver'
   #   require 'my_app/kookaburra/ui_driver'
   #   
-  #   Kookaburra.configuration = {
-  #     :given_driver_class => MyApp::Kookaburra::GivenDriver,
-  #     :ui_driver_class => MyApp::Kookaburra::UIDriver,
-  #     :app_host => 'http://my_app.example.com:12345',
-  #     :browser => Capybara,
-  #     :server_error_detection => lambda { |browser|
-  #       browser.has_css?('h1', text: 'Internal Server Error')
+  #   Kookaburra.configure do |c|
+  #     c.given_driver_class = myapp::kookaburra::givendriver,
+  #     c.ui_driver_class = myapp::kookaburra::uidriver,
+  #     c.app_host = 'http://my_app.example.com:12345',
+  #     c.browser = capybara,
+  #     c.server_error_detection { |browser|
+  #       browser.has_css?('h1', text: 'internal server error')
   #     }
-  #   }
+  #   end
   #
   #   RSpec.configure do |c|
   #     c.include(Kookaburra::TestHelpers, :type => :request)
@@ -49,15 +50,15 @@ class Kookaburra
   #   require 'my_app/kookaburra/given_driver'
   #   require 'my_app/kookaburra/ui_driver'
   #   
-  #   Kookaburra.configuration = {
-  #     :given_driver_class => MyApp::Kookaburra::GivenDriver,
-  #     :ui_driver_class => MyApp::Kookaburra::UIDriver,
-  #     :app_host => 'http://my_app.example.com:12345',
-  #     :browser => Capybara,
-  #     :server_error_detection => lambda { |browser|
-  #       browser.has_css?('h1', text: 'Internal Server Error')
+  #   Kookaburra.configure do |c|
+  #     c.given_driver_class = myapp::kookaburra::givendriver,
+  #     c.ui_driver_class = myapp::kookaburra::uidriver,
+  #     c.app_host = 'http://my_app.example.com:12345',
+  #     c.browser = capybara,
+  #     c.server_error_detection { |browser|
+  #       browser.has_css?('h1', text: 'internal server error')
   #     }
-  #   }
+  #   end
   #
   #   World(Kookaburra::TestHelpers)
   #
@@ -85,7 +86,7 @@ class Kookaburra
     #
     # @return [Kookaburra]
     def k
-      @k ||= Kookaburra.new(Kookaburra.configuration)
+      @k ||= Kookaburra.new
     end
 
     # @method given

data/lib/kookaburra/ui_driver/ui_component/address_bar.rb

@@ -0,0 +1,23 @@
+require 'kookaburra/ui_driver/ui_component'
+
+class Kookaburra
+  class UIDriver
+    class UIComponent
+      # This represents the browser's address bar, so that you can tell your
+      # tests to explicitly visit a URL.
+      class AddressBar < UIComponent
+        # Causes the browser to explicitly navigate to the given url.
+        #
+        # @param [String, #url] addressable Can be either a URL string or an
+        # object that responds to #url and returns a URL string
+        def go_to(addressable)
+          if addressable.respond_to?(:url)
+            browser.visit(addressable.url)
+          else
+            browser.visit(addressable.to_s)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/kookaburra/ui_driver/ui_component.rb

@@ -1,4 +1,5 @@
 require 'kookaburra/exceptions'
+require 'kookaburra/assertion'
 require 'active_support/core_ext/object/try'
 
 class Kookaburra
@@ -63,26 +64,21 @@ class Kookaburra
     # element.    
     #
     # @abstract Subclass and implement (at least) {#component_locator}. Unless
-    #   you override the default implementation of {#show}, you must also
+    #   you override the default implementation of {#url}, you must also
     #   override the {#component_path} method.
     class UIComponent
+      include Assertion
+
       # New UIComponent instances are typically created for you by your
       # {Kookaburra::UIDriver} instance.
       #
       # @see Kookaburra::UIDriver.ui_component
       #
-      # @option options [Capybara::Session] :browser This is the browser driver
-      #   that allows you to interact with the web application's interface.
-      # @option options [String] :app_host The root URL of your running
-      #   application (e.g. "http://my_app.example.com:12345")
-      # @option options [Proc] :server_error_detection A proc that will receive
-      #   the object passed in to the :browser option as an argument and must
-      #   return `true` if the server responded with an unexpected error or
-      #   `false` if it did not.
-      def initialize(options = {})
-        @browser = options[:browser]
-        @app_host = options[:app_host]
-        @server_error_detection = options[:server_error_detection]
+      # @param [Kookaburra::Configuration] configuration
+      def initialize(configuration)
+        @browser = configuration.browser
+        @app_host = configuration.app_host
+        @server_error_detection = configuration.server_error_detection
       end
 
       # If the UIComponent is sent a message it does not understand, it will
@@ -107,27 +103,6 @@ class Kookaburra
         super || browser.respond_to?(name)
       end
 
-      # Causes the UIComponent to be visible.
-      #
-      # The browser to navigates directly to {#component_path} (unless the
-      # component is already visible).
-      #
-      # You may need to override this method in your own UIComponent subclasses,
-      # especially for components that are dynamically added/removed on the page
-      # in response to user actions. The implementation should not make any
-      # assumptions about the current state of the user interface before it is
-      # invoked.
-      #
-      # @param args Any arguments are passed to the {#component_path} method.
-      #
-      # @raise [RuntimeError] if the component is not visible after attempting
-      #   to make it so.
-      def show(*args)
-        return if visible?
-        browser.visit component_url(*args)
-        assert visible?, "The #{self.class.name} component is not visible!"
-      end
-
       # Is the component's element found on the page and is it considered
       # "visible" by the browser driver.
       def visible?
@@ -138,30 +113,16 @@ class Kookaburra
         visible
       end
 
-      protected
-
-      # This is the browser driver with which the UIComponent was initialized.
-      # 
-      # If no :browser option was specified in {#initialize}, it returns a
-      # default {Kookaburra::NullBrowser} instance.
-      def browser
-        @browser ||= NullBrowser.new
+      # Returns the full URL by appending {#component_path} to the value of the
+      # {Kookaburra::Configuration#app_host} from the initialized configuration.
+      def url(*args)
+        "#{@app_host}#{component_path(*args)}"
       end
 
-      # Provides a mechanism to make assertions about the state of your
-      # UIComponent without relying on a specific testing framework. A good
-      # reason to use this would be to provide a more informative error message
-      # when a pre-condition is not met, rather than waiting on an operation
-      # further down the line to fail.
-      #
-      # @param test an expression that will be evaluated in a boolean context
-      # @param [String] message the exception message that will be used if
-      #   test is false
-      #
-      # @raise [Kookaburra::AssertionFailed] raised if test evaluates to false
-      def assert(test, message = "You might want to provide a better message, eh?")
-        test or raise AssertionFailed, message
-      end
+      protected
+
+      # The browser object from the initialized configuration
+      attr_reader :browser
 
       # @abstract
       # @return [String] the URL path that should be loaded in order to reach this component
@@ -171,12 +132,6 @@ class Kookaburra
         raise ConfigurationError, "You must define #{self.class.name}#component_path."
       end
 
-      # Returns the full URL by appending {#component_path} to the value of the
-      # :app_host option passed to {#initialize}.
-      def component_url(*args)
-        "#{@app_host}#{component_path(*args)}"
-      end
-
       # @abstract
       # @return [String] the CSS3 selector that will find the element in the DOM
       # @raise [Kookaburra::ConfigurationError] raised if you haven't provided
@@ -185,7 +140,8 @@ class Kookaburra
         raise ConfigurationError, "You must define #{self.class.name}#component_locator."
       end
 
-      # Runs the server error detection function specified in {#initialize}.
+      # Runs the server error detection function specified in
+      # {Kookaburra::Configuration#server_error_detection}.
       #
       # It's a noop if no server error detection was specified.
       #