Module: MobyBehaviour::Application

Includes:
Behaviour
Defined in:
lib/tdriver/base/sut/generic/behaviours/application.rb

Overview

description

Describes the behaviour of application and its associated methods

behaviour

GenericApplication

requires

*

input_type

*

sut_type

*

sut_version

*

objects

application

Instance Method Summary collapse

Instance Method Details

#bring_to_foreground ⇒ Object

description

Bring the application to foreground.n n

b]NOTE:[/b

Currently this works only for Symbian OS target!

returns

NilClass

description: -
example: -



362
363
364
365
366
367
368
369
370
371
372
373
374
 
# File 'lib/tdriver/base/sut/generic/behaviours/application.rb', line 362

def bring_to_foreground

  @sut.execute_command(
    MobyCommand::Application.new(
      :BringToForeground, 
      { 
        :application_uid => @id, 
        :sut => @sut
       }
     )
   )

end

#closable? ⇒ Boolean

nodoc

TODO: to be removed?

description

Indicates whether this application can be closed with the ApplicationBehaviour::close method. Note: at the moment it always returns true!

returns

Boolean

True if closing is possible with the ApplicationBehaviour::close method

example

puts @sut.application.closable #prints foreground application closable status to console (at the moment always true)

Returns:

  • (Boolean) 


345
346
347
348
349
 
# File 'lib/tdriver/base/sut/generic/behaviours/application.rb', line 345

def closable?

  true

end

#close(options_hash = {}) ⇒ Object

description

Closes application and optionally verifies that it is closed. A Hash argument can be used to set any of the optional parameters. Keys not set in the hash will use default values. Close can be set to force kill the application process if close fails. It can also be set to not check if the application process is terminated, in which case close is considered to be successful if the application is no longer in the foreground.n n

b]NOTE:[/b

this will currently always try to close applications, also privilegied applications. n

n

b]For backwards compatibility:[/b

Instead of using a Hash as argument, the value can also be true, false or nil which will be taken as the value of :force_kill

arguments

options_hash

Hash
 description: See supported hash keys from [link="#close_hash_keys"]close application options hash keys table[/link] 
 example: {:force_kill => true, :check_process => false}
TrueClass
 description: For backwards compatibility: same as :force_kill => true   
 example: true
FalseClass
 description: For backwards compatibility: same as :force_kill => false 
 example: false
NilClass
 description: For backwards compatibility: same as :force_kill => nil (uses 'application_close_kill' from TDriver parameters file)
 example: nil

tables

close_hash_keys

title: Close application options hash keys
|Key|Type|Description|Default|Required|
|:force_kill|TrueClass, FalseClass|If this options is set to true, the application process is killed if close fails. Setting this option to nil (default value), will cause close to use the value defined in the 'application_close_kill' parameter as defined in the TDriver parameter file.|nil|No|
|:check_process|TrueClass, FalseClass|If this options is set to true, success of the close method is verified by checking if the process is still active. If it is set to false, TDriver will only check that the application is no longer in the foreground.|true|No|

returns

NilClass

description: -
example: -

exceptions

TestObjectNotFoundError

description: If this application is not the foreground application on the device under test.

VerificationError

description: If no application test object is found after close or if this application is still in the foreground after the close.

TypeError

description: Wrong argument type <class> for options_hash (expected a Hash, TrueClass or FalseClass)

TypeError

description: Wrong argument type <class> for :force_kill (expected NilClass, TrueClass or FalseClass)

TypeError

description: Wrong argument type <class> for :check_process (expected TrueClass or FalseClass)



97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
 
# File 'lib/tdriver/base/sut/generic/behaviours/application.rb', line 97

def close( options_hash = {} )

  begin
    
    # check if closable
    raise RuntimeError, 'The application is of a type that cannot be closed.' unless closable?
    
    # default options
    default_options = { :force_kill => nil, :check_process => true }
    
    # for backwards compatibility
    if options_hash.kind_of?( Hash )

      # merge user defined options with default options 
      close_options = default_options.merge( options_hash )

    else

      # support legacy option of defining only force_kill as argument
      close_options = default_options

      # if options defined
      if options_hash != nil

        # workaround/backwards compatibility: allow string as hash key value 
        options_hash = options_hash.to_boolean if options_hash.kind_of?( String )

        # verify options_hash value
        options_hash.check_type( [ FalseClass, TrueClass ], "Wrong argument type $1 for options hash (expected $2)" )

        # store force_kill value
        close_options[ :force_kill ] = options_hash

      end

    end

    # workaround/backwards compatibility: allow string as hash key value 
    close_options[ :force_kill ] = close_options[ :force_kill ].to_boolean if close_options[ :force_kill ].kind_of?( String )
    
    # verify :force_kill value type
    close_options[ :force_kill ].check_type( [ NilClass, TrueClass, FalseClass ], 'Wrong argument type $1 for :force_kill (expected $2)' )

    # workaround/backwards compatibility: allow string as hash key value 
    close_options[ :check_process ] = close_options[ :check_process ].to_boolean if close_options[ :check_process ].kind_of?( String )

    # verify :check_process value type
    close_options[ :check_process ].check_type( [ TrueClass, FalseClass ], 'Wrong argument type $1 for :check_process (expected $2)' )
    
    if close_options[ :force_kill ] != nil

      @sut.execute_command( 
        MobyCommand::Application.new( 
          :Close,     
          {
            :application_name => @name,
            :application_uid => @id,  
            :sut => @sut,              
            :flags => { :force_kill => close_options[ :force_kill ] }
          } 
        )
      )

    else   

      @sut.execute_command( 
        MobyCommand::Application.new( 
          :Close, 
          { 
            :application_name => @name, 
            :application_uid => @id, 
            :sut => @sut
          }
        ) 
      )

    end

    # store start time
    start_time = Time.now

    # store original logger state
    original_logger_state = $logger.enabled

    # disable logging
    $logger.enabled = false

    # retrieve application synchronization timeout value
    timeout_time = sut_parameters[ :application_synchronization_timeout, '60' ].to_f

    # retrieve application synchronization timeout retry interval value
    refresh_interval = sut_parameters[ :application_synchronization_retry_interval, '0.25' ].to_f

    # create application identification hash
    application_identification_hash = { :type => 'application', :id => @id }

    begin

      # verify close results
      MobyUtil::Retryable.until(
        :timeout => timeout_time,
        :interval => refresh_interval,
        :exception => MobyBase::VerificationError,
        :unless => [ MobyBase::TestObjectNotFoundError, MobyBase::ApplicationNotAvailableError ] 
      ){

        # raises MobyBase::ApplicationNotAvailableError if application was not found 
        @sut.refresh( application_identification_hash, [ {:className => 'application', :tasId => @id } ] )

        # retrieve application object from sut.xml_data
        matches, unused_rule = @test_object_adapter.get_objects( @sut.xml_data, application_identification_hash, true )

        # check if the application is still found or not
        if ( close_options[ :check_process ] == true ) 

          # the application did not close
          raise MobyBase::VerificationError, "Verification of close failed. The application that was to be closed is still running." if matches.count > 0 && (Time.now - start_time) >= timeout_time

        elsif ( close_options[ :check_process ] == false )

          if matches.count > 0 
          
            if @test_object_adapter.test_object_element_attribute( matches.first, 'id' ) == @id 

              # the application was still in the foreground
              raise MobyBase::VerificationError, "Verification of close failed. The application that was to be closed was still in the foreground."

            else

              # The foreground application was not the one being closed.
              raise MobyBase::TestObjectNotFoundError, "The foreground application was not the one being closed (id: #{ @id })."

            end 

          end

        end

        # The application could not be found, break
        break

      } # MobyUtil::Retryable.until
      
    rescue MobyBase::TestObjectNotFoundError

      # everything ok: application not running anymore

		rescue MobyBase::ApplicationNotAvailableError

      # everything ok: application not running anymore

    rescue RuntimeError
    
      # something unexpected happened during the close, let exception through
      raise unless $!.message =~ /The application with Id \d+ is no longer available/

    ensure

      # restore original state
      $logger.enabled = original_logger_state

    end

  rescue Exception

    $logger.behaviour "FAIL;Failed when closing.;#{ identity };close;"

    # let exception through
    raise

  end

  $logger.behaviour "PASS;Closed successfully.;#{ identity };close;"

  #@sut.application
        
  nil

end

#environment ⇒ Object

nodoc

TODO: document all the possible values and then make public



330
331
332
333
334
 
# File 'lib/tdriver/base/sut/generic/behaviours/application.rb', line 330

def environment

  @environment
  
end

#executable_name ⇒ Object

description

Returns executable name (exe) of foreground application

returns

String

description: Application's executable name
example: "calculator"

exceptions

RuntimeError

description: No executable name has been defined for this application.

example

puts @sut.application.executable_name #prints foreground executable name to console



288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
 
# File 'lib/tdriver/base/sut/generic/behaviours/application.rb', line 288

def executable_name

  begin

    name = attribute('FullName')

  rescue MobyBase::AttributeNotFoundError

    begin

      name = attribute('exepath')

    rescue MobyBase::AttributeNotFoundError

      name = ''

    end

  end

  name.not_empty 'Application does not have "FullName" or "exepath" attribute', RuntimeError

  File.basename( name.gsub( /\\/, '/' ) )

end

#kill ⇒ Object

description

Kills the application process

returns

NilClass

description: -
example: -



384
385
386
387
388
389
390
391
392
393
394
395
396
397
 
# File 'lib/tdriver/base/sut/generic/behaviours/application.rb', line 384

def kill

  @sut.execute_command( 
    MobyCommand::Application.new( 
      :Kill, 
      {
        :application_name => executable_name, 
        :application_uid => @id, 
        :sut => @sut 
       }
     ) 
   )

end

#mem_usage ⇒ Object

description

Returns the mem usage of the application if the information is available. Will return -1 if the information is not available.

returns

Integer

description: Current memory usage
example: 124354



408
409
410
411
412
413
414
415
416
417
418
419
420
 
# File 'lib/tdriver/base/sut/generic/behaviours/application.rb', line 408

def mem_usage

  begin

	  attribute('memUsage').to_i

  rescue

     -1
     
  end

end

#uid ⇒ Object

description

Returns uid of foreground application

returns

String

description: Unique ID of the application.
example: "2197"

example

puts @sut.application.uid #prints foreground executable uid to console



322
323
324
325
326
 
# File 'lib/tdriver/base/sut/generic/behaviours/application.rb', line 322

def uid

  @id

end