1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/testing/mozbase/docs/mozdevice.rst Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,121 @@
1.4 +:mod:`mozdevice` --- Interact with remote devices
1.5 +=================================================
1.6 +
1.7 +Mozdevice provides an interface to interact with a remote device such
1.8 +as an Android- or FirefoxOS-based phone connected to a
1.9 +host machine. Currently there are two implementations of the interface: one
1.10 +uses a custom TCP-based protocol to communicate with a server running
1.11 +on the device, another uses Android's adb utility.
1.12 +
1.13 +.. automodule:: mozdevice
1.14 +
1.15 +DeviceManager interface
1.16 +-----------------------
1.17 +.. autoclass:: DeviceManager
1.18 +
1.19 +Here's an example script which lists the files in '/mnt/sdcard' and sees if a
1.20 +process called 'org.mozilla.fennec' is running. In this example, we're
1.21 +instantiating the DeviceManagerADB implementation, but we could just
1.22 +as easily have used DeviceManagerSUT (assuming the device had an agent
1.23 +running speaking the SUT protocol).
1.24 +
1.25 +::
1.26 +
1.27 + import mozdevice
1.28 +
1.29 + dm = mozdevice.DeviceManagerADB()
1.30 + print dm.listFiles("/mnt/sdcard")
1.31 + if dm.processExist("org.mozilla.fennec"):
1.32 + print "Fennec is running"
1.33 +
1.34 +Informational methods
1.35 +`````````````````````
1.36 +.. automethod:: DeviceManager.getInfo(self, directive=None)
1.37 +.. automethod:: DeviceManager.getCurrentTime(self)
1.38 +.. automethod:: DeviceManager.getIP
1.39 +.. automethod:: DeviceManager.saveScreenshot
1.40 +.. automethod:: DeviceManager.recordLogcat
1.41 +.. automethod:: DeviceManager.getLogcat
1.42 +
1.43 +File management methods
1.44 +```````````````````````
1.45 +.. automethod:: DeviceManager.pushFile(self, localFilename, remoteFilename, retryLimit=1)
1.46 +.. automethod:: DeviceManager.pushDir(self, localDirname, remoteDirname, retryLimit=1)
1.47 +.. automethod:: DeviceManager.pullFile(self, remoteFilename)
1.48 +.. automethod:: DeviceManager.getFile(self, remoteFilename, localFilename)
1.49 +.. automethod:: DeviceManager.getDirectory(self, remoteDirname, localDirname, checkDir=True)
1.50 +.. automethod:: DeviceManager.validateFile(self, remoteFilename, localFilename)
1.51 +.. automethod:: DeviceManager.mkDir(self, remoteDirname)
1.52 +.. automethod:: DeviceManager.mkDirs(self, filename)
1.53 +.. automethod:: DeviceManager.dirExists(self, dirpath)
1.54 +.. automethod:: DeviceManager.fileExists(self, filepath)
1.55 +.. automethod:: DeviceManager.listFiles(self, rootdir)
1.56 +.. automethod:: DeviceManager.removeFile(self, filename)
1.57 +.. automethod:: DeviceManager.removeDir(self, remoteDirname)
1.58 +.. automethod:: DeviceManager.chmodDir(self, remoteDirname, mask="777")
1.59 +.. automethod:: DeviceManager.getDeviceRoot(self)
1.60 +.. automethod:: DeviceManager.getAppRoot(self, packageName=None)
1.61 +.. automethod:: DeviceManager.getTestRoot(self, harnessName)
1.62 +.. automethod:: DeviceManager.getTempDir(self)
1.63 +
1.64 +Process management methods
1.65 +``````````````````````````
1.66 +.. automethod:: DeviceManager.shell(self, cmd, outputfile, env=None, cwd=None, timeout=None, root=False)
1.67 +.. automethod:: DeviceManager.shellCheckOutput(self, cmd, env=None, cwd=None, timeout=None, root=False)
1.68 +.. automethod:: DeviceManager.getProcessList(self)
1.69 +.. automethod:: DeviceManager.processExist(self, processName)
1.70 +.. automethod:: DeviceManager.killProcess(self, processName)
1.71 +
1.72 +System control methods
1.73 +``````````````````````
1.74 +.. automethod:: DeviceManager.reboot(self, ipAddr=None, port=30000)
1.75 +
1.76 +Application management methods
1.77 +``````````````````````````````
1.78 +.. automethod:: DeviceManager.uninstallAppAndReboot(self, appName, installPath=None)
1.79 +.. automethod:: DeviceManager.installApp(self, appBundlePath, destPath=None)
1.80 +.. automethod:: DeviceManager.uninstallApp(self, appName, installPath=None)
1.81 +.. automethod:: DeviceManager.updateApp(self, appBundlePath, processName=None, destPath=None, ipAddr=None, port=30000)
1.82 +
1.83 +DeviceManagerADB implementation
1.84 +-------------------------------
1.85 +
1.86 +.. autoclass:: mozdevice.DeviceManagerADB
1.87 +
1.88 +ADB-specific methods
1.89 +````````````````````
1.90 +DeviceManagerADB has several methods that are not present in all
1.91 +DeviceManager implementations. Please do not use them in code that
1.92 +is meant to be interoperable.
1.93 +
1.94 +.. automethod:: DeviceManagerADB.forward
1.95 +.. automethod:: DeviceManagerADB.remount
1.96 +.. automethod:: DeviceManagerADB.devices
1.97 +
1.98 +DeviceManagerSUT implementation
1.99 +-------------------------------
1.100 +
1.101 +.. autoclass:: mozdevice.DeviceManagerSUT
1.102 +
1.103 +SUT-specific methods
1.104 +````````````````````
1.105 +DeviceManagerSUT has several methods that are only used in specific
1.106 +tests and are not present in all DeviceManager implementations. Please
1.107 +do not use them in code that is meant to be interoperable.
1.108 +
1.109 +.. automethod:: DeviceManagerSUT.unpackFile
1.110 +.. automethod:: DeviceManagerSUT.adjustResolution
1.111 +
1.112 +Android extensions
1.113 +------------------
1.114 +
1.115 +For Android, we provide two variants of the `DeviceManager` interface
1.116 +with extensions useful for that platform. These classes are called
1.117 +DroidADB and DroidSUT. They inherit all methods from DeviceManagerADB
1.118 +and DeviceManagerSUT. Here is the interface for DroidADB:
1.119 +
1.120 +.. automethod:: mozdevice.DroidADB.launchApplication
1.121 +.. automethod:: mozdevice.DroidADB.launchFennec
1.122 +.. automethod:: mozdevice.DroidADB.getInstalledApps
1.123 +
1.124 +These methods are also found in the DroidSUT class.
