1## Test Module Config
2
3Some test modules may require customized setup and tear down steps that cannot
4be performed within test case itself. Typical examples may include:
5
6*   install other apks (in addition to the test apk)
7*   push some files to the device
8*   run commands (e.g. adb shell pm ...)
9
10In the past, component teams usually resort to writing a host side test to
11perform such tasks, which requires understanding of TradeFederation harness
12and typically increases the complexity of a test module .
13
14Borrowing from CTS, we introduced the concept of test module config to support
15such tasks, the common tasks list above can be achieved by just a few lines of
16config. For maximum flexibility, you can even implement your own target
17preparer, as defined by [ITargetPreparer]
18(https://source.android.com/reference/com/android/tradefed/targetprep/ITargetPreparer.html)
19or [ITargetCleaner]
20(https://source.android.com/reference/com/android/tradefed/targetprep/ITargetCleaner.html),
21and configure them to use in your own test module config.
22
23A test module config for a test module is a required XML file added to the top
24level module source folder, named ‘AndroidTest.xml’. The XML follows the format
25of a configuration file used by TradeFederation test automation harness.
26Currently the main tags handled via the test module configs are the “target_preparer” and
27"test" tags.
28
29## Target Preparers
30A “target_preparer” tag, as the name suggests, defines a target preparer
31(see [ITargetPreparer](https://source.android.com/reference/com/android/tradefed/targetprep/ITargetPreparer.html))
32that offers a setup method, which gets called before the test module is executed
33for testing; and if the class referenced in the “target_preparer” tag also
34implements
35[ITargetCleaner](https://source.android.com/reference/com/android/tradefed/targetprep/ITargetCleaner.html),
36its teardown method will be invoked after the test module has finished.
37
38To use the built-in common module config, add a new file ‘AndroidTest.xml’ at
39the top level folder for your test module, and populate it with the following
40content:
41
42```xml
43<?xml version="1.0" encoding="utf-8"?>
44<!-- [insert standard AOSP copyright here] -->
45<configuration description="Test module config for Foo">
46<!-- insert options here -->
47</configuration>
48```
49
50As an example, we can add the following option tags (at the “insert” comment
51above):
52
53```xml
54    <target_preparer class="com.android.tradefed.targetprep.RunCommandTargetPreparer">
55        <option name="run-command" value="settings put secure accessibility_enabled 1" />
56        <option name="teardown-command" value="settings put secure accessibility_enabled 0" />
57    </target_preparer>
58```
59
60The options will configure the test harness to:
61
621.  before test module is invoked, execute shell command “settings put secure
63    accessibility_enabled 1” on device
642.  after test module is finished, execute shell command “settings put secure
65    accessibility_enabled 0”
66
67In this particular example, accessibility is enabled/disabled before/after the
68test module execution, respectively. With a simple example demonstrated, it’s
69necessary to cover more details on how the “option” tag is used. As shown above,
70the tag can have two attributes: name, value. The name attribute indicated the
71name of the option, and is further broken down into two parts separated by a
72colon: short name for the preparer, and the actual option name offered by the
73preparer. The exact purpose of value field is dependent on how preparer defined
74the option: it can be a string, a number, a boolean, or even a file path etc. In
75the example above, name “run-command:run-command” means that we are setting
76value for the option “run-command” defined by a target preparer with short name
77“run-command”; and name “run-command:teardown-command” means that we are setting
78value for the option “teardown-command” also defined by the same target preparer
79with short name “run-command”. Here's a summary of the 3 common target
80preparers:
81
82*   class name: [PushFilePreparer](https://android.googlesource.com/platform/tools/tradefederation/+/master/src/com/android/tradefed/targetprep/PushFilePreparer.java)
83
84    *   **short name**: push-file
85    *   **function**: pushes arbitrary files under test case folder into
86        destination on device
87    *   **notes**:
88        *   this preparer can push from folder to folder, or file to file; that
89            is, you cannot push a file under a folder on device: you must
90            specify the destination filename under that folder as well
91    *   **options**:
92        *   **push:** A push-spec, formatted as
93            '`/path/to/srcfile.txt->/path/to/destfile.txt`' or
94            '`/path/to/srcfile.txt->/path/to/destdir/`'. May be repeated
95            This path may be relative to the test module directory or the out
96            directory itself.
97        *   **post-push: **A command to run on the device (with \``adb shell
98            <your command>`\`) after all pushes have been attempted. Typical use
99            case would be using chmod for permissions
100
101*   class name: [InstallApkSetup](https://android.googlesource.com/platform/tools/tradefederation/+/master/src/com/android/tradefed/targetprep/InstallApkSetup.java)
102
103    *   **short name:**install-apk
104    *   **function:** pushes arbitrary apk files under into destination on
105        device
106    *   **options:**
107        *   **test-file-name:** the name of the apk to be installed on to
108            device.
109        *   **install-arg:** Additional arguments to be passed to the pm install
110            command, including leading dash, e.g. “-d". May be repeated
111
112*   class name: [RunCommandTargetPreparer](https://android.googlesource.com/platform/tools/tradefederation/+/master/src/com/android/tradefed/targetprep/RunCommandTargetPreparer.java)
113
114    *   **short name:** run-command
115    *   **function:** executes arbitrary shell commands before or after test
116        module execution
117    *   **options:**
118        *   **run-command:**adb shell command to run. May be repeated
119        *   **teardown-command:**adb shell command to run during teardown phase.
120            May be repeated
121
122## Test Class
123A test class is the TradeFederation class to use to execute the test.
124
125```xml
126<test class="com.android.tradefed.testtype.AndroidJUnitTest">
127  <option name="package" value="android.test.example.helloworld"/>
128  <option name="runner" value="android.support.test.runner.AndroidJUnitRunner"/>
129</test>
130```
131
132Here are 3 common test classes:
133
134*   class name: [GTest](https://android.googlesource.com/platform/tools/tradefederation/+/master/src/com/android/tradefed/testtype/GTest.java)
135
136    *   **short name:** gtest
137    *   **function:** A Test that runs a native test package on given device.
138    *   **options:**
139        *   **native-test-device-path:**The path on the device where native tests are located.
140
141*   class name: [InstrumentationTest](https://android.googlesource.com/platform/tools/tradefederation/+/master/src/com/android/tradefed/testtype/InstrumentationTest.java)
142
143    *   **short name:** instrumentation
144    *   **function:** A Test that runs an instrumentation test package on given device
145    *   **options:**
146        *   **package:**The manifest package name of the Android test application to run.
147        *   **class:**The test class name to run.
148        *   **method:**The test method name to run.
149
150*   class name: [AndroidJUnitTest](https://android.googlesource.com/platform/tools/tradefederation/+/master/src/com/android/tradefed/testtype/AndroidJUnitTest.java)
151
152    *   **function:** A Test that runs an instrumentation test package on given
153                      device using the android.support.test.runner.AndroidJUnitRunner
154                      This is the main way to execute an instrumentation test.
155
156