1 files changed, 254 insertions, 0 deletions
diff --git a/testing/mozbase/docs/mozdevice.rst b/testing/mozbase/docs/mozdevice.rst
new file mode 100644
index 000000000..5e18b56d2
--- /dev/null
+++ b/testing/mozbase/docs/mozdevice.rst
@@ -0,0 +1,254 @@
+:mod:`mozdevice` --- Interact with remote devices
+=================================================
+
+Mozdevice provides several interfaces to interact with a remote device
+such as an Android- or FirefoxOS-based phone. It allows you to push
+files to these types of devices, launch processes, and more. There are
+currently two available interfaces:
+
+* :ref:`DeviceManager`: Works either via ADB or a custom TCP protocol
+  (the latter requires an agent application running on the device).
+* :ref:`ADB`: Uses the Android Debugger Protocol explicitly
+
+In general, new code should use the ADB abstraction where possible as
+it is simpler and more reliable.
+
+.. automodule:: mozdevice
+
+.. _DeviceManager:
+
+DeviceManager interface
+-----------------------
+.. autoclass:: DeviceManager
+
+Here's an example script which lists the files in '/mnt/sdcard' and sees if a
+process called 'org.mozilla.fennec' is running. In this example, we're
+instantiating the DeviceManagerADB implementation, but we could just
+as easily have used DeviceManagerSUT (assuming the device had an agent
+running speaking the SUT protocol).
+
+::
+
+  import mozdevice
+
+  dm = mozdevice.DeviceManagerADB()
+  print dm.listFiles("/mnt/sdcard")
+  if dm.processExist("org.mozilla.fennec"):
+      print "Fennec is running"
+
+Informational methods
+`````````````````````
+.. automethod:: DeviceManager.getInfo(self, directive=None)
+.. automethod:: DeviceManager.getCurrentTime(self)
+.. automethod:: DeviceManager.getIP
+.. automethod:: DeviceManager.saveScreenshot
+.. automethod:: DeviceManager.recordLogcat
+.. automethod:: DeviceManager.getLogcat
+
+File management methods
+```````````````````````
+.. autoattribute:: DeviceManager.deviceRoot
+.. automethod:: DeviceManager.getDeviceRoot(self)
+.. automethod:: DeviceManager.pushFile(self, localFilename, remoteFilename, retryLimit=1)
+.. automethod:: DeviceManager.pushDir(self, localDirname, remoteDirname, retryLimit=1)
+.. automethod:: DeviceManager.pullFile(self, remoteFilename)
+.. automethod:: DeviceManager.getFile(self, remoteFilename, localFilename)
+.. automethod:: DeviceManager.getDirectory(self, remoteDirname, localDirname, checkDir=True)
+.. automethod:: DeviceManager.validateFile(self, remoteFilename, localFilename)
+.. automethod:: DeviceManager.mkDir(self, remoteDirname)
+.. automethod:: DeviceManager.mkDirs(self, filename)
+.. automethod:: DeviceManager.dirExists(self, dirpath)
+.. automethod:: DeviceManager.fileExists(self, filepath)
+.. automethod:: DeviceManager.listFiles(self, rootdir)
+.. automethod:: DeviceManager.removeFile(self, filename)
+.. automethod:: DeviceManager.removeDir(self, remoteDirname)
+.. automethod:: DeviceManager.chmodDir(self, remoteDirname, mask="777")
+.. automethod:: DeviceManager.getTempDir(self)
+
+Process management methods
+``````````````````````````
+.. automethod:: DeviceManager.shell(self, cmd, outputfile, env=None, cwd=None, timeout=None, root=False)
+.. automethod:: DeviceManager.shellCheckOutput(self, cmd, env=None, cwd=None, timeout=None, root=False)
+.. automethod:: DeviceManager.getProcessList(self)
+.. automethod:: DeviceManager.processExist(self, processName)
+.. automethod:: DeviceManager.killProcess(self, processName)
+
+System control methods
+``````````````````````
+.. automethod:: DeviceManager.reboot(self, ipAddr=None, port=30000)
+
+Application management methods
+``````````````````````````````
+.. automethod:: DeviceManager.uninstallAppAndReboot(self, appName, installPath=None)
+.. automethod:: DeviceManager.installApp(self, appBundlePath, destPath=None)
+.. automethod:: DeviceManager.uninstallApp(self, appName, installPath=None)
+.. automethod:: DeviceManager.updateApp(self, appBundlePath, processName=None, destPath=None, ipAddr=None, port=30000)
+
+DeviceManagerADB implementation
+```````````````````````````````
+
+.. autoclass:: mozdevice.DeviceManagerADB
+
+DeviceManagerADB has several methods that are not present in all
+DeviceManager implementations. Please do not use them in code that
+is meant to be interoperable.
+
+.. automethod:: DeviceManagerADB.forward
+.. automethod:: DeviceManagerADB.remount
+.. automethod:: DeviceManagerADB.devices
+
+DeviceManagerSUT implementation
+```````````````````````````````
+
+.. autoclass:: mozdevice.DeviceManagerSUT
+
+DeviceManagerSUT has several methods that are only used in specific
+tests and are not present in all DeviceManager implementations. Please
+do not use them in code that is meant to be interoperable.
+
+.. automethod:: DeviceManagerSUT.unpackFile
+.. automethod:: DeviceManagerSUT.adjustResolution
+
+Android extensions
+``````````````````
+
+For Android, we provide two variants of the `DeviceManager` interface
+with extensions useful for that platform. These classes are called
+DroidADB and DroidSUT. They inherit all methods from DeviceManagerADB
+and DeviceManagerSUT. Here is the interface for DroidADB:
+
+.. automethod:: mozdevice.DroidADB.launchApplication
+.. automethod:: mozdevice.DroidADB.launchFennec
+.. automethod:: mozdevice.DroidADB.getInstalledApps
+.. automethod:: mozdevice.DroidADB.getAppRoot
+
+These methods are also found in the DroidSUT class.
+
+.. _ADB:
+
+ADB Interface
+-------------
+
+The following classes provide a basic interface to interact with the
+Android Debug Tool (adb) and Android-based devices.  It is intended to
+provide the basis for a replacement for DeviceManager and
+DeviceManagerADB.
+
+ADBCommand
+``````````
+
+.. autoclass:: mozdevice.ADBCommand
+
+.. automethod:: ADBCommand.command(self, cmds, timeout=None)
+.. automethod:: ADBCommand.command_output(self, cmds, timeout=None)
+
+ADBHost
+```````
+.. autoclass:: mozdevice.ADBHost
+
+.. automethod:: ADBHost.command(self, cmds, timeout=None)
+.. automethod:: ADBHost.command_output(self, cmds, timeout=None)
+.. automethod:: ADBHost.start_server(self, timeout=None)
+.. automethod:: ADBHost.kill_server(self, timeout=None)
+.. automethod:: ADBHost.devices(self, timeout=None)
+
+ADBDevice
+`````````
+.. autoclass:: mozdevice.ADBDevice
+
+Host Command methods
+++++++++++++++++++++
+.. automethod:: ADBDevice.command(self, cmds, timeout=None)
+.. automethod:: ADBDevice.command_output(self, cmds, timeout=None)
+
+Device Shell methods
+++++++++++++++++++++
+.. automethod:: ADBDevice.shell(self, cmd, env=None, cwd=None, timeout=None, root=False)
+.. automethod:: ADBDevice.shell_bool(self, cmd, env=None, cwd=None, timeout=None, root=False)
+.. automethod:: ADBDevice.shell_output(self, cmd, env=None, cwd=None, timeout=None, root=False)
+
+Informational methods
++++++++++++++++++++++
+.. automethod:: ADBDevice.clear_logcat
+.. automethod:: ADBDevice.get_battery_percentage
+.. automethod:: ADBDevice.get_info
+.. automethod:: ADBDevice.get_logcat
+.. automethod:: ADBDevice.get_prop
+.. automethod:: ADBDevice.get_state
+
+System control methods
+++++++++++++++++++++++
+.. automethod:: ADBDevice.is_device_ready
+.. automethod:: ADBDevice.reboot
+
+File management methods
++++++++++++++++++++++++
+.. automethod:: ADBDevice.chmod
+.. automethod:: ADBDevice.cp
+.. automethod:: ADBDevice.exists
+.. automethod:: ADBDevice.is_dir
+.. automethod:: ADBDevice.is_file
+.. automethod:: ADBDevice.list_files
+.. automethod:: ADBDevice.mkdir
+.. automethod:: ADBDevice.mv
+.. automethod:: ADBDevice.push
+.. automethod:: ADBDevice.rm
+.. automethod:: ADBDevice.rmdir
+.. autoattribute:: ADBDevice.test_root
+
+Process management methods
+++++++++++++++++++++++++++
+.. automethod:: ADBDevice.get_process_list
+.. automethod:: ADBDevice.kill
+.. automethod:: ADBDevice.pkill
+.. automethod:: ADBDevice.process_exist
+
+ADBAndroid
+``````````
+.. autoclass:: ADBAndroid
+
+Informational methods
++++++++++++++++++++++
+.. automethod:: ADBAndroid.get_battery_percentage
+
+System control methods
+++++++++++++++++++++++
+.. automethod:: ADBAndroid.is_device_ready
+.. automethod:: ADBAndroid.power_on
+
+Application management methods
+++++++++++++++++++++++++++++++
+.. automethod:: ADBAndroid.install_app
+.. automethod:: ADBAndroid.is_app_installed
+.. automethod:: ADBAndroid.launch_application
+.. automethod:: ADBAndroid.launch_fennec
+.. automethod:: ADBAndroid.stop_application
+.. automethod:: ADBAndroid.uninstall_app
+.. automethod:: ADBAndroid.update_app
+
+ADBB2G
+``````
+.. autoclass:: ADBB2G
+
+Informational methods
++++++++++++++++++++++
+.. automethod:: ADBB2G.get_battery_percentage
+.. automethod:: ADBB2G.get_info
+.. automethod:: ADBB2G.get_memory_total
+
+ADBProcess
+``````````
+.. autoclass:: mozdevice.ADBProcess
+
+ADBError
+````````
+.. autoexception:: mozdevice.ADBError
+
+ADBRootError
+````````````
+.. autoexception:: mozdevice.ADBRootError
+
+ADBTimeoutError
+```````````````
+.. autoexception:: mozdevice.ADBTimeoutError
+