testability-driver 0.9.2 → 1.0.0

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

@@ -17,11 +17,10 @@
 ## 
 ############################################################################
 
-
 # Find behaviour 
 # Methods for finding test objects on the suttest objet state
 module MobyBehaviour
-
+  
 	# == description
 	# This module contains generic find behaviour
 	#
@@ -45,12 +44,12 @@ module MobyBehaviour
 	module Find   
 
 		include MobyBehaviour::Behaviour
-
+    # == nodoc
 		# == description
 		# Finds a child test_object given its name and type and returns it as a reference 
 		#
 		# == arguments
-		# find_hash
+		# attributes
 		#  Hash
 		#   description: one or more attributes defining the rules for the test object search. Must not be empty.
 		#   example: { :name => 'oneButton' }
@@ -63,27 +62,34 @@ module MobyBehaviour
 		#
 		# == exceptions
 		# TypeError
-		#  description: raised if agument is not a Hash or is an emtpy Hash
-		#    
+		#  description: Wrong argument type %s for attributes (expected Hash)
+		# 
+		# ArgumentError
+		#  description: Attributes hash must not be empty
+		# 
 		# == info
 		#  Same as calling child method.
-		def find ( find_hash = {} )
+		def find ( attributes = {} )
 
 			begin
 
-				raise TypeError.new( 'Input parameter not of Type: Hash or empty.\nIt is: ' + find_hash.class.to_s ) unless find_hash.kind_of?( Hash ) and !find_hash.empty?
+        attributes.check_type( Hash, "Wrong argument type $1 for attributes (expected $2)" )
+        
+        attributes.not_empty( 'Attributes hash must not be empty' )
 
-				search_result = child(find_hash)
+				#raise ArgumentError.new( 'Attributes hash must not be empty' ) if attributes.empty?
+        
+				search_result = child( attributes )
 
 			rescue Exception => e
 
-				MobyUtil::Logger.instance.log "behaviour" , "FAIL;Failed to find test object.;#{id.to_s};sut;{};find;" << ( find_hash.kind_of?( Hash ) ? find_hash.inspect : find_hash.class.to_s )
+				MobyUtil::Logger.instance.log "behaviour" , "FAIL;Failed to find test object.;#{id.to_s};sut;{};find;" << ( attributes.kind_of?( Hash ) ? attributes.inspect : attributes.class.to_s )
 
 				Kernel::raise e
 
 			end
 
-			MobyUtil::Logger.instance.log "behaviour" , "PASS;Test object found.;#{id.to_s};sut;{};application;" << find_hash.inspect 
+			MobyUtil::Logger.instance.log "behaviour" , "PASS;Test object found.;#{id.to_s};sut;{};application;" << attributes.inspect 
 
 			search_result
 		end

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

@@ -43,45 +43,41 @@ module MobyBehaviour
     include MobyBehaviour::Behaviour
 
     # == description
-    # Instructs the sut to start the flash operation with default TDriver parameters for sut that are:
-    # how many times TDriver will attempt to flash the device:
-    # [code]<parameter name="flash_attempts" value="2" />[/code]
-    # timeout in seconds between the switchbox commands:
-    # [code]<parameter name="timeout_between_command_sequence" value="25" />[/code]
-    # commands you want to be executed before flash:
-    # [code]<parameter name="switchbox_commands_before_flash" value="" />[/code]
-    # flash commands before flash:
-    # [code]<parameter name="commands_before_flash" value="" />[/code]
-    # intial flash command:
-    # [code]<parameter name="flash_command" value="" />[/code]
-    # timeout in seconds before executing the commands during flash:
-    # <parameter name="timeout_before_executing_commands_during_flash" value="20" />
-    # commands you want to be executed during flash:
-    # <parameter name="switchbox_commands_during_flash" value="" />
-    # optional flash parameters:
-    # <parameter name="optional_parameters_after_flashing" value="" />
-    # images to flash:
-    # <parameter name="flash_images" value="" />
-    # need to wait for the flash process to finish:
-    # <parameter name="sleep_time_after_flash_command" value="70" />
-    # flash command after flash:
-    # <parameter name="command_after_flash" value="" />
-    # commands for switchbox after failed flash:
-    # <parameter name="switchbox_commands_after_failed_flash" value="" />
-    # commands after failed flash:
-    # <parameter name="commands_after_failed_flash" value="" />
-    # If no error then no string is displayed:
-    # <parameter name="flash_command_success_string" value="" />
-    # commands you want to be executed after flash:
-    # <parameter name="switchbox_commands_after_flash" value="" /> 
+    # Instructs the sut to start the flash operation with default TDriver parameters  
+    #
+    #
     # == arguments
     # == returns
+    # Boolean
+    #  description: Indicating that did flashing success
+    #  example: true
     # == exceptions
     # BehaviourError
     #  description: If mandatory parameters are missing
     # BehaviourError
     #  description: If flashing is failed
-    # === info
+    #
+    # == tables
+    # flash_prameters
+    #  title: Flash parameters
+    #  description: Flash parameters for sut
+    #  |Parameter|Description|Example|
+    #  |:flash_attempts|How many times TDriver will attempt to flash the device|<parameter name="flash_attempts" value="2" />|
+    #  |:timeout_between_command_sequence|Timeout in seconds between the switchbox commands|<parameter name="timeout_between_command_sequence" value="25" />|
+    #  |:switchbox_commands_before_flash|Commands you want to be executed before flash|<parameter name="switchbox_commands_before_flash" value="" />|
+    #  |:commands_before_flash|Flash commands before flash|<parameter name="commands_before_flash" value="" />|
+    #  |:flash_command|Intial flash command|<parameter name="flash_command" value="" />|
+    #  |:timeout_before_executing_commands_during_flash|Timeout in seconds before executing the commands during flash|<parameter name="timeout_before_executing_commands_during_flash" value="20" />|
+    #  |:switchbox_commands_during_flash|Commands you want to be executed during flash|<parameter name="switchbox_commands_during_flash" value="" />|
+    #  |:optional_parameters_after_flashing|Optional flash parameters|<parameter name="optional_parameters_after_flashing" value="" />|
+    #  |:flash_images|Images to flash|<parameter name="flash_images" value="" />|
+    #  |:sleep_time_after_flash_command|Wait time for the flash process to finish|<parameter name="sleep_time_after_flash_command" value="70" />|
+    #  |:command_after_flash|Flash command after flash|<parameter name="command_after_flash" value="" />|
+    #  |:switchbox_commands_after_failed_flash|Commands for switchbox after failed flash|<parameter name="switchbox_commands_after_failed_flash" value="" />|
+    #  |:commands_after_failed_flash|Commands after failed flash|<parameter name="commands_after_failed_flash" value="" />|
+    #  |:flash_command_success_string|If no error then no string is displayed|<parameter name="flash_command_success_string" value="" />|
+    #  |:switchbox_commands_after_flash|Commands you want to be executed after flash|<parameter name="switchbox_commands_after_flash" value="" />|
+
     def flash()
 
       flash_images
@@ -89,49 +85,43 @@ module MobyBehaviour
     end
 
     # == description
-    # Instructs the sut to start the flash operation with default TDriver parameters for sut that are:
-    # how many times TDriver will attempt to flash the device:
-    # <parameter name="flash_attempts" value="2" />
-    # timeout in seconds between the switchbox commands:
-    # <parameter name="timeout_between_command_sequence" value="25" />
-    # commands you want to be executed before flash:
-    # <parameter name="switchbox_commands_before_flash" value="" />
-    # flash commands before flash:
-    # <parameter name="commands_before_flash" value="" />
-    # intial flash command:
-    # <parameter name="flash_command" value="" />
-    # timeout in seconds before executing the commands during flash:
-    # <parameter name="timeout_before_executing_commands_during_flash" value="20" />
-    # commands you want to be executed during flash:
-    # <parameter name="switchbox_commands_during_flash" value="" />
-    # optional flash parameters:
-    # <parameter name="optional_parameters_after_flashing" value="" />
-    # images to flash:
-    # <parameter name="flash_images" value="" />
-    # need to wait for the flash process to finish:
-    # <parameter name="sleep_time_after_flash_command" value="70" />
-    # flash command after flash:
-    # <parameter name="command_after_flash" value="" />
-    # commands for switchbox after failed flash:
-    # <parameter name="switchbox_commands_after_failed_flash" value="" />
-    # commands after failed flash:
-    # <parameter name="commands_after_failed_flash" value="" />
-    # If no error then no string is displayed:
-    # <parameter name="flash_command_success_string" value="" />
-    # commands you want to be executed after flash:
-    # <parameter name="switchbox_commands_after_flash" value="" />
+    # Instructs the sut to start the flash operation with the configured flash files
+    #
     # == arguments
     # flash_files
     #  String
     #  description: The location of the software image file
     #  example: "C:/images/flash_image.img"
     # == returns
