1# Atest Developer Workflow
2
3This document explains the practical steps for contributing code to atest.
4
5##### Table of Contents
61. [Identify the code you should work on](#identify-the-code-you-should-work-on)
72. [Working on the Python Code](#working-on-the-python-code)
83. [Working on the TradeFed Code](#working-on-the-tradefed-code)
94. [Working on the VTS10-TradeFed Code](#working-on-the-vts10-tradefed-code)
105. [Working on the Robolectric Code](#working-on-the-robolectric-code)
11
12
13## <a name="what-code">Identify the code you should work on</a>
14
15Atest is essentially a wrapper around various test runners. Because of
16this division, your first step should be to identify the code
17involved with your change. This will help determine what tests you write
18and run.  Note that the wrapper code is written in python, so we'll be
19referring to it as the "Python Code".
20
21##### The Python Code
22
23This code defines atest's command line interface.
24Its job is to translate user inputs into (1) build targets and (2)
25information needed for the test runner to run the test. It then invokes
26the appropriate test runner code to run the tests. As the tests
27are run it also parses the test runner's output into the output seen by
28the user. It uses Test Finder and Test Runner classes to do this work.
29If your contribution involves any of this functionality, this is the
30code you'll want to work on.
31
32<p>For more details on how this code works, checkout the following docs:
33
34 - [General Structure](./atest_structure.md)
35 - [Test Finders](./develop_test_finders.md)
36 - [Test Runners](./develop_test_runners.md)
37
38##### The Test Runner Code
39
40This is the code that actually runs the test. If your change
41involves how the test is actually run, you'll need to work with this
42code.
43
44Each test runner will have a different workflow. Atest currently
45supports the following test runners:
46- TradeFed
47- VTS10-TradeFed
48- Robolectric
49
50
51## <a name="working-on-the-python-code">Working on the Python Code</a>
52
53##### Where does the Python code live?
54
55The python code lives here: `tools/asuite/atest/`
56(path relative to android repo root)
57
58##### Writing tests
59
60Test files go in the same directory as the file being tested. The test
61file should have the same name as the file it's testing, except it
62should have "_unittests" appended to the name. For example, tests
63for the logic in `cli_translator.py` go in the file
64`cli_translator_unittests.py` in the same directory.
65
66
67##### Running tests
68
69Python tests are just python files executable by the Python interpreter.
70You can use atest to run all unit tests via:<br>
71
72```
73atest atest_unittests --host
74```
75
76Alternatively, it is possible to run ALL the python tests by executing the
77python script in the atest root dir:<br>
78
79```
80croot <atest_dir>
81./atest_run_unittests.py
82```
83
84To directly execute any individual unittest file, you'll need to first add
85atest to your PYTHONPATH:<br>
86
87```croot <atest_dir>
88PYTHONPATH=.:$PYTHONPATH test_finders/module_finder_unittest.py
89```
90
91All tests should be passing before you submit your change.
92
93## <a name="working-on-the-tradefed-code">Working on the TradeFed Code</a>
94
95##### Where does the TradeFed code live?
96
97The TradeFed code lives here:
98`tools/tradefederation/core/src/com/android/tradefed/` (path relative
99to android repo root).
100
101The `testtype/suite/AtestRunner.java` is the most important file in
102the TradeFed Code. It defines the TradeFed API used
103by the Python Code, specifically by
104`test_runners/atest_tf_test_runner.py`. This is the file you'll want
105to edit if you need to make changes to the TradeFed code.
106
107
108##### Writing tests
109
110Tradefed test files live in a parallel `/tests/` file tree here:
111`tools/tradefederation/core/tests/src/com/android/tradefed/`.
112A test file should have the same name as the file it's testing,
113except with the word "Test" appended to the end. <p>
114For example, the tests for `tools/tradefederation/core/src/com/android/tradefed/testtype/suite/AtestRunner.java`
115can be found in `tools/tradefederation/core/tests/src/com/android/tradefed/testtype/suite/AtestRunnerTest.java`.
116
117##### Running tests
118
119TradeFed itself is used to run the TradeFed unittests so you'll need
120to build TradeFed first. See the
121[TradeFed README](../../README.md) for information about setting up
122TradeFed. <p>
123There are so many TradeFed tests that you'll probably want to
124first run the test file your code change affected individually. The
125command to run an individual test file is:<br>
126
127```
128tradefed.sh run host -n --class <fully.qualified.ClassName>
129```
130
131Thus, to run all the tests in AtestRunnerTest.java, you'd enter:
132
133```
134tradefed.sh run host -n --class com.android.tradefed.testtype.suite.AtestRunnerTest
135```
136
137To run ALL the TradeFed unittests:<br>
138```
139croot tools/tradefederation/core
140javatests/run_tradefed_tests.sh
141```
142
143Before submitting code you should run all the TradeFed tests.
144
145## <a name="working-on-the-vts10-tradefed-code">Working on the VTS10-TradeFed Code</a>
146
147##### Where does the VTS10-TradeFed code live?
148
149The VTS10-Tradefed code lives here: `test/vts/tools/vts-tradefed/`
150(path relative to android repo root)
151
152##### Writing tests
153
154You shouldn't need to edit vts10-tradefed code, so there is no
155need to write vts10 tests. Reach out to the vts team
156if you need information on their unittests.
157
158##### Running tests
159
160Again, you shouldn't need to change vts10-tradefed code.
161
162## <a name="working-on-the-robolectric-code">Working on the Robolectric Code</a>
163
164##### Where does the Robolectric code live?
165
166The Robolectric code lives here: `prebuilts/misc/common/robolectric/4.3.1/`
167(path relative to android repo root)
168
169