Merge pull request #552 from jeffherman/issues/504
Refactor docs to publish contents to readthedocs.io
diff --git a/docs/Makefile b/docs/Makefile
index 9effe0e..600951b 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -3,6 +3,7 @@
# You can set these variables from the command line.
SPHINXOPTS =
+SPHINXAPIDOC = sphinx-apidoc
SPHINXBUILD = sphinx-build
PAPER =
BUILDDIR = _build
@@ -50,45 +51,48 @@
clean:
rm -rf $(BUILDDIR)/*
+autodoc:
+ $(SPHINXAPIDOC) -f -o ./ ../mobly
+
.PHONY: html
-html:
+html: autodoc
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
.PHONY: dirhtml
-dirhtml:
+dirhtml: autodoc
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
.PHONY: singlehtml
-singlehtml:
+singlehtml: autodoc
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
.PHONY: pickle
-pickle:
+pickle: autodoc
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo
@echo "Build finished; now you can process the pickle files."
.PHONY: json
-json:
+json: autodoc
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
@echo
@echo "Build finished; now you can process the JSON files."
.PHONY: htmlhelp
-htmlhelp:
+htmlhelp: autodoc
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."
.PHONY: qthelp
-qthelp:
+qthelp: autodoc
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
@@ -98,7 +102,7 @@
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Mobly.qhc"
.PHONY: applehelp
-applehelp:
+applehelp: autodoc
$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
@echo
@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
@@ -107,7 +111,7 @@
"bundle."
.PHONY: devhelp
-devhelp:
+devhelp: autodoc
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
@echo
@echo "Build finished."
@@ -117,19 +121,19 @@
@echo "# devhelp"
.PHONY: epub
-epub:
+epub: autodoc
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
@echo
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
.PHONY: epub3
-epub3:
+epub3: autodoc
$(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3
@echo
@echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3."
.PHONY: latex
-latex:
+latex: autodoc
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@@ -137,47 +141,47 @@
"(use \`make latexpdf' here to do that automatically)."
.PHONY: latexpdf
-latexpdf:
+latexpdf: autodoc
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through pdflatex..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
.PHONY: latexpdfja
-latexpdfja:
+latexpdfja: autodoc
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through platex and dvipdfmx..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
.PHONY: lualatexpdf
-lualatexpdf:
+lualatexpdf: autodoc
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through lualatex..."
$(MAKE) PDFLATEX=lualatex -C $(BUILDDIR)/latex all-pdf
@echo "lualatex finished; the PDF files are in $(BUILDDIR)/latex."
.PHONY: xelatexpdf
-xelatexpdf:
+xelatexpdf: autodoc
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through xelatex..."
$(MAKE) PDFLATEX=xelatex -C $(BUILDDIR)/latex all-pdf
@echo "xelatex finished; the PDF files are in $(BUILDDIR)/latex."
.PHONY: text
-text:
+text: autodoc
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
@echo
@echo "Build finished. The text files are in $(BUILDDIR)/text."
.PHONY: man
-man:
+man: autodoc
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
@echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
.PHONY: texinfo
-texinfo:
+texinfo: autodoc
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
@@ -185,57 +189,57 @@
"(use \`make info' here to do that automatically)."
.PHONY: info
-info:
+info: autodoc
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo "Running Texinfo files through makeinfo..."
make -C $(BUILDDIR)/texinfo info
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
.PHONY: gettext
-gettext:
+gettext: autodoc
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
@echo
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
.PHONY: changes
-changes:
+changes: autodoc
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo
@echo "The overview file is in $(BUILDDIR)/changes."
.PHONY: linkcheck
-linkcheck:
+linkcheck: autodoc
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."
.PHONY: doctest
-doctest:
+doctest: autodoc
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."
.PHONY: coverage
-coverage:
+coverage: autodoc
$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
@echo "Testing of coverage in the sources finished, look at the " \
"results in $(BUILDDIR)/coverage/python.txt."
.PHONY: xml
-xml:
+xml: autodoc
$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
@echo
@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
.PHONY: pseudoxml
-pseudoxml:
+pseudoxml: autodoc
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
@echo
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
.PHONY: dummy
-dummy:
+dummy: autodoc
$(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy
@echo
@echo "Build finished. Dummy builder generates no files."
diff --git a/docs/android_device_service.md b/docs/android_device_service.md
index 220ff19..f9b4ba1 100644
--- a/docs/android_device_service.md
+++ b/docs/android_device_service.md
@@ -21,7 +21,7 @@
Here is a dummy service example:
-`my_service.py`
+**my_service.py**
```python
class Configs(object):
diff --git a/docs/conf.py b/docs/conf.py
index 8d8d354..a1b6b04 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -81,10 +81,7 @@
# This patterns also effect to html_static_path and html_extra_path
exclude_patterns = ['_build',
'Thumbs.db',
- '.DS_Store',
- 'tutorial.md',
- 'instrumentation_tutorial.md',
- 'android_device_service.md']
+ '.DS_Store']
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
diff --git a/docs/index.rst b/docs/index.rst
index 093c955..779706e 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -6,12 +6,51 @@
Welcome to Mobly's documentation!
=================================
-.. toctree::
- :maxdepth: 4
- :caption: Contents:
+**Mobly** is a Python-based test framework that specializes in supporting
+test cases that require multiple devices, complex environments, or custom
+hardware setups.
+Here are some example use cases:
+
+* P2P data transfer between two devices
+* Conference calls across three phones
+* Wearable device interacting with a phone
+* Internet-of-Things devices interacting with each other
+* Testing RF characteristics of devices with special equipment
+* Testing LTE network by controlling phones, base stations, and eNBs
+
+Mobly can support many different types of devices and equipment, and it's
+easy to plug your own device or custom equipment/service into Mobly.
+
+Mobly comes with a set of libraries to control common devices like Android
+devices.
+
+While developed by Googlers, Mobly is not an official Google product.
+
+.. toctree::
+ :maxdepth: 2
+
+ tutorial
+ android_device_service
+ instrumentation_tutorial
mobly
+License
+-------
+
+Copyright 2019 Google Inc. All Rights Reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
Indices and tables
==================
diff --git a/docs/instrumentation_tutorial.md b/docs/instrumentation_tutorial.md
index ff3d258..4291bc7 100644
--- a/docs/instrumentation_tutorial.md
+++ b/docs/instrumentation_tutorial.md
@@ -1,8 +1,9 @@
# Running Android instrumentation tests with Mobly
This tutorial shows how to write and execute Mobly tests for running Android
-instrumentation tests. For more details about instrumentation tests, please refer to
-https://developer.android.com/studio/test/index.html.
+instrumentation tests. For more details about instrumentation tests, please
+refer to
+[Android Studio](https://developer.android.com/studio/test/index.html).
## Setup Requirements
diff --git a/docs/mobly.controllers.android_device_lib.rst b/docs/mobly.controllers.android_device_lib.rst
deleted file mode 100644
index a8d5395..0000000
--- a/docs/mobly.controllers.android_device_lib.rst
+++ /dev/null
@@ -1,108 +0,0 @@
-mobly.controllers.android_device_lib package
-============================================
-
-Subpackages
------------
-
-.. toctree::
-
- mobly.controllers.android_device_lib.services
-
-Submodules
-----------
-
-mobly.controllers.android_device_lib.adb module
------------------------------------------------
-
-.. automodule:: mobly.controllers.android_device_lib.adb
- :members:
- :undoc-members:
- :show-inheritance:
-
-mobly.controllers.android_device_lib.callback_handler module
-------------------------------------------------------------
-
-.. automodule:: mobly.controllers.android_device_lib.callback_handler
- :members:
- :undoc-members:
- :show-inheritance:
-
-mobly.controllers.android_device_lib.errors module
---------------------------------------------------
-
-.. automodule:: mobly.controllers.android_device_lib.errors
- :members:
- :undoc-members:
- :show-inheritance:
-
-mobly.controllers.android_device_lib.event_dispatcher module
-------------------------------------------------------------
-
-.. automodule:: mobly.controllers.android_device_lib.event_dispatcher
- :members:
- :undoc-members:
- :show-inheritance:
-
-mobly.controllers.android_device_lib.fastboot module
-----------------------------------------------------
-
-.. automodule:: mobly.controllers.android_device_lib.fastboot
- :members:
- :undoc-members:
- :show-inheritance:
-
-mobly.controllers.android_device_lib.jsonrpc_client_base module
----------------------------------------------------------------
-
-.. automodule:: mobly.controllers.android_device_lib.jsonrpc_client_base
- :members:
- :undoc-members:
- :show-inheritance:
-
-mobly.controllers.android_device_lib.jsonrpc_shell_base module
---------------------------------------------------------------
-
-.. automodule:: mobly.controllers.android_device_lib.jsonrpc_shell_base
- :members:
- :undoc-members:
- :show-inheritance:
-
-mobly.controllers.android_device_lib.service_manager module
---------------------------------------------------------------
-
-.. automodule:: mobly.controllers.android_device_lib.service_manager
- :members:
- :undoc-members:
- :show-inheritance:
-
-mobly.controllers.android_device_lib.sl4a_client module
--------------------------------------------------------
-
-.. automodule:: mobly.controllers.android_device_lib.sl4a_client
- :members:
- :undoc-members:
- :show-inheritance:
-
-mobly.controllers.android_device_lib.snippet_client module
-----------------------------------------------------------
-
-.. automodule:: mobly.controllers.android_device_lib.snippet_client
- :members:
- :undoc-members:
- :show-inheritance:
-
-mobly.controllers.android_device_lib.snippet_event module
---------------------------------------------------------------
-
-.. automodule:: mobly.controllers.android_device_lib.snippet_event
- :members:
- :undoc-members:
- :show-inheritance:
-
-Module contents
----------------
-
-.. automodule:: mobly.controllers.android_device_lib
- :members:
- :undoc-members:
- :show-inheritance:
diff --git a/docs/mobly.controllers.android_device_lib.services.rst b/docs/mobly.controllers.android_device_lib.services.rst
deleted file mode 100644
index 602f9ab..0000000
--- a/docs/mobly.controllers.android_device_lib.services.rst
+++ /dev/null
@@ -1,45 +0,0 @@
-mobly.controllers.android_device_lib.services package
-=====================================================
-
-Submodules
-----------
-
-mobly.controllers.android_device_lib.services.base_service module
------------------------------------------------------------------
-
-.. automodule:: mobly.controllers.android_device_lib.services.base_service
- :members:
- :undoc-members:
- :show-inheritance:
-
-mobly.controllers.android_device_lib.services.logcat module
------------------------------------------------------------
-
-.. automodule:: mobly.controllers.android_device_lib.services.logcat
- :members:
- :undoc-members:
- :show-inheritance:
-
-mobly.controllers.android_device_lib.services.sl4a_service module
------------------------------------------------------------------
-
-.. automodule:: mobly.controllers.android_device_lib.services.sl4a_service
- :members:
- :undoc-members:
- :show-inheritance:
-
-mobly.controllers.android_device_lib.services.snippet_management_service module
--------------------------------------------------------------------------------
-
-.. automodule:: mobly.controllers.android_device_lib.services.snippet_management_service
- :members:
- :undoc-members:
- :show-inheritance:
-
-Module contents
----------------
-
-.. automodule:: mobly.controllers.android_device_lib.services
- :members:
- :undoc-members:
- :show-inheritance:
diff --git a/docs/mobly.controllers.attenuator_lib.rst b/docs/mobly.controllers.attenuator_lib.rst
deleted file mode 100644
index 38cf837..0000000
--- a/docs/mobly.controllers.attenuator_lib.rst
+++ /dev/null
@@ -1,30 +0,0 @@
-mobly.controllers.attenuator_lib package
-========================================
-
-Submodules
-----------
-
-mobly.controllers.attenuator_lib.minicircuits module
-----------------------------------------------------
-
-.. automodule:: mobly.controllers.attenuator_lib.minicircuits
- :members:
- :undoc-members:
- :show-inheritance:
-
-mobly.controllers.attenuator_lib.telnet_scpi_client module
-----------------------------------------------------------
-
-.. automodule:: mobly.controllers.attenuator_lib.telnet_scpi_client
- :members:
- :undoc-members:
- :show-inheritance:
-
-
-Module contents
----------------
-
-.. automodule:: mobly.controllers.attenuator_lib
- :members:
- :undoc-members:
- :show-inheritance:
diff --git a/docs/mobly.controllers.rst b/docs/mobly.controllers.rst
deleted file mode 100644
index 8871142..0000000
--- a/docs/mobly.controllers.rst
+++ /dev/null
@@ -1,63 +0,0 @@
-mobly.controllers package
-=========================
-
-Subpackages
------------
-
-.. toctree::
-
- mobly.controllers.android_device_lib
- mobly.controllers.attenuator_lib
- mobly.controllers.sniffer_lib
-
-Submodules
-----------
-
-mobly.controllers.android_device module
----------------------------------------
-
-.. automodule:: mobly.controllers.android_device
- :members:
- :undoc-members:
- :show-inheritance:
-
-mobly.controllers.attenuator module
------------------------------------
-
-.. automodule:: mobly.controllers.attenuator
- :members:
- :undoc-members:
- :show-inheritance:
-
-mobly.controllers.iperf_server module
--------------------------------------
-
-.. automodule:: mobly.controllers.iperf_server
- :members:
- :undoc-members:
- :show-inheritance:
-
-mobly.controllers.monsoon module
---------------------------------
-
-.. automodule:: mobly.controllers.monsoon
- :members:
- :undoc-members:
- :show-inheritance:
-
-mobly.controllers.sniffer module
---------------------------------
-
-.. automodule:: mobly.controllers.sniffer
- :members:
- :undoc-members:
- :show-inheritance:
-
-
-Module contents
----------------
-
-.. automodule:: mobly.controllers
- :members:
- :undoc-members:
- :show-inheritance:
diff --git a/docs/mobly.controllers.sniffer_lib.local.rst b/docs/mobly.controllers.sniffer_lib.local.rst
deleted file mode 100644
index 0c15a30..0000000
--- a/docs/mobly.controllers.sniffer_lib.local.rst
+++ /dev/null
@@ -1,38 +0,0 @@
-mobly.controllers.sniffer_lib.local package
-===========================================
-
-Submodules
-----------
-
-mobly.controllers.sniffer_lib.local.local_base module
------------------------------------------------------
-
-.. automodule:: mobly.controllers.sniffer_lib.local.local_base
- :members:
- :undoc-members:
- :show-inheritance:
-
-mobly.controllers.sniffer_lib.local.tcpdump module
---------------------------------------------------
-
-.. automodule:: mobly.controllers.sniffer_lib.local.tcpdump
- :members:
- :undoc-members:
- :show-inheritance:
-
-mobly.controllers.sniffer_lib.local.tshark module
--------------------------------------------------
-
-.. automodule:: mobly.controllers.sniffer_lib.local.tshark
- :members:
- :undoc-members:
- :show-inheritance:
-
-
-Module contents
----------------
-
-.. automodule:: mobly.controllers.sniffer_lib.local
- :members:
- :undoc-members:
- :show-inheritance:
diff --git a/docs/mobly.controllers.sniffer_lib.rst b/docs/mobly.controllers.sniffer_lib.rst
deleted file mode 100644
index f728ce7..0000000
--- a/docs/mobly.controllers.sniffer_lib.rst
+++ /dev/null
@@ -1,17 +0,0 @@
-mobly.controllers.sniffer_lib package
-=====================================
-
-Subpackages
------------
-
-.. toctree::
-
- mobly.controllers.sniffer_lib.local
-
-Module contents
----------------
-
-.. automodule:: mobly.controllers.sniffer_lib
- :members:
- :undoc-members:
- :show-inheritance:
diff --git a/docs/mobly.rst b/docs/mobly.rst
deleted file mode 100644
index d855a22..0000000
--- a/docs/mobly.rst
+++ /dev/null
@@ -1,133 +0,0 @@
-mobly package
-=============
-
-Subpackages
------------
-
-.. toctree::
-
- mobly.controllers
-
-Submodules
-----------
-
-mobly.asserts module
---------------------
-
-.. automodule:: mobly.asserts
- :members:
- :undoc-members:
- :show-inheritance:
-
-mobly.base_instrumentation_test module
---------------------------------------
-
-.. automodule:: mobly.base_instrumentation_test
- :members:
- :undoc-members:
- :show-inheritance:
-
-mobly.base_test module
-----------------------
-
-.. automodule:: mobly.base_test
- :members:
- :undoc-members:
- :show-inheritance:
-
-mobly.config_parser module
---------------------------
-
-.. automodule:: mobly.config_parser
- :members:
- :undoc-members:
- :show-inheritance:
-
-mobly.controller_manager module
--------------------------------
-
-.. automodule:: mobly.controller_manager
- :members:
- :undoc-members:
- :show-inheritance:
-
-mobly.expects module
---------------------
-
-.. automodule:: mobly.expects
- :members:
- :undoc-members:
- :show-inheritance:
-
-mobly.keys module
------------------
-
-.. automodule:: mobly.keys
- :members:
- :undoc-members:
- :show-inheritance:
-
-mobly.logger module
--------------------
-
-.. automodule:: mobly.logger
- :members:
- :undoc-members:
- :show-inheritance:
-
-mobly.records module
---------------------
-
-.. automodule:: mobly.records
- :members:
- :undoc-members:
- :show-inheritance:
-
-mobly.runtime_test_info module
-------------------------------
-
-.. automodule:: mobly.runtime_test_info
- :members:
- :undoc-members:
- :show-inheritance:
-
-mobly.signals module
---------------------
-
-.. automodule:: mobly.signals
- :members:
- :undoc-members:
- :show-inheritance:
-
-mobly.suite_runner module
--------------------------
-
-.. automodule:: mobly.suite_runner
- :members:
- :undoc-members:
- :show-inheritance:
-
-mobly.test_runner module
-------------------------
-
-.. automodule:: mobly.test_runner
- :members:
- :undoc-members:
- :show-inheritance:
-
-mobly.utils module
-------------------
-
-.. automodule:: mobly.utils
- :members:
- :undoc-members:
- :show-inheritance:
-
-
-Module contents
----------------
-
-.. automodule:: mobly
- :members:
- :undoc-members:
- :show-inheritance:
diff --git a/docs/tutorial.md b/docs/tutorial.md
index 5fd98c0..3d50e7d 100644
--- a/docs/tutorial.md
+++ b/docs/tutorial.md
@@ -6,22 +6,23 @@
## Setup Requirements
-* A computer with at least 2 USB ports.
-* Mobly package and its system dependencies installed on the computer.
-* One or two Android devices with the [Mobly Bundled Snippets]
- (https://github.com/google/mobly-bundled-snippets) (MBS) installed. We will
- use MBS to trigger actions on the Android devices.
-* A working adb setup. To check, connect one Android device to the computer
- and make sure it has "USB debugging" enabled. Make sure the device shows up
- in the list printed by `adb devices`.
+* A computer with at least 2 USB ports.
+* Mobly package and its system dependencies installed on the computer.
+* One or two Android devices with the
+ [Mobly Bundled Snippets](https://github.com/google/mobly-bundled-snippets)
+ (MBS) installed. We will
+ use MBS to trigger actions on the Android devices.
+* A working adb setup. To check, connect one Android device to the computer
+ and make sure it has "USB debugging" enabled. Make sure the device shows up
+ in the list printed by `adb devices`.
## Example 1: Hello World!
-
+
Let's start with the simple example of posting "Hello World" on the Android
device's screen. Create the following files:
-
+
**sample_config.yml**
-
+
```yaml
TestBeds:
# A test bed where adb will find Android devices.
@@ -29,32 +30,33 @@
Controllers:
AndroidDevice: '*'
```
-
+
**hello_world_test.py**
-
+
```python
from mobly import base_test
from mobly import test_runner
from mobly.controllers import android_device
-
+
+
class HelloWorldTest(base_test.BaseTestClass):
-
def setup_class(self):
# Registering android_device controller module declares the test's
- # dependency on Android device hardware. By default, we expect at least one
- # object is created from this.
+ # dependency on Android device hardware. By default, we expect at
+ # least one object is created from this.
self.ads = self.register_controller(android_device)
self.dut = self.ads[0]
# Start Mobly Bundled Snippets (MBS).
self.dut.load_snippet('mbs', 'com.google.android.mobly.snippet.bundled')
-
+
def test_hello(self):
self.dut.mbs.makeToast('Hello World!')
-
+
+
if __name__ == '__main__':
- test_runner.main()
+ test_runner.main()
```
-
+
To execute:
```
@@ -65,9 +67,10 @@
A "Hello World!" toast notification appears on your device's screen.
-Within SampleTestBed's `Controllers` section, we used `AndroidDevice: '*'` to tell
-the test runner to automatically find all connected Android devices. You can also
-specify particular devices by serial number and attach extra attributes to the object:
+Within SampleTestBed's `Controllers` section, we used `AndroidDevice: '*'`
+to tell the test runner to automatically find all connected Android devices.
+You can also specify particular devices by serial number and attach extra
+attributes to the object:
```yaml
AndroidDevice:
@@ -88,20 +91,20 @@
from mobly import base_test
from mobly import test_runner
from mobly.controllers import android_device
-
+
class HelloWorldTest(base_test.BaseTestClass):
-
+
def setup_class(self):
self.ads = self.register_controller(android_device)
self.dut = self.ads[0]
self.dut.load_snippet('mbs', 'com.google.android.mobly.snippet.bundled')
-
+
def test_hello(self):
self.dut.mbs.makeToast('Hello World!')
-
+
def test_bye(self):
self.dut.mbs.makeToast('Goodbye!')
-
+
if __name__ == '__main__':
test_runner.main()
```
@@ -133,7 +136,8 @@
You could specify user parameters to be passed into your test class in the
config file.
-In the following config, we added a parameter `favorite_food` to be used in the test case.
+In the following config, we added a parameter `favorite_food` to be used in
+the test case.
**sample_config.yml**
@@ -203,7 +207,8 @@
In this example, we use one Android device to discover another Android device
via bluetooth. This test demonstrates several essential elements in test
-writing, like asserts, device debug tag, and general logging vs logging with device tag.
+writing, like asserts, device debug tag, and general logging vs logging with
+device tag.
**sample_config.yml**
@@ -293,27 +298,27 @@
There's potentially a lot more we could do in this test, e.g. check
the hardware address, see whether we can pair devices, transfer files, etc.
-To learn more about the features included in MBS, go to [MBS repo]
-(https://github.com/google/mobly-bundled-snippets) to see how to check its help
-menu.
+To learn more about the features included in MBS, go to
+[MBS repo](https://github.com/google/mobly-bundled-snippets) to see how to
+check its help menu.
-To learn more about Mobly Snippet Lib, including features like Espresso support
-and asynchronous calls, see the [snippet lib examples]
-(https://github.com/google/mobly-snippet-lib/tree/master/examples).
+To learn more about Mobly Snippet Lib, including features like Espresso
+support and asynchronous calls, see the
+[snippet lib examples](https://github.com/google/mobly-snippet-lib/tree/master/examples).
## Example 6: Generated Tests
A common use case in writing tests is to execute the same test logic multiple
-times, each time with a different set of parameters. Instead of duplicating the
-same test case with minor tweaks, you could use the **Generated tests** in
-Mobly.
+times, each time with a different set of parameters. Instead of duplicating
+the same test case with minor tweaks, you could use the **Generated tests**
+in Mobly.
Mobly could generate test cases for you based on a list of parameters and a
function that contains the test logic. Each generated test case is equivalent
to an actual test case written in the class in terms of execution, procedure
-functions (setup/teardown/on_fail), and result collection. You could also
-select generated test cases via the `--test_case` cli arg as well.
+functions (`setup`, `teardown`, `on_fail`), and result collection. You could
+also select generated test cases via the `--test_case` cli arg as well.
Here's an example of generated tests in action. We will reuse the "Example 1:
@@ -323,7 +328,6 @@
You could reuse the config file from Example 1.
The test class would look like:
-
**many_greetings_test.py**