+    # Boolean
+    #  description: Indicating that did flashing success
+    #  example: true
     # == raises
     # BehaviourError If mandatory parameters are missing
     # BehaviourError If flashing is failed
     # === examples
     # @sut.flash_images("C:/path/image_file.img")
-    def flash_images(flash_files=nil)
+    # == tables
+    # flash_prameters
+    #  title: Flash parameters
+    #  description: Flash parameters for sut
+    #  |Parameter|Description|Example|
+    #  |:flash_attempts|How many times TDriver will attempt to flash the device|<parameter name="flash_attempts" value="2" />|
+    #  |:timeout_between_command_sequence|Timeout in seconds between the switchbox commands|<parameter name="timeout_between_command_sequence" value="25" />|
+    #  |:switchbox_commands_before_flash|Commands you want to be executed before flash|<parameter name="switchbox_commands_before_flash" value="" />|
+    #  |:commands_before_flash|Flash commands before flash|<parameter name="commands_before_flash" value="" />|
+    #  |:flash_command|Intial flash command|<parameter name="flash_command" value="" />|
+    #  |:timeout_before_executing_commands_during_flash|Timeout in seconds before executing the commands during flash|<parameter name="timeout_before_executing_commands_during_flash" value="20" />|
+    #  |:switchbox_commands_during_flash|Commands you want to be executed during flash|<parameter name="switchbox_commands_during_flash" value="" />|
+    #  |:optional_parameters_after_flashing|Optional flash parameters|<parameter name="optional_parameters_after_flashing" value="" />|
+    #  |:flash_images|Images to flash|<parameter name="flash_images" value="" />|
+    #  |:sleep_time_after_flash_command|Wait time for the flash process to finish|<parameter name="sleep_time_after_flash_command" value="70" />|
+    #  |:command_after_flash|Flash command after flash|<parameter name="command_after_flash" value="" />|
+    #  |:switchbox_commands_after_failed_flash|Commands for switchbox after failed flash|<parameter name="switchbox_commands_after_failed_flash" value="" />|
+    #  |:commands_after_failed_flash|Commands after failed flash|<parameter name="commands_after_failed_flash" value="" />|
+    #  |:flash_command_success_string|If no error then no string is displayed|<parameter name="flash_command_success_string" value="" />|
+    #  |:switchbox_commands_after_flash|Commands you want to be executed after flash|<parameter name="switchbox_commands_after_flash" value="" />|
+    def flash_images(flash_files = nil)
       file, line = caller.first.split(":")
 
       begin
@@ -221,12 +211,13 @@ module MobyBehaviour
       flash_command="#{str_flash_command} #{flash_files} #{str_optional_parameters}"
 
       #start flashing
-      result=start_flashing(flash_command)
+      result = start_flashing( flash_command )
+      
       Kernel::raise MobyBase::BehaviourError.new("flash_images", "Flashing failed") if result.to_s == 'false'
 
     end
 
-    private
+  private
 
     def execute_command_sequence(command_sequence)
 

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

@@ -38,7 +38,7 @@ module MobyBehaviour
   # *
   #
   # == objects
-  # *
+  # sut
   #
   module SUT
 
@@ -47,38 +47,50 @@ module MobyBehaviour
     # == nodoc
     attr_accessor(
 
-				  :dump_count,                # number of UI dump requests done to current SUT
-				  :current_application_id,    # id of the current appication if set
-				  :input,                     # the input method used for interacting with this sut as a symbol, eg. :key or :touch.
-				  :refresh_tries,             # number of retries for ui dump on error case
-				  :refresh_timeout           # timeout between timeout retry
+        :dump_count,                # number of UI dump requests done to current SUT
+        :current_application_id,    # id of the current appication if set
+        :input,                     # the input method used for interacting with this sut as a symbol, eg. :key or :touch.
+        :refresh_tries,             # number of retries for ui dump on error case
+        :refresh_timeout           # timeout between timeout retry
 
-	  )
+    )
 
     # == nodoc
     attr_reader(
 
-				:xml_data,      # sut xml_data
-				:x_path,        # x_path pattern for xml_data
-				:ui_type,       # type of the UI used on the sut, ie. s60, qt, windows
-				:ui_version,    # version of the ui used on the sut, ie 3.2.3
-				:frozen,        # flag that tells if the ui dump getting is disabled
-				:xml_data_crc,  # crc of the previous ui state message
-				:verify_blocks  # verify blocks              
+        :xml_data,      # sut xml_data
+        :x_path,        # x_path pattern for xml_data
+        :ui_type,       # type of the UI used on the sut, ie. s60, qt, windows
+        :ui_version,    # version of the ui used on the sut, ie 3.2.3
+        :frozen,        # flag that tells if the ui dump getting is disabled
+        :xml_data_crc,  # crc of the previous ui state message
+        :verify_blocks  # verify blocks              
 
-		)
+    )
 
-    
     # == description
     # Connects selected SUT according to configuration in tdriver_parameters.xml.
-    #
+    # == arguments
+    # id
+    #  Symbol
+    #   description: SUT id
+    #   example: :sut_qt
+    # == returns
+    # Boolean
+    #  description: Determines if SUT is connected
+    #  example: true
     def connect( id )
 
       @_sutController.connect( id )
 
     end
 
-    # Retrieves the total amount of data sent in bytes
+    # == description
+    # Disconnects the current SUT
+    # == returns
+    # Boolean
+    #  description: Determines if SUT is connected
+    #  example: false
     # == examples
     #  @sut.disconnect
     def disconnect
@@ -87,16 +99,26 @@ module MobyBehaviour
 
     end
 
+    # == description
     # Retrieves the total amount of data received in bytes
+    # == returns
+    # Fixnum
+    #  description: Total amount of data received in bytes
+    #  example: 65535
     # == examples
     #  @sut.disconnect
     def received_data
-	  
+    
       @_sutController.received_bytes
 
     end
 
+    # == description
     # Retrieves the total amount of data sent in bytes
+    # == returns
+    # Fixnum
+    #  description: Total amount of data sent in bytes
+    #  example: 65535
     # == examples
     #  @sut.sent_data
     def sent_data
@@ -105,19 +127,35 @@ module MobyBehaviour
 
     end
 
-    # function to disable taking ui dumps from target for a moment
-    # user must remember to enable ui dumps again using unfreeze
+    # == description
+    # Function to disable taking UI dumps from target for a moment. This method might be deprecated in future release.\n
+    # \n
+    # [b]NOTE:[/b] Remember to enable ui dumps again using unfreeze! 
+    # == returns
+    # NilClass
+    #  description: -
+    #  example: -
     def freeze
 
       @frozen = true
 
+      nil
+
     end
 
-    # function to enable taking ui dumps from target
+    # == description
+    # Function to enable taking ui dumps from target. This method might be deprecated in future release.\n
+    # \n
+    # == returns
+    # NilClass
+    #  description: -
+    #  example: -
     def unfreeze
 
       @frozen = false
 
+      nil
+
     end
 
     # == nodoc
@@ -131,41 +169,52 @@ module MobyBehaviour
 
     end
 
