kookaburra 1.1.0 → 1.2.0

data/README.markdown

@@ -115,22 +115,28 @@ and shut down a Rack application server. Just add the following to
 `spec/support/kookaburra_setup.rb`:
 
     require 'kookaburra/test_helpers'
-    require 'thwait'
-    require 'find_a_port' # from the find_a_port gem
+    require 'kookaburra/rack_app_server'
 
     # Change these to the files that define your custom GivenDriver and UIDriver
     # implementations.
     require 'my_app/kookaburra/given_driver'
     require 'my_app/kookaburra/ui_driver'
 
-    APP_PORT = FindAPort.available_port
+    # `MyApplication` below should be replaced with the object that
+    # implements the Rack `#call` interface for your application. For a
+    # Rails app, this would be along the lines of
+    # `MyAppName::Application`.
+    app_server = Kookaburra::RackAppServer.new do
+      require 'path/to/my_application'
+      MyApplication
+    end
 
-    # c.app_host below should be set to whatever the root URL of your running
-    # application is.
+    # 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.ui_driver_class = MyApp::Kookaburra::UIDriver
-      c.app_host = 'http://localhost:%d' % APP_PORT
+      c.app_host = 'http://localhost:%d' % app_server.port
       c.browser = Capybara::Session.new(:selenium)
       c.server_error_detection { |browser|
         browser.has_css?('head title', :text => 'Internal Server Error')
@@ -140,36 +146,12 @@ and shut down a Rack application server. Just add the following to
     RSpec.configure do |c|
       c.include(Kookaburra::TestHelpers, :type => :request)
 
-      # Start the application server prior to running a group of integration
-      # specs. `MyApplication` below should be replaced with the object that
-      # implements the Rack `#call` interface for your application. For a Rails
-      # app, this would be along the lines of `MyAppName::Application`.
       c.before(:all, :type => :request) do
-        # Run the server process in a forked process, and get a handle on that
-        # process, so that it can be shut down after the tests run.
-        #
-        # Note that you cannot fork under JRuby and will need to use a thread.
-        # See `spec/integration/test_a_rack_application_spec.rb` for an
-        # example.
-        @rack_server_pid = fork do
-          Capybara.server_port = APP_PORT
-          Capybara::Server.new(MyApplication).boot
-
-          # This ensures that this forked process keeps running, because the
-          # actual server is started in a thread by Capybara.
-          ThreadsWait.all_waits(Thread.list)
-        end
-
-        # Give the server a chance to start up in the forked process. You may
-        # need to adjust this depending on how long your application takes to
-        # start up.
-        sleep 1
+        app_server.boot
       end
 
-      # After the tests run, kill the server process. 
       c.after(:all, :type => :request) do
-        Process.kill(9, @rack_server_pid)
-        Process.wait
+        app_server.shutdown
       end
     end
 
@@ -214,22 +196,28 @@ and shut down a Rack application server. Just add the following to
 `features/support/kookaburra_setup.rb`:
 
     require 'kookaburra/test_helpers'
-    require 'thwait'
-    require 'find_a_port' # from the find_a_port gem
+    require 'kookaburra/rack_app_server'
 
     # Change these to the files that define your custom GivenDriver and UIDriver
     # implementations.
     require 'my_app/kookaburra/given_driver'
     require 'my_app/kookaburra/ui_driver'
 
-    APP_PORT = FindAPort.available_port
+    # `MyApplication` below should be replaced with the object that
+    # implements the Rack `#call` interface for your application. For a
+    # Rails app, this would be along the lines of
+    # `MyAppName::Application`.
+    app_server = Kookaburra::RackAppServer.new do
+      require 'path/to/my_application'
+      MyApplication
+    end
 
-    # c.app_host below should be set to whatever the root URL of your running
-    # application is.
+    # 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.ui_driver_class = MyApp::Kookaburra::UIDriver
-      c.app_host = 'http://localhost:%d' % APP_PORT
+      c.app_host = 'http://localhost:%d' % app_server.port
       c.browser = Capybara::Session.new(:selenium)
       c.server_error_detection { |browser|
         browser.has_css?('head title', :text => 'Internal Server Error')
@@ -238,34 +226,10 @@ and shut down a Rack application server. Just add the following to
 
     World(Kookaburra::TestHelpers)
 
-    # Start the application server prior to running the tests.
-    # `MyApplication` below should be replaced with the object that
-    # implements the Rack `#call` interface for your application. For a Rails
-    # app, this would be along the lines of `MyAppName::Application`.
-    # Runs the server process in a forked process, and get a handle on that
-    # process, so that it can be shut down after the tests run.
-    #
-    # Note that you cannot fork under JRuby and will need to use a thread.
-    # See `spec/integration/test_a_rack_application_spec.rb` for an
-    # example.
-    @rack_server_pid = fork do
-      Capybara.server_port = APP_PORT
-      Capybara::Server.new(MyApplication).boot
-
-      # This ensures that this forked process keeps running, because the
-      # actual server is started in a thread by Capybara.
-      ThreadsWait.all_waits(Thread.list)
-    end
-
-    # Give the server a chance to start up in the forked process. You may
-    # need to adjust this depending on how long your application takes to
-    # start up.
-    sleep 1
+    app_server.boot
 
-    # After the tests run, kill the server process. 
     at_exit do
-      Process.kill(9, @rack_server_pid)
-      Process.wait
+      app_server.shutdown
     end
 
 ## Defining Your Testing DSL ##
@@ -297,7 +261,7 @@ have the following scenario defined for an e-commerce application:
     Feature: Purchase Items in Cart
 
       Scenario: Using Existing Billing and Shipping Information
-        
+
         Given I have an existing account
         And I have previously specified default payment options
         And I have previously specified default shipping options

data/VERSION

@@ -1 +1 @@
-1.1.0
+1.2.0

data/kookaburra.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = "kookaburra"
-  s.version = "1.1.0"
+  s.version = "1.2.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-12-14"
+  s.date = "2013-03-16"
   s.description = "Cucumber + Capybara = Kookaburra? It made sense at the time."
   s.email = "johnwilger@gmail.com"
   s.extra_rdoc_files = [
@@ -39,6 +39,7 @@ Gem::Specification.new do |s|
     "lib/kookaburra/given_driver.rb",
     "lib/kookaburra/mental_model.rb",
     "lib/kookaburra/mental_model_matcher.rb",
+    "lib/kookaburra/rack_app_server.rb",
     "lib/kookaburra/test_helpers.rb",
     "lib/kookaburra/ui_driver.rb",
     "lib/kookaburra/ui_driver/has_ui_components.rb",

data/lib/kookaburra/api_driver.rb

@@ -5,11 +5,11 @@ require 'kookaburra/exceptions'
 class Kookaburra
   # Communicate with a Web Services API
   #
-  # You will create a subclass of `APIDriver` in your testing
+  # You will create a subclass of {APIDriver} in your testing
   # implementation to be used with you subclass of
-  # `Kookaburra::GivenDriver`. While the `GivenDriver` implements the
+  # {Kookaburra::GivenDriver}. While the {GivenDriver} implements the
   # "business domain" DSL for setting up your application state, the
-  # `APIDriver` maps discreet operations to your application's web
+  # {APIDriver} 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.
@@ -17,8 +17,8 @@ class Kookaburra
     class << self
       # Serializes input data
       #
-      # If specified, any input data provided to `APIDriver#post`,
-      # `APIDriver#put` or `APIDriver#request` will be processed through
+      # If specified, any input data provided to {APIDriver#post},
+      # {APIDriver#put} or {APIDriver#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
@@ -40,7 +40,7 @@ class Kookaburra
       # Deserialize response body
       #
       # If specified, the response bodies of all requests made using
-      # this `APIDriver` will be processed through this function prior
+      # this {APIDriver} will be processed through this function prior
       # to being returned.
       #
       # @yieldparam data [String] The response body sent by the HTTP
@@ -63,7 +63,7 @@ class Kookaburra
       # Set custom HTTP headers
       #
       # Can be called multiple times to set HTTP headers that will be
-      # provided with every request made by the `APIDriver`.
+      # provided with every request made by the {APIDriver}.
       #
       # @param [String] name The name of the header, e.g. 'Content-Type'
       # @param [String] value The value to which the header is set
@@ -87,7 +87,7 @@ class Kookaburra
       end
     end
 
-    # Create a new `APIDriver` instance
+    # Create a new {APIDriver} instance
     #
     # @param [Kookaburra::Configuration] configuration
     # @param [RestClient] http_client (optional) Generally only
@@ -146,7 +146,7 @@ class Kookaburra
     #
     # @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
+    #        {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

data/lib/kookaburra/configuration.rb

@@ -23,7 +23,7 @@ class Kookaburra
 
     # This object is used by {Kookaburra::UIDriver::UIComponent} to interface
     # with the web browser. Typically it should be an instance of
-    # `Capybara::Session`
+    # {Capybara::Session}
     #
     # @attribute [rw] browser
     # @raise [Kookaburra::ConfigurationError] if you try to read this attribute

data/lib/kookaburra/given_driver.rb

@@ -5,7 +5,7 @@ class Kookaburra
   # test preconditions. Unlike {Kookaburra::APIDriver}, which is meant to be a
   # simple mapping to your application's API, a method in the GivenDriver may be
   # comprised of several distinct API calls as well as access to Kookaburra's
-  # test data store via `#mental_model`.
+  # test data store via {#mental_model}.
   #
   # @abstract Subclass and implement your Given DSL.
   #

data/lib/kookaburra/mental_model.rb

@@ -32,7 +32,7 @@ class Kookaburra
       true
     end
 
-    # A MentalModel::Collection behaves much like a `Hash` object, with the
+    # A MentalModel::Collection behaves much like a {Hash} object, with the
     # exception that it will raise an {UnknownKeyError} rather than return nil
     # if you attempt to access a key that has not been set. The exception
     # attempts to provide a more helpful error message.
@@ -61,7 +61,7 @@ class Kookaburra
       end
 
       # Unlike a Hash, this object is only identical to another if the actual
-      # `#object_id` attributes match.
+      # {#object_id} attributes match.
       #
       # @return [Boolean]
       def ===(other)
@@ -71,8 +71,8 @@ class Kookaburra
       # Returns a new hash that contains key/value pairs for the
       # specified keys with values copied from this collection.
       #
-      # @note This is semantically the same as `Hash#slice` as provided
-      #   by `ActiveSupport::CoreExt::Hash`
+      # @note This is semantically the same as {Hash#slice} as provided
+      #   by {ActiveSupport::CoreExt::Hash}
       # @param [Object] keys The list of keys that should be copied from
       #   the collection
       # @return [Hash] The resulting keys/values from the collection
@@ -86,8 +86,8 @@ class Kookaburra
       # Returns a new hash that contains every key/value from this
       # collection *except* for the specified keys
       #
-      # @note This is semantically the same as `Hash#except` as provided
-      #   by `ActiveSupport::CoreExt::Hash`
+      # @note This is semantically the same as {Hash#except} as provided
+      #   by {ActiveSupport::CoreExt::Hash}
       # @param [Object] keys The list of keys that should *not* be
       #   copied from the collection
       # @return [Hash] The resulting keys/values from the collection
@@ -99,8 +99,8 @@ class Kookaburra
       # in a subcollection.
       #
       # Deleting a key/value pair from a collection on the MentalModel works just
-      # like `Hash#delete` but with a side effect - deleted members are added to
-      # a subcollection, accessible at `#deleted`.
+      # like {Hash#delete} but with a side effect - deleted members are added to
+      # a subcollection, accessible at {#deleted}.
       #
       # @param key the key to delete from the collection
       #
@@ -114,7 +114,7 @@ class Kookaburra
 
       # Finds or initializes, and returns, the subcollection of deleted items
       #
-      # Key/value pairs `#delete`d from a collection on the MentalModel will be added
+      # Key/value pairs {#delete}d from a collection on the MentalModel will be added
       # to this subcollection.
       #
       # @return [Kookaburra::MentalModel::Collection] the deleted items subcollection
@@ -125,8 +125,8 @@ class Kookaburra
       # Deletes key/value pairs from the collection for which the given block evaluates
       # to true, and persists all deleted pairs in a subcollection.
       #
-      # Works just like `Hash#delete_if` but with a side effect - deleted members are
-      # added to a subcollection, accessible at `#deleted`.
+      # Works just like {Hash#delete_if} but with a side effect - deleted members are
+      # added to a subcollection, accessible at {#deleted}.
       #
       # @return [Hash] the key/value pairs still remaining after the deletion
       def delete_if(&block)

data/lib/kookaburra/rack_app_server.rb

@@ -0,0 +1,110 @@
+require 'capybara'
+require 'thwait'
+require 'find_a_port'
+
+# Handles Starting/Stopping Rack Server for Tests
+#
+# {RackAppServer} is basically a wrapper around {Capybara::Server} that
+# makes it a bit easier to use Kookaburra with a Rack application (such
+# as Rails or Sinatra) when you want to run your tests locally against a
+# server that is only running for the duration of the tests. You simply
+# tell it how to get ahold of your Rack application (see {#initialize})
+# and then call {#boot} before your tests run and {#shutdown} after your
+# tests run.
+#
+# @example using RSpec
+#   # put this in something like `spec_helper.rb`
+#   app_server = Kookaburra::RackAppServer.new do
+#     # unless you are in JRuby, this stuff all runs in a new fork later
+#     # on
+#     ENV['RAILS_ENV'] = 'test'
+#     require File.expand_path(File.join('..', '..', 'config', 'environment'), __FILE__)
+#     MyAppName::Application
+#   end
+#   RSpec.configure do
+#     c.before(:all) do
+#       app_server.boot
+#     end
+#     c.after(:all) do
+#       app_server.shutdown
+#     end
+#   end
+class Kookaburra::RackAppServer
+  attr_reader :port
+
+  # Sets up a new app server
+  #
+  # @param startup_timeout [Integer] The maximum number of seconds to
+  #        wait for the app server to respond
+  # @yieldreturn [#call] block must return a valid Rack application
+  def initialize(startup_timeout=10, &rack_app_initializer)
+    self.startup_timeout = startup_timeout
+    self.rack_app_initializer = rack_app_initializer
+    self.port = FindAPort.available_port
+  end
+
+  # Start the application server
+  #
+  # This will launch the server on a (detected to be) available port. It
+  # will then monitor that port and only return once the app server is
+  # responding (or after the timeout period specified on {#initialize}).
+  def boot
+    if defined?(JRUBY_VERSION)
+      thread_app_server
+    else
+      fork_app_server
+    end
+    wait_for_app_to_respond
+  end
+
+  def shutdown
+    return if defined?(JRUBY_VERSION)
+    Process.kill(9, rack_server_pid)
+    Process.wait
+  end
+
+  private
+
+  attr_accessor :rack_app_initializer, :rack_server_pid, :startup_timeout
+  attr_writer :port
+
+  def thread_app_server
+    Thread.new { start_server }
+  end
+
+  def fork_app_server
+    self.rack_server_pid = fork do
+      start_server
+    end
+  end
+
+  def start_server
+    app = rack_app_initializer.call
+    Capybara.server_port = port
+    Capybara::Server.new(app).boot
+    # This ensures that this forked process keeps running, because the
+    # actual server is started in a thread by Capybara.
+    ThreadsWait.all_waits(Thread.list)
+  end
+
+  def wait_for_app_to_respond
+    begin
+      Timeout.timeout(startup_timeout) do
+        next until running?
+      end
+    rescue Timeout::Error
+      raise "Application does not seem to be responding on port #{port}."
+    end
+  end
+
+  def running?
+    res = Net::HTTP.start('localhost', port) { |http| http.get('/__identify__') }
+    if res.is_a?(Net::HTTPSuccess) or res.is_a?(Net::HTTPRedirection)
+      true
+    else
+      false
+    end
+  rescue Errno::ECONNREFUSED, Errno::EBADF, Errno::ETIMEDOUT
+    false
+  end
+end

data/lib/kookaburra/ui_driver/has_ui_components.rb

@@ -3,10 +3,10 @@ class Kookaburra
     # Classes that can contain reerences to {UIComponent} instances
     # (i.e. {UIDriver} and {UIDriver::UIComponent} subclasses are
     # extended by this module in order to set up those references.
-    # `UIDriver` and `UIComponent` are already extended, so you
+    # {UIDriver} and {UIComponent} are already extended, so you
     # shouldn't need to do so elsewhere.
     #
-    # Instances of the extending class must define a `#configuration`
+    # Instances of the extending class must define a {#configuration}
     # method that returns the current Kookaburra::Configuration
     module HasUIComponents
 
@@ -17,7 +17,7 @@ class Kookaburra
       # @param [Class] component_class The {UIComponent} subclass that defines
       #   this component.
       # @param [Hash] options An extra options hash that will be passed
-      #   to the `UIComponent` on initialization.
+      #   to the {UIComponent} on initialization.
       def ui_component(component_name, component_class, options = {})
         define_method(component_name) do
           component_class.new(configuration, options)

data/lib/kookaburra/ui_driver/scoped_browser.rb

@@ -2,7 +2,7 @@ class Kookaburra
   class UIDriver
     # Wraps a Kookaburra `browser` object and changes all method calls
     # to that object so that they are scoped within the specified
-    # `component_locator`.
+    # {#component_locator}.
     class ScopedBrowser < BasicObject
 
       # @param [Object] browser The browser driver object used by
@@ -11,7 +11,7 @@ class Kookaburra
       #   locator used to identify the HTML element within which all
       #   calls to this object should be scoped. (A Proc is used rather
       #   than a string, because it is possible that the object creating
-      #   this `ScopedBrowser` will not know the correct string at the
+      #   this {ScopedBrowser} will not know the correct string at the
       #   time this object is created.)
       def initialize(browser, component_locator)
         @browser = browser

data/lib/kookaburra/ui_driver/ui_component.rb

@@ -60,13 +60,13 @@ class Kookaburra
     #     end
     #   end
     #
-    # Note that the "browser operation" methods such as `#fill_in` and
-    # `#click_button` are delegated to a {ScopedBrowser} and are
-    # automatically scoped to the component's DOM element.    
+    # Note that the "browser operation" methods such as {#fill_in} and
+    # {#click_button} are delegated to a {ScopedBrowser} and are
+    # automatically scoped to the component's DOM element.
     #
-    # @note Even though a `UIComponent` should respond to all of the
+    # @note Even though a {UIComponent} should respond to all of the
     #   methods on the browser (i.e. all of the Capybara DSL methods),
-    #   for some reason call to `#select` get routed to `Kernel#select`.
+    #   for some reason call to {#select} get routed to {Kernel#select}.
     #   You can get around this by calling it as `self.select`. See
     #   https://gist.github.com/3192103 for an example of this behavior.
     #
@@ -92,7 +92,7 @@ class Kookaburra
       #
       # @param [Kookaburra::Configuration] configuration
       # @param [Hash] options An options hash that can be used to
-      #   further configure a `UIComponent`'s behavior.
+      #   further configure a {UIComponent}'s behavior.
       def initialize(configuration, options = {})
         @configuration = configuration
         @options = options

data/spec/integration/test_a_rack_application_spec.rb

@@ -1,16 +1,12 @@
 require 'kookaburra/test_helpers'
 require 'kookaburra/api_driver'
+require 'kookaburra/rack_app_server'
 require 'capybara'
-require 'thwait'
-require 'find_a_port'
 
 # These are required for the Rack app used for testing
 require 'sinatra/base'
 require 'json'
 
-# The server port to which the application server will attach
-APP_PORT = FindAPort.available_port
-
 describe "testing a Rack application with Kookaburra" do
   describe "with an HTML interface" do
     describe "with a JSON API" do
@@ -319,37 +315,23 @@ describe "testing a Rack application with Kookaburra" do
         end
       end
 
+      app_server = Kookaburra::RackAppServer.new do
+        JsonApiApp.new
+      end
+
       before(:all) do
-        start_server = lambda {
-          Capybara.server_port = APP_PORT
-          Capybara::Server.new(JsonApiApp.new).boot
-          ThreadsWait.all_waits(Thread.list)
-        }
-        if defined?(JRUBY_VERSION)
-          # Can't `fork` in JRuby. This doesn't provide the state
-          # isolation that you get with forking (AFAIK, I'm no JVM
-          # expert, though), but it lets the tests run and pass.
-          Thread.new { start_server.call }
-        else
-          @rack_server_pid = fork do
-            start_server.call
-          end
-        end
-        sleep 1 # Give the server a chance to start up.
+        app_server.boot
       end
 
       after(:all) do
-        unless defined?(JRUBY_VERSION)
-          Process.kill(9, @rack_server_pid)
-          Process.wait
-        end
+        app_server.shutdown
       end
 
       it "runs the tests against the app" do
         Kookaburra.configure do |c|
           c.ui_driver_class = MyUIDriver
           c.given_driver_class = MyGivenDriver
-          c.app_host = 'http://127.0.0.1:%d' % APP_PORT
+          c.app_host = 'http://127.0.0.1:%d' % app_server.port
           c.browser = Capybara::Session.new(:selenium)
           c.server_error_detection do |browser|
             browser.has_css?('head title', :text => 'Internal Server Error')

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kookaburra
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -11,7 +11,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-12-14 00:00:00.000000000 Z
+date: 2013-03-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client
@@ -219,6 +219,7 @@ files:
 - lib/kookaburra/given_driver.rb
 - lib/kookaburra/mental_model.rb
 - lib/kookaburra/mental_model_matcher.rb
+- lib/kookaburra/rack_app_server.rb
 - lib/kookaburra/test_helpers.rb
 - lib/kookaburra/ui_driver.rb
 - lib/kookaburra/ui_driver/has_ui_components.rb
@@ -254,7 +255,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -3075821559668997121
+      hash: -356630097343812047
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements: