kookaburra 0.8.0 → 0.9.0

data/.yardopts

@@ -1 +1,2 @@
 --markup=markdown
+--no-private

data/README.markdown

@@ -129,17 +129,23 @@ 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
+**Test 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.
+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. Kookaburra provides its own `#assert` method
+for this purpose. You may use it directly or build your own custom assertions
+using it as a base. However, this method should be used only for the purpose
+of short-circuiting your Domain Driver with an informative error message, not
+to test the results of your operations as you would at the test implementation
+layer.
 
 Given the Cucumber scenario above, here is how the test implementation layer
 might look:

data/VERSION

@@ -1 +1 @@
-0.8.0
+0.9.0

data/kookaburra.gemspec

@@ -5,7 +5,7 @@
 
 Gem::Specification.new do |s|
   s.name = "kookaburra"
-  s.version = "0.8.0"
+  s.version = "0.9.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Renewable Funding, LLC"]
@@ -29,6 +29,7 @@ Gem::Specification.new do |s|
     "kookaburra.gemspec",
     "lib/kookaburra.rb",
     "lib/kookaburra/api_driver.rb",
+    "lib/kookaburra/assertion.rb",
     "lib/kookaburra/given_driver.rb",
     "lib/kookaburra/test_data.rb",
     "lib/kookaburra/ui_driver.rb",
@@ -38,6 +39,7 @@ Gem::Specification.new do |s|
     "lib/kookaburra/ui_driver/mixins/has_ui_component.rb",
     "lib/kookaburra/ui_driver/ui_component.rb",
     "test/helper.rb",
+    "test/kookaburra/assertion_test.rb",
     "test/kookaburra/test_data_test.rb",
     "test/kookaburra/ui_driver_test.rb",
     "test/kookaburra_test.rb"

data/lib/kookaburra/api_driver.rb

@@ -2,6 +2,8 @@ require 'rack/test'
 
 module Kookaburra
   class APIDriver
+    include Kookaburra::Assertion
+
     def initialize(opts)
       @app = opts.fetch(:app)
     end

data/lib/kookaburra/assertion.rb

@@ -0,0 +1,32 @@
+module Kookaburra
+  module Assertion
+    # Custom exception class for assertion failures
+    class Failure < Exception; end
+
+    # Provides a mechanism for making assertions within your domain and window drivers
+    # without creating a dependency on any specific testing framework.
+    #
+    # @param [Truthy] predicate The thing you are asserting should be `true` (or at least truthy).
+    # @param [String] message Optional message to return if `predicate` is not `true` (or at least truthy).
+    # @return [nil] if `predicate` does not evaluate to `false` or `nil`
+    # @raise [Kookaburra::Assertion::Failure] if `predicate` evaluates to `false` or `nil`
+    def assert(predicate, message = nil)
+      return if predicate
+      raise Failure, message
+    rescue Failure => e
+      raise Backtrace.clean(e)
+    end
+
+    # @private
+    module Backtrace
+      module_function
+      
+      def clean(exception)
+        new_backtrace = exception.backtrace.dup
+        new_backtrace.shift while new_backtrace.first.include?('lib/kookaburra/assertion.rb')
+        exception.set_backtrace(new_backtrace)
+        exception
+      end
+    end
+  end
+end

data/lib/kookaburra/given_driver.rb

@@ -1,5 +1,7 @@
 module Kookaburra
   class GivenDriver
+    include Kookaburra::Assertion
+
     attr_reader :api
     attr_reader :test_data
 

data/lib/kookaburra/ui_driver/ui_component.rb

@@ -5,6 +5,7 @@ require 'kookaburra/ui_driver/mixins/has_subcomponents'
 module Kookaburra
   class UIDriver
     class UIComponent
+      include Kookaburra::Assertion
       include HasBrowser
       include HasStrategies
       extend HasSubcomponents

data/lib/kookaburra/ui_driver.rb