-    # Force to use user defined ui state (e.g. for debugging purposes)
+    # == nodoc  
+    # == description
+    # Force to use user defined ui state (e.g. for debugging purposes). Freezes the SUT xml_data, until unfreezed or set to nil. 
     #
-    # Freezes the SUT xml_data, until unfreezed or set to nil. 
-    # == params
-    # xml:: String, MobyUtil::XML::Element or NilClass
-    # == examples
-    #  @sut.xml_data = "<tasMessage>.....</tasMessage>"
-    #  @sut.xml_data = xml_element
-  	#  @sut.xml_data = nil
-    # == raises
-    # ArgumentError:: Unexpected argument type (%s) for xml, expected: %s
+    # == arguments
+    # xml
+    #  String
+    #   description: Freeze SUT XML data with given XML string
+    #   example: "<tasMessage>.....</tasMessage>"
+    #  MobyUtil::XML::Element
+    #   description: Freeze SUT XML data with given XML element
+    #   example: -
+    #  NilClass
+    #   description: Unfreeze SUT XML data
+    #   example: nil
+    #
+    # == returns
+    # NilClass
+    #  description: This method doesn't return anything
+    #  example: -
+    #
+    # == exception
+    # TypeError
+    #  description: Wrong argument type %s for XML (expected MobyUtil::XML::Element, String or NilClass)
     def xml_data=( xml )
 
+      xml.check_type( [ MobyUtil::XML::Element, String, NilClass ], "Wrong argument type $1 for XML (expected $2)" )
+
       if xml.kind_of?( MobyUtil::XML::Element )
 
         @xml_data = xml
+        @frozen = true
 
       elsif xml.kind_of?( String )
 
         @xml_data = MobyUtil::XML.parse_string( xml ).root
+        @frozen = true
 
-      elsif xml.nil?
+      elsif xml.kind_of?( NilClass )
 
         @xml_data = nil
-
         @frozen = false
 
-      else
-
-        Kernel::raise ArgumentError.new( "Unexpected argument type (%s) for xml, expected: %s" % [ xml.class, "MobyUtil::XML::Element or String"] )
-
       end
-	  
-      # freeze sut - xml won't be updated unless unfreezed first
-      @frozen = true unless xml.nil?
+
+      nil
 
     end
 
@@ -180,50 +229,50 @@ module MobyBehaviour
       if !@frozen && ( @_previous_refresh.nil? || ( current_time - @_previous_refresh ).to_f > @refresh_interval )
 
         MobyUtil::Retryable.while(
-								  :tries => @refresh_tries,
-								  :interval => @refresh_interval,
-								  :unless => [ MobyBase::ControllerNotFoundError, MobyBase::CommandNotFoundError ] ) {
-
-
-		  #use find_object if set on and the method exists
-		  if MobyUtil::Parameter[ @id ][ :use_find_object, 'false' ] == 'true' and self.methods.include?('find_object')
-			new_xml_data, crc = find_object(refresh_args.clone, creation_attributes)
-		  else
-			app_command = MobyCommand::Application.new( 
-													 :State, 
-													 ( refresh_args[ :FullName ] || refresh_args[ :name ] ),
-													 refresh_args[ :id ], 
-													 self 
-													 ) 
-			#store in case needed
-			app_command.refresh_args(refresh_args)
-			new_xml_data, crc = execute_command( app_command )
-		  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, @childs_updated = MobyUtil::XML.parse_string( new_xml_data ).root, false
-
-			@last_xml_data = xml_data_no_timestamp
-
-		  end
-
-
-		  #            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
-		  
-		  @dump_count += 1
-		  
-		  @_previous_refresh = current_time
+          :tries => @refresh_tries,
+          :interval => @refresh_interval,
+          :unless => [ MobyBase::ControllerNotFoundError, MobyBase::CommandNotFoundError, MobyBase::ApplicationNotAvailableError ] 
+        ) {
 
-        } 
+          #use find_object if set on and the method exists
+          if MobyUtil::Parameter[ @id ][ :use_find_object, 'false' ] == 'true' and self.respond_to?('find_object') # self.methods.include?('find_object')
 
-        
-		
+            new_xml_data, crc = find_object( refresh_args.clone, creation_attributes )
+
+          else
+
+            app_command = MobyCommand::Application.new( 
+              :State, 
+              refresh_args[ :FullName ] || refresh_args[ :name ],
+              refresh_args[ :id ], 
+              self 
+            ) 
+
+            #store in case needed
+            app_command.refresh_args( refresh_args )
+
+            new_xml_data, crc = execute_command( app_command )
+
+          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, @childs_updated = MobyUtil::XML.parse_string( new_xml_data ).root, false
+
+            #@last_xml_data = xml_data_no_timestamp
+
+          #end
+
+          #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
+
+          @dump_count += 1
+
+          @_previous_refresh = current_time
+
+        } 
 
       end
 
@@ -233,109 +282,107 @@ module MobyBehaviour
       
     end
 
-    # Creates a test object that belongs to this SUT.
-    # Usually it is 'Application' TestObject
-    # Associates child object as current object's child.
-    # and associates self as child object's parent.
+    # TODO: merge TestObject#child and SUT#child 
+    # == description
+    # Creates a child test object from this SUT. SUT object will be associated as child test objects parent.\n
     #
-    # NOTE:
-    # Subsequent calls to SUT#child(rule) always returns reference to same Testobject:
-    # a = sut.child(rule) ; b = sut.child(rule) ; a.equal?( b ); # => true
-    # note the usage of equal? above instead of normally used eql?. Please refer to Ruby manual for more information.
+    # [b]NOTE:[/b] Subsequent calls to TestObject#child( rule ) always returns reference to same Testobject:\n
+    # [code]a = sut.child( :type => 'Button', :text => '1' )
+    # b = sut.child( :type => 'Button', :text => '1' )
+    # a.eql?( b ) # => true[/code]
+    #
+    # == arguments
+    # attributes
+    #  Hash
+    #   description: Hash object holding information for identifying which child to create
+    #   example: { :type => "application" }
     #
-    # == params
-    # hash_rule:: Hash object holding information for identifying which child to create, eg. :type => :application
     # == returns
-    # TestObject:: new child test object or reference to existing child
-    def child( hash_rule )
+    # TestObject
+    #  description: New child test object or reference to existing child
+    #  example: -
+    def child( attributes )
 
-      creation_hash = hash_rule.clone
+      ###############################################################################################################
+      #
+      #  NOTICE: Please do not add anything unnessecery to this method, it might cause a major performance impact
+      #
+      
+      # verify attributes argument format
+      attributes.check_type( Hash, "Wrong argument type $1 for attributes (expected $2)" )
+            
+      # store original hash
+      creation_hash = attributes.clone
 
-      initial_timeout = @test_object_factory.timeout unless ( custom_timeout = creation_hash.delete( :__timeout ) ).nil?
+      identification_directives = creation_hash.strip_dynamic_attributes!
 
-      logging_enabled = MobyUtil::Logger.instance.enabled
-      MobyUtil::Logger.instance.enabled = false if ( creation_hash.delete( :__logging ) == 'false' )
+      # raise exception if wrong value type given for ;__logging 
+      identification_directives[ :__logging ].check_type( 
+      
+        [ TrueClass, FalseClass ], 
+        
+        "Wrong value type $1 for :__logging test object creation directive (expected $2)"
+        
+      ) if identification_directives.has_key?( :__logging )
+
+      # disable logging if requested, remove pair from creation_hash
+      MobyUtil::Logger.instance.push_enabled( identification_directives[ :__logging ] || TDriver.logger.enabled )
 
       begin
 
-        @test_object_factory.timeout = custom_timeout unless custom_timeout.nil?
-        child_test_object = @test_object_factory.make( self, MobyBase::TestObjectIdentificator.new( creation_hash ) )
+        # TODO: refactor me
+        child_test_object = @test_object_factory.get_test_objects(
+
+          # current object as parent, can be either TestObject or SUT
+          :parent => self,
+ 
+          # test object identification hash
+          :object_attributes_hash => creation_hash,
+          
+          :identification_directives => identification_directives
+
+        )
 
       rescue MobyBase::MultipleTestObjectsIdentifiedError => exception
 
