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