1# test\_droid: Quick Primer
2
3## References
4
5[Autotest Best Practices](best-practices.md)
6
7[test\_that Basic Usage](test-that.md)
8
9## Objective
10This document contains instructions for Brillo/Android developers interested in
11running automated integration tests at their desk.
12
13## Usage
14The autotest repository, the `test_droid` tool, and all tests are checked out
15in both AOSP and internal Android trees at external/autotest.  You need a copy
16of the autotest source code and an `adb` binary in your PATH to run tests.
17
18### Running tests against a single local device under test
19Once you have a local copy of the autotest source, you can easily run tests
20against a DUT connected directly to your workstation via a USB cable. Please
21note your first time running `test_droid` it will download and install a number
22of required packages locally into your autotest checkout.
23
24Run site\_utils/test\_droid.py from your autotest checkout to launch a test
25against a given DUT:
26
27```
28 $ ./site_utils/test_droid.py <Test Name>
29```
30
31For example, to run the brillo\_WhitelistedGtests test:
32
33```
34 $ ./site_utils/test_droid.py brillo_WhitelistedGtests
35```
36
37`test_droid` can run multiple tests at once:
38
39```
40 $ ./site_utils/test_droid.py brillo_WhitelistedGtests brillo_KernelVersionTest
41```
42
43As well as test suites:
44
45```
46 $ ./site_utils/test_droid.py suite:brillo-bvt
47```
48
49#### Selecting a specific device
50If you have more than one device connected, you'll have to specify its serial
51number.  First, look it up:
52
53```
54 $ adb devices
55* daemon started successfully *
56List of devices attached
577d52318 device
58```
59
60Then use it when running:
61
62```
63 $ ./site_utils/test_droid.py -s 7d52318 brillo_WhitelistedGtests
64```
65
66### Running tests that require multiple devices under test
67Autotest now supports the concept of testbeds, which are multiple devices being
68controlled by a single test. `test_droid` supports running these tests
69by specifying a comma separated list of serials as the test device:
70
71```
72 $ adb devices
73List of devices attached
74emulator-5554 device
757d52318 device
76
77 $ ./site_utils/test_droid.py -s emulator-5554,7d52318 testbed_DummyTest
78```
79
80### Running tests against a remote device under test
81`test_droid` can run tests against devices connected to a remote server.  This
82requires passwordless SSH access from the workstation to the remote server.
83If no username is specified, `test_droid` will try the root and adb users.
84If using the adb user, make sure it has passwordless sudo
85rights to run the adb and fastboot commands. You can specify a
86different user in the remote host name (the same passwordless requirement
87applies).
88
89The easiest way to set this up is to use the
90[Chrome OS testing keys](https://www.chromium.org/chromium-os/testing/autotest-developer-faq/ssh-test-keys-setup).
91Add to your SSH config an entry that looks like the following:
92
93```
94HostName <Remote Server IP or Hostname>
95  Port 9222
96  User root
97  CheckHostIP no
98  StrictHostKeyChecking no
99  IdentityFile ~/.ssh/testing_rsa
100  Protocol 2
101```
102
103To run the test:
104
105```
106 $ ./site_utils/test_droid.py \
107       -r <Remote Server IP or Hostname> \
108       <Test Name>
109
110 $ ./site_utils/test_droid.py \
111       -r <User>@<Remote Server IP or Hostname> \
112       <Test Name>
113
114 $ ./site_utils/test_droid.py -r 100.96.48.119 suite:brillo-bvt
115```
116
117### Advanced: Uploading Commits for Review
118Currently Autotest in AOSP is read-only, so you cannot use repo upload to
119upload code changes. If you do edit or add a new test, make a commit and upload
120it to https://chromium-review.googlesource.com.
121
122Due to the way Android does its automerging, the AOSP mirror of Autotest cannot
123be uploaded directly back to the Chromium upstream because the upstream does not
124contain the merge commits.  It will also reject the automerge committer ID.
125To work around this, if you need to upload a commit to Autotest, you first have
126to fetch and check out the upstream branch before making your changes:
127
128```
129 $ git remote add -t master cros \
130     https://chromium.googlesource.com/chromiumos/third_party/autotest
131 $ git fetch cros
132 $ git checkout cros/master
133 $ git checkout -b <local branch name>
134 $ git branch --set-upstream-to=cros/master
135```
136
137Be sure to run pylint on every file you touch:
138
139```
140 $ ./utils/run_pylint.py <file name>
141```
142
143Run autotest unittests (which usually requires external packages):
144
145```
146 $ utils/build_externals.py  # install any missing os packages with apt-get
147 $ utils/unittest_suite.py
148```
149
150Then upload your commit for review:
151
152```
153 $ git push cros <local branch name>:refs/for/master
154```
155
156## Limitations
157
158Testing on Brillo/Android (and `test_droid` by extension) is currently limited
159to server-side tests, which run on an autotest server and control a
160Brillo/Android DUT (device under test) via remote command execution.  In the
161context of `test_droid`, the test logic is running on your development machine,
162and controlling devices with commands executed via `adb`.
163
164`test_droid` does not support the autoupdate end-to-end test. For instructions
165on how to run this test please refer to the Running Brillo/Android Autoupdate
166End-to-End Test doc.
167