-        MobyUtil::Logger.instance.log "behaviour", "FAIL;Multiple child objects matched criteria.;#{ id };sut;{};child;#{ hash_rule.inspect }"
+        MobyUtil::Logger.instance.log "behaviour", "FAIL;Multiple child objects matched criteria.;#{ id };sut;{};child;#{ attributes.inspect }"
+
         Kernel::raise exception
 
       rescue MobyBase::TestObjectNotFoundError => exception
 
-        MobyUtil::Logger.instance.log "behaviour", "FAIL;The child object could not be found.;#{ id };sut;{};child;#{ hash_rule.inspect }"
+        MobyUtil::Logger.instance.log "behaviour", "FAIL;The child object could not be found.;#{ id };sut;{};child;#{ attributes.inspect }"
+
         Kernel::raise exception
 
       rescue Exception => exception
 
-        MobyUtil::Logger.instance.log "behaviour", "FAIL;Failed when trying to find child object.;#{ id };sut;{};child;#{ hash_rule.inspect }"
+        MobyUtil::Logger.instance.log "behaviour", "FAIL;Failed when trying to find child object.;#{ id };sut;{};child;#{ attributes.inspect }"
+
         Kernel::raise exception
 
       ensure
 
-        @test_object_factory.timeout = initial_timeout unless custom_timeout.nil?
-        MobyUtil::Logger.instance.enabled = logging_enabled
+        # restore original logger state
+        MobyUtil::Logger.instance.pop_enabled
 
       end
 
-      # return already existing child TestObject so that there is references to only one TestObject
-      child_test_object.add_parent( self )
-
-      # Type information is stored in a separate member, not in the Hash
-      creation_hash.delete( :type )
-
-      @_child_object_cache.each_value do | _child |
-
-        if _child.eql?( child_test_object )
-
-          # Update the attributes that were used to create the child object.
-          #_child.creation_attributes = creation_hash
-
-          _child.instance_eval("@creation_attributes = #{ creation_hash.inspect }")
-
-          return _child
-
-        end
-
-      end
-
-=begin
-		 @_child_objects.each do | _child |
-
-		  if _child.eql? child_test_object
-
-			# Update the attributes that were used to create the child object.
-			_child.creation_attributes = creation_hash
-			return _child
-
-		  end
-
-		end
-=end
-      # Store the attributes that were used to create the child object.
-      child.creation_attributes = creation_hash
-
-      add_child( child_test_object )
-
+      # return child test object
       child_test_object
 
     end
 
-		# == description
+    # == 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.
     # == returns
-    # StateObject:: State of this test object
+    # StateObject
+    #  description: State of this test object
+    #  example: -
     # == exceptions
     # RuntimeError
-    # description: If the xml source for the object is not in initialized
-    # == example
-    # sut_state = @sut.state #get the state object for the sut
+    #  description: If the XML source for the object is not in initialized
     def state
 
       # refresh if xml data is empty
@@ -343,16 +390,12 @@ module MobyBehaviour
 
       Kernel::raise RuntimeError.new( "Can not create state object of SUT with id '%s', no XML content or SUT not initialized properly." % @id ) if @xml_data.empty?
 
-      MobyBase::StateObject.new( 
-
-								MobyUtil::XML.parse_string( 
-
-														   "<sut name='sut' type='sut' id='%s'><objects>%s</objects></sut>" % [ @id, xml_data.xpath("tasInfo/object").collect{ | element | element.to_s }.join ]
-
-														   ).root, 
-								self 
-
-								)
+      MobyBase::StateObject.new(
+        MobyUtil::XML.parse_string( 
+          "<sut name='sut' type='sut' id='%s'><objects>%s</objects></sut>" % [ @id, xml_data.xpath("tasInfo/object").collect{ | element | element.to_s }.join ]
+        ).root, 
+        self 
+      )
 
     end
 
@@ -371,17 +414,20 @@ module MobyBehaviour
     #  example: -
     #
     # == exceptions
-    # ArgumentError
-    #   description: The attributes argument was not a Hash
+    # TypeError
+    #  description: Wrong argument type %s for attributes (expected Hash)
+    #
     def application( attributes = {} )
 
       begin
 
-        raise TypeError.new( "Input parameter not of Type: Hash.\nIt is: #{ attributes.class }" ) unless attributes.kind_of?( Hash )
+        attributes.check_type( Hash, "Wrong argument type $1 for attributes (expected $2)" )
+
         get_default_app = attributes.empty?
+
         attributes[ :type ] = 'application'
-        current_application_id = nil if attributes[ :id ].nil?
 
+        @current_application_id = nil if attributes[ :id ].nil?
 
         app_child = child( attributes )
 
@@ -406,13 +452,13 @@ module MobyBehaviour
     #  Hash
     #   description: 
     #    Options to be used for screen capture. See [link="#capture_options_table"]Options table[/link] for valid keys
-    #   example: ( :Filename => "c:/screen_shot.png" )
+    #   example: ( :filename => "output.png" )
     #
     # == tables
     # capture_options_table
     #  title: Options table
     #  |Key|Type|Description|Example|Required|
-    #  |:Filename|String|Filename where file is stored: either absolute path or if no path given uses working directory|:Filename => "c:/screen_shot.png"|Yes|
+    #  |:filename|String|Store output binary to this file. Absolute or relative path supported.|:filename => "screen_shots/output.png"|Yes|
     #
     # == returns
     # NilClass
@@ -420,33 +466,53 @@ module MobyBehaviour
     #   example: -    
     #
     # == exceptions
+    # TypeError
+    #   description: Wrong argument type %s (expected Hash)
+    #
     # ArgumentError
-    #   description: Wrong argument type %s (Expected Hash)
+    #   description: Output filename (:filename) not defined in argument hash
     #
     # ArgumentError
-    #   description: Symbol %s expected in argument(s)
+    #  description: Wrong argument type %s for output filename (expected String)
     #
     # ArgumentError 
-    #   description: Invalid string length for output filename: '%s'
+    #   description: Output filename must not be empty string
     # 
     def capture_screen( arguments )
 
       begin
 
-        MobyBase::Error.raise( :WrongArgumentType, arguments.class, "Hash" ) unless arguments.kind_of?( Hash )
-        MobyBase::Error.raise( :ArgumentSymbolExpected, ":Filename" ) unless arguments.include?( :Filename )
-        MobyBase::Error.raise( :WrongArgumentTypeFor, arguments[ :Filename ].class, "output filename", "String" ) unless arguments[:Filename].kind_of?( String )
-        MobyBase::Error.raise( :InvalidStringLengthFor, arguments[ :Filename ].length, "output filename", ">=1" ) unless arguments[:Filename].length > 0
+        # raise exception with default message if wrong argument type given
+        arguments.check_type( Hash, "Wrong argument type $1 (expected $2)" )
+
+        # legacy support: support also :Filename
+        arguments[ :filename ] = arguments.delete( :Filename ) if arguments.has_key?( :Filename )
+
+        # raise exception with default message if hash doesn't contain required key
+        arguments.require_key( :filename, "Output filename ($1) not defined in argument hash" )
+
+        # verify that filename is type of String
+        arguments[ :filename ].check_type( String, "Wrong argument type $1 for output filename (expected $2)" )
+
+        # verify that filename is not empty string
+        arguments[ :filename ].not_empty( "Output filename must not be empty string" )
 
-        screen_capture_command_object = MobyCommand::ScreenCapture.new()
-        screen_capture_command_object.redraw = arguments[ :Redraw ] if arguments[ :Redraw ]
-        image_binary = execute_command( screen_capture_command_object )
+        # create screen capture command object
+        command = MobyCommand::ScreenCapture.new()
 
-        File.open( arguments[ :Filename ], 'wb:binary'){ | image_file | image_file << image_binary }
+        command.redraw = arguments[ :Redraw ] if arguments[ :Redraw ]
+
+        # execute command and write binary to file
+        File.open( File.expand_path( arguments[ :filename ] ), 'wb:binary' ){ | file | 
+
+          file << execute_command( command ) 
+
+        }
 
       rescue Exception => e
 
