wx-nobbie 0.0.2

data/KNOWN ISSUES

@@ -0,0 +1,24 @@
+= KNOWN ISSUES
+
+On Windows there seems to be a strange delay between launching the application and it yielding control to the test
+runner. It seems that the smaller the application, the worse the problem is (i.e. the longer it takes).
+
+When typing into a TextCtrl, if the value being typed is the same as the current value it seems that on OSX the
+text changed event is not fired, but on Windows it is.  I'm not sure which is correct, but the result should be
+consistent - so this looks like a WxRuby issue.
+
+When typing into a readonly ComboBox, on Windows the value changes which is not consistent with the WxRuby
+documentation for 'set_value'. (might be fixed)
+
+OSX seems to have some problems with regard to the UI repainting and the timing/order of events. Further
+investigation is required but there are two problems highlighted in the tests. (1) when a value is set for a TextCtrl 
+during initialisation it is not painted to the screen untill you focus on it.  (2) when typing into a ComboBox the
+events value seems to be behind what is actually typed, e.g. if you type 'ab', two events are raised, but the values
+are '' and 'a'.
+
+Element highlighting seems to be a bit too quick in Windows.
+
+Currently there is no way to interact with the UI if an operation results in a blocking dialog.  For example,
+if 'File -> New' results in a FileDialog being displayed, test execution stops until the blocking dialog
+has been closed manually.  This is annoying and I welcome suggestions of how to overcome this problem, in a platform
+neutral way.

data/README

