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 VTS-TradeFed Code](#working-on-the-vts-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- VTS-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/tradefederation/core/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 run ALL the python tests by executing this bash script in the
71atest root dir: `./run_atest_unittests.sh`. Alternatively, you can
72directly execute any individual unittest file. However, you'll need to
73first add atest to your PYTHONPATH via entering in your terminal:
74`PYTHONPATH=<atest_dir>:$PYTHONPATH`.
75
76All tests should be passing before you submit your change.
77
78## <a name="working-on-the-tradefed-code">Working on the TradeFed Code</a>
79
80##### Where does the TradeFed code live?
81
82The TradeFed code lives here:
83`tools/tradefederation/core/src/com/android/tradefed/` (path relative
84to android repo root).
85
86The `testtype/suite/AtestRunner.java` is the most important file in
87the TradeFed Code. It defines the TradeFed API used
88by the Python Code, specifically by
89`test_runners/atest_tf_test_runner.py`. This is the file you'll want
90to edit if you need to make changes to the TradeFed code.
91
92
93##### Writing tests
94
95Tradefed test files live in a parallel `/tests/` file tree here:
96`tools/tradefederation/core/tests/src/com/android/tradefed/`.
97A test file should have the same name as the file it's testing,
98except with the word "Test" appended to the end. <p>
99For example, the tests for `tools/tradefederation/core/src/com/android/tradefed/testtype/suite/AtestRunner.java`
100can be found in `tools/tradefederation/core/tests/src/com/android/tradefed/testtype/suite/AtestRunnerTest.java`.
101
102##### Running tests
103
104TradeFed itself is used to run the TradeFed unittests so you'll need
105to build TradeFed first. See the
106[TradeFed README](../../README.md) for information about setting up
107TradeFed. <p>
108There are so many TradeFed tests that you'll probably want to
109first run the test file your code change affected individually. The
110command to run an individual test file is:<br>
111
112`tradefed.sh run host -n --class <fully.qualified.ClassName>`
113
114Thus, to run all the tests in AtestRunnerTest.java, you'd enter:
115
116`tradefed.sh run host -n --class com.android.tradefed.testtype.suite.AtestRunnerTest`
117
118To run ALL the TradeFed unittests, enter:
119`./tools/tradefederation/core/tests/run_tradefed_tests.sh`
120(from android repo root)
121
122Before submitting code you should run all the TradeFed tests.
123
124## <a name="working-on-the-vts-tradefed-code">Working on the VTS-TradeFed Code</a>
125
126##### Where does the VTS-TradeFed code live?
127
128The VTS-Tradefed code lives here: `test/vts/tools/vts-tradefed/`
129(path relative to android repo root)
130
131##### Writing tests
132
133You shouldn't need to edit vts-tradefed code, so there is no
134need to write vts-tradefed tests. Reach out to the vts team
135if you need information on their unittests.
136
137##### Running tests
138
139Again, you shouldn't need to change vts-tradefed code.
140
141## <a name="working-on-the-robolectric-code">Working on the Robolectric Code</a>
142
143##### Where does the Robolectric code live?
144
145The Robolectric code lives here: `prebuilts/misc/common/robolectric/3.6.1/`
146(path relative to android repo root)
147
148##### Writing tests
149
150You shouldn't need to edit this code, so no need to write tests.
151
152##### Running tests
153
154Again, you shouldn't need to edit this code, so no need to run test.
155