-        MobyUtil::Logger.instance.log "behaviour" , "FAIL;Failed to capture screen.;#{id.to_s};sut;{};capture_screen;" << (arguments.kind_of?( Hash ) ? arguments.inspect : arguments.class.to_s )
+        MobyUtil::Logger.instance.log "behaviour" , "FAIL;Failed to capture screen.;#{id.to_s};sut;{};capture_screen;" << ( arguments.kind_of?( Hash ) ? arguments.inspect : arguments.class.to_s )
+
         Kernel::raise e
 
       end
@@ -457,47 +523,61 @@ module MobyBehaviour
 
     end
 
+    # == description
     # Instructs the SUT to start the specified application if it is not currenly being executed
     # The application will also be brought to the foregound.
-    # === params
-    # target:: Hash, used to indetify the application to be executed. All symbols defined in the hash
-    # must match with the launched application.
-    # The following symbols can be defined in the hash, at least one them must be included:
-    # [:uid] = String or Integer, uid of the application (268458181)
-    # [:name] = String, executable name of the application ('Mce.exe')
-    # [:arguments] = Comma separated list of arguments passed to application when starting. ('--nogui,-v')
-    # Examples:
-    #  @sut.run(:name => 'Mce.exe')
-    #  @sut.run(:name => 'Mce.exe', :uid => 268458181)
-    #  @sut.run(:name => 'demoapp.exe', :arguments => '--nogui')
-    # === returns
-    # TestObject:: Test object of the started application
-    # === raises
-    # ArgumentError:: If no Hash is provided as argument or the Hash does not contain at least a valid :uid or :name
-    # VerificationError:: If no application test object can be found after starting the application, or the found object does not match the launched application
+    #
+    # == 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' }
+    #
+    # == tables
+    # run_hash_arguments
+    #  title: Run argument hash keys
+    #  description: The following symbols can be defined in the hash, at least one them must be defined.
+    #  |Key|Type|Description|Example|
+    #  |:uid|String or Integer|Unique ID of the application|{ :uid => 268458181 }|
+    #  |:name|String|Executable name of the application|{ :name => 'calculator' }|
+    #  |:arguments|String|Comma separated list of arguments passed to application when starting|{ :arguments => '--nogui,-v' }|
+    #
+    # == returns
+    # TestObject
+    #  description: Test object of the started application
+    #  example: -
+    #
+    # == exceptions
+    # TypeError
+    #  description: Wrong argument type %s for run method (expected Hash)
+    #  
+    # ArgumentError
+    #  description: Required key :uid or :name not found from argument hash
+    #
+    # VerificationError
+    #  description: If no application test object can be found after starting the application, or the found object does not match the launched application
+    #
     def run( target )
 
       begin
+
         # set the refresh interval to zero while the application is launched
         #orig_interval = MobyUtil::Parameter[ @id ][ :refresh_interval ]
         #MobyUtil::Parameter[ @id ][ :refresh_interval ] = '0'
 
         # raise exception if argument type other than hash
-        Kernel::raise ArgumentError.new( "Wrong argument type %s) for %s (Expected: %s)" % [ target.class, "run method", "Hash" ]) unless target.instance_of?( Hash )
+        target.check_type( Hash, "Wrong argument type $1 for run method (expected $2)" )
 
-        # default value for keys that does not exist in hash
+        # default value for missing keys
         target.default = nil
 
-        Kernel::raise ArgumentError.new( "Argument hash must contain at least :uid or :name" ) unless target[ :uid ] || target[ :name ]
+        # 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" )
 
-        # nils are valid arguments here, at least one of :name, :id has been verified to not be nil
-        # ArgumentError is raised by MobyCommnand::Application if the parameters are not valid
-        sleep_time = target[ :sleep_after_launch ].to_i #( target[ :sleep_after_launch ] == nil ? 0 : target[ :sleep_after_launch ].to_i)
+        sleep_time = target[ :sleep_after_launch ].to_i
 
-        #Kernel::raise ArgumentError.new( "Sleep time need to be Integer >= 0" ) unless sleep_time.kind_of? Numeric #instance_of?( Fixnum )
         Kernel::raise ArgumentError.new( "Sleep time need to be >= 0" ) unless sleep_time >= 0
 
-
         # try to find an existing app with the current arguments
         if target[ :try_attach ]
 
@@ -506,36 +586,52 @@ module MobyBehaviour
           # 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
           # otherwhise attempt to get the application test object
+
           app_info = find_app(app_list, {:id => target[ :uid ]}) if target[ :uid ] != nil
           app_info = find_app(app_list, {:name => target[ :name ]}) unless app_info
           app = self.application(:id => app_info.id) if app_info
+
           if app
-			begin
-			  app.bring_to_foreground
-			rescue Exception => e
-			  MobyUtil::Logger.instance.log "WARNING", "Could not bring app to foreground"
-			end
-			return app
+
+            begin
+
+              app.bring_to_foreground
+
+            rescue Exception => e
+
+              MobyUtil::Logger.instance.log "WARNING", "Could not bring app to foreground"
+
+            end
+
+            return app
+
           end
+
         end
 
         if ( target[ :start_command ] != nil )
+
           Kernel::raise MobyBase::BehaviourError.new("Run", "Failed to load execute_shell_method") unless self.respond_to?("execute_shell_command")
+
           execute_shell_command( target[ :start_command ], :detached => "true" )
+
         else
-          run_command = MobyCommand::Application.new(
-													 :Run,
-													 target[ :name ],
-													 target[ :uid ],
-													 self,
-													 target[ :arguments ],
-													 target[ :environment ],
-													 target[ :events_to_listen ],
-													 target[ :signals_to_listen ]
-													 )
 
           # execute the application control service request
-          execute_command( run_command )
+          execute_command(
+
+            MobyCommand::Application.new(
+              :Run,
+              target[ :name ],
+              target[ :uid ],
+              self,
+              target[ :arguments ],
+              target[ :environment ],
+              target[ :events_to_listen ],
+              target[ :signals_to_listen ]
+            )
+
+          )
 
         end
         
@@ -545,22 +641,16 @@ module MobyBehaviour
 
         sleep sleep_time if sleep_time > 0
 
-        #TODO: Refresh should be initiated by sut_controller
-        #PKI: one refresh might not be enough as application launch takes more time sometimes
-        #PKI: added artificial wait for now until this has been refactored
-
-        expected_attributes = Hash.new
-
-        expected_attributes[ :type ] = 'application'
+        expected_attributes = { :type => 'application' }
 
         expected_attributes[ :id ] = target[ :uid ] unless target[ :uid ].nil?
+
         expected_attributes[ :FullName ] = target[ :name ] unless target[ :name ].nil?
 
         error_details = target[ :name ].nil? ? "" : "name: " << target[ :name ].to_s
-
         error_details << ( error_details.empty? ? "" : ", ") << "id: " << target[ :uid ].to_s if !target[ :uid ].nil?
 
-        if( self.ui_type.downcase.include?( 'qt' ) && !expected_attributes[ :FullName ].nil? )
+        if( !expected_attributes[ :FullName ].nil? )
 
           if( expected_attributes[ :FullName ].include?('/') )
 
@@ -589,10 +679,10 @@ module MobyBehaviour
         begin
 
           self.wait_child(
-						  expected_attributes,
-						  MobyUtil::Parameter[ @id ][ :application_synchronization_timeout, '5' ].to_f,
-						  MobyUtil::Parameter[ @id ][ :application_synchronization_retry_interval, '0.5' ].to_f
-						  )
+            expected_attributes,
+            MobyUtil::Parameter[ @id ][ :application_synchronization_timeout, '5' ].to_f,
+            MobyUtil::Parameter[ @id ][ :application_synchronization_retry_interval, '0.5' ].to_f
+          )
 
         rescue MobyBase::SyncTimeoutError
 
