Home | History | Annotate | Download | only in acts 
      1 # Android Comms Test Suite
      2 ACTS is a python-based test framework that is designed to be lightweight,
      3 pluggable, and easy to use. It initializes equipment and services associated
      4 to a test run, provides those resources to test classes, executes test cases,
      5 and generates test reports.
      6 
      7 ACTS follows the Google Open-source
      8 [Python Style Guide](https://google.github.io/styleguide/pyguide.html), and
      9 it is recommended for all new test cases.
     10 
     11 ## ACTS Execution Flow Overview
     12 Below is a high level view of the ACTS flow:
     13 1. Read configuration files
     14 2. Create controllers
     15 3. Sequentially execute test classes
     16 ```
     17 FooTest.setup_class()
     18 FooTest.setup_test()
     19 FooTest.test_A()
     20 FooTest.teardown_test()
     21 FooTest.setup_test()
     22 FooTest.test_B()
     23 FooTest.teardown_test()
     24 ....
     25 FooTest.teardown_class()
     26 BarTest.setup_class()
     27 ....
     28 ```
     29 4. Destroy controllers
     30 
     31 ## Preparing an Android Device
     32 ### Allow USB Debugging
     33 USB debugging must be enabled before a device can take commands from adb.
     34 To enable USB debugging, first enable developer mode.
     35 1. Go to Settings->About phone
     36 2. Tap Build number repeatedly until "You're a developer now" is displayed.
     37 
     38 In developer mode:
     39 1. Plug the device into a computer (host)
     40 2. Run `$adb devices`
     41 - A pop-up asking to allow the host to access the android device may be
     42 displayed. Check the "Always" box and click "Yes".
     43 
     44 ## ACTS Setup
     45 1. ACTS requires three python dependencies:
     46 - Python3.4
     47 - The setuptools package
     48 - The pyserial package
     49 2. From the ACTS directory, run setup
     50 - `$ sudo python3 setup.py develop`
     51 
     52 After installation, `act.py` and `flashutil.py` will be in usr/bin and can be
     53 called as command line utilities. Components in ACTS are importable under the
     54 package "acts." in Python3.4, for example:
     55 ```
     56 $ python3
     57 >>> from acts.controllers import android_device
     58 >>> device_list = android_device.get_all_instances()
     59 ```
     60 
     61 ## Verifying Setup
     62 To verify the host and device are ready, from the frameworks folder run:
     63 - `$ act.py -c sample_config.json -tb SampleTestBed -tc SampleTest`
     64 
     65 If the above command executed successfully, the ouput should look something
     66 similar to following:
     67 ```
     68 [SampleTestBed] 07-22 15:23:50.323 INFO ==========> SampleTest <==========
     69 [SampleTestBed] 07-22 15:23:50.327 INFO [Test Case] test_make_toast
     70 [SampleTestBed] 07-22 15:23:50.334 INFO [Test Case] test_make_toast PASS
     71 [SampleTestBed] 07-22 15:23:50.338 INFO Summary for test class SampleTest:
     72 Requested 1, Executed 1, Passed 1, Failed 0, Skipped 0
     73 [SampleTestBed] 07-22 15:23:50.338 INFO Summary for test run
     74 SampleTestBed@07-22-2015_1-23-44-096: Requested 1, Executed 1, Passed 1,
     75 Failed 0, Skipped 0
     76 ```
     77 By default, all logs are saved in `/tmp/logs`
     78 
     79 ## Breaking Down the Example
     80 Below are the components of the command run for the SampleTest:
     81 - `acts.py`: is the script that runs the test
     82 -  -c sample_config: is the flag and name of the configuration file to be used
     83 in the test
     84 -  -tb StampleTestBed: is the flag and name of the test bed to be used
     85 -  -tc SampleTest: is the name of the test case
     86 
     87 ### Configuration Files
     88 To run tests, required information must be provided via a json-formatted
     89 text file. The required information includes a list of testbed configs.
     90 Each specifies the hardware, services, the path to the logs directory, and
     91 a list of paths where the python test case files are located. Below are the
     92 contents of a sample configuration file:
     93 ```
     94 {   "_description": "This is an example skeleton test configuration file.",
     95     "testbed":
     96     [
     97         {
     98             "_description": "Sample testbed with no devices",
     99             "name": "SampleTestBed"
    100         }
    101     ],
    102     "logpath": "/tmp/logs",
    103     "testpaths": ["../tests/sample"],
    104     "custom_param1": {"favorite_food": "Icecream!"}
    105 }
    106 ```
    107 
    108 ### Test Class
    109 Test classes are instantiated with a dictionary of controllers. The
    110 controllers dictionary contains all resources provided to the test class
    111 and are created based on the provided configuration file.
    112 
    113 Test classes must also contain an iterable member self.tests that lists the
    114 test case names within the class.  More on this is discussed after the following
    115 code snippet.
    116 ```
    117 from acts.base_test import BaseTestClass
    118 
    119 class SampleTest(BaseTestClass):
    120 
    121     def __init__(self, controllers):
    122         BaseTestClass.__init__(self, controllers)
    123         self.tests = (
    124             "test_make_toast",
    125         )
    126 
    127     """Tests"""
    128     def test_make_toast(self):
    129         for ad in self.android_devices:
    130             ad.droid.makeToast("Hello World.")
    131         return True
    132 ```
    133 By default all test cases listed in a Test Class\'s self.tests will be run.
    134 Using the syntax below will override the default behavior by executing only
    135 specific tests within a test class.
    136 
    137 The following will run a single test, test_make_toast:
    138 `$ act.py -c sample_config.txt -tb SampleTestBed -tc SampleTest:test_make_toast`
    139 
    140 Multiple tests may be specified with a comma-delimited list. The following
    141 will execute test_make_toast and test_make_bagel:
    142 - `$ act.py -c sample_config.txt -tb SampleTestBed -tc
    143 SampleTest:test_make_toast,test_make_bagel`
    144