@@ -0,0 +1,153 @@
+= Wx-Nobbie -- An implementation of the Nobbie GUI Driving API for WxRuby2
+
+Nobbie is a simple generic api for driving GUI's (both web and rich-client interfaces).  This
+particular implementation is for driving WxRuby2 applications.  There are other implementations available for
+driving Java Swing and Web Applications - but they all use the same generic API.
+
+Nobbie attempts to make the driving of UI's as simple as possible.  Whereas most UI drivers tend to give you multiple
+ways to find components and subsequently multiple ways to interact with them, Nobbie's philosophy is:
+
+* finding components by name is the simplest, least brittle approach.
+* *most* UI interactions boil down to: *typing*, *choosing* and *clicking*
+
+(Note: if you can't sleep without the ability to find things using xpath or whatever, there are hooks to specify your
+own component finding strategies).
+
+With this in mind, Nobbie provides a simple method of {finding components}[link:classes/Nobbie/Wx/ElementPathBuilder.html]
+and a simple set of {Operations}[link:classes/Nobbie/Wx/Operations.html] to perform on them.
+
+A quick overview with examples:
+
+* Paths ...
+
+  In order to perform operations[link:classes/Nobbie/Wx/Operations.html] on a component, you need to first find it.
+  Only very simple 'named' paths are supported by default (but you can implement your own by providing an object that
+  responds to 'find_component'). When specifying a path, if you do not provide an object that responds to
+  'find_component', Nobbie will attempt to coerce the path into the default path type: Nobbie::Wx::ElementPathBuilder.
+
+  That may sound complicated but its really just sugar.  The following paths will all find the component
+  named 'text_ctrl':
+
+   'text_ctrl'
+   :in => 'text_ctrl'
+   in_('text_ctrl')
+   Nobbie::Wx::ElementPathBuilder.new('text_ctrl')
+   :text_ctrl
+
+
+* Typing[link:classes/Nobbie/Wx/Operations.html#type] ...
+
+   type(value, path)
+
+  e.g.
+
+   type('fred', in_('first_name'))
+   
+  ...or if you're one of those DSL/anglification people
+   
+   type 'fred', :in => 'first_name'
+   type 'fred', 'first_name'
+   type 'fred', :first_name
+   
+  This will find the component named 'first_name' and type 'fred' into it.
+  ...this works for anything you can type into, see:
+  {supported components}[link:classes/Nobbie/Wx/Operations.html#type].
+
+
+* Selecting[link:classes/Nobbie/Wx/Operations.html#selection] ...
+
+   selection(path).choose(value)
+
+  e.g.
+
+   selection(in_('title')).choose('Mr')
+   
+  ...or
+   
+   selection(:in => 'title').choose 'Mr'
+   selection('title').choose 'Mr'
+   selection(:title).choose 'Mr'
+
+  This will find the component named 'title' and select 'Mr'.
+  ...this works for anything where you can make a selection from a number of options
+  (which is quite a lot of things), see:
+  {supported components}[link:classes/Nobbie/Wx/SelectOperations.html#selection].
+
+  You can get the value of the current selection using:
+
+   selection(path).selected_value
+
+
+* Clicking[link:classes/Nobbie/Wx/Operations.html#click] ...
+
+   click(path) (for buttons you can also use the label instead of a path)
+
+  e.g.
+
+   click('save')
+   
+  ...or
+   
+   click 'save'
+   click :save
+   etc
+   
+  This will find the component named (or labelled) 'save' and click it.
+  ...this works for anything you can click, see:
+  {supported components}[link:classes/Nobbie/Wx/Operations.html#click].
+
+
+* Choosing[link:classes/Nobbie/Wx/Operations.html#choosable] ...
+
+   choosable(path).choose
+
+  e.g.
+
+   choosable(in_('female')).choose
+
+  ...or
+
+   choosable(:in => 'female').choose
+   choosable('female').choose
+   choosable(:female).choose
+
+  This will find the component named 'female' and choose it
+  ...this works for anything that has a chosen/non-chosen state, see:
+  {supported components}[link:classes/Nobbie/Wx/ChoosableOperations.html#choose].
+
+  You can determine if a component is currently chosen using:
+
+   choosable(path).chosen?
+
+Hopefully that makes some degree of sense, there are a few other operations available, that should be self
+explanatory from the documentation[link:classes/Nobbie/Wx/Operations.html].
+
+* Writing that first test ...
+
+  By default Nobbie hooks into test/unit.  However, due to a Wx limitation its not possible to launch a new
+  instance of your application for every test run (this would also be very slow anyway).  So, instead Nobbie
+  will launch your application, run all the tests in your suite and then close down the application. (Note: If
+  anyone has a better solution to this ... please let me know).
+
+  In order for this to happen, you must advise Nobbie which application you wish to test by setting the constant
+  APPLICATION_UNDER_TEST to an instance of your application, i.e.:
+
+   require 'rubygems'
+   require_gem 'nobbie-wx-preview'
+
+   require 'your_application'
+   require 'your_test_suite'
+
+   APPLICATION_UNDER_TEST = YourApp.new
+
+  Finally, to prevent your application being loaded when its file is 'required', edit your application startup
+  as follows:
+
+   YourApp.new.main_loop  if __FILE__ == $0
+
+* More examples ...
+
+  Nobbie has a suite of tests which are installed as part of the gem.  Take a look at the 'test' directory.
+
+
+

data/lib/nobbie/wx/acceptance_test.rb

@@ -0,0 +1,19 @@
+require 'test/unit'
+require 'nobbie/wx/operations'
+
+def require_all_in_directory(dir)
+  Dir.glob("#{dir}/**/*.rb") {|f| require "#{f}" }
+end
+
+class Test::Unit::TestCase
+  include Nobbie::Wx::Operations
+end
+
+Test::Unit.run = false
+
+#todo: how the hell does this work(/not work as expected) on OSX?
+at_exit do
+  unless $! || Test::Unit.run?
+    exit = Nobbie::Wx::ApplicationLauncher.new.with_application { Thread.pass }
+  end
+end

data/lib/nobbie/wx/command.rb

@@ -0,0 +1,63 @@
+module Nobbie
+  module Wx
+    module Command
+
+      class ComponentAwareCommand  #:nodoc:
+        def initialize(path)
+          @path = path
+        end
+
+        def component
+          @component ||= @path.find_component
+        end
+
+        def handle_unsupported_operation_for_component
+          Kernel.raise(UnsupportedOperationForComponentException,
+            "cannot: #{describe} because component #{component.class} does not support it")
+        end
+
+        def handle_value_not_found
+          Kernel.raise(ValueNotFoundException,
+            "cannot: #{describe} because value #{@value} not found")
+        end
+
+        def ensure_enabled(id = nil)
+          #is_enabled takes an id for menu's
+          enabled = id.nil? ? component.is_enabled : component.is_enabled(id)
+
+          Kernel.raise(ComponentDisabledException,
+            "cannot: #{describe} because component is disabled") unless enabled
+        end
+
+        def highlight(component = component)
+          Kernel.raise "highlight requires a block" unless block_given?
+
+          begin
+            unless [Menu, Panel].include?(component.class)
+              #puts "highlight on: #{component.class} - #{component.name}"
+              original_colour = component.background_colour
+              component.background_colour = Colour.from_hex('#FFFF00')
+
+              #todo: these were previously disabled
+#              component.refresh
+              component.update
+            end
+            result = yield component
+            unless component.is_a?(Menu)
+              component.update
+            end
+            return result
+          ensure
+            unless [Menu, Panel].include?(component.class)
+              #puts "highlight off: #{component.class} - #{component.name}"
+              component.background_colour = original_colour
+              component.refresh
+              #component.update
+            end
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/nobbie/wx/command/choose.rb

@@ -0,0 +1,38 @@
+module Nobbie
+  module Wx
+    module Command
+
+      class ChooseCommand < ComponentAwareCommand #:nodoc:
+        def execute
+          highlight {
+            ensure_enabled
+            
+            if component.is_a?(RadioButton) || component.is_a?(CheckBox)
+              handle_radio_button_or_check_box
+            else
+              handle_unsupported_operation_for_component
+            end
+          }
+        end
+      
+        def describe
+          "Choose #{@path}"
+        end
+
+        private
+
+        def handle_radio_button_or_check_box
+          event_type = (component.is_a?(RadioButton) ? EVT_COMMAND_RADIOBUTTON_SELECTED : EVT_COMMAND_CHECKBOX_CLICKED)
+
+          event = CommandEvent.new(event_type, component.get_id)
+          event.int = 1 #no idea why this works .. but it is needed
+          event.event_object = component
+
+          #todo: should this use process_event
+          component.command(event)
+        end
+      end
+
+    end    
+  end
+end  

data/lib/nobbie/wx/command/click_on.rb

@@ -0,0 +1,35 @@
+module Nobbie
+  module Wx
+    module Command  
+
+      class ClickOnCommand < ComponentAwareCommand #:nodoc:
+        def execute
+          highlight {
+            ensure_enabled
+
+            if component.is_a?(Button)
+              handle_button
+            else
+              handle_unsupported_operation_for_component
+            end
+          }
+        end
+        
+        def describe
+          "Click on #{@path}"
+        end
+
+        private
+
+        def handle_button
+          event = CommandEvent.new(EVT_COMMAND_BUTTON_CLICKED, component.get_id)
+          event.event_object = component
+
+          #todo: should this use process_event
+          component.command(event)
+        end
+      end
+
+    end
+  end    
+end

data/lib/nobbie/wx/command/get_component.rb

@@ -0,0 +1,17 @@
+module Nobbie
+  module Wx
+    module Command
+
+      class GetComponentCommand < ComponentAwareCommand #:nodoc:
+        def execute
+          component
+        end
+        
+        def describe
+          "Get component #{@path}"
+        end
+      end
+
+    end    
+  end
+end  

data/lib/nobbie/wx/command/get_options.rb

@@ -0,0 +1,27 @@
+module Nobbie
+  module Wx
+    module Command
+
+      class GetOptionsCommand < ComponentAwareCommand #:nodoc:
+        def execute
+          if component.is_a?(Notebook)
+            result = []
+            component.page_count.times{|i| result << component.page_text(i)}
+            result            
+          elsif component.is_a?(ComboBox) || component.is_a?(ListBox) || component.is_a?(Choice)
+            result = []
+            component.count.times{|i| result << component.string(i)}
+            result
+          else
+            handle_unsupported_operation_for_component
+          end
+        end
+
+        def describe
+          "Get options #{@path}"
+        end
+      end
+
+    end
+  end
+end

data/lib/nobbie/wx/command/get_selected_values.rb

@@ -0,0 +1,25 @@
+module Nobbie
+  module Wx
+    module Command
+
+      class GetSelectedValuesCommand < ComponentAwareCommand #:nodoc:
+        def execute
+          if component.is_a?(Notebook)
+            component.page(component.get_selection).name
+          elsif component.is_a?(ComboBox)
+            component.value
+          elsif component.is_a?(ListBox) || component.is_a?(Choice)
+            component.string_selection
+          else
+            handle_unsupported_operation_for_component
+          end
+        end
+        
+        def describe
+          "Get selected values #{@path}"
+        end
+      end
+
+    end    
+  end
+end  

data/lib/nobbie/wx/command/is_chosen.rb

@@ -0,0 +1,21 @@
+module Nobbie
+  module Wx
+    module Command  
+
+      class IsChosenCommand < ComponentAwareCommand #:nodoc:
+        def execute
+          if component.is_a?(RadioButton) || component.is_a?(CheckBox) 
+            return component.value
+          else
+            handle_unsupported_operation_for_component
+          end
+        end
+      
+        def describe
+          "Is chosen #{@path}"
+        end
+      end
+
+    end    
+  end
+end  

data/lib/nobbie/wx/command/is_enabled.rb

@@ -0,0 +1,18 @@
+module Nobbie
+  module Wx
+    module Command
+
+      class IsEnabledCommand < ComponentAwareCommand #:nodoc:
+        def execute
+          #todo: are there any components that do not respond to is_enabled? 
+          component.is_enabled
+        end
+      
+        def describe
+          "Is enabled #{@path}"
+        end
+      end
+
+    end    
+  end
+end