@@ -611,10 +701,6 @@ module MobyBehaviour
 
         Kernel::raise MobyBase::BehaviourError.new("Run", "Failed to launch application")
 
-        #MobyBase::Error.raise( :BehaviourErrorOccured, "Run", "Failed to launch application", e.message )
-        #Kernel::raise behaviour_runtime_error("Run", "Failed to launch application", e.message, e.backtrace)
-        #Kernel::raise e
-
       end
 
       MobyUtil::Logger.instance.log "behaviour" , "PASS;The application was launched successfully.;#{id.to_s};sut;{};run;" << target.inspect
@@ -648,7 +734,7 @@ module MobyBehaviour
     #  |:LongPress|Holds a key as long_press_timeout specifies in tdriver_parameters.xml. Please note also long_press_interval (Only for S60)|MobyCommand::KeySequence.new( :kApp, :LongPress )|
     #
     # == arguments
-    # symbol_or_sequence
+    # value
     #  Symbol
     #   description: one of the key symbols defined in /tdriver/keymaps/
     #   example: @sut.press_key(:kDown)
@@ -662,38 +748,29 @@ module MobyBehaviour
     #  example: -
     #
     # == exceptions
-    # ArgumentError
-    #  description: if input not a symbol or not of type MobyCommand::KeySequence
+    # TypeError
+    #  description: Wrong argument type $1 for press_key (expected $2)
     #
-    def press_key( symbol_or_sequence )
+    def press_key( value )
 
       begin
 
-        if symbol_or_sequence.instance_of?( Symbol )
-
-          sequence = MobyCommand::KeySequence.new( symbol_or_sequence )
-
-        elsif symbol_or_sequence.instance_of? MobyCommand::KeySequence
-
-          sequence = symbol_or_sequence
+        value.check_type( [ Symbol, MobyCommand::KeySequence ], "Wrong argument type $1 for press_key (expected $2)" )
 
-        else
-
-          raise ArgumentError.new('Data not of type Symbol or MobyController::KeySequence.')
-
-        end
+        sequence = value.kind_of?( Symbol ) ? MobyCommand::KeySequence.new( value ) : value
 
         sequence.set_sut( self )
+
         execute_command( sequence )
 
       rescue Exception => e
 
-        MobyUtil::Logger.instance.log "behaviour" , "FAIL;Failed to press key(s).;#{id.to_s};sut;{};press_key;#{ symbol_or_sequence }"
+        MobyUtil::Logger.instance.log "behaviour" , "FAIL;Failed to press key(s).;#{id.to_s};sut;{};press_key;#{ value }"
         Kernel::raise e
 
       end
 
-      MobyUtil::Logger.instance.log "behaviour" , "PASS;Successfully pressed key(s).;#{id.to_s};sut;{};press_key;#{ symbol_or_sequence }"
+      MobyUtil::Logger.instance.log "behaviour" , "PASS;Successfully pressed key(s).;#{id.to_s};sut;{};press_key;#{ value }"
 
       nil
 
@@ -705,29 +782,29 @@ module MobyBehaviour
     #
     # == arguments
     # *arguments
-    #	 String
+    #   String
     #   description: Optional argument which is the name of parameter.
     #   example: 'new_parameter'
     #  Symbol
     #   description: Optional argument which is the name of parameter.
-    #	  example: :product
+    #    example: :product
     #
     # == returns
     # String
-    #	 description: Value matching the parameter name given as argument
-    #	 example: 'testability-driver-qt-sut-plugin'
+    #   description: Value matching the parameter name given as argument
+    #   example: 'testability-driver-qt-sut-plugin'
     #
     # MobyUtil::ParameterHash
-    # 	description: Hash of values, if no arguments is specified
+    #   description: Hash of values, if no arguments is specified
     #   example: { :value => '1', :inner_hash => { :another_value => 100 } }
     #
     # == exceptions
     # ParameterNotFoundError
-    #	 description: If the parameter with the given name does not exist
+    #   description: If the parameter with the given name does not exist
     #
     # == example
-    # parameter_hash = @sut.parameter	 #returns the hash of all sut parameters
-    # value = @sut.parameter[:product] 	#returns the value for parameter 'product' for this particular sut
+    # parameter_hash = @sut.parameter   #returns the hash of all sut parameters
+    # value = @sut.parameter[:product]   #returns the value for parameter 'product' for this particular sut
     # value = @sut.parameter['non_existing_parameter'] #raises exception that 'non_existing_parameter' was not found
     # value = sut.parameter['non_existing_parameter', 'default'] #returns default value if given parameter is not found
     # sut.parameter[:new_parameter] ='new_value'  # set the value of parameter 'product' for this particular sut
@@ -747,185 +824,191 @@ module MobyBehaviour
 
     end
 
