testability-driver 1.1.1 → 1.2.1

data/lib/tdriver/base/sut/generic/behaviours/sut.rb

@@ -138,7 +138,7 @@ module MobyBehaviour
     def freeze
 
 =begin
-      if $parameters[ @id ][ :use_find_object, 'false' ] == 'true' && self.respond_to?( 'find_object' )
+      if sut_parameters[ :use_find_object, 'false' ] == 'true' && self.respond_to?( 'find_object' )
 
         warn("warning: SUT##{ __method__ } is not supported when use_find_objects optimization is enabled")
 
@@ -166,7 +166,7 @@ module MobyBehaviour
     def unfreeze
 
 =begin
-      if $parameters[ @id ][ :use_find_object, 'false' ] == 'true' && self.respond_to?( 'find_object' )
+      if sut_parameters[ :use_find_object, 'false' ] == 'true' && self.respond_to?( 'find_object' )
 
         warn("warning: SUT##{ __method__ } is not supported when use_find_objects optimization is enabled")
 
@@ -280,7 +280,7 @@ module MobyBehaviour
       ) if identification_directives.has_key?( :__logging )
 
       # disable logging if requested, remove pair from creation_hash
-      $logger.push_enabled( identification_directives[ :__logging ] || TDriver.logger.enabled )
+      $logger.push_enabled( identification_directives[ :__logging ] || $logger.enabled )
 
       begin
 
@@ -299,19 +299,19 @@ module MobyBehaviour
 
       rescue MobyBase::MultipleTestObjectsIdentifiedError => exception
 
-        TDriver.logger.behaviour "FAIL;Multiple child objects matched criteria.;#{ id };sut;{};child;#{ attributes.inspect }"
+        $logger.behaviour "FAIL;Multiple child objects matched criteria.;#{ id };sut;{};child;#{ attributes.inspect }"
 
         Kernel::raise exception
 
       rescue MobyBase::TestObjectNotFoundError => exception
 
-        TDriver.logger.behaviour "FAIL;The child object could not be found.;#{ id };sut;{};child;#{ attributes.inspect }"
+        $logger.behaviour "FAIL;The child object could not be found.;#{ id };sut;{};child;#{ attributes.inspect }"
 
         Kernel::raise exception
 
       rescue Exception => exception
 
-        TDriver.logger.behaviour "FAIL;Failed when trying to find child object.;#{ id };sut;{};child;#{ attributes.inspect }"
+        $logger.behaviour "FAIL;Failed when trying to find child object.;#{ id };sut;{};child;#{ attributes.inspect }"
 
         Kernel::raise exception
 
@@ -330,6 +330,7 @@ module MobyBehaviour
 
     # == description
     # Method for executing sut specific setup method
+    # https://projects.forum.nokia.com/Testabilitydriver/wiki/FeatureSutSetupTeardown
     # == returns
     # Result
     #  description: -
@@ -344,15 +345,15 @@ module MobyBehaviour
         if self.parameter[ :sut_setup, nil ]
           require MobyUtil::FileHelper.expand_path(self.parameter[ :sut_setup ])
 
-          TDriver.logger.behaviour "PASS;sut.setup method found"
+          $logger.behaviour "PASS;sut.setup method found"
 
           self.setup
 
-          TDriver.logger.behaviour "PASS;sut.setup executed"
+          $logger.behaviour "PASS;sut.setup executed"
         end
 
         if self.parameter[ :setup, nil ]
-          TDriver.logger.behaviour "PASS;sut.setup parameters found"
+          $logger.behaviour "PASS;sut.setup parameters found"
           methods=self.parameter[ :setup ]
           methods.each do |method|
             m=method[0].to_s
@@ -363,11 +364,11 @@ module MobyBehaviour
               eval("self.#{m}(:#{args.to_sym})")
             end
           end
-          TDriver.logger.behaviour "PASS;sut.setup parameter methods executed"
+          $logger.behaviour "PASS;sut.setup parameter methods executed"
         end
 
       else
-        TDriver.logger.behaviour "FAIL;No methods or parameters found for sut.setup"
+        $logger.behaviour "FAIL;No methods or parameters found for sut.setup"
 
         Kernel::raise MobyBase::BehaviourError.new("Setup", "Failed to load sut.setup method check the :sut_setup parameter")
       end
@@ -378,6 +379,7 @@ module MobyBehaviour
 
     # == description
     # Method for executing sut specific teardown method
+    # https://projects.forum.nokia.com/Testabilitydriver/wiki/FeatureSutSetupTeardown
     # == returns
     # Result
     #  description: -
@@ -392,15 +394,15 @@ module MobyBehaviour
         if self.parameter[ :sut_teardown, nil ]
           require MobyUtil::FileHelper.expand_path(self.parameter[ :sut_teardown ])
 
