src/third_party/android_testrunner/adb_interface.py

   1 #!/usr/bin/python2.4
   2 #
   3 #
   4 # Copyright 2008, The Android Open Source Project
   5 #
   6 # Licensed under the Apache License, Version 2.0 (the "License");
   7 # you may not use this file except in compliance with the License.
   8 # You may obtain a copy of the License at
   9 #
  10 #     http://www.apache.org/licenses/LICENSE-2.0
  11 #
  12 # Unless required by applicable law or agreed to in writing, software
  13 # distributed under the License is distributed on an "AS IS" BASIS,
  14 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15 # See the License for the specific language governing permissions and
  16 # limitations under the License.
  17
  18 """Provides an interface to communicate with the device via the adb command.
  19
  20 Assumes adb binary is currently on system path.
  21 """
  22 # Python imports
  23 import os
  24 import string
  25 import time
  26
  27 # local imports
  28 import am_instrument_parser
  29 import errors
  30 import logger
  31 import run_command
  32
  33
  34 class AdbInterface:
  35   """Helper class for communicating with Android device via adb."""
  36
  37   # argument to pass to adb, to direct command to specific device
  38   _target_arg = ""
  39
  40   DEVICE_TRACE_DIR = "/data/test_results/"
  41
  42   def SetEmulatorTarget(self):
  43     """Direct all future commands to the only running emulator."""
  44     self._target_arg = "-e"
  45
  46   def SetDeviceTarget(self):
  47     """Direct all future commands to the only connected USB device."""
  48     self._target_arg = "-d"
  49
  50   def SetTargetSerial(self, serial):
  51     """Direct all future commands to Android target with the given serial."""
  52     self._target_arg = "-s %s" % serial
  53
  54   def SendCommand(self, command_string, timeout_time=20, retry_count=3):
  55     """Send a command via adb.
  56
  57     Args:
  58       command_string: adb command to run
  59       timeout_time: number of seconds to wait for command to respond before
  60         retrying
  61       retry_count: number of times to retry command before raising
  62         WaitForResponseTimedOutError
  63     Returns:
  64       string output of command
  65
  66     Raises:
  67       WaitForResponseTimedOutError if device does not respond to command within time
  68     """
  69     adb_cmd = "adb %s %s" % (self._target_arg, command_string)
  70     logger.SilentLog("about to run %s" % adb_cmd)
  71     return run_command.RunCommand(adb_cmd, timeout_time=timeout_time,
  72                                   retry_count=retry_count)
  73
  74   def SendShellCommand(self, cmd, timeout_time=20, retry_count=3):
  75     """Send a adb shell command.
  76
  77     Args:
  78       cmd: adb shell command to run
  79       timeout_time: number of seconds to wait for command to respond before
  80         retrying
  81       retry_count: number of times to retry command before raising
  82         WaitForResponseTimedOutError
  83
  84     Returns:
  85       string output of command
  86
  87     Raises:
  88       WaitForResponseTimedOutError: if device does not respond to command
  89     """
  90     return self.SendCommand("shell %s" % cmd, timeout_time=timeout_time,
  91                             retry_count=retry_count)
  92
  93   def BugReport(self, path):
  94     """Dumps adb bugreport to the file specified by the path.
  95
  96     Args:
  97       path: Path of the file where adb bugreport is dumped to.
  98     """
  99     bug_output = self.SendShellCommand("bugreport", timeout_time=60)
 100     bugreport_file = open(path, "w")
 101     bugreport_file.write(bug_output)
 102     bugreport_file.close()
 103
 104   def Push(self, src, dest):
 105     """Pushes the file src onto the device at dest.
 106
 107     Args:
 108       src: file path of host file to push
 109       dest: destination absolute file path on device
 110     """
 111     self.SendCommand("push %s %s" % (src, dest), timeout_time=60)
 112
 113   def Pull(self, src, dest):
 114     """Pulls the file src on the device onto dest on the host.
 115
 116     Args:
 117       src: absolute file path of file on device to pull
 118       dest: destination file path on host
 119
 120     Returns:
 121       True if success and False otherwise.
 122     """
 123     # Create the base dir if it doesn't exist already
 124     if not os.path.exists(os.path.dirname(dest)):
 125       os.makedirs(os.path.dirname(dest))
 126
 127     if self.DoesFileExist(src):
 128       self.SendCommand("pull %s %s" % (src, dest), timeout_time=60)
 129       return True
 130     else:
 131       logger.Log("ADB Pull Failed: Source file %s does not exist." % src)
 132       return False
 133
 134   def DoesFileExist(self, src):
 135     """Checks if the given path exists on device target.
 136
 137     Args:
 138       src: file path to be checked.
 139
 140     Returns:
 141       True if file exists
 142     """
 143
 144     output = self.SendShellCommand("ls %s" % src)
 145     error = "No such file or directory"
 146
 147     if error in output:
 148       return False
 149     return True
 150
 151   def EnableAdbRoot(self):
 152     """Enable adb root on device."""
 153     output = self.SendCommand("root")
 154     if "adbd is already running as root" in output:
 155       return True
 156     elif "restarting adbd as root" in output:
 157       # device will disappear from adb, wait for it to come back
 158       self.SendCommand("wait-for-device")
 159       return True
 160     else:
 161       logger.Log("Unrecognized output from adb root: %s" % output)
 162       return False
 163
 164   def StartInstrumentationForPackage(
 165       self, package_name, runner_name, timeout_time=60*10,
 166       no_window_animation=False, instrumentation_args={}):
 167     """Run instrumentation test for given package and runner.
 168
 169     Equivalent to StartInstrumentation, except instrumentation path is
 170     separated into its package and runner components.
 171     """
 172     instrumentation_path = "%s/%s" % (package_name, runner_name)
 173     return self.StartInstrumentation(instrumentation_path, timeout_time=timeout_time,
 174                                      no_window_animation=no_window_animation,
 175                                      instrumentation_args=instrumentation_args)
 176
 177   def StartInstrumentation(
 178       self, instrumentation_path, timeout_time=60*10, no_window_animation=False,
 179       profile=False, instrumentation_args={}, silent_log=False):
 180
 181     """Runs an instrumentation class on the target.
 182
 183     Returns a dictionary containing the key value pairs from the
 184     instrumentations result bundle and a list of TestResults. Also handles the
 185     interpreting of error output from the device and raises the necessary
 186     exceptions.
 187
 188     Args:
 189       instrumentation_path: string. It should be the fully classified package
 190       name, and instrumentation test runner, separated by "/"
 191         e.g. com.android.globaltimelaunch/.GlobalTimeLaunch
 192       timeout_time: Timeout value for the am command.
 193       no_window_animation: boolean, Whether you want window animations enabled
 194         or disabled
 195       profile: If True, profiling will be turned on for the instrumentation.
 196       instrumentation_args: Dictionary of key value bundle arguments to pass to
 197       instrumentation.
 198       silent_log: If True, the invocation of the instrumentation test runner
 199         will not be logged.
 200
 201     Returns:
 202       (test_results, inst_finished_bundle)
 203
 204       test_results: a list of TestResults
 205       inst_finished_bundle (dict): Key/value pairs contained in the bundle that
 206         is passed into ActivityManager.finishInstrumentation(). Included in this
 207         bundle is the return code of the Instrumentation process, any error
 208         codes reported by the activity manager, and any results explicitly added
 209         by the instrumentation code.
 210
 211      Raises:
 212        WaitForResponseTimedOutError: if timeout occurred while waiting for
 213          response to adb instrument command
 214        DeviceUnresponsiveError: if device system process is not responding
 215        InstrumentationError: if instrumentation failed to run
 216     """
 217
 218     command_string = self._BuildInstrumentationCommandPath(
 219         instrumentation_path, no_window_animation=no_window_animation,
 220         profile=profile, raw_mode=True,
 221         instrumentation_args=instrumentation_args)
 222     if silent_log:
 223       logger.SilentLog(command_string)
 224     else:
 225       logger.Log(command_string)
 226     (test_results, inst_finished_bundle) = (
 227         am_instrument_parser.ParseAmInstrumentOutput(
 228             self.SendShellCommand(command_string, timeout_time=timeout_time,
 229                                   retry_count=2)))
 230     if "code" not in inst_finished_bundle:
 231       logger.Log('No code available. inst_finished_bundle contains: %s '
 232                  % inst_finished_bundle)
 233       raise errors.InstrumentationError("no test results... device setup "
 234                                         "correctly?")
 235
 236     if inst_finished_bundle["code"] == "0":
 237       long_msg_result = "no error message"
 238       if "longMsg" in inst_finished_bundle:
 239         long_msg_result = inst_finished_bundle["longMsg"]
 240         logger.Log("Error! Test run failed: %s" % long_msg_result)
 241       raise errors.InstrumentationError(long_msg_result)
 242
 243     if "INSTRUMENTATION_ABORTED" in inst_finished_bundle:
 244       logger.Log("INSTRUMENTATION ABORTED!")
 245       raise errors.DeviceUnresponsiveError
 246
 247     return (test_results, inst_finished_bundle)
 248
 249   def StartInstrumentationNoResults(
 250       self, package_name, runner_name, no_window_animation=False,
 251       raw_mode=False, instrumentation_args={}):
 252     """Runs instrumentation and dumps output to stdout.
 253
 254     Equivalent to StartInstrumentation, but will dump instrumentation
 255     'normal' output to stdout, instead of parsing return results. Command will
 256     never timeout.
 257     """
 258     adb_command_string = self.PreviewInstrumentationCommand(
 259         package_name, runner_name, no_window_animation=no_window_animation,
 260         raw_mode=raw_mode, instrumentation_args=instrumentation_args)
 261     logger.Log(adb_command_string)
 262     run_command.RunCommand(adb_command_string, return_output=False)
 263
 264   def PreviewInstrumentationCommand(
 265       self, package_name, runner_name, no_window_animation=False,
 266       raw_mode=False, instrumentation_args={}):
 267     """Returns a string of adb command that will be executed."""
 268     inst_command_string = self._BuildInstrumentationCommand(
 269         package_name, runner_name, no_window_animation=no_window_animation,
 270         raw_mode=raw_mode, instrumentation_args=instrumentation_args)
 271     command_string = "adb %s shell %s" % (self._target_arg, inst_command_string)
 272     return command_string
 273
 274   def _BuildInstrumentationCommand(
 275       self, package, runner_name, no_window_animation=False, profile=False,
 276       raw_mode=True, instrumentation_args={}):
 277     instrumentation_path = "%s/%s" % (package, runner_name)
 278
 279     return self._BuildInstrumentationCommandPath(
 280         instrumentation_path, no_window_animation=no_window_animation,
 281         profile=profile, raw_mode=raw_mode,
 282         instrumentation_args=instrumentation_args)
 283
 284   def _BuildInstrumentationCommandPath(
 285       self, instrumentation_path, no_window_animation=False, profile=False,
 286       raw_mode=True, instrumentation_args={}):
 287     command_string = "am instrument"
 288     if no_window_animation:
 289       command_string += " --no_window_animation"
 290     if profile:
 291       self._CreateTraceDir()
 292       command_string += (
 293           " -p %s/%s.dmtrace" %
 294           (self.DEVICE_TRACE_DIR, instrumentation_path.split(".")[-1]))
 295
 296     for key, value in instrumentation_args.items():
 297       command_string += " -e %s '%s'" % (key, value)
 298     if raw_mode:
 299       command_string += " -r"
 300     command_string += " -w %s" % instrumentation_path
 301     return command_string
 302
 303   def _CreateTraceDir(self):
 304     ls_response = self.SendShellCommand("ls /data/trace")
 305     if ls_response.strip("#").strip(string.whitespace) != "":
 306       self.SendShellCommand("create /data/trace", "mkdir /data/trace")
 307       self.SendShellCommand("make /data/trace world writeable",
 308                             "chmod 777 /data/trace")
 309
 310   def WaitForDevicePm(self, wait_time=120):
 311     """Waits for targeted device's package manager to be up.
 312
 313     Args:
 314       wait_time: time in seconds to wait
 315
 316     Raises:
 317       WaitForResponseTimedOutError if wait_time elapses and pm still does not
 318       respond.
 319     """
 320     logger.Log("Waiting for device package manager...")
 321     self.SendCommand("wait-for-device")
 322     # Now the device is there, but may not be running.
 323     # Query the package manager with a basic command
 324     try:
 325       self._WaitForShellCommandContents("pm path android", "package:",
 326                                         wait_time)
 327     except errors.WaitForResponseTimedOutError:
 328       raise errors.WaitForResponseTimedOutError(
 329           "Package manager did not respond after %s seconds" % wait_time)
 330
 331   def WaitForInstrumentation(self, package_name, runner_name, wait_time=120):
 332     """Waits for given instrumentation to be present on device
 333
 334     Args:
 335       wait_time: time in seconds to wait
 336
 337     Raises:
 338       WaitForResponseTimedOutError if wait_time elapses and instrumentation
 339       still not present.
 340     """
 341     instrumentation_path = "%s/%s" % (package_name, runner_name)
 342     logger.Log("Waiting for instrumentation to be present")
 343     # Query the package manager
 344     try:
 345       command = "pm list instrumentation | grep %s" % instrumentation_path
 346       self._WaitForShellCommandContents(command, "instrumentation:", wait_time,
 347                                         raise_abort=False)
 348     except errors.WaitForResponseTimedOutError :
 349       logger.Log(
 350           "Could not find instrumentation %s on device. Does the "
 351           "instrumentation in test's AndroidManifest.xml match definition"
 352           "in test_defs.xml?" % instrumentation_path)
 353       raise
 354
 355   def WaitForProcess(self, name, wait_time=120):
 356     """Wait until a process is running on the device.
 357
 358     Args:
 359       name: the process name as it appears in `ps`
 360       wait_time: time in seconds to wait
 361
 362     Raises:
 363       WaitForResponseTimedOutError if wait_time elapses and the process is
 364           still not running
 365     """
 366     logger.Log("Waiting for process %s" % name)
 367     self.SendCommand("wait-for-device")
 368     self._WaitForShellCommandContents("ps", name, wait_time)
 369
 370   def WaitForProcessEnd(self, name, wait_time=120):
 371     """Wait until a process is no longer running on the device.
 372
 373     Args:
 374       name: the process name as it appears in `ps`
 375       wait_time: time in seconds to wait
 376
 377     Raises:
 378       WaitForResponseTimedOutError if wait_time elapses and the process is
 379           still running
 380     """
 381     logger.Log("Waiting for process %s to end" % name)
 382     self._WaitForShellCommandContents("ps", name, wait_time, invert=True)
 383
 384   def _WaitForShellCommandContents(self, command, expected, wait_time,
 385                                    raise_abort=True, invert=False):
 386     """Wait until the response to a command contains a given output.
 387
 388     Assumes that a only successful execution of "adb shell <command>" contains
 389     the substring expected. Assumes that a device is present.
 390
 391     Args:
 392       command: adb shell command to execute
 393       expected: the string that should appear to consider the
 394           command successful.
 395       wait_time: time in seconds to wait
 396       raise_abort: if False, retry when executing the command raises an
 397           AbortError, rather than failing.
 398       invert: if True, wait until the command output no longer contains the
 399           expected contents.
 400
 401     Raises:
 402       WaitForResponseTimedOutError: If wait_time elapses and the command has not
 403           returned an output containing expected yet.
 404     """
 405     # Query the device with the command
 406     success = False
 407     attempts = 0
 408     wait_period = 5
 409     while not success and (attempts*wait_period) < wait_time:
 410       # assume the command will always contain expected in the success case
 411       try:
 412         output = self.SendShellCommand(command, retry_count=1)
 413         if ((not invert and expected in output)
 414             or (invert and expected not in output)):
 415           success = True
 416       except errors.AbortError, e:
 417         if raise_abort:
 418           raise
 419         # ignore otherwise
 420
 421       if not success:
 422         time.sleep(wait_period)
 423         attempts += 1
 424
 425     if not success:
 426       raise errors.WaitForResponseTimedOutError()
 427
 428   def WaitForBootComplete(self, wait_time=120):
 429     """Waits for targeted device's bootcomplete flag to be set.
 430
 431     Args:
 432       wait_time: time in seconds to wait
 433
 434     Raises:
 435       WaitForResponseTimedOutError if wait_time elapses and pm still does not
 436       respond.
 437     """
 438     logger.Log("Waiting for boot complete...")
 439     self.SendCommand("wait-for-device")
 440     # Now the device is there, but may not be running.
 441     # Query the package manager with a basic command
 442     boot_complete = False
 443     attempts = 0
 444     wait_period = 5
 445     while not boot_complete and (attempts*wait_period) < wait_time:
 446       output = self.SendShellCommand("getprop dev.bootcomplete", retry_count=1)
 447       output = output.strip()
 448       if output == "1":
 449         boot_complete = True
 450       else:
 451         time.sleep(wait_period)
 452         attempts += 1
 453     if not boot_complete:
 454       raise errors.WaitForResponseTimedOutError(
 455           "dev.bootcomplete flag was not set after %s seconds" % wait_time)
 456
 457   def Sync(self, retry_count=3, runtime_restart=False):
 458     """Perform a adb sync.
 459
 460     Blocks until device package manager is responding.
 461
 462     Args:
 463       retry_count: number of times to retry sync before failing
 464       runtime_restart: stop runtime during sync and restart afterwards, useful
 465         for syncing system libraries (core, framework etc)
 466
 467     Raises:
 468       WaitForResponseTimedOutError if package manager does not respond
 469       AbortError if unrecoverable error occurred
 470     """
 471     output = ""
 472     error = None
 473     if runtime_restart:
 474       self.SendShellCommand("setprop ro.monkey 1", retry_count=retry_count)
 475       # manual rest bootcomplete flag
 476       self.SendShellCommand("setprop dev.bootcomplete 0",
 477                             retry_count=retry_count)
 478       self.SendShellCommand("stop", retry_count=retry_count)
 479
 480     try:
 481       output = self.SendCommand("sync", retry_count=retry_count)
 482     except errors.AbortError, e:
 483       error = e
 484       output = e.msg
 485     if "Read-only file system" in output:
 486       logger.SilentLog(output)
 487       logger.Log("Remounting read-only filesystem")
 488       self.SendCommand("remount")
 489       output = self.SendCommand("sync", retry_count=retry_count)
 490     elif "No space left on device" in output:
 491       logger.SilentLog(output)
 492       logger.Log("Restarting device runtime")
 493       self.SendShellCommand("stop", retry_count=retry_count)
 494       output = self.SendCommand("sync", retry_count=retry_count)
 495       self.SendShellCommand("start", retry_count=retry_count)
 496     elif error is not None:
 497       # exception occurred that cannot be recovered from
 498       raise error
 499     logger.SilentLog(output)
 500     if runtime_restart:
 501       # start runtime and wait till boot complete flag is set
 502       self.SendShellCommand("start", retry_count=retry_count)
 503       self.WaitForBootComplete()
 504       # press the MENU key, this will disable key guard if runtime is started
 505       # with ro.monkey set to 1
 506       self.SendShellCommand("input keyevent 82", retry_count=retry_count)
 507     else:
 508       self.WaitForDevicePm()
 509     return output
 510
 511   def GetSerialNumber(self):
 512     """Returns the serial number of the targeted device."""
 513     return self.SendCommand("get-serialno").strip()