-	# == description
-	# Wrapper function to return translated string for this SUT to read the values from localisation database.
-	#
-	# == arguments
-	# logical_name
-	#  String
-	#   description: Logical name (LNAME) of the item to be translated. If prefix for User Information or Operator Data are used then the appropiate retrieve methods will be called
-	#   example: "txt_button_ok"
-	#  Symbol
-	#   description: Symbol form of the logical name (LNAME) of the item to be translated.
-	#   example: :txt_button_ok
-	#
-	# file_name
-	#  String
-	#   description: Optional FNAME search argument for the translation
-	#   example: "agenda"
-	#   default: nil
-	#
-	# plurality
-	#  String
-	#   description: Optional PLURALITY search argument for the translation
-	#   example: "a" or "singular"
-	#	default: nil
-	#
-	# numerus
-	#  String
-	#   description: Optional numeral replacement of '%Ln' tags on translation strings
-	#   example: "1"
-	#   default: nil
-	#  Integer
-	#   description: Optional numeral replacement of '%Ln' tags on translation strings
-	#   example: 1
-	# 
-	# lengthvariant
-	#  String
-	#   description: Optional LENGTHVAR search argument for the translation (1-9)
-	#   example: "1"
-	#   default: nil
-	#
-	# == returns
-	# String
-	#  description: Translation matching the logical_name
-	#  example: "Ok"
-	# Array
-	#  description: If multiple translations have been found for the search conditions an Array with all Strings be returned
-	#  example: ["Ok", "OK"]
-	# 
-	# == exceptions
-	# LanguageNotFoundError
-	#  description: In case language is not found
-	#
-	# LogicalNameNotFoundError
-	#  description: In case no logical name is not found for current language
-	#
-	# SqlError
-	#  description: In case there are problems with the database connectivity
-	#
-	def translate( logical_name, file_name = nil, plurality = nil, numerus = nil, lengthvariant = nil )
-	  
-	  Kernel::raise LogicalNameNotFoundError.new("Logical name is nil") if logical_name.nil?
-	  
-	  translation_type = "localisation"
-	  
-	  # Check for User Information prefix( "uif_...")
-	  MobyUtil::Parameter[ :user_data_logical_string_identifier, 'uif_' ].split('|').each do |identifier|
-		if logical_name.to_s.index(identifier)==0
-		  translation_type="user_data"
-		end
-	  end
-	  
-	  # Check for Operator Data prefix( "operator_...")
-	  MobyUtil::Parameter[ :operator_data_logical_string_identifier, 'operator_' ].split('|').each do |identifier|
-		if logical_name.to_s.index(identifier)==0
-		  translation_type="operator_data"
-		end
-	  end
-	  
-	  case translation_type
-		
-	  when "user_data"
-		get_user_information( logical_name )
-		
-	  when "operator_data"
-		get_operator_data( logical_name )
-		
-	  when "localisation"
-		language=nil
-		if ( MobyUtil::Parameter[ self.id ][:read_lang_from_app]=='true')
-		  #read localeName app
-		  language=self.application.attribute("localeName")
-		  #determine the language from the locale
-		  language=language.split('_')[0].to_s if (language!=nil && !language.empty?)
-		else
-		  language=MobyUtil::Parameter[ self.id ][ :language ]
-		end
-		Kernel::raise LanguageNotFoundError.new("Language cannot be determind to perform translation") if (language==nil || language.empty?)
-		translation = MobyUtil::Localisation.translation( logical_name, language,
-			MobyUtil::Parameter[ self.id ][ :localisation_server_database_tablename ], file_name,
-			plurality, lengthvariant )
-
-		if translation.kind_of? String and !numerus.nil?
-		  translation.gsub!(/%(Ln|1)/){|s| numerus} 
-		elsif translation.kind_of? Array and !numerus.nil?
-		  translation.each do |trans|
-			trans.gsub!(/%(Ln|1)/){|s| numerus}
-		  end
-		end
-		translation
-	  end
-	end
-	
-	# == description
-	# Wrapper function to retrieve user information for this SUT from the user information database.
-	#
-	# == arguments
-	# user_data_lname
-	#  String
-	#   description: Logical name (LNAME) of the user information item to be retrieved.
-	#   example: "uif_first_name"
-	#  Symbol
-	#   description: Symbol form of the logical name (LNAME) of the user information item to be retrieved.
-	#   example: :uif_first_name
-	#
-	# == returns
-	# String
-	#  description: User data string
-	#  example: "Ivan"
-	# Array
-	#  description: Array of Strings when multiple user data strings found.
-	#  example: ["Ivan", "Manolo"]
-	# 
-	# == exceptions
-	# UserDataNotFoundError
-	#  description: In case the desired user data is not found
-	#
-	# UserDataColumnNotFoundError
-	#  description: In case the desired data column name to be used for the output is not found
-	#
-	# SqlError
-	#  description: In case there are problems with the database connectivity
-	#
-	def get_user_information( user_data_lname )
-	  language = MobyUtil::Parameter[ self.id ][ :language ]
-	  table_name = MobyUtil::Parameter[ self.id ][ :user_data_server_database_tablename ] 
-	  MobyUtil::UserData.retrieve( user_data_lname, language, table_name )
-	end
-	
-	# == description
-	# Wrapper function to retrieve operator data for this SUT from the operator data database.
-	#
-	# == arguments
-	# operator_data_lname
-	#  String
-	#   description: Logical name (LNAME) of the operator data item to be retrieved.
-	#   example: "operator_welcome_message"
-	#  Symbol
-	#   description: Symbol form of the logical name (LNAME) of the operator data item to be retrieved.
-	#   example: :operator_welcome_message
-	#
-	# == returns
-	# String
-	#  description: User data string
-	#  example: "Welcome to Orange"
-	# 
-	# == exceptions
-	# OperatorDataNotFoundError
-	#  description: In case the desired operator data is not found
-	#
-	# OperatorDataColumnNotFoundError
-	#  description: In case the desired data column name to be used for the output is not found
-	#
-	# SqlError
-	#  description: In case there are problems with the database connectivity
-	#
-	def get_operator_data( operator_data_lname )
-	  operator = MobyUtil::Parameter[ self.id ][ :operator_selected ]
-	  table_name = MobyUtil::Parameter[ self.id ][ :operator_data_server_database_tablename]
-	  MobyUtil::OperatorData.retrieve( operator_data_lname, operator, table_name )
-	end
+  # == description
+  # Wrapper function to return translated string for this SUT to read the values from localisation database.
+  #
+  # == arguments
+  # logical_name
+  #  String
+  #   description: Logical name (LNAME) of the item to be translated. If prefix for User Information or Operator Data are used then the appropiate retrieve methods will be called
+  #   example: "txt_button_ok"
+  #  Symbol
+  #   description: Symbol form of the logical name (LNAME) of the item to be translated.
+  #   example: :txt_button_ok
+  #
+  # file_name
+  #  String
+  #   description: Optional FNAME search argument for the translation
+  #   example: "agenda"
+  #   default: nil
+  #
+  # plurality
+  #  String
+  #   description: Optional PLURALITY search argument for the translation
+  #   example: "a" or "singular"
+  #  default: nil
+  #
+  # numerus
+  #  String
+  #   description: Optional numeral replacement of an '%Ln | %1' tag on the translated string
+  #   example: "1"
+  #   default: nil
+  #  Integer
+  #   description: Optional numeral replacement of an '%Ln | %1' tag on the translated string
+  #   example: 1
+  #  Array
+  #   description: Optional numeral replacements for multiple '%L1 | %1, %L2 | %2, ...' tags on the translated string
+  #   example: [ 3, 2]
+  # 
+  # lengthvariant
+  #  String
+  #   description: Optional LENGTHVAR search argument for the translation (1-9)
+  #   example: "1"
+  #   default: nil
+  #
+  # == returns
+  # String
+  #  description: Translation matching the logical_name
+  #  example: "Ok"
+  # Array
+  #  description: If multiple translations have been found for the search conditions an Array with all Strings be returned
+  #  example: ["Ok", "OK"]
+  # 
+  # == exceptions
+  # LanguageNotFoundError
+  #  description: In case language is not found
+  #
+  # LogicalNameNotFoundError
+  #  description: In case no logical name is not found for current language
+  #
+  # SqlError
+  #  description: In case there are problems with the database connectivity
+  #
+  def translate( logical_name, file_name = nil, plurality = nil, numerus = nil, lengthvariant = nil )
+    Kernel::raise LogicalNameNotFoundError.new("Logical name is nil") if logical_name.nil?
+    translation_type = "localisation"
+    
+    # Check for User Information prefix( "uif_...")
+    MobyUtil::Parameter[ :user_data_logical_string_identifier, 'uif_' ].split('|').each do |identifier|
+      if logical_name.to_s.index(identifier)==0
+        translation_type="user_data"
+      end
+    end
+    
+    # Check for Operator Data prefix( "operator_...")
+    MobyUtil::Parameter[ :operator_data_logical_string_identifier, 'operator_' ].split('|').each do |identifier|
+      if logical_name.to_s.index(identifier)==0
+        translation_type="operator_data"
+      end
+    end
+    
+    case translation_type
+      when "user_data"
+        get_user_information( logical_name )
+    
+      when "operator_data"
+        get_operator_data( logical_name )
+    
+      when "localisation"
+        language=nil
+        if ( MobyUtil::Parameter[ self.id ][:read_lang_from_app]=='true')
+          #read localeName app
+          language=self.application.attribute("localeName")
+          #determine the language from the locale
+          language=language.split('_')[0].to_s if (language!=nil && !language.empty?)
+        else
+          language=MobyUtil::Parameter[ self.id ][ :language ]
+        end
+        Kernel::raise LanguageNotFoundError.new("Language cannot be determind to perform translation") if (language==nil || language.empty?)
+        translation = MobyUtil::Localisation.translation( logical_name, language,
+        MobyUtil::Parameter[ self.id ][ :localisation_server_database_tablename ], file_name, plurality, lengthvariant )        
+        if translation.kind_of? String and !numerus.nil?
+          if numerus.kind_of? Array
+            translation.gsub!(/%[L]?(\d)/){|s| numerus[($1.to_i) -1] }
+          elsif numerus.kind_of? String or numerus.kind_of? Integer
+            translation.gsub!(/%(Ln|1)/){|s| numerus.to_s} 
+          end
+        elsif translation.kind_of? Array and !numerus.nil?
+          translation.each do |trans|
+            if numerus.kind_of? Array
+              trans.gsub!(/%[L]?(\d)/){|s| numerus[($1.to_i) -1] }
+            elsif numerus.kind_of? String or numerus.kind_of? Integer
+              trans.gsub!(/%(Ln|1)/){|s| numerus.to_s} 
+            end
+          end
+        end
+        translation
+    end
+  end
+  
+  # == description
+  # Wrapper function to retrieve user information for this SUT from the user information database.
+  #
+  # == arguments
+  # user_data_lname
+  #  String
+  #   description: Logical name (LNAME) of the user information item to be retrieved.
+  #   example: "uif_first_name"
+  #  Symbol
+  #   description: Symbol form of the logical name (LNAME) of the user information item to be retrieved.
+  #   example: :uif_first_name
+  #
+  # == returns
+  # String
+  #  description: User data string
+  #  example: "Ivan"
+  # Array
+  #  description: Array of Strings when multiple user data strings found.
+  #  example: ["Ivan", "Manolo"]
+  # 
+  # == exceptions
+  # UserDataNotFoundError
+  #  description: In case the desired user data is not found
+  #
+  # UserDataColumnNotFoundError
+  #  description: In case the desired data column name to be used for the output is not found
+  #
+  # SqlError
+  #  description: In case there are problems with the database connectivity
+  #
+  def get_user_information( user_data_lname )
+    language = MobyUtil::Parameter[ self.id ][ :language ]
+    table_name = MobyUtil::Parameter[ self.id ][ :user_data_server_database_tablename ] 
+    MobyUtil::UserData.retrieve( user_data_lname, language, table_name )
+  end
+  
+  # == description
+  # Wrapper function to retrieve operator data for this SUT from the operator data database.
+  #
+  # == arguments
+  # operator_data_lname
+  #  String
+  #   description: Logical name (LNAME) of the operator data item to be retrieved.
+  #   example: "operator_welcome_message"
+  #  Symbol
+  #   description: Symbol form of the logical name (LNAME) of the operator data item to be retrieved.
+  #   example: :operator_welcome_message
+  #
+  # == returns
+  # String
+  #  description: User data string
+  #  example: "Welcome to Orange"
+  # 
+  # == exceptions
+  # OperatorDataNotFoundError
+  #  description: In case the desired operator data is not found
+  #
+  # OperatorDataColumnNotFoundError
+  #  description: In case the desired data column name to be used for the output is not found
+  #
+  # SqlError
+  #  description: In case there are problems with the database connectivity
+  #
+  def get_operator_data( operator_data_lname )
+    operator = MobyUtil::Parameter[ self.id ][ :operator_selected ]
+    table_name = MobyUtil::Parameter[ self.id ][ :operator_data_server_database_tablename]
+    MobyUtil::OperatorData.retrieve( operator_data_lname, operator, table_name )
+  end
 
     # == nodoc
     # Function to update all children of current SUT
