diff options
Diffstat (limited to 'catapult/devil/docs/device_utils.md')
| -rw-r--r-- | catapult/devil/docs/device_utils.md | 1183 |
1 files changed, 743 insertions, 440 deletions
diff --git a/catapult/devil/docs/device_utils.md b/catapult/devil/docs/device_utils.md index a6e89a70..960ca894 100644 --- a/catapult/devil/docs/device_utils.md +++ b/catapult/devil/docs/device_utils.md @@ -1,133 +1,297 @@ # [devil.android.device_utils](https://github.com/catapult-project/catapult/blob/master/devil/devil/android/device_utils.py) -*This page was autogenerated by `devil/utils/markdown.py --module-link https://github.com/catapult-project/catapult/blob/master/devil/devil/android/device_utils.py`* +*This page was autogenerated. Run `devil/bin/generate_md_docs` to update* ## DeviceUtils -### DeviceUtils.\_\_init\_\_ +### DeviceUtils.BroadcastIntent -DeviceUtils constructor. +Send a broadcast intent. ``` Args: - device: Either a device serial, an existing AdbWrapper instance, or an - an existing AndroidCommands instance. - enable_device_files_cache: For PushChangedFiles(), cache checksums of - pushed files rather than recomputing them on a subsequent call. - default_timeout: An integer containing the default number of seconds to - wait for an operation to complete if no explicit value is provided. - default_retries: An integer containing the default number or times an - operation should be retried on failure if no explicit value is provided. + intent: An Intent to broadcast. + timeout: timeout in seconds + retries: number of retries + + Raises: + CommandTimeoutError on timeout. + DeviceUnreachableError on missing device. ``` -### DeviceUtils.\_\_eq\_\_ +### DeviceUtils.ChangeOwner -Checks whether |other| refers to the same device as |self|. +Changes file system ownership for permissions. ``` Args: - other: The object to compare to. This can be a basestring, an instance - of adb_wrapper.AdbWrapper, or an instance of DeviceUtils. - Returns: - Whether |other| refers to the same device as |self|. + owner_group: New owner and group to assign. Note that this should be a + string in the form user[.group] where the group is option. + paths: Paths to change ownership of. + + Note that the -R recursive option is not supported by all Android + versions. ``` -### DeviceUtils.\_\_lt\_\_ +### DeviceUtils.ChangeSecurityContext -Compares two instances of DeviceUtils. +Changes the SELinux security context for files. ``` - This merely compares their serial numbers. + Args: + security_context: The new security context as a string + paths: Paths to change the security context of. + + Note that the -R recursive option is not supported by all Android + versions. +``` + +### DeviceUtils.ClearApplicationState + +Clear all state for the given package. +``` Args: - other: The instance of DeviceUtils to compare to. + package: A string containing the name of the package to stop. + permissions: List of permissions to set after clearing data. + timeout: timeout in seconds + retries: number of retries + + Raises: + CommandTimeoutError on timeout. + DeviceUnreachableError on missing device. +``` + + +### DeviceUtils.ClearCache + +Clears all caches. +### DeviceUtils.DismissCrashDialogIfNeeded + +Dismiss the error/ANR dialog if present. +``` + Returns: Name of the crashed package if a dialog is focused, + None otherwise. +``` + + +### DeviceUtils.DumpCacheData + +Dumps the current cache state to a string. +``` + Args: + timeout: timeout in seconds + retries: number of retries + Returns: - Whether |self| is less than |other|. + A serialized cache as a string. ``` -### DeviceUtils.\_\_str\_\_ +### DeviceUtils.EnableRoot -Returns the device serial. -### DeviceUtils.NeedsSU +Restarts adbd with root privileges. +``` + Args: + timeout: timeout in seconds + retries: number of retries -Checks whether 'su' is needed to access protected resources. + Raises: + CommandFailedError if root could not be enabled. + CommandTimeoutError on timeout. +``` + + +### DeviceUtils.FileExists + +Checks whether the given file exists on the device. +``` + Arguments are the same as PathExists. +``` + + +### DeviceUtils.FileSize + +Get the size of a file on the device. ``` + Note: This is implemented by parsing the output of the 'ls' command on + the device. On some Android versions, when passing a directory or special + file, the size is *not* reported and this function will throw an exception. + Args: + device_path: A string containing the path of a file on the device. + as_root: A boolean indicating whether the to use root privileges to + access the file information. timeout: timeout in seconds retries: number of retries Returns: - True if 'su' is available on the device and is needed to to access - protected resources; False otherwise if either 'su' is not available - (e.g. because the device has a user build), or not needed (because adbd - already has root privileges). + The size of the file in bytes. Raises: + CommandFailedError if device_path cannot be found on the device, or + its size cannot be determited for some reason. CommandTimeoutError on timeout. DeviceUnreachableError on missing device. ``` -### DeviceUtils.IsOnline +### DeviceUtils.ForceStop -Checks whether the device is online. +Close the application. +``` + Args: + package: A string containing the name of the package to stop. + timeout: timeout in seconds + retries: number of retries + + Raises: + CommandTimeoutError on timeout. + DeviceUnreachableError on missing device. +``` + + +### DeviceUtils.GetABI + +Gets the device main ABI. ``` Args: timeout: timeout in seconds retries: number of retries Returns: - True if the device is online, False otherwise. + The device's main ABI name. For supported ABIs, the return value will be + one of the values defined in devil.android.ndk.abis. Raises: CommandTimeoutError on timeout. ``` -### DeviceUtils.HasRoot +### DeviceUtils.GetAppWritablePath -Checks whether or not adbd has root privileges. +Get a path that on the device's SD card that apps can write. ``` Args: timeout: timeout in seconds retries: number of retries Returns: - True if adbd has root privileges, False otherwise. + A app-writeable path on the device's SD card. Raises: + CommandFailedError if the external storage path could not be determined. CommandTimeoutError on timeout. DeviceUnreachableError on missing device. ``` -### DeviceUtils.EnableRoot +### DeviceUtils.GetApplicationDataDirectory -Restarts adbd with root privileges. +Get the data directory on the device for the given package. +``` + Args: + package: Name of the package. + + Returns: + The package's data directory. + Raises: + CommandFailedError if the package's data directory can't be found, + whether because it's not installed or otherwise. +``` + + +### DeviceUtils.GetApplicationPaths + +Get the paths of the installed apks on the device for the given package. +``` + Args: + package: Name of the package. + + Returns: + List of paths to the apks on the device for the given package. +``` + + +### DeviceUtils.GetApplicationPids + +Returns the PID or PIDs of a given process name. ``` + Note that the |process_name|, often the package name, must match exactly. + Args: + process_name: A string containing the process name to get the PIDs for. + at_most_one: A boolean indicating that at most one PID is expected to + be found. timeout: timeout in seconds retries: number of retries + Returns: + A list of the PIDs for the named process. If at_most_one=True returns + the single PID found or None otherwise. + Raises: - CommandFailedError if root could not be enabled. + CommandFailedError if at_most_one=True and more than one PID is found + for the named process. CommandTimeoutError on timeout. + DeviceUnreachableError on missing device. ``` -### DeviceUtils.IsUserBuild +### DeviceUtils.GetApplicationTargetSdk -Checks whether or not the device is running a user build. +Get the targetSdkVersion of a package installed on the device. +``` + Args: + package: Name of the package. + + Returns: + A string with the targetSdkVersion or None if the package is not found on + the device. Note: this cannot always be cast to an integer. If this + application targets a pre-release SDK, this returns the version codename + instead (ex. "R"). +``` + + +### DeviceUtils.GetApplicationVersion + +Get the version name of a package installed on the device. +``` + Args: + package: Name of the package. + + Returns: + A string with the version name or None if the package is not found + on the device. +``` + + +### DeviceUtils.GetClientCache + +Returns client cache. +### DeviceUtils.GetCountry + +Returns the country setting on the device. +``` + DEPRECATED: Prefer GetLocale() instead. + + Args: + cache: Whether to use cached properties when available. +``` + + +### DeviceUtils.GetEnforce + +Get the current mode of SELinux. ``` Args: timeout: timeout in seconds retries: number of retries Returns: - True if the device is running a user build, False otherwise (i.e. if - it's running a userdebug build). + True (enforcing), False (permissive), or None (disabled). Raises: + CommandFailedError on failure. CommandTimeoutError on timeout. DeviceUnreachableError on missing device. ``` @@ -137,6 +301,9 @@ Checks whether or not the device is running a user build. Get the device's path to its SD card. ``` + Note: this path is read-only by apps in R+. Use GetAppWritablePath() to + obtain a path writable by apps. + Args: timeout: timeout in seconds retries: number of retries @@ -151,6 +318,9 @@ Get the device's path to its SD card. ``` +### DeviceUtils.GetFeatures + +Returns the features supported on the device. ### DeviceUtils.GetIMEI Get the device's IMEI. @@ -167,93 +337,190 @@ Get the device's IMEI. ``` -### DeviceUtils.GetApplicationPaths +### DeviceUtils.GetLanguage -Get the paths of the installed apks on the device for the given package. +Returns the language setting on the device. +``` + DEPRECATED: Prefer GetLocale() instead. + + Args: + cache: Whether to use cached properties when available. +``` + + +### DeviceUtils.GetLocale + +Returns the locale setting on the device. +``` + Args: + cache: Whether to use cached properties when available. + Returns: + A pair (language, country). +``` + + +### DeviceUtils.GetLogcatMonitor + +Returns a new LogcatMonitor associated with this device. +``` + Parameters passed to this function are passed directly to + |logcat_monitor.LogcatMonitor| and are documented there. +``` + + +### DeviceUtils.GetPackageArchitecture + +Get the architecture of a package installed on the device. ``` Args: package: Name of the package. Returns: - List of paths to the apks on the device for the given package. + A string with the architecture, or None if the package is missing. ``` -### DeviceUtils.TakeBugReport +### DeviceUtils.GetPids -Takes a bug report and dumps it to the specified path. +Returns the PIDs of processes containing the given name as substring. ``` - This doesn't use adb's bugreport option since its behavior is dependent on - both adb version and device OS version. To make it simpler, this directly - runs the bugreport command on the device itself and dumps the stdout to a - file. + DEPRECATED + + Note that the |process_name| is often the package name. Args: - path: Path on the host to drop the bug report. - timeout: (optional) Timeout per try in seconds. - retries: (optional) Number of retries to attempt. + process_name: A string containing the process name to get the PIDs for. + If missing returns PIDs for all processes. + timeout: timeout in seconds + retries: number of retries + + Returns: + A dict mapping process name to a list of PIDs for each process that + contained the provided |process_name|. + + Raises: + CommandTimeoutError on timeout. + DeviceUnreachableError on missing device. ``` -### DeviceUtils.GetApplicationVersion +### DeviceUtils.GetProp -Get the version name of a package installed on the device. +Gets a property from the device. ``` Args: - package: Name of the package. + property_name: A string containing the name of the property to get from + the device. + cache: Whether to use cached properties when available. + timeout: timeout in seconds + retries: number of retries Returns: - A string with the version name or None if the package is not found - on the device. + The value of the device's |property_name| property. + + Raises: + CommandTimeoutError on timeout. ``` -### DeviceUtils.GetApplicationDataDirectory +### DeviceUtils.GetSecurityContextForPackage -Get the data directory on the device for the given package. +Gets the SELinux security context for the given package. ``` Args: package: Name of the package. + encrypted: Whether to check in the encrypted data directory + (/data/user_de/0/) or the unencrypted data directory (/data/data/). Returns: - The package's data directory. + The package's security context as a string, or None if not found. +``` + + +### DeviceUtils.GetTracingPath + +Gets tracing path from the device. +``` + Args: + timeout: timeout in seconds + retries: number of retries + + Returns: + /sys/kernel/debug/tracing for device with debugfs mount support; + /sys/kernel/tracing for device with tracefs support; + /sys/kernel/debug/tracing if support can't be determined. + Raises: - CommandFailedError if the package's data directory can't be found, - whether because it's not installed or otherwise. + CommandTimeoutError on timeout. ``` -### DeviceUtils.WaitUntilFullyBooted +### DeviceUtils.GetWebViewUpdateServiceDump -Wait for the device to fully boot. +Get the WebView update command sysdump on the device. ``` - This means waiting for the device to boot, the package manager to be - available, and the SD card to be ready. It can optionally mean waiting - for wifi to come up, too. + Returns: + A dictionary with these possible entries: + FallbackLogicEnabled: True|False + CurrentWebViewPackage: "package name" or None + MinimumWebViewVersionCode: int + WebViewPackages: Dict of installed WebView providers, mapping "package + name" to "reason it's valid/invalid." + + It may return an empty dictionary if device does not + support the "dumpsys webviewupdate" command. + + Raises: + CommandFailedError on failure. + CommandTimeoutError on timeout. + DeviceUnreachableError on missing device. +``` + + +### DeviceUtils.GoHome + +Return to the home screen and obtain launcher focus. +``` + This command launches the home screen and attempts to obtain + launcher focus until the timeout is reached. Args: - wifi: A boolean indicating if we should wait for wifi to come up or not. timeout: timeout in seconds retries: number of retries Raises: - CommandFailedError on failure. - CommandTimeoutError if one of the component waits times out. - DeviceUnreachableError if the device becomes unresponsive. + CommandTimeoutError on timeout. + DeviceUnreachableError on missing device. ``` -### DeviceUtils.Reboot +### DeviceUtils.GrantPermissions -Reboot the device. +### DeviceUtils.HasRoot + +Checks whether or not adbd has root privileges. ``` + A device is considered to have root if all commands are implicitly run + with elevated privileges, i.e. without having to use "su" to run them. + + Note that some devices do not allow this implicit privilige elevation, + but _can_ run commands as root just fine when done explicitly with "su". + To check if your device can run commands with elevated privileges at all + use: + + device.HasRoot() or device.NeedsSU() + + Luckily, for the most part you don't need to worry about this and using + RunShellCommand(cmd, as_root=True) will figure out for you the right + command incantation to run with elevated privileges. + Args: - block: A boolean indicating if we should wait for the reboot to complete. - wifi: A boolean indicating if we should wait for wifi to be enabled after - the reboot. The option has no effect unless |block| is also True. timeout: timeout in seconds retries: number of retries + Returns: + True if adbd has root privileges, False otherwise. + Raises: CommandTimeoutError on timeout. DeviceUnreachableError on missing device. @@ -262,18 +529,30 @@ Reboot the device. ### DeviceUtils.Install -Install an APK. +Install an APK or app bundle. ``` - Noop if an identical APK is already installed. + Noop if an identical APK is already installed. If installing a bundle, the + bundletools helper script (bin/*_bundle) should be used rather than the .aab + file. Args: - apk: An ApkHelper instance or string containing the path to the APK. + apk: An ApkHelper instance or string containing the path to the APK or + bundle. allow_downgrade: A boolean indicating if we should allow downgrades. reinstall: A boolean indicating if we should keep any existing app data. + Ignored if |apk| is a bundle. permissions: Set of permissions to set. If not set, finds permissions with apk helper. To set no permissions, pass []. timeout: timeout in seconds retries: number of retries + modules: An iterable containing specific bundle modules to install. + Error if set and |apk| points to an APK instead of a bundle. + fake_modules: An iterable containing specific bundle modules that should + have their apks copied to |MODULES_SRC_DIRECTORY_PATH| subdirectory + rather than installed. Thus the app can emulate SplitCompat while + running. This should not have any overlap with |modules|. + additional_locales: An iterable with additional locales to install for a + bundle. Raises: CommandFailedError if the installation fails. @@ -308,82 +587,69 @@ Install a split APK. ``` -### DeviceUtils.Uninstall +### DeviceUtils.IsApplicationInstalled -Remove the app |package\_name| from the device. +Determines whether a particular package is installed on the device. ``` - This is a no-op if the app is not already installed. + Args: + package: Name of the package. + + Returns: + True if the application is installed, False otherwise. +``` + +### DeviceUtils.IsOnline + +Checks whether the device is online. +``` Args: - package_name: The package to uninstall. - keep_data: (optional) Whether to keep the data and cache directories. - timeout: Timeout in seconds. - retries: Number of retries. + timeout: timeout in seconds + retries: number of retries + + Returns: + True if the device is online, False otherwise. Raises: - CommandFailedError if the uninstallation fails. - CommandTimeoutError if the uninstallation times out. - DeviceUnreachableError on missing device. + CommandTimeoutError on timeout. ``` -### DeviceUtils.RunShellCommand +### DeviceUtils.IsScreenOn -Run an ADB shell command. +Determines if screen is on. ``` - The command to run |cmd| should be a sequence of program arguments - (preferred) or a single string with a shell script to run. + Dumpsys input_method exposes screen on/off state. Below is an explination of + the states. - When |cmd| is a sequence, it is assumed to contain the name of the command - to run followed by its arguments. In this case, arguments are passed to the - command exactly as given, preventing any further processing by the shell. - This allows callers to easily pass arguments with spaces or special - characters without having to worry about quoting rules. Whenever possible, - it is recomended to pass |cmd| as a sequence. + Pre-L: + On: mScreenOn=true + Off: mScreenOn=false + L+: + On: mInteractive=true + Off: mInteractive=false - When |cmd| is passed as a single string, |shell| should be set to True. - The command will be interpreted and run by the shell on the device, - allowing the use of shell features such as pipes, wildcards, or variables. - Failing to set shell=True will issue a warning, but this will be changed - to a hard failure in the future (see: catapult:#3242). + Returns: + True if screen is on, false if it is off. + + Raises: + device_errors.CommandFailedError: If screen state cannot be found. +``` - This behaviour is consistent with that of command runners in cmd_helper as - well as Python's own subprocess.Popen. - TODO(perezju) Change the default of |check_return| to True when callers - have switched to the new behaviour. +### DeviceUtils.IsUserBuild +Checks whether or not the device is running a user build. +``` Args: - cmd: A sequence containing the command to run and its arguments, or a - string with a shell script to run (should also set shell=True). - shell: A boolean indicating whether shell features may be used in |cmd|. - check_return: A boolean indicating whether or not the return code should - be checked. - cwd: The device directory in which the command should be run. - env: The environment variables with which the command should be run. - run_as: A string containing the package as which the command should be - run. - as_root: A boolean indicating whether the shell command should be run - with root privileges. - single_line: A boolean indicating if only a single line of output is - expected. - large_output: Uses a work-around for large shell command output. Without - this large output will be truncated. - raw_output: Whether to only return the raw output - (no splitting into lines). timeout: timeout in seconds retries: number of retries Returns: - If single_line is False, the output of the command as a list of lines, - otherwise, a string with the unique line of output emmited by the command - (with the optional newline at the end stripped). + True if the device is running a user build, False otherwise (i.e. if + it's running a userdebug build). Raises: - AdbCommandFailedError if check_return is True and the exit code of - the command run on the device is non-zero. - CommandFailedError if single_line is True but the output contains two or - more lines. CommandTimeoutError on timeout. DeviceUnreachableError on missing device. ``` @@ -419,108 +685,127 @@ Kill all processes with the given name on the device. ``` -### DeviceUtils.StartActivity +### DeviceUtils.ListDirectory -Start package's activity on the device. +List all files on a device directory. ``` + Mirroring os.listdir (and most client expectations) the resulting list + does not include the special entries '.' and '..' even if they are present + in the directory. + Args: - intent_obj: An Intent object to send. - blocking: A boolean indicating whether we should wait for the activity to - finish launching. - trace_file_name: If present, a string that both indicates that we want to - profile the activity and contains the path to which the - trace should be saved. - force_stop: A boolean indicating whether we should stop the activity - before starting it. + device_path: A string containing the path of the directory on the device + to list. + as_root: A boolean indicating whether the to use root privileges to list + the directory contents. timeout: timeout in seconds retries: number of retries + Returns: + A list of filenames for all entries contained in the directory. + Raises: - CommandFailedError if the activity could not be started. + AdbCommandFailedError if |device_path| does not specify a valid and + accessible directory in the device. CommandTimeoutError on timeout. DeviceUnreachableError on missing device. ``` -### DeviceUtils.StartInstrumentation - -### DeviceUtils.BroadcastIntent +### DeviceUtils.ListProcesses -Send a broadcast intent. +Returns a list of tuples with info about processes on the device. ``` + This essentially parses the output of the |ps| command into convenient + ProcessInfo tuples. + Args: - intent: An Intent to broadcast. + process_name: A string used to filter the returned processes. If given, + only processes whose name have this value as a substring + will be returned. timeout: timeout in seconds retries: number of retries - Raises: - CommandTimeoutError on timeout. - DeviceUnreachableError on missing device. + Returns: + A list of ProcessInfo tuples with |name|, |pid|, and |ppid| fields. ``` -### DeviceUtils.GoHome +### DeviceUtils.LoadCacheData -Return to the home screen and obtain launcher focus. +Initializes the cache from data created using DumpCacheData. ``` - This command launches the home screen and attempts to obtain - launcher focus until the timeout is reached. + The cache is used only if its token matches the one found on the device. + This prevents a stale cache from being used (which can happen when sharing + devices). Args: + data: A previously serialized cache (string). timeout: timeout in seconds retries: number of retries - Raises: - CommandTimeoutError on timeout. - DeviceUnreachableError on missing device. + Returns: + Whether the cache was loaded. ``` -### DeviceUtils.ForceStop +### DeviceUtils.NeedsSU -Close the application. +Checks whether 'su' is needed to access protected resources. ``` Args: - package: A string containing the name of the package to stop. timeout: timeout in seconds retries: number of retries + Returns: + True if 'su' is available on the device and is needed to to access + protected resources; False otherwise if either 'su' is not available + (e.g. because the device has a user build), or not needed (because adbd + already has root privileges). + Raises: CommandTimeoutError on timeout. DeviceUnreachableError on missing device. ``` -### DeviceUtils.ClearApplicationState +### DeviceUtils.PathExists -Clear all state for the given package. +Checks whether the given path(s) exists on the device. ``` Args: - package: A string containing the name of the package to stop. - permissions: List of permissions to set after clearing data. + device_path: A string containing the absolute path to the file on the + device, or an iterable of paths to check. + as_root: Whether root permissions should be use to check for the existence + of the given path(s). timeout: timeout in seconds retries: number of retries + Returns: + True if the all given paths exist on the device, False otherwise. + Raises: CommandTimeoutError on timeout. DeviceUnreachableError on missing device. ``` -### DeviceUtils.SendKeyEvent +### DeviceUtils.PullFile -Sends a keycode to the device. +Pull a file from the device. ``` - See the devil.android.sdk.keyevent module for suitable keycode values. - Args: - keycode: A integer keycode to send to the device. + device_path: A string containing the absolute path of the file to pull + from the device. + host_path: A string containing the absolute path of the destination on + the host. + as_root: Whether root permissions should be used to pull the file. timeout: timeout in seconds retries: number of retries Raises: + CommandFailedError on failure. CommandTimeoutError on timeout. - DeviceUnreachableError on missing device. ``` @@ -538,79 +823,14 @@ Push files to the device, skipping files that don't need updating. |host_path| is an absolute path of a file or directory on the host that should be minimially pushed to the device, and |device_path| is an absolute path of the destination on the device. - timeout: timeout in seconds - retries: number of retries delete_device_stale: option to delete stale files on device - - Raises: - CommandFailedError on failure. - CommandTimeoutError on timeout. - DeviceUnreachableError on missing device. -``` - - -### DeviceUtils.FileExists - -Checks whether the given file exists on the device. -``` - Arguments are the same as PathExists. -``` - - -### DeviceUtils.PathExists - -Checks whether the given path(s) exists on the device. -``` - Args: - device_path: A string containing the absolute path to the file on the - device, or an iterable of paths to check. - as_root: Whether root permissions should be use to check for the existence - of the given path(s). - timeout: timeout in seconds - retries: number of retries - - Returns: - True if the all given paths exist on the device, False otherwise. - - Raises: - CommandTimeoutError on timeout. - DeviceUnreachableError on missing device. -``` - - -### DeviceUtils.RemovePath - -Removes the given path(s) from the device. -``` - Args: - device_path: A string containing the absolute path to the file on the - device, or an iterable of paths to check. - force: Whether to remove the path(s) with force (-f). - recursive: Whether to remove any directories in the path(s) recursively. - as_root: Whether root permissions should be use to remove the given - path(s). - rename: Whether to rename the path(s) before removing to help avoid - filesystem errors. See https://stackoverflow.com/questions/11539657 - timeout: timeout in seconds - retries: number of retries -``` - - -### DeviceUtils.PullFile - -Pull a file from the device. -``` - Args: - device_path: A string containing the absolute path of the file to pull - from the device. - host_path: A string containing the absolute path of the destination on - the host. timeout: timeout in seconds retries: number of retries Raises: CommandFailedError on failure. CommandTimeoutError on timeout. + DeviceUnreachableError on missing device. ``` @@ -642,156 +862,143 @@ Reads the contents of a file from the device. ``` -### DeviceUtils.WriteFile +### DeviceUtils.Reboot -Writes |contents| to a file on the device. +Reboot the device. ``` Args: - device_path: A string containing the absolute path to the file to write - on the device. - contents: A string containing the data to write to the device. - as_root: A boolean indicating whether the write should be executed with - root privileges (if available). - force_push: A boolean indicating whether to force the operation to be - performed by pushing a file to the device. The default is, when the - contents are short, to pass the contents using a shell script instead. + block: A boolean indicating if we should wait for the reboot to complete. + wifi: A boolean indicating if we should wait for wifi to be enabled after + the reboot. + The option has no effect unless |block| is also True. + decrypt: A boolean indicating if we should wait for full-disk decryption + to complete after the reboot. + The option has no effect unless |block| is also True. timeout: timeout in seconds retries: number of retries Raises: - CommandFailedError if the file could not be written on the device. CommandTimeoutError on timeout. DeviceUnreachableError on missing device. ``` -### DeviceUtils.ListDirectory +### DeviceUtils.RemovePath -List all files on a device directory. +Removes the given path(s) from the device. ``` - Mirroring os.listdir (and most client expectations) the resulting list - does not include the special entries '.' and '..' even if they are present - in the directory. - Args: - device_path: A string containing the path of the directory on the device - to list. - as_root: A boolean indicating whether the to use root privileges to list - the directory contents. + device_path: A string containing the absolute path to the file on the + device, or an iterable of paths to check. + force: Whether to remove the path(s) with force (-f). + recursive: Whether to remove any directories in the path(s) recursively. + as_root: Whether root permissions should be use to remove the given + path(s). + rename: Whether to rename the path(s) before removing to help avoid + filesystem errors. See https://stackoverflow.com/questions/11539657 timeout: timeout in seconds retries: number of retries +``` - Returns: - A list of filenames for all entries contained in the directory. - Raises: - AdbCommandFailedError if |device_path| does not specify a valid and - accessible directory in the device. - CommandTimeoutError on timeout. - DeviceUnreachableError on missing device. +### DeviceUtils.RestartAdbd + +### DeviceUtils.RunShellCommand + +Run an ADB shell command. ``` + The command to run |cmd| should be a sequence of program arguments + (preferred) or a single string with a shell script to run. + When |cmd| is a sequence, it is assumed to contain the name of the command + to run followed by its arguments. In this case, arguments are passed to the + command exactly as given, preventing any further processing by the shell. + This allows callers to easily pass arguments with spaces or special + characters without having to worry about quoting rules. Whenever possible, + it is recomended to pass |cmd| as a sequence. -### DeviceUtils.StatDirectory + When |cmd| is passed as a single string, |shell| should be set to True. + The command will be interpreted and run by the shell on the device, + allowing the use of shell features such as pipes, wildcards, or variables. + Failing to set shell=True will issue a warning, but this will be changed + to a hard failure in the future (see: catapult:#3242). -List file and stat info for all entries on a device directory. -``` - Implementation notes: this is currently implemented by parsing the output - of 'ls -a -l' on the device. Whether possible and convenient, we attempt to - make parsing strict and return values mirroring those of the standard |os| - and |stat| Python modules. + This behaviour is consistent with that of command runners in cmd_helper as + well as Python's own subprocess.Popen. - Mirroring os.listdir (and most client expectations) the resulting list - does not include the special entries '.' and '..' even if they are present - in the directory. + TODO(crbug.com/1029769) Change the default of |check_return| to True when + callers have switched to the new behaviour. Args: - device_path: A string containing the path of the directory on the device - to list. - as_root: A boolean indicating whether the to use root privileges to list - the directory contents. + cmd: A sequence containing the command to run and its arguments, or a + string with a shell script to run (should also set shell=True). + shell: A boolean indicating whether shell features may be used in |cmd|. + check_return: A boolean indicating whether or not the return code should + be checked. + cwd: The device directory in which the command should be run. + env: The environment variables with which the command should be run. + run_as: A string containing the package as which the command should be + run. + as_root: A boolean indicating whether the shell command should be run + with root privileges. + single_line: A boolean indicating if only a single line of output is + expected. + large_output: Uses a work-around for large shell command output. Without + this large output will be truncated. + raw_output: Whether to only return the raw output + (no splitting into lines). timeout: timeout in seconds retries: number of retries Returns: - A list of dictionaries, each containing the following keys: - filename: A string with the file name. - st_mode: File permissions, use the stat module to interpret these. - st_nlink: Number of hard links (may be missing). - st_owner: A string with the user name of the owner. - st_group: A string with the group name of the owner. - st_rdev_pair: Device type as (major, minior) (only if inode device). - st_size: Size of file, in bytes (may be missing for non-regular files). - st_mtime: Time of most recent modification, in seconds since epoch - (although resolution is in minutes). - symbolic_link_to: If entry is a symbolic link, path where it points to; - missing otherwise. + If single_line is False, the output of the command as a list of lines, + otherwise, a string with the unique line of output emmited by the command + (with the optional newline at the end stripped). Raises: - AdbCommandFailedError if |device_path| does not specify a valid and - accessible directory in the device. + AdbCommandFailedError if check_return is True and the exit code of + the command run on the device is non-zero. + CommandFailedError if single_line is True but the output contains two or + more lines. CommandTimeoutError on timeout. DeviceUnreachableError on missing device. ``` -### DeviceUtils.StatPath +### DeviceUtils.SendKeyEvent -Get the stat attributes of a file or directory on the device. +Sends a keycode to the device. ``` + See the devil.android.sdk.keyevent module for suitable keycode values. + Args: - device_path: A string containing the path of a file or directory from - which to get attributes. - as_root: A boolean indicating whether the to use root privileges to - access the file information. + keycode: A integer keycode to send to the device. timeout: timeout in seconds retries: number of retries - Returns: - A dictionary with the stat info collected; see StatDirectory for details. - Raises: - CommandFailedError if device_path cannot be found on the device. CommandTimeoutError on timeout. DeviceUnreachableError on missing device. ``` -### DeviceUtils.FileSize +### DeviceUtils.SetEnforce -Get the size of a file on the device. +Modify the mode SELinux is running in. ``` - Note: This is implemented by parsing the output of the 'ls' command on - the device. On some Android versions, when passing a directory or special - file, the size is *not* reported and this function will throw an exception. - Args: - device_path: A string containing the path of a file on the device. - as_root: A boolean indicating whether the to use root privileges to - access the file information. + enabled: a boolean indicating whether to put SELinux in encorcing mode + (if True), or permissive mode (otherwise). timeout: timeout in seconds retries: number of retries - Returns: - The size of the file in bytes. - Raises: - CommandFailedError if device_path cannot be found on the device, or - its size cannot be determited for some reason. + CommandFailedError on failure. CommandTimeoutError on timeout. DeviceUnreachableError on missing device. ``` -### DeviceUtils.GetLanguage - -Returns the language setting on the device. -``` - Args: - cache: Whether to use cached properties when available. -``` - - ### DeviceUtils.SetJavaAsserts Enables or disables Java asserts. @@ -811,159 +1018,211 @@ Enables or disables Java asserts. ``` -### DeviceUtils.GetCountry +### DeviceUtils.SetProp -Returns the country setting on the device. +Sets a property on the device. ``` Args: - cache: Whether to use cached properties when available. + property_name: A string containing the name of the property to set on + the device. + value: A string containing the value to set to the property on the + device. + check: A boolean indicating whether to check that the property was + successfully set on the device. + timeout: timeout in seconds + retries: number of retries + + Raises: + CommandFailedError if check is true and the property was not correctly + set on the device (e.g. because it is not rooted). + CommandTimeoutError on timeout. ``` -### DeviceUtils.GetApplicationPids +### DeviceUtils.SetScreen -Returns the PID or PIDs of a given process name. +Turns screen on and off. ``` - Note that the |process_name|, often the package name, must match exactly. + Args: + on: bool to decide state to switch to. True = on False = off. +``` + + +### DeviceUtils.SetWebViewFallbackLogic + +Set whether WebViewUpdateService's "fallback logic" should be enabled. +``` + WebViewUpdateService has nonintuitive "fallback logic" for devices where + Monochrome (Chrome Stable) is preinstalled as the WebView provider, with a + "stub" (little-to-no code) implementation of standalone WebView. + + "Fallback logic" (enabled by default) is designed, in the case where the + user has disabled Chrome, to fall back to the stub standalone WebView by + enabling the package. The implementation plumbs through the Chrome APK until + Play Store installs an update with the full implementation. + + A surprising side-effect of "fallback logic" is that, immediately after + sideloading WebView, WebViewUpdateService re-disables the package and + uninstalls the update. This can prevent successfully using standalone + WebView for development, although "fallback logic" can be disabled on + userdebug/eng devices. + + Because this is only relevant for devices with the standalone WebView stub, + this command is only relevant on N-P (inclusive). + + You can determine if "fallback logic" is currently enabled by checking + FallbackLogicEnabled in the dictionary returned by + GetWebViewUpdateServiceDump. Args: - process_name: A string containing the process name to get the PIDs for. - at_most_one: A boolean indicating that at most one PID is expected to - be found. + enabled: bool - True for enabled, False for disabled timeout: timeout in seconds retries: number of retries - Returns: - A list of the PIDs for the named process. If at_most_one=True returns - the single PID found or None otherwise. - Raises: - CommandFailedError if at_most_one=True and more than one PID is found - for the named process. + CommandFailedError on failure. CommandTimeoutError on timeout. DeviceUnreachableError on missing device. ``` -### DeviceUtils.GetProp +### DeviceUtils.SetWebViewImplementation -Gets a property from the device. +Select the WebView implementation to the specified package. ``` Args: - property_name: A string containing the name of the property to get from - the device. - cache: Whether to use cached properties when available. + package_name: The package name of a WebView implementation. The package + must be already installed on the device. timeout: timeout in seconds retries: number of retries - Returns: - The value of the device's |property_name| property. - Raises: + CommandFailedError on failure. CommandTimeoutError on timeout. + DeviceUnreachableError on missing device. ``` -### DeviceUtils.SetProp +### DeviceUtils.StartActivity -Sets a property on the device. +Start package's activity on the device. ``` Args: - property_name: A string containing the name of the property to set on - the device. - value: A string containing the value to set to the property on the - device. - check: A boolean indicating whether to check that the property was - successfully set on the device. + intent_obj: An Intent object to send. + blocking: A boolean indicating whether we should wait for the activity to + finish launching. + trace_file_name: If present, a string that both indicates that we want to + profile the activity and contains the path to which the + trace should be saved. + force_stop: A boolean indicating whether we should stop the activity + before starting it. timeout: timeout in seconds retries: number of retries Raises: - CommandFailedError if check is true and the property was not correctly - set on the device (e.g. because it is not rooted). + CommandFailedError if the activity could not be started. CommandTimeoutError on timeout. + DeviceUnreachableError on missing device. ``` -### DeviceUtils.GetABI +### DeviceUtils.StartInstrumentation -Gets the device main ABI. +### DeviceUtils.StartService + +Start a service on the device. ``` Args: - timeout: timeout in seconds - retries: number of retries - - Returns: - The device's main ABI name. + intent_obj: An Intent object to send describing the service to start. + user_id: A specific user to start the service as, defaults to current. + timeout: Timeout in seconds. + retries: Number of retries Raises: + CommandFailedError if the service could not be started. CommandTimeoutError on timeout. + DeviceUnreachableError on missing device. ``` -### DeviceUtils.GetPids +### DeviceUtils.StatDirectory -Returns the PIDs of processes containing the given name as substring. +List file and stat info for all entries on a device directory. ``` - Note that the |process_name| is often the package name. + Implementation notes: this is currently implemented by parsing the output + of 'ls -a -l' on the device. Whether possible and convenient, we attempt to + make parsing strict and return values mirroring those of the standard |os| + and |stat| Python modules. + + Mirroring os.listdir (and most client expectations) the resulting list + does not include the special entries '.' and '..' even if they are present + in the directory. Args: - process_name: A string containing the process name to get the PIDs for. - If missing returns PIDs for all processes. + device_path: A string containing the path of the directory on the device + to list. + as_root: A boolean indicating whether the to use root privileges to list + the directory contents. timeout: timeout in seconds retries: number of retries Returns: - A dict mapping process name to a list of PIDs for each process that - contained the provided |process_name|. + A list of dictionaries, each containing the following keys: + filename: A string with the file name. + st_mode: File permissions, use the stat module to interpret these. + st_nlink: Number of hard links (may be missing). + st_owner: A string with the user name of the owner. + st_group: A string with the group name of the owner. + st_rdev_pair: Device type as (major, minior) (only if inode device). + st_size: Size of file, in bytes (may be missing for non-regular files). + st_mtime: Time of most recent modification, in seconds since epoch + (although resolution is in minutes). + symbolic_link_to: If entry is a symbolic link, path where it points to; + missing otherwise. Raises: + AdbCommandFailedError if |device_path| does not specify a valid and + accessible directory in the device. CommandTimeoutError on timeout. DeviceUnreachableError on missing device. ``` -### DeviceUtils.GetLogcatMonitor - -Returns a new LogcatMonitor associated with this device. -``` - Parameters passed to this function are passed directly to - |logcat_monitor.LogcatMonitor| and are documented there. -``` - - -### DeviceUtils.GetEnforce +### DeviceUtils.StatPath -Get the current mode of SELinux. +Get the stat attributes of a file or directory on the device. ``` Args: + device_path: A string containing the path of a file or directory from + which to get attributes. + as_root: A boolean indicating whether the to use root privileges to + access the file information. timeout: timeout in seconds retries: number of retries Returns: - True (enforcing), False (permissive), or None (disabled). + A dictionary with the stat info collected; see StatDirectory for details. Raises: - CommandFailedError on failure. + CommandFailedError if device_path cannot be found on the device. CommandTimeoutError on timeout. DeviceUnreachableError on missing device. ``` -### DeviceUtils.SetEnforce +### DeviceUtils.TakeBugReport -Modify the mode SELinux is running in. +Takes a bug report and dumps it to the specified path. ``` - Args: - enabled: a boolean indicating whether to put SELinux in encorcing mode - (if True), or permissive mode (otherwise). - timeout: timeout in seconds - retries: number of retries + This doesn't use adb's bugreport option since its behavior is dependent on + both adb version and device OS version. To make it simpler, this directly + runs the bugreport command on the device itself and dumps the stdout to a + file. - Raises: - CommandFailedError on failure. - CommandTimeoutError on timeout. - DeviceUnreachableError on missing device. + Args: + path: Path on the host to drop the bug report. + timeout: (optional) Timeout per try in seconds. + retries: (optional) Number of retries to attempt. ``` @@ -988,84 +1247,128 @@ Takes a screenshot of the device. ``` -### DeviceUtils.DismissCrashDialogIfNeeded +### DeviceUtils.Uninstall -Dismiss the error/ANR dialog if present. -``` - Returns: Name of the crashed package if a dialog is focused, - None otherwise. +Remove the app |package\_name| from the device. ``` + This is a no-op if the app is not already installed. + Args: + package_name: The package to uninstall. + keep_data: (optional) Whether to keep the data and cache directories. + timeout: Timeout in seconds. + retries: Number of retries. -### DeviceUtils.GetClientCache + Raises: + CommandFailedError if the uninstallation fails. + CommandTimeoutError if the uninstallation times out. + DeviceUnreachableError on missing device. +``` -Returns client cache. -### DeviceUtils.LoadCacheData -Initializes the cache from data created using DumpCacheData. +### DeviceUtils.WaitUntilFullyBooted + +Wait for the device to fully boot. ``` - The cache is used only if its token matches the one found on the device. - This prevents a stale cache from being used (which can happen when sharing - devices). + This means waiting for the device to boot, the package manager to be + available, and the SD card to be ready. + It can optionally wait the following: + - Wait for wifi to come up. + - Wait for full-disk decryption to complete. Args: - data: A previously serialized cache (string). + wifi: A boolean indicating if we should wait for wifi to come up or not. + decrypt: A boolean indicating if we should wait for full-disk decryption + to complete. timeout: timeout in seconds retries: number of retries - Returns: - Whether the cache was loaded. + Raises: + CommandFailedError on failure. + CommandTimeoutError if one of the component waits times out. + DeviceUnreachableError if the device becomes unresponsive. ``` -### DeviceUtils.DumpCacheData +### DeviceUtils.WriteFile -Dumps the current cache state to a string. +Writes |contents| to a file on the device. ``` Args: + device_path: A string containing the absolute path to the file to write + on the device. + contents: A string containing the data to write to the device. + as_root: A boolean indicating whether the write should be executed with + root privileges (if available). + force_push: A boolean indicating whether to force the operation to be + performed by pushing a file to the device. The default is, when the + contents are short, to pass the contents using a shell script instead. timeout: timeout in seconds retries: number of retries - Returns: - A serialized cache as a string. + Raises: + CommandFailedError if the file could not be written on the device. + CommandTimeoutError on timeout. + DeviceUnreachableError on missing device. ``` -### DeviceUtils.RestartAdbd - -### DeviceUtils.GrantPermissions - -### DeviceUtils.IsScreenOn +### DeviceUtils.\_\_eq\_\_ -Determines if screen is on. +Checks whether |other| refers to the same device as |self|. +``` + Args: + other: The object to compare to. This can be a basestring, an instance + of adb_wrapper.AdbWrapper, or an instance of DeviceUtils. + Returns: + Whether |other| refers to the same device as |self|. ``` - Dumpsys input_method exposes screen on/off state. Below is an explination of - the states. - Pre-L: - On: mScreenOn=true - Off: mScreenOn=false - L+: - On: mInteractive=true - Off: mInteractive=false - Returns: - True if screen is on, false if it is off. +### DeviceUtils.\_\_init\_\_ - Raises: - device_errors.CommandFailedError: If screen state cannot be found. +DeviceUtils constructor. +``` + Args: + device: Either a device serial, an existing AdbWrapper instance, or an + an existing AndroidCommands instance. + enable_device_files_cache: For PushChangedFiles(), cache checksums of + pushed files rather than recomputing them on a subsequent call. + default_timeout: An integer containing the default number of seconds to + wait for an operation to complete if no explicit value is provided. + default_retries: An integer containing the default number or times an + operation should be retried on failure if no explicit value is provided. ``` -### DeviceUtils.SetScreen +### DeviceUtils.\_\_lt\_\_ -Turns screen on and off. +Compares two instances of DeviceUtils. ``` + This merely compares their serial numbers. + Args: - on: bool to decide state to switch to. True = on False = off. + other: The instance of DeviceUtils to compare to. + Returns: + Whether |self| is less than |other|. ``` +### DeviceUtils.\_\_str\_\_ + +Returns the device serial. +## ProcessInfo + +ProcessInfo(name, pid, ppid) +### ProcessInfo.\_\_getnewargs\_\_ + +Return self as a plain tuple. Used by copy and pickle. +### ProcessInfo.\_\_getstate\_\_ + +Exclude the OrderedDict from pickling +### ProcessInfo.\_\_repr\_\_ + +Return a nicely formatted representation string ### GetAVDs Returns a list of Android Virtual Devices. |