michael@0: :mod:`mozdevice` --- Interact with remote devices
michael@0: =================================================
michael@0: 
michael@0: Mozdevice provides an interface to interact with a remote device such
michael@0: as an Android- or FirefoxOS-based phone connected to a
michael@0: host machine. Currently there are two implementations of the interface: one
michael@0: uses a custom TCP-based protocol to communicate with a server running
michael@0: on the device, another uses Android's adb utility.
michael@0: 
michael@0: .. automodule:: mozdevice
michael@0: 
michael@0: DeviceManager interface
michael@0: -----------------------
michael@0: .. autoclass:: DeviceManager
michael@0: 
michael@0: Here's an example script which lists the files in '/mnt/sdcard' and sees if a
michael@0: process called 'org.mozilla.fennec' is running. In this example, we're
michael@0: instantiating the DeviceManagerADB implementation, but we could just
michael@0: as easily have used DeviceManagerSUT (assuming the device had an agent
michael@0: running speaking the SUT protocol).
michael@0: 
michael@0: ::
michael@0: 
michael@0:   import mozdevice
michael@0: 
michael@0:   dm = mozdevice.DeviceManagerADB()
michael@0:   print dm.listFiles("/mnt/sdcard")
michael@0:   if dm.processExist("org.mozilla.fennec"):
michael@0:       print "Fennec is running"
michael@0: 
michael@0: Informational methods
michael@0: `````````````````````
michael@0: .. automethod:: DeviceManager.getInfo(self, directive=None)
michael@0: .. automethod:: DeviceManager.getCurrentTime(self)
michael@0: .. automethod:: DeviceManager.getIP
michael@0: .. automethod:: DeviceManager.saveScreenshot
michael@0: .. automethod:: DeviceManager.recordLogcat
michael@0: .. automethod:: DeviceManager.getLogcat
michael@0: 
michael@0: File management methods
michael@0: ```````````````````````
michael@0: .. automethod:: DeviceManager.pushFile(self, localFilename, remoteFilename, retryLimit=1)
michael@0: .. automethod:: DeviceManager.pushDir(self, localDirname, remoteDirname, retryLimit=1)
michael@0: .. automethod:: DeviceManager.pullFile(self, remoteFilename)
michael@0: .. automethod:: DeviceManager.getFile(self, remoteFilename, localFilename)
michael@0: .. automethod:: DeviceManager.getDirectory(self, remoteDirname, localDirname, checkDir=True)
michael@0: .. automethod:: DeviceManager.validateFile(self, remoteFilename, localFilename)
michael@0: .. automethod:: DeviceManager.mkDir(self, remoteDirname)
michael@0: .. automethod:: DeviceManager.mkDirs(self, filename)
michael@0: .. automethod:: DeviceManager.dirExists(self, dirpath)
michael@0: .. automethod:: DeviceManager.fileExists(self, filepath)
michael@0: .. automethod:: DeviceManager.listFiles(self, rootdir)
michael@0: .. automethod:: DeviceManager.removeFile(self, filename)
michael@0: .. automethod:: DeviceManager.removeDir(self, remoteDirname)
michael@0: .. automethod:: DeviceManager.chmodDir(self, remoteDirname, mask="777")
michael@0: .. automethod:: DeviceManager.getDeviceRoot(self)
michael@0: .. automethod:: DeviceManager.getAppRoot(self, packageName=None)
michael@0: .. automethod:: DeviceManager.getTestRoot(self, harnessName)
michael@0: .. automethod:: DeviceManager.getTempDir(self)
michael@0: 
michael@0: Process management methods
michael@0: ``````````````````````````
michael@0: .. automethod:: DeviceManager.shell(self, cmd, outputfile, env=None, cwd=None, timeout=None, root=False)
michael@0: .. automethod:: DeviceManager.shellCheckOutput(self, cmd, env=None, cwd=None, timeout=None, root=False)
michael@0: .. automethod:: DeviceManager.getProcessList(self)
michael@0: .. automethod:: DeviceManager.processExist(self, processName)
michael@0: .. automethod:: DeviceManager.killProcess(self, processName)
michael@0: 
michael@0: System control methods
michael@0: ``````````````````````
michael@0: .. automethod:: DeviceManager.reboot(self, ipAddr=None, port=30000)
michael@0: 
michael@0: Application management methods
michael@0: ``````````````````````````````
michael@0: .. automethod:: DeviceManager.uninstallAppAndReboot(self, appName, installPath=None)
michael@0: .. automethod:: DeviceManager.installApp(self, appBundlePath, destPath=None)
michael@0: .. automethod:: DeviceManager.uninstallApp(self, appName, installPath=None)
michael@0: .. automethod:: DeviceManager.updateApp(self, appBundlePath, processName=None, destPath=None, ipAddr=None, port=30000)
michael@0: 
michael@0: DeviceManagerADB implementation
michael@0: -------------------------------
michael@0: 
michael@0: .. autoclass:: mozdevice.DeviceManagerADB
michael@0: 
michael@0: ADB-specific methods
michael@0: ````````````````````
michael@0: DeviceManagerADB has several methods that are not present in all
michael@0: DeviceManager implementations. Please do not use them in code that
michael@0: is meant to be interoperable.
michael@0: 
michael@0: .. automethod:: DeviceManagerADB.forward
michael@0: .. automethod:: DeviceManagerADB.remount
michael@0: .. automethod:: DeviceManagerADB.devices
michael@0: 
michael@0: DeviceManagerSUT implementation
michael@0: -------------------------------
michael@0: 
michael@0: .. autoclass:: mozdevice.DeviceManagerSUT
michael@0: 
michael@0: SUT-specific methods
michael@0: ````````````````````
michael@0: DeviceManagerSUT has several methods that are only used in specific
michael@0: tests and are not present in all DeviceManager implementations. Please
michael@0: do not use them in code that is meant to be interoperable.
michael@0: 
michael@0: .. automethod:: DeviceManagerSUT.unpackFile
michael@0: .. automethod:: DeviceManagerSUT.adjustResolution
michael@0: 
michael@0: Android extensions
michael@0: ------------------
michael@0: 
michael@0: For Android, we provide two variants of the `DeviceManager` interface
michael@0: with extensions useful for that platform. These classes are called
michael@0: DroidADB and DroidSUT. They inherit all methods from DeviceManagerADB
michael@0: and DeviceManagerSUT. Here is the interface for DroidADB:
michael@0: 
michael@0: .. automethod:: mozdevice.DroidADB.launchApplication
michael@0: .. automethod:: mozdevice.DroidADB.launchFennec
michael@0: .. automethod:: mozdevice.DroidADB.getInstalledApps
michael@0: 
michael@0: These methods are also found in the DroidSUT class.