1# Android Comms Test Suite
2The Android Comms Test Suite, is a lightweight Python-based automation tool set
3that is used to perform automated testing of current and upcoming Android
4devices. It provides a simple execution interface; a set of pluggable libraries
5for accessing commercially avilable devices, Android devices, and a collection
6of utility functions to further ease test development. It is an ideal desktop
7tool for a wireless stack developer or integrator whether exercising a new code
8path, performing sanity testing, or running extended regression test suites.
9
10Included in the tests/google directory are a bundle of tests, many of which can
11be run with as little as one or two Android devices with wifi, cellular, or
12bluetooth connectivity, including:
131. Wifi tests for access point interopability, enterprise server integration,
14WiFi scanning, WiFi auto join, and round trip time.
152. Bluetooth tests for low energy, GATT, SPP, and bonding.
163. Cellular tests for circuit switch and IMS calling, data connectivity,
17messaging, network switching, and WiFi hotspot.
18
19ACTS follows the Google Open-source
20[Python Style Guide](https://google.github.io/styleguide/pyguide.html), and
21it is recommended for all new test cases.
22
23System dependencies:
24  - adb
25  - python3.4+
26  - python3.4-setuptools
27
28Python dependencies (installed automatically by setup.py):
29  - future
30  - pyserial
31
32To run unit tests:
33$ python3 setup.py test
34$ python setup.py test
35
36## ACTS Execution Flow Overview
37Below is a high level view of the ACTS flow:
38
391. Read configuration files
402. Create controllers
413. Sequentially execute test classes
42
43```
44FooTest.setup_class()
45FooTest.setup_test()
46FooTest.test_A()
47FooTest.teardown_test()
48FooTest.setup_test()
49FooTest.test_B()
50FooTest.teardown_test()
51....
52FooTest.teardown_class()
53BarTest.setup_class()
54....
55```
56
574. Destroy controllers
58
59## Preparing an Android Device
60### Allow USB Debugging
61USB debugging must be enabled before a device can take commands from adb.
62To enable USB debugging, first enable developer mode.
631. Go to Settings->About phone
642. Tap Build number repeatedly until "You're a developer now" is displayed.
65
66In developer mode:
671. Plug the device into a computer (host)
682. Run `$adb devices`
69- A pop-up asking to allow the host to access the android device may be
70displayed. Check the "Always" box and click "Yes".
71
72## ACTS Setup
73
741. Install the system dependencies.
75     On Ubuntu, sudo apt-get install python3.4 python3-setuptools
762. Run "python3.4 setup.py install" with elevated permissions
773. To verify ACTS is ready to go, at the location for README, and run:
78     cd framework/tests/ \
79     && act.py -c acts_sanity_test_config.json -tc IntegrationTest
80
81After installation, `act.py` will be in usr/bin and can be called as command
82line utilities. Components in ACTS are importable under the package "acts."
83in Python, for example:
84
85```
86$ python
87>>> from acts.controllers import android_device
88>>> device_list = android_device.get_all_instances()
89```
90
91## Breaking Down a Sample Command
92
93Above, the command `act.py -c acts_sanity_test_config.json -tc IntegrationTest`
94was run to verify ACTS was properly set up.
95Below are the components of that command:
96- `act.py`: is the script that runs the test
97-  -c acts_sanity_test_config: is the flag and name of the configuration file
98to be used in the test
99-  -tc IntegrationTest: is the name of the test case
100
101### Configuration Files
102To run tests, required information must be provided via a json-formatted
103text file. The required information includes a list of ***testbed*** configs.
104Each specifies the hardware, services, the path to the logs directory, and
105a list of paths where the python test case files are located. Below are the
106contents of a sample configuration file:
107
108```
109{   "_description": "This is an example skeleton test configuration file.",
110    "testbed":
111    [
112        {
113            "_description": "Sample testbed with no devices",
114            "name": "SampleTestBed"
115        }
116    ],
117    "logpath": "/tmp/logs",
118    "testpaths": ["../tests/sample"],
119    "custom_param1": {"favorite_food": "Icecream!"}
120}
121```
122The ***testpaths*** and ***logpath*** keys may alternately be supplied via the
123execution environment though the ACTS_TESTPATHS and ACTS_LOGPATH keys
124respectively. To specify multiple test paths, the key should follow
125standard a ':'-delimited format. Explicit keys in a configuration file will
126override any defaults provided by the environment.
127
128### Test Class
129Test classes are instantiated with a dictionary of “controllers”. The
130controllers dictionary contains all resources provided to the test class
131and are created based on the provided configuration file.
132
133Test classes must also contain an iterable member self.tests that lists the
134test case names within the class.  More on this is discussed after the
135following code snippet.
136
137```
138from acts.base_test import BaseTestClass
139
140class SampleTest(BaseTestClass):
141
142    def __init__(self, controllers):
143        BaseTestClass.__init__(self, controllers)
144        self.tests = (
145            "test_make_toast",
146        )
147
148    """Tests"""
149    def test_make_toast(self):
150        for ad in self.android_devices:
151            ad.droid.makeToast("Hello World.")
152        return True
153```
154By default all test cases listed in a Test Class\'s self.tests will be run.
155Using the syntax below will override the default behavior by executing only
156specific tests within a test class.
157
158The following will run a single test, test_make_toast:
159
160`$ act.py -c sample_config.txt -tb SampleTestBed -tc SampleTest:test_make_toast`
161
162Multiple tests may be specified with a comma-delimited list. The following
163will execute test_make_toast and test_make_bagel:
164
165- `$ act.py -c sample_config.txt -tb SampleTestBed -tc
166SampleTest:test_make_toast,test_make_bagel`
167