@@ -940,13 +1023,12 @@ module MobyBehaviour
 
       unless @childs_updated
 
-        @_child_object_cache.each_value{ | test_object | 
+        @child_object_cache.each_object{ | test_object | 
 
           test_object.update( @xml_data ) 
 
         }
 
-
       end
 
       @childs_updated = true
@@ -1001,26 +1083,25 @@ module MobyBehaviour
 
       @verify_blocks << MobyUtil::VerifyBlock.new( block,expected, message, 0, MobyUtil::KernelHelper.find_source( caller( 3 ).first.to_s ) )
 
+      nil
+
     end
 
     # == description
     # Clears all verification blocks added to the sut through verify_always() method and
     # verify_blocks configuration parameter in the tdriver parameters file
     #
-    # == arguments
-    #
     # == returns
     # Array
-    #  description: Now empty array of verification blocks
-    #
-    # == exceptions
-    #
+    #  description: Empty array
+    #  example: []
     def clear_verify_blocks
 
       @verify_blocks = []
 
     end
 
+    # == nodoc
     def get_application_id
       
       orig_frozen = @frozen;
@@ -1047,8 +1128,9 @@ module MobyBehaviour
 
     end
 
-	private
+  private
 
+    # TODO: document me
     def fetch_references( xml )
 
       pids = []
@@ -1064,7 +1146,7 @@ module MobyBehaviour
 
         nodes.each { | element |
 
-          pid = element.xpath('//attribute[@name = "uri"]/value/text()')[ 0 ].to_s
+          pid = element.at_xpath('//attribute[@name = "uri"]/value/text()').content #[ 0 ].to_s
 
           if pid.nil? or pid.empty? or pid.to_i <= 0 # invalid reference
 
@@ -1078,7 +1160,7 @@ module MobyBehaviour
           y_abs = xml.xpath( '//object[@type = "TDriverRef"]/../../attributes/attribute[@name ="y_absolute"]/value/text()' )[ idx - 1 ]
 
           # window size
-          winSize = xml.xpath( "//objects/object[@type = 'MainWindow']/attributes/attribute[@name ='size']/value/text()" )[ 0 ].to_s
+          winSize = xml.at_xpath( "//objects/object[@type = 'MainWindow']/attributes/attribute[@name ='size']/value/text()" ).content #[ 0 ].to_s
 
           # ref-ref parent does not know x coordinate, use the grandparent xys
           x_prev = x_abs.to_s unless x_abs.nil?
@@ -1090,56 +1172,56 @@ module MobyBehaviour
 
             begin
 
-			  subdata =
-				MobyUtil::XML.parse_string( 
-										   execute_command( 
-														   MobyCommand::Application.new(
-																						:State,
-																						nil,
-																						pid,
-																						self,
-																						nil,
-																						nil,
-																						nil,
-																						nil,
-																						{
-																						  'x_parent_absolute' => x_prev,
-																						  'y_parent_absolute' => y_prev,
-																						  'embedded' => 'true',
-																						  'parent_size' => winSize
-																						}
-																						)
-														   )[ 0 ]
-										   )
-
-			  child = subdata.root.xpath('//object')[0]
-
-			  # Remove the attribute with the pid retrieval was not successful.
-			  # (server returns the previous hit if not found)
-			  if child.attribute('id' ) != pid
-				
-				element.remove
+        subdata =
+        MobyUtil::XML.parse_string( 
+                       execute_command( 
+                               MobyCommand::Application.new(
+                                            :State,
+                                            nil,
+                                            pid,
+                                            self,
+                                            nil,
+                                            nil,
+                                            nil,
+                                            nil,
+                                            {
+                                              'x_parent_absolute' => x_prev,
+                                              'y_parent_absolute' => y_prev,
+                                              'embedded' => 'true',
+                                              'parent_size' => winSize
+                                            }
+                                            )
+                               )[ 0 ]
+                       )
+
+        child = subdata.root.xpath('//object')[0]
+
+        # Remove the attribute with the pid retrieval was not successful.
+        # (server returns the previous hit if not found)
+        if child.attribute('id' ) != pid
+        
+        element.remove
 
-			  else
+        else
 
-				# Remove the application layer
-				objs = child.xpath( '/tasMessage/tasInfo/object/objects/*' )
+        # Remove the application layer
+        objs = child.xpath( '/tasMessage/tasInfo/object/objects/*' )
 
-				if !objs.nil?
+        if !objs.nil?
 
-				  objs.each { | el | element.add_previous_sibling( el ) }
+          objs.each { | el | element.add_previous_sibling( el ) }
 
-				  element.remove
+          element.remove
 
-				end
+        end
 
-			  end
+        end
 
             rescue RuntimeError => e
 
-			  raise e unless e.message.include? "no longer available"
+        raise e unless e.message.include? "no longer available"
 
-			  return xml
+        return xml
 
             end
 
@@ -1193,11 +1275,10 @@ module MobyBehaviour
 
       @frozen = false
 
-      @_child_object_cache = {}
+      @child_object_cache = TDriver::TestObjectCache.new
 
       @current_application_id = nil
 
-
       @dump_count = 0
 
       # default values
@@ -1218,9 +1299,9 @@ module MobyBehaviour
         @refresh_interval = MobyUtil::Parameter[ @id ][ :refresh_interval, @refresh_interval ].to_f
 
       end
-	  
+    
       @last_xml_data = nil
-	  
+    
       ruby_file = MobyUtil::Parameter[ @id ][ :verify_blocks ] 
 
       @verify_blocks = []
@@ -1240,7 +1321,7 @@ module MobyBehaviour
 
     end
 
-	public # deprecated
+  public # deprecated
 
     
     # == nodoc
@@ -1253,7 +1334,7 @@ module MobyBehaviour
     # == raises
     # someException:: If Dump does not conform to the tasMessage schema error is raised
     def get_ui_dump( refresh_args = {} )
-	  
+    
       #$stderr.puts "warning: SUT#get_ui_dump is deprecated, please use SUT#refresh_ui_dump instead."
 
       refresh_ui_dump refresh_args, {}