@@ -3,6 +3,7 @@ require 'kookaburra/ui_driver/mixins/has_ui_component'
 
 module Kookaburra
   class UIDriver
+    include Kookaburra::Assertion
     include HasBrowser
     include HasUIComponent
 

data/lib/kookaburra.rb

@@ -1,3 +1,4 @@
+require 'kookaburra/assertion'
 require 'kookaburra/test_data'
 require 'kookaburra/api_driver'
 require 'kookaburra/given_driver'

data/test/kookaburra/assertion_test.rb

@@ -0,0 +1,68 @@
+require 'helper'
+
+describe Kookaburra::Assertion do
+  let(:api)          { Class.new(Kookaburra::APIDriver).new({:app => nil}) }
+  let(:given)        { Class.new(Kookaburra::GivenDriver).new({:api_driver => api, :test_data => nil}) }
+  let(:ui_component) { Class.new(Kookaburra::UIDriver::UIComponent).new(:test_data => nil) }
+  let(:ui) { ui_class.new }
+  let(:ui_class) do
+    Class.new(Kookaburra::UIDriver) do
+      def positive_assertion
+        assert true
+      end
+
+      def negative_assertion
+        assert false
+      end
+
+      def negative_assertion_with_message
+        assert false, "Hello, world!"
+      end
+    end
+  end
+
+  it 'should be included in Kookaburra::APIDriver' do
+    assert_kind_of Kookaburra::Assertion, api
+  end
+  it 'should be included in Kookaburra::GivenDriver' do
+    assert_kind_of Kookaburra::Assertion, given
+  end
+  it 'should be included in Kookaburra::UIDriver' do
+    assert_kind_of Kookaburra::Assertion, ui
+  end
+  it 'should be included in Kookaburra::UIDriver::UIComponent' do
+    assert_kind_of Kookaburra::Assertion, ui_component
+  end
+
+  it 'should be able to make a positive assertion' do
+    ui.positive_assertion
+  end
+  
+  it 'should be able to make a negative assertion' do
+    assert_raises(Kookaburra::Assertion::Failure) do
+      ui.negative_assertion
+    end
+  end
+  
+  it 'should be able to make a negative assertion with a custom failure message' do
+    begin
+      ui.negative_assertion_with_message
+    rescue Kookaburra::Assertion::Failure => e
+      assert_equal 'Hello, world!', e.message
+    end
+  end
+
+  describe Kookaburra::Assertion::Failure do
+    let(:base_path) { File.expand_path(File.join(File.dirname(__FILE__), *%w[.. .. lib kookaburra])) }
+
+    it 'removes lines including assertion.rb from the top of its backtrace' do
+      begin
+        ui.negative_assertion
+      rescue Kookaburra::Assertion::Failure => e
+        assert e.backtrace.none? { |line| line.include?('lib/kookaburra/assertion.rb') },
+          '"assertion.rb" should be cleaned from backtrace'
+      end
+    end
+  end
+  
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: kookaburra
 version: !ruby/object:Gem::Version 
-  hash: 63
+  hash: 59
   prerelease: 
   segments: 
   - 0
-  - 8
+  - 9
   - 0
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors: 
 - Renewable Funding, LLC
@@ -181,6 +181,7 @@ files:
 - kookaburra.gemspec
 - lib/kookaburra.rb
 - lib/kookaburra/api_driver.rb
+- lib/kookaburra/assertion.rb
 - lib/kookaburra/given_driver.rb
 - lib/kookaburra/test_data.rb
 - lib/kookaburra/ui_driver.rb
@@ -190,6 +191,7 @@ files:
 - lib/kookaburra/ui_driver/mixins/has_ui_component.rb
 - lib/kookaburra/ui_driver/ui_component.rb
 - test/helper.rb
+- test/kookaburra/assertion_test.rb
 - test/kookaburra/test_data_test.rb
 - test/kookaburra/ui_driver_test.rb
 - test/kookaburra_test.rb