kookaburra 0.18.3 → 0.20.0

data/lib/kookaburra/null_browser.rb

@@ -1,6 +1,10 @@
 require 'basic_object'
 
 class Kookaburra
+  # If you don't specify a browser in your {Kookaburra#configuration} but you
+  # try to access one in your {Kookaburra::UIDriver}, you'll get this instead.
+  # It gives a slightly better error message than complaining about calling
+  # stuff on `nil`.
   class NullBrowser < BasicObject
     def method_missing(*args)
       raise NullBrowserError, 

data/lib/kookaburra/test_helpers.rb

@@ -9,14 +9,13 @@ class Kookaburra
   # @example RSpec setup
   #   # in 'spec/support/kookaburra_setup.rb'
   #   require 'kookaburra/test_helpers'
-  #   require 'my_app/kookaburra/api_driver'
   #   require 'my_app/kookaburra/given_driver'
   #   require 'my_app/kookaburra/ui_driver'
   #   
   #   Kookaburra.configuration = {
   #     :given_driver_class => MyApp::Kookaburra::GivenDriver,
-  #     :api_driver_class => MyApp::Kookaburra::APIDriver,
   #     :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')
@@ -47,14 +46,13 @@ class Kookaburra
   # @example Cucumber setup
   #   # in 'features/support/kookaburra_setup.rb'
   #   require 'kookaburra/test_helpers'
-  #   require 'my_app/kookaburra/api_driver'
   #   require 'my_app/kookaburra/given_driver'
   #   require 'my_app/kookaburra/ui_driver'
   #   
   #   Kookaburra.configuration = {
   #     :given_driver_class => MyApp::Kookaburra::GivenDriver,
-  #     :api_driver_class => MyApp::Kookaburra::APIDriver,
   #     :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')

data/lib/kookaburra/ui_driver.rb

@@ -4,9 +4,9 @@ require 'kookaburra/ui_driver/ui_component'
 class Kookaburra
   # You UIDriver subclass is where you define the DSL for testing your
   # application via its user interface. Methods defined in your DSL should
-  # represent business processes rather than user interface manipulations. A
+  # represent business actions rather than user interface manipulations. A
   # good test of this is whether the names of your methods would need to change
-  # significantly if the business process needed to be implemented in a vastly
+  # significantly if the application needed to be implemented in a vastly
   # different manner (a text-only terminal app vs. a web app, for instance).
   #
   # @abstract Subclass and implement your UI testing DSL
@@ -48,7 +48,8 @@ class Kookaburra
       #   this component.
       def ui_component(component_name, component_class)
         define_method(component_name) do
-          component_class.new(:browser => @browser, :server_error_detection => @server_error_detection)
+          component_class.new(:browser => @browser, :server_error_detection => @server_error_detection,
+                              :app_host => @app_host)
         end
       end
     end
@@ -56,21 +57,24 @@ class Kookaburra
     # It is unlikely that you would instantiate your UIDriver on your own; the
     # object is configured for you when you call {Kookaburra#ui}.
     #
-    # @option options [Object] browser Most likely a `Capybara::Session`
-    #   instance.
-    # @option options [Kookaburra::TestData] test_data
-    # @option options [Proc] server_error_detection A lambda that is passed the
-    #   `browser` object and should return `true` if the page indicates a server
+    # @option options [Capybara::Session] :browser Most likely a
+    #   `Capybara::Session` instance.
+    # @option options [Kookaburra::MentalModel] :mental_model
+    # @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 lambda that is passed the
+    #   `:browser` object and should return `true` if the page indicates a server
     #   error has occured
     def initialize(options = {})
       @browser = options[:browser]
-      @test_data = options[:test_data]
+      @app_host = options[:app_host]
+      @mental_model = options[:mental_model]
       @server_error_detection = options[:server_error_detection]
     end
 
     protected
 
-    # @attribute [r] test_data
-    dependency_accessor :test_data
+    # @attribute [r] mental_model
+    dependency_accessor :mental_model
   end
 end

data/lib/kookaburra/ui_driver/ui_component.rb

@@ -70,11 +70,17 @@ class Kookaburra
       #
       # @see Kookaburra::UIDriver.ui_component
       #
-      # @option options [Object] :browser probably ought to be a
-      #   `Capybara::Session` instance
-      # @option options [Proc] :server_error_detection
+      # @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]
       end
 
@@ -94,7 +100,8 @@ class Kookaburra
       end
 
       # @private
-      # Behaves as you might expect given #method_missing
+      # (Not really private, but YARD seemingly lacks RDoc's :nodoc tag, and the
+      # semantics here don't differ from Object#respond_to?)
       def respond_to?(name)
         super || browser.respond_to?(name)
       end
@@ -116,7 +123,7 @@ class Kookaburra
       #   to make it so.
       def show(*args)
         return if visible?
-        browser.visit component_path(*args)
+        browser.visit component_url(*args)
         assert visible?, "The #{self.class.name} component is not visible!"
       end
 
@@ -157,12 +164,22 @@ class Kookaburra
 
       # @abstract
       # @return [String] the URL path that should be loaded in order to reach this component
+      # @raise [Kookaburra::ConfigurationError] raised if you haven't provided
+      #   an implementation
       def component_path
         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
+      #   an implementation
       def component_locator
         raise ConfigurationError, "You must define #{self.class.name}#component_locator."
       end

data/spec/integration/test_a_rack_application_spec.rb

@@ -1,135 +1,22 @@
 require 'kookaburra'
+require 'kookaburra/json_api_driver'
 require 'capybara'
+
+# These are required for the Rack app used for testing
 require 'sinatra/base'
+require 'active_support/json'
 require 'active_support/hash_with_indifferent_access'
 
 describe "testing a Rack application with Kookaburra" do
   describe "with an HTML interface" do
     describe "with a JSON API" do
-      require 'kookaburra/json_api_driver'
-      class MyAPIDriver < Kookaburra::JsonApiDriver
-        def create_user(user_data)
-          post '/users', user_data
-        end
-
-        def create_widget(widget_data)
-          post '/widgets', widget_data
-        end
-      end
-
-      class MyGivenDriver < Kookaburra::GivenDriver
-        def a_user(name)
-          user = {'email' => 'bob@example.com', 'password' => '12345'}
-          result = api.create_user(user)
-          test_data.users[name] = result
-        end
-
-        def a_widget(name, attributes = {})
-          widget = {'name' => 'Foo'}.merge(attributes)
-          result = api.create_widget(widget)
-          test_data.widgets[name] = result
-        end
-      end
-
-      class SignInScreen < Kookaburra::UIDriver::UIComponent
-        def component_path
-          '/session/new'
-        end
-
-        def component_locator
-          '#sign_in_screen'
-        end
-
-        def sign_in(user_data)
-          fill_in 'Email:', :with => user_data['email']
-          fill_in 'Password:', :with => user_data['password']
-          click_button 'Sign In'
-        end
-      end
-
-      class WidgetList < Kookaburra::UIDriver::UIComponent
-        def component_path
-          '/widgets'
-        end
-
-        def component_locator
-          '#widget_list'
-        end
-
-        def widgets
-          all('.widget_summary').map do |el|
-            extract_widget_data(el)
-          end
-        end
-
-        def last_widget_created
-          element = find('.last_widget.created')
-          extract_widget_data(element)
-        end
-
-        def choose_to_create_new_widget
-          click_on 'New Widget'
-        end
-
-        def choose_to_delete_widget(widget_data)
-          find("#delete_#{widget_data['id']}").click_button('Delete')
-        end
-
-        private
-
-        def extract_widget_data(element)
-          {
-            'id' => element.find('.id').text,
-            'name' => element.find('.name').text
-          }
-        end
-      end
-
-      class WidgetForm < Kookaburra::UIDriver::UIComponent
-        def component_locator
-          '#widget_form'
-        end
-
-        def submit(widget_data)
-          fill_in 'Name:', :with => widget_data['name']
-          click_on 'Save'
-        end
-      end
-
-      class MyUIDriver < Kookaburra::UIDriver
-        ui_component :sign_in_screen, SignInScreen
-        ui_component :widget_list, WidgetList
-        ui_component :widget_form, WidgetForm
-
-        def sign_in(name)
-          sign_in_screen.show
-          sign_in_screen.sign_in(test_data.users[name])
-        end
-
-        def create_new_widget(name, attributes = {})
-          widget_list.show
-          widget_list.choose_to_create_new_widget
-          widget_form.submit('name' => 'My Widget')
-          test_data.widgets[name] = widget_list.last_widget_created
-        end
-
-        def delete_widget(name)
-          widget_list.show
-          widget_list.choose_to_delete_widget(test_data.widgets[name])
-        end
-      end
-
       # This is the fixture Rack application against which the integration
       # test will run. It uses class variables to persist data, because
       # Sinatra will instantiate a new instance of TestRackApp for each
       # request.
-      class TestRackApp < Sinatra::Base
+      class JsonApiApp < Sinatra::Base
         enable :sessions
-
-        # we want error handling to behave as it would for a production
-        # deployment rather than development
-        set :raise_errors, false
-        set :show_exceptions, false
+        disable :show_exceptions
 
         def parse_json_req_body
           request.body.rewind
@@ -241,20 +128,20 @@ describe "testing a Rack application with Kookaburra" do
             </head>
             <body>
               <div id="widget_list">
-                EOF
-                if last_widget_created
-                  content << <<-EOF
+          EOF
+          if last_widget_created
+            content << <<-EOF
                   <div class="last_widget created">
                     <span class="id">#{last_widget_created[:id]}</span>
                     <span class="name">#{last_widget_created[:name]}</span>
                   </div>
-                  EOF
-                end
-                content << <<-EOF
+            EOF
+          end
+          content << <<-EOF
                 <ul>
-                EOF
-                @@widgets.each do |w|
-                  content << <<-EOF
+          EOF
+          @@widgets.each do |w|
+            content << <<-EOF
                   <li class="widget_summary">
                     <span class="id">#{w[:id]}</span>
                     <span class="name">#{w[:name]}</span>