-          TDriver.logger.behaviour "PASS;sut.teardown method found"
+          $logger.behaviour "PASS;sut.teardown method found"
 
           self.teardown
 
-          TDriver.logger.behaviour "PASS;sut.teardown executed"
+          $logger.behaviour "PASS;sut.teardown executed"
         end
 
         if self.parameter[ :teardown, nil ]
-          TDriver.logger.behaviour "PASS;sut.teardown parameters found"
+          $logger.behaviour "PASS;sut.teardown parameters found"
           methods=self.parameter[ :teardown ]
           methods.each do |method|
             m=method[0].to_s
@@ -411,11 +413,11 @@ module MobyBehaviour
               eval("self.#{m}(:#{args.to_sym})")
             end
           end
-          TDriver.logger.behaviour "PASS;sut.teardown parameter methods executed"
+          $logger.behaviour "PASS;sut.teardown parameter methods executed"
         end
 
       else
-        TDriver.logger.behaviour "FAIL;No method or parameters found for sut.teardown"
+        $logger.behaviour "FAIL;No method or parameters found for sut.teardown"
 
         Kernel::raise MobyBase::BehaviourError.new("Teardown", "Failed to load sut.teardown method check the :sut_teardown parameter")
       end
@@ -423,23 +425,65 @@ module MobyBehaviour
     end
 
     # == description
-    # Returns a StateObject containing the current state of this test object as XML.
-    # The state object is static and thus is not refreshed or synchronized etc.
+    # Creates a state object of current test object or given XML as argument. The state object is static and thus is not refreshed or synchronized.
+    #
+    # == arguments
+    # source_data
+    #  String
+    #   description: Object state as XML string
+    #   example: -
+    #  MobyBase::XML::Element
+    #   description: Object state as XML element
+    #   example: -
+    #
+    # parent_object
+    #  MobyBase::TestObject
+    #   description: Parent object
+    #   example: -
+    #  MobyBase::SUT
+    #   description: Parent object
+    #   example: -
+    #  NilClass
+    #   description: No parent object defined
+    #   example: nil
+    #
     # == returns
-    # StateObject
-    #  description: State of this test object
+    # MobyBase::StateObject
+    #  description: State of this SUT, test object or given XML
     #  example: -
+    #
     # == exceptions
+    # ArgumentError
+    #  description: Wrong argmument type given
     # RuntimeError
     #  description: If the XML source for the object is not in initialized
-    def state
+    def state_object( source_data = nil, parent_object = nil )
+
+      if source_data.nil?
 
-      # refresh if xml data is empty
-      self.refresh if @xml_data.empty?
+        # refresh if xml data is empty
+        self.refresh if @xml_data.empty?
 
-      Kernel::raise RuntimeError, "Can not create state object of SUT with id #{ @id.inspect }, no XML content or SUT not initialized properly." if @xml_data.empty?
+        Kernel::raise RuntimeError, "Can not create state object of SUT with id #{ @id.inspect }, no XML content or SUT not initialized properly." if @xml_data.empty?
 
-      MobyBase::StateObject.new( TDriver::TestObjectAdapter.state_object_xml( @xml_data, @id ), self )
+        source_data = @test_object_adapter.state_object_xml( @xml_data, @id )
+
+        parent_object = self
+
+      end
+
+      # verify that type of xml_source argument is correct
+      source_data.check_type [ String, MobyUtil::XML::Element ], 'wrong argument type $1 for state object source data (expected $2)'
+
+      parent_object.check_type [ MobyBase::SUT, MobyBase::TestObject, MobyBase::StateObject, NilClass ], 'wrong argument type $1 for parent object (expected $2)'
+
+      MobyBase::StateObject.new( 
+
+        :source_data => source_data, 
+        :parent => parent_object,
+        :test_object_adapter => @test_object_adapter
+
+      )
 
     end
 
@@ -465,7 +509,7 @@ module MobyBehaviour
 
       begin
 
-        attributes.check_type( Hash, "Wrong argument type $1 for attributes (expected $2)" )
+        attributes.check_type( Hash, 'Wrong argument type $1 for attributes (expected $2)' )
 
         attributes[ :type ] = 'application'
 
@@ -483,7 +527,7 @@ module MobyBehaviour
 
       rescue
 
-        TDriver.logger.behaviour(
+        $logger.behaviour(
           "FAIL;Failed to find application.;#{ id.to_s };sut;{};application;#{ attributes.kind_of?( Hash ) ? attributes.inspect : attributes.class.to_s }"
         )
 
@@ -492,7 +536,7 @@ module MobyBehaviour
 
       ensure
 
-        TDriver.logger.behaviour "PASS;Application found.;#{ id.to_s };sut;{};application;#{ attributes.inspect }" if $!.nil?
+        $logger.behaviour "PASS;Application found.;#{ id.to_s };sut;{};application;#{ attributes.inspect }" if $!.nil?
 
       end
 
@@ -565,13 +609,13 @@ module MobyBehaviour
 
       rescue
 
-        TDriver.logger.behaviour "FAIL;Failed to capture screen.;#{ id.to_s };sut;{};capture_screen;#{ arguments.kind_of?( Hash ) ? arguments.inspect : arguments.class.to_s }"
+        $logger.behaviour "FAIL;Failed to capture screen.;#{ id.to_s };sut;{};capture_screen;#{ arguments.kind_of?( Hash ) ? arguments.inspect : arguments.class.to_s }"
 
         Kernel::raise $!
 
       end
 
-      TDriver.logger.behaviour "PASS;Screen was captured successfully.;#{ id.to_s };sut;{};capture_screen;#{ arguments.inspect }"
+      $logger.behaviour "PASS;Screen was captured successfully.;#{ id.to_s };sut;{};capture_screen;#{ arguments.inspect }"
 
       nil
 
@@ -584,8 +628,11 @@ module MobyBehaviour
     # == arguments
     # target
     #  Hash
-    #   description: used to indetify the application to be executed. All symbols defined in the hash must match with the launched application. See application [link="#run_hash_arguments"]run argument hash keys[/link] table.
-    #   example: { :name => 'calculator' }
+    #   description: Used to indetify the application to be executed. All symbols defined in the hash must match with the launched application. See application [link="#run_hash_arguments"]run argument hash keys[/link] table.
+    #   example: { :name => "calculator" }
+    #  String
+    #   description: If target application is given in String format it is interpreted as application name. String "calculator"' is equivalent to {:name => "calculator"} hash.
+    #   example: "calculator"
     #
     # == tables
     # run_hash_arguments
@@ -594,13 +641,15 @@ module MobyBehaviour
     #  |Key|Type|Description|Example|
     #  |:uid|String or Integer|Unique ID of the application|{ :uid => 268458181 }|
     #  |:name|String|Executable name of the application|{ :name => 'calculator' }|
+    #  |:restart_if_running|Boolean|Restart application if already running||{ :restart_if_running => true }|
     #  |:arguments|String|Comma separated list of arguments passed to the application when it is started|{ :arguments => '--nogui,-v' }|
-    #	|:sleep_time|Integer|Number of seconds to sleep immediately after launching the process|{ :sleep_time => 10 }|
-    #	|:start_command|String|When set, the run method will execute this command and expect the application provided by the :name key to be launched. Note that applications launched this way can't be sent a Kill message and its start up events and signals may not be recorded.|{ :start_command => 'start_app_batch',:name => 'calculator' }|
-    #	|:try_attach|Boolean|If set to true, run will attempt to attach to an existing application with the given name or id. If not found the application will be launched as normal. If more than 1 are found then an exception is thrown|{:try_attach => true, :name => 'calculator'}|
-    #	|:environment|String|Environment variables you want to pass to started process, passed as key value pairs separated by '=' and pairs separated by spaces |{ :environment => 'LC_ALL=en SPECIAL_VAR=value' }|
-    #	|:events_to_listen|String|List of events you want to start listening to when application starts, passed as comma separated string.  You can retrieve a list of events fired by a test object by first enabling event listening and then using the get_events method. See methods enable_events, get_events and disable_events |{ :events_to_listen => 'Paint,Show' }|
-    #	|:signals_to_listen|String|List of signals you want to start listening to when application starts, passed as comma separated string. Check your application class what signals it can emit, or you can use the 'signal' fixture's 'list_signal' method to retrieve an xml string listing all the signals the object can emit.  E.g. xml = @object.fixture('signal', 'list_signals')|{ :signals_to_listen => 'applicationReady()' }|
+    #  |:check_pid|Boolean|Overrides default value of SUT parameter :application_check_pid; When set to true, process id is used to test object identification|false|
+    #   |:sleep_time|Integer|Number of seconds to sleep immediately after launching the process|{ :sleep_time => 10 }|
+    #   |:start_command|String|When set, the run method will execute this command and expect the application provided by the :name key to be launched. Note that applications launched this way can't be sent a Kill message and its start up events and signals may not be recorded.|{ :start_command => 'start_app_batch',:name => 'calculator' }|
+    #   |:try_attach|Boolean|If set to true, run will attempt to attach to an existing application with the given name or id. If not found the application will be launched as normal. If more than 1 are found then an exception is thrown|{:try_attach => true, :name => 'calculator'}|
+    #   |:environment|String|Environment variables you want to pass to started process, passed as key value pairs separated by '=' and pairs separated by spaces |{ :environment => 'LC_ALL=en SPECIAL_VAR=value' }|
+    #   |:events_to_listen|String|List of events you want to start listening to when application starts, passed as comma separated string.  You can retrieve a list of events fired by a test object by first enabling event listening and then using the get_events method. See methods enable_events, get_events and disable_events |{ :events_to_listen => 'Paint,Show' }|
+    #   |:signals_to_listen|String|List of signals you want to start listening to when application starts, passed as comma separated string. Check your application class what signals it can emit, or you can use the 'signal' fixture's 'list_signal' method to retrieve an xml string listing all the signals the object can emit.  E.g. xml = @object.fixture('signal', 'list_signals')|{ :signals_to_listen => 'applicationReady()' }|
     #
     # == returns
     # TestObject
@@ -622,27 +671,51 @@ module MobyBehaviour
       begin
 
         # set the refresh interval to zero while the application is launched
-        #orig_interval = $parameters[ @id ][ :refresh_interval ]
-        #$parameters[ @id ][ :refresh_interval ] = '0'
+        #orig_interval = sut_parameters[ :refresh_interval ]
+        #sut_parameters[ :refresh_interval ] = '0'
 
         # raise exception if argument type other than hash
-        target.check_type( Hash, "Wrong argument type $1 for run method (expected $2)" )
+        target.check_type( [ String, Hash ], "Wrong argument type $1 for run method (expected $2)" )
+
+        # if target application is given as string, interpret it as application name
+        target = { :name => target.to_s } if target.kind_of?( String )
 
         # default value for missing keys
         target.default = nil
 
         # raise exception if :uid or :name not found from hash
-        target.require_key( [ :uid, :name ], "Required key :uid or :name not found from argument hash" )
+        target.require_one( [ :uid, :name ], "Required key :uid or :name not found from argument hash" )
 
         # due to bug #1488
         sleep_time = ( target[ :sleep_after_launch ] || target[ :sleep_time ] ).to_i
 
+        timeout_time = sut_parameters[ :application_synchronization_timeout, '5' ].to_f
+
+        retry_interval = sut_parameters[ :application_synchronization_retry_interval, '0.5' ].to_f
+
+        if target.has_key?( :check_pid )
+
+          check_pid = target[ :check_pid ].check_type [ TrueClass, FalseClass ], 'wrong argument type $1 for SUT#run :check_pid (expected $2)' 
+        
+        else
+                    
+          # due to bug #1710; pid checking must be configurable
+          check_pid = sut_parameters[ :application_check_pid, false ].to_s.to_boolean( false )
+
+        end
+
         Kernel::raise ArgumentError, "Sleep time need to be >= 0" unless sleep_time >= 0
 
         # try to find an existing app with the current arguments
-        if target[ :try_attach ]
+        if target[ :try_attach ] || target[:restart_if_running]
+
+          app_list = MobyBase::StateObject.new( 
+
+            :source_data => self.list_apps,
+            :parent => nil,
+            :test_object_adapter => @test_object_adapter
 
-          app_list = MobyBase::StateObject.new( self.list_apps() )
+          )
 
           # either ID or NAME have been passed to identify the application
           # raise exception if more than one app has been found for this id/name
@@ -653,15 +726,20 @@ module MobyBehaviour
 
           app = self.application(:id => app_info.id) if app_info
 
-          if app
+          if target[:restart_if_running] && app
+
+            # Close the application,
+            app.close # (:force_kill => true)
 
+          elsif app
+            
             begin
 
               app.bring_to_foreground
 
             rescue Exception => e
 
-              TDriver.logger.warning "Could not bring app to foreground"
+              $logger.warning "Could not bring app to foreground"
 
             end
 
@@ -679,27 +757,11 @@ module MobyBehaviour
 
         else
 
-=begin
           # execute the application control service request
-          execute_command(
-
-            MobyCommand::Application.new(
-              :Run,
-              target[ :name ],
-              target[ :uid ],
-              self,
-              target[ :arguments ],
-              target[ :environment ],
-              target[ :working_directory ],
-              target[ :events_to_listen ],
-              target[ :signals_to_listen ]
-            )
-
-          )
-=end
+          # the run request will return the pid if all goes well
+          app_pid = nil
 
-          # execute the application control service request
-          execute_command(
+          app_pid = execute_command(
             MobyCommand::Application.new(
               :Run,
               { 
@@ -719,37 +781,39 @@ module MobyBehaviour
 
         # do not remove this, unless qttas server & plugin handles the syncronization between plugin registration & first ui state request
         # first ui dump is requested too early and target/server seems not be ready...
-        #sleep 0.100
-
         sleep sleep_time if sleep_time > 0
-
+     
+        # Now the application id is its PID that we get from the execute_command response
         expected_attributes = { :type => 'application' }
 
-        expected_attributes[ :id ] = target[ :uid ] unless target[ :uid ].nil?
+        # fix to bug #1710; pid checking must be configurable
+        if check_pid == true
+        
+          expected_attributes[ :id ] = app_pid unless app_pid.nil?
 
+        end        
+                
         expected_attributes[ :FullName ] = target[ :name ] unless target[ :name ].nil?
 
+        # For error reporting
         error_details = target[ :name ].nil? ? "" : "name: " << target[ :name ].to_s
         error_details << ( error_details.empty? ? "" : ", ") << "id: " << target[ :uid ].to_s if !target[ :uid ].nil?
 
-        app_name=target[ :name ].nil? ? "" : "name: " << target[ :name ].to_s
+        # Calculate the application name from :FullName ( used later )
+        app_name = target[ :name ].nil? ? "" : "name: " << target[ :name ].to_s
 
         if( !expected_attributes[ :FullName ].nil? )
-
           if( expected_attributes[ :FullName ].include?('/') )
-
             app_name = expected_attributes[ :FullName ].split('/')[ expected_attributes[ :FullName ].split( '/' ).size-1 ]
             app_name.slice!( ".exe" )
             expected_attributes[ :name ] = app_name
 
           elsif( expected_attributes[ :FullName ].include?("\\") )
-
             app_name = expected_attributes[ :FullName ].split("\\")[ expected_attributes[ :FullName ].split( "\\" ).size-1 ]
             app_name.slice!( ".exe" )
             expected_attributes[:name] = app_name
 
           else
-
             app_name = expected_attributes[ :FullName ]
             app_name.slice!( ".exe" )
             expected_attributes[ :name ] = app_name
@@ -758,17 +822,16 @@ module MobyBehaviour
 
           expected_attributes.delete( :FullName )
           expected_attributes.delete( :name )
-
         end
 
+        # Wait for application to register and then create the application test object
         begin
-          timeout_time=$parameters[ @id ][ :application_synchronization_timeout, '5' ].to_f
-          retryinterval=$parameters[ @id ][ :application_synchronization_retry_interval, '0.5' ].to_f
 
           MobyUtil::Retryable.until(
             :timeout => timeout_time,
-            :interval => retryinterval,
+            :interval => retry_interval,
             :exception => MobyBase::ApplicationNotAvailableError) {
+
             # verify that application is launched and application test object is found from xml
             expected_attributes.delete( :name )
 
@@ -781,17 +844,17 @@ module MobyBehaviour
               timeout_time,
 
               # wait retry interval and try again if application was not found
-              retryinterval
+              retry_interval
 
             )
 
             expected_attributes[ :name ] = app_name
             # retrieve application object element from sut.xml_data
 
-            @@matches, unused_rule = TDriver::TestObjectAdapter.get_objects( xml_data, expected_attributes, true )
+            @matches, unused_rule = @test_object_adapter.get_objects( xml_data, expected_attributes, true )
 
             # raise exception if application element was not found; this shouldn't ever happen?
-            raise MobyBase::ApplicationNotAvailableError if @@matches.count == 0
+            raise MobyBase::ApplicationNotAvailableError if @matches.count == 0
 
           }
 
@@ -804,7 +867,7 @@ module MobyBehaviour
 
             :object_attributes_hash => expected_attributes,
 
-            :xml_object => @@matches.first
+            :xml_object => @matches.first
 
           )
 
@@ -824,16 +887,16 @@ module MobyBehaviour
 
         end
 
-        # raise behaviour error if any exception is raised
-      rescue # Exception => e
+      # raise behaviour error if any exception is raised
+      rescue
 
-        TDriver.logger.behaviour "FAIL;Failed to launch application.;#{ id.to_s };sut;{};run;#{ target.kind_of?( Hash ) ? target.inspect : target.class.to_s }"
+        $logger.behaviour "FAIL;Failed to launch application.;#{ id.to_s };sut;{};run;#{ target.kind_of?( Hash ) ? target.inspect : target.class.to_s }"
 
         Kernel::raise MobyBase::BehaviourError.new("Run", "Failed to launch application")
 
       end
 
-      TDriver.logger.behaviour "PASS;The application was launched successfully.;#{ id.to_s };sut;{};run;#{ target.inspect }"
+      $logger.behaviour "PASS;The application was launched successfully.;#{ id.to_s };sut;{};run;#{ target.inspect }"
 
       foreground_app
 
@@ -887,7 +950,15 @@ module MobyBehaviour
 
         value.check_type( [ Symbol, MobyCommand::KeySequence ], "Wrong argument type $1 for press_key (expected $2)" )
 
-        sequence = value.kind_of?( Symbol ) ? MobyCommand::KeySequence.new( value ) : value
+        if value.kind_of?( Symbol )
+
+          sequence = MobyCommand::KeySequence.new( value )
+        
+        else
+
+          sequence = value
+        
+        end
 
         sequence.set_sut( self )
 
@@ -895,13 +966,13 @@ module MobyBehaviour
 
       rescue
 
-        TDriver.logger.behaviour "FAIL;Failed to press key(s).;#{id.to_s};sut;{};press_key;#{ value }"
+        $logger.behaviour "FAIL;Failed to press key(s).;#{id.to_s};sut;{};press_key;#{ value }"
 
         Kernel::raise $!
 
       end
 
-      TDriver.logger.behaviour "PASS;Successfully pressed key(s).;#{ id.to_s };sut;{};press_key;#{ value }"
+      $logger.behaviour "PASS;Successfully pressed key(s).;#{ id.to_s };sut;{};press_key;#{ value }"
 
       nil
 
@@ -925,7 +996,7 @@ module MobyBehaviour
     #   description: Value matching the parameter name given as argument
     #   example: 'testability-driver-qt-sut-plugin'
     #
-    # MobyUtil::ParameterHash
+    # TDriver::ParameterHash
     #   description: Hash of values, if no arguments is specified
     #   example: { :value => '1', :inner_hash => { :another_value => 100 } }
     #
@@ -943,13 +1014,11 @@ module MobyBehaviour
 
       if ( arguments.count == 0 )
 
-        MobyUtil::ParameterUserAPI[ @id ]
+        $parameters[ @id ]
 
       else
 
-        #$stderr.puts "%s:%s warning: deprecated method usage convention, please use sut#parameter[] instead of sut#parameter()" % ( caller.first || "%s:%s" % [ __FILE__, __LINE__ ] ).split(":")[ 0..1 ]
-
-        MobyUtil::ParameterUserAPI[ @id ][ *arguments ]
+        $parameters[ @id ][ *arguments ]
 
       end
 
@@ -985,7 +1054,7 @@ module MobyBehaviour
     #   example: "1"
     #   default: nil
     #  Integer
-    #   description: Optional numeral replacement of an '%Ln | %1' tag on the translated string
+    #   description: Optional numeral replacement of an '%Ln | %1 | %D | %U | %N' tag on the translated string
     #   example: 1
     #  Array
     #   description: Optional numeral replacements for multiple '%L1 | %1, %L2 | %2, ...' tags on the translated string
@@ -1055,9 +1124,9 @@ module MobyBehaviour
 
       when "localisation"
 
-        language=nil
+        language = nil
 
-        if ( $parameters[ self.id ][:read_lang_from_app]=='true')
+        if ( sut_parameters[ :read_lang_from_app ]=='true')
 
           #read localeName app
           language=self.application.attribute("localeName")
@@ -1067,7 +1136,7 @@ module MobyBehaviour
 
         else
 
-          language=$parameters[ self.id ][ :language ]
+          language = sut_parameters[ :language ]
 
         end
 
@@ -1076,7 +1145,7 @@ module MobyBehaviour
         translation = MobyUtil::Localisation.translation(
           logical_name,
           language,
-          $parameters[ self.id ][ :localisation_server_database_tablename ],
+          sut_parameters[ :localisation_server_database_tablename ],
           file_name,
           plurality,
           lengthvariant
@@ -1090,7 +1159,7 @@ module MobyBehaviour
 
           elsif numerus.kind_of? String or numerus.kind_of? Integer
 
-            translation.gsub!(/%(Ln|1)/){|s| numerus.to_s}
+            translation.gsub!(/%(Ln|1|U|D|N)/){|s| numerus.to_s}
 
           end
 
@@ -1104,7 +1173,7 @@ module MobyBehaviour
 
             elsif numerus.kind_of? String or numerus.kind_of? Integer
 
-              trans.gsub!(/%(Ln|1)/){|s| numerus.to_s}
+              trans.gsub!(/%(Ln|1|U|D|N)/){|s| numerus.to_s}
 
             end
 
@@ -1191,10 +1260,10 @@ module MobyBehaviour
         user_data_lname,
 
         # language
-        $parameters[ self.id ][ :language ],
+        sut_parameters[ :language ],
 
         # table name
-        $parameters[ self.id ][ :user_data_server_database_tablename ]
+        sut_parameters[ :user_data_server_database_tablename ]
 
       )
 
@@ -1234,10 +1303,10 @@ module MobyBehaviour
         operator_data_lname,
 
         # operator
-        $parameters[ self.id ][ :operator_selected ],
+        sut_parameters[ :operator_selected ],
 
         # table name
-        $parameters[ self.id ][ :operator_data_server_database_tablename ]
+        sut_parameters[ :operator_data_server_database_tablename ]
 
       )
 
@@ -1252,9 +1321,7 @@ module MobyBehaviour
     # === raises
     def update
 
-      #@_child_objects.each{ | test_object | test_object.update( @xml_data ) } if !@childs_updated
-
-      unless @childs_updated
+      if @update_childs
 
         @child_object_cache.each_object{ | test_object |
 
@@ -1264,9 +1331,17 @@ module MobyBehaviour
 
         }
 
-      end
+        @update_childs = false
 
-      @childs_updated = true
+        # childs were updated
+        true
+
+      else
+
+        # nothing was updated
+        false
+
+      end
 
     end
 
@@ -1275,7 +1350,7 @@ module MobyBehaviour
 
       refresh_ui_dump( refresh_args, creation_attributes )
 
-      # update childs only if ui state is new
+      # update childs if required, returns true or false
       update_childs
 
     end
@@ -1340,13 +1415,13 @@ module MobyBehaviour
     def get_application_id
 
       # retrieve application object from sut.xml_data
-      matches, unused_rule = TDriver::TestObjectAdapter.get_objects( xml_data, { :type => 'application' }, true )
+      matches, unused_rule = @test_object_adapter.get_objects( xml_data, { :type => 'application' }, true )
 
       # retrieve id attribute if application test object found
       if matches.count > 0
 
         # return id attribute value
-        TDriver::TestObjectAdapter.test_object_element_attribute( matches.first, 'id' )
+        @test_object_adapter.test_object_element_attribute( matches.first, 'id' )
 
       else
 
@@ -1357,13 +1432,13 @@ module MobyBehaviour
 
     end
 
-    private
+  private
 
     # TODO: document me
     def update_childs
 
       # update childs only if ui state is new
-      update if !@childs_updated
+      update if @update_childs
 
     end
 
@@ -1377,72 +1452,77 @@ module MobyBehaviour
 
       if !@frozen #&& ( @_previous_refresh.nil? || ( current_time - @_previous_refresh ).to_f >= @refresh_interval )
 
-        use_find_objects = $parameters[ @id ][ :use_find_object, 'false' ] == 'true' and self.respond_to?( 'find_object' )
+        # determine should FindObjects service be used
+        use_find_objects =  sut_parameters[ :use_find_object, 'false' ] == 'true' and self.respond_to?( 'find_object' ) == true
 
+        # duplicate refresh arguments hash
         refresh_arguments = refresh_args.clone
 
         MobyUtil::Retryable.while(
           :tries => @refresh_tries,
           :interval => @refresh_interval,
           :unless => [ MobyBase::ControllerNotFoundError, MobyBase::CommandNotFoundError, MobyBase::ApplicationNotAvailableError ]
-        ) {
+        ){
 
           #use find_object if set on and the method exists
           if use_find_objects
 
-            new_xml_data, crc = find_object( refresh_arguments, creation_attributes )
+            # retrieve new ui dump xml and crc
+            new_xml_data, crc = find_object( refresh_arguments, creation_attributes, @xml_data_crc )
+
+            crc = @xml_data_crc if new_xml_data.empty?
 
           else
 
-=begin
-            app_command = MobyCommand::Application.new(
-              :State,
-              refresh_args[ :FullName ] || refresh_args[ :name ],
-              refresh_args[ :id ],
-              self
+            # retrieve new ui dump xml and crc
+            new_xml_data, crc = execute_command(  
+            
+              MobyCommand::Application.new(
+                :State,
+                {
+                  :application_name => refresh_args[ :FullName ] || refresh_args[ :name ],
+                  :application_uid => refresh_args[ :id ],
+                  :sut => self,
+                  :refresh_arguments => refresh_args,
+                  :checksum => @xml_data_crc
+                }
+              )
+            
             )
-=end
 
-            app_command = MobyCommand::Application.new(
-              :State,
-              {
-                :application_name => refresh_args[ :FullName ] || refresh_args[ :name ],
-                :application_uid => refresh_args[ :id ],
-                :sut => self
-              }
-            )
+            crc = @xml_data_crc if new_xml_data.empty?
 
-            # store in case needed
-            app_command.refresh_args( refresh_args )
+          end
 
-            new_xml_data, crc = execute_command( app_command )
+          # parse the xml if crc does not match with previously retrieved crc
+          if ( @xml_data_crc == 0 || crc != @xml_data_crc || crc.nil? )
 
-          end
+              # parse new xml string, return cached object if one is found; crc is used for caching and identifying the duplicate xml strings
+              xml_data, from_cache = MobyUtil::XML.parse_string( new_xml_data, crc )
 
-          @dump_count += 1
+              # store new xml data object
+              @xml_data = xml_data.root
 
-          @childs_updated = false
+              # store xml crc to be compared while next ui dump request; do not reparse xml if crc values are equal
+              @xml_data_crc = crc
 
-          @xml_data = MobyUtil::XML.parse_string( new_xml_data ).root
+              # mark that child objects needs to be updated 
+              @update_childs = true #unless from_cache
 
-          @_previous_refresh = Time.now
+          end
 
-          # remove timestamp from the beginning of tasMessage, parse if not same as previous ui state
-          #if ( xml_data_no_timestamp = new_xml_data.split( ">", 2 ).last ) != @last_xml_data
-          # @xml_data = MobyUtil::XML.parse_string( new_xml_data ).root
-          # @last_xml_data = xml_data_no_timestamp
-          #end
+          # increase number of sent ui dump requests by one
+          @dump_count += 1
 
-          #if ( @xml_data_crc == 0 || crc != @xml_data_crc || crc.nil? )
-          # @xml_data, @xml_data_crc, @childs_updated = MobyUtil::XML.parse_string( new_xml_data ).root, crc, false
-          #end
+          # store timestamp of last performed ui dump request 
+          @_previous_refresh = Time.now
 
         }
 
       end
 
-#      fetch_references( @xml_data )
       @xml_data
+      
     end
 
     # TODO: document me
@@ -1604,58 +1684,72 @@ module MobyBehaviour
 
     end
 
-    def initialize_settings
-
-      @xml_data = ""
-
-      @x_path = '.'
-
-      @frozen = false
-
-      @child_object_cache = TDriver::TestObjectCache.new
-
-      @current_application_id = nil
-
-      @dump_count = 0
-
-      # default values
-      @input = :key
-
-      @refresh_tries = 5
-      @refresh_interval = 0.5
+    def load_verify_blocks( filename )
 
-      @childs_updated = false
+      # load verify blocks if filename not empty
+      unless filename.blank?
 
-      # id not found from parameters
-      if $parameters[ @id, nil ] != nil
+        # verify that file exists
+        if File.exists?( filename )
 
-        @input = $parameters[ @id ][ :input_type, "key" ].to_sym
+          # load verify blocks configuration file
+          load filename
 
-        @refresh_tries = $parameters[ @id ][ :ui_state_refresh_tries, @refresh_tries ].to_f
+          # return collection of verify blocks; reference directly to VERIFY_BLOCKS must not be used, due to it may get cleared by user
+          SutParameters::VERIFY_BLOCKS.collect{ | block | block }
 
-        @refresh_interval = $parameters[ @id ][ :refresh_interval, @refresh_interval ].to_f
+        else
+        
+          # return empty array due to file didn't exist
+          []
+        
+        end
 
+      else
+      
+        # return empty array due to no filename was given
+        []
+      
       end
 
-      @last_xml_data = nil
-
-      ruby_file = $parameters[ @id ][ :verify_blocks ]
+    end
 
-      @verify_blocks = []
+    # TODO: document me
+    def initialize_settings
 
-      if File.exists?( ruby_file )
+      # default values
+      @x_path = '.'
+      @xml_data = ""
+      @dump_count = 0
 
-        load ruby_file
+      # determines that should child test objects be updated
+      @update_childs = true
+      
+      @last_xml_data = nil
+      @frozen = false
 
-        SutParameters::VERIFY_BLOCKS.each { | block |
+      # initialize cache for sut children
+      @child_object_cache = TDriver::TestObjectCache.new
 
-          @verify_blocks << block
+      @current_application_id = nil
 
-        }
+      # create empty hash for sut parameters if sut id not found from parameters
+      $parameters[ @id ] = {} unless $parameters.has_key?( @id )
 
+      @input            = sut_parameters[ :input_type,             'key' ].to_sym
+      @refresh_tries    = sut_parameters[ :ui_state_refresh_tries, '5'   ].to_f
+      @refresh_interval = sut_parameters[ :refresh_interval,       '0.5' ].to_f
 
-      end
+      # load verify blocks from defined sut configuration file 
+      @verify_blocks    = load_verify_blocks( sut_parameters[ :verify_blocks, nil ] )
+      
+    end
 
+    # accessor for sut parameters
+    def sut_parameters
+    
+      $parameters[ @id ]
+    
     end
 
     public # deprecated
@@ -1669,7 +1763,7 @@ module MobyBehaviour
 
       warn "warning: deprecated method SUT#get_object; please use SUT#child instead"
 
-      child object_id
+      child( object_id )
 
     end
 
@@ -1686,7 +1780,22 @@ module MobyBehaviour
 
       #$stderr.puts "warning: SUT#get_ui_dump is deprecated, please use SUT#refresh_ui_dump instead."
 
-      refresh_ui_dump refresh_args, {}
+      refresh_ui_dump( refresh_args, {} )
+
+    end
+
+    # This method is deprecated, please use [link="#GenericSut:state_object"]SUT#state_object[/link] instead.
+    # == deprecated
+    # 1.1.1
+    #
+    # == description
+    # This method is deprecated, please use SUT#state_object
+    #
+    def state
+
+      warn "warning: deprecated method SUT#state; please use SUT#state_object instead"
+
+      state_object
 
     end