@@ -262,9 +149,9 @@ describe "testing a Rack application with Kookaburra" do
                       <button type="submit" value="Delete" />
                     </form>
                   </li>
-                  EOF
-                end
-                content << <<-EOF
+            EOF
+          end
+          content << <<-EOF
                 </ul>
                 <a href="/widgets/new">New Widget</a>
               </div>
@@ -273,22 +160,169 @@ describe "testing a Rack application with Kookaburra" do
           EOF
           body content
         end
+
+        error do
+          e = request.env['sinatra.error']
+          body << <<-EOF
+          <html>
+            <head>
+              <title>Internal Server Error</title>
+            </head>
+            <body>
+              <pre>
+          #{e.to_s}\n#{e.backtrace.join("\n")}
+              </pre>
+            </body>
+          </html>
+          EOF
+        end
       end
 
+      class MyAPIDriver < Kookaburra::JsonApiDriver
+        def create_user(user_data)
+          post '/users', user_data
+        end
 
-      it "runs the tests against the app" do
-        my_app = TestRackApp.new
+        def create_widget(widget_data)
+          post '/widgets', widget_data
+        end
+      end
+
+      class MyGivenDriver < Kookaburra::GivenDriver
+        def api
+          MyAPIDriver.new(:app_host => initialization_options[:app_host])
+        end
+
+        def a_user(name)
+          user = {'email' => 'bob@example.com', 'password' => '12345'}
+          result = api.create_user(user)
+          mental_model.users[name] = result
+        end
+
+        def a_widget(name, attributes = {})
+          widget = {'name' => 'Foo'}.merge(attributes)
+          result = api.create_widget(widget)
+          mental_model.widgets[name] = result
+        end
+      end
+
+      class SignInScreen < Kookaburra::UIDriver::UIComponent
+        def component_path
+          '/session/new'
+        end
+
+        def component_locator
+          '#sign_in_screen'
+        end
+
+        def sign_in(user_data)
+          fill_in 'Email:', :with => user_data['email']
+          fill_in 'Password:', :with => user_data['password']
+          click_button 'Sign In'
+        end
+      end
+
+      class WidgetList < Kookaburra::UIDriver::UIComponent
+        def component_path
+          '/widgets'
+        end
+
+        def component_locator
+          '#widget_list'
+        end
 
+        def widgets
+          all('.widget_summary').map do |el|
+            extract_widget_data(el)
+          end
+        end
+
+        def last_widget_created
+          element = find('.last_widget.created')
+          extract_widget_data(element)
+        end
+
+        def choose_to_create_new_widget
+          click_on 'New Widget'
+        end
+
+        def choose_to_delete_widget(widget_data)
+          find("#delete_#{widget_data['id']}").click_button('Delete')
+        end
+
+        private
+
+        def extract_widget_data(element)
+          {
+            'id' => element.find('.id').text,
+            'name' => element.find('.name').text
+          }
+        end
+      end
+
+      class WidgetForm < Kookaburra::UIDriver::UIComponent
+        def component_locator
+          '#widget_form'
+        end
+
+        def submit(widget_data)
+          fill_in 'Name:', :with => widget_data['name']
+          click_on 'Save'
+        end
+      end
+
+      class MyUIDriver < Kookaburra::UIDriver
+        ui_component :sign_in_screen, SignInScreen
+        ui_component :widget_list, WidgetList
+        ui_component :widget_form, WidgetForm
+
+        def sign_in(name)
+          sign_in_screen.show
+          sign_in_screen.sign_in(mental_model.users[name])
+        end
+
+        def create_new_widget(name, attributes = {})
+          widget_list.show
+          widget_list.choose_to_create_new_widget
+          widget_form.submit('name' => 'My Widget')
+          mental_model.widgets[name] = widget_list.last_widget_created
+        end
+
+        def delete_widget(name)
+          widget_list.show
+          widget_list.choose_to_delete_widget(mental_model.widgets[name])
+        end
+      end
+
+      before(:all) do
+        @rack_server_port = 3339
+        @rack_server_pid = fork do
+          Rack::Server.start(
+            :app => JsonApiApp.new,
+            :server => :webrick,
+            :Host => '127.0.0.1',
+            :Port => @rack_server_port,
+            :environment => 'production'
+          )
+        end
+        sleep 1 # Give the server a chance to start up.
+      end
+
+      after(:all) do
+        Process.kill(9, @rack_server_pid)
+        Process.wait
+      end
+
+      it "runs the tests against the app" do
         server_error_detection = lambda { |browser|
-          browser.has_css?('h1', :text => 'Internal Server Error')
+          browser.has_css?('head title', :text => 'Internal Server Error')
         }
 
         k = Kookaburra.new({
           :ui_driver_class        => MyUIDriver,
           :given_driver_class     => MyGivenDriver,
-          :api_driver_class       => MyAPIDriver,
-          :browser                => Capybara::Session.new(:rack_test, my_app),
-          :rack_app               => my_app,
+          :app_host               => 'http://127.0.0.1:%d' % @rack_server_port,
+          :browser                => Capybara::Session.new(:selenium),
           :server_error_detection => server_error_detection
         })