1# test\_droid: Quick Primer
2
3## References
4[Autotest Developer Guide](https://www.chromium.org/chromium-os/testing/autotest-user-doc)
5
6[test\_that Basic Usage](docs/test-that.md)
7
8## Objective
9This document contains instructions for Brillo/Android developers interested in
10running basic automated integration tests at their desk.  Developers can run
11existing autotest tests as well as write their own.  Testing on Brillo/Android
12is currently limited to server-side tests, which run on an autotest server and
13control a Brillo/Android DUT (device under test) via remote command execution.
14Running client-side autotest tests requires Python on the DUT and isn’t
15currently supported.  `test_droid` does not support the autoupdate end-to-end
16test, for instructions on how to run this test please refer to the Running
17Brillo/Android Autoupdate End-to-End Test doc.
18
19## Usage
20The autotest repository is checked out in both AOSP and internal manifests at
21external/autotest.
22
23### Running tests against a single local device under test
24Once you have a local copy of the autotest source, you can easily run tests
25against a DUT connected directly to your workstation via a USB cable. Please
26note your first time running `test_droid` it will download and install a number
27of required packages locally into your autotest checkout.
28
29First lookup the device serial number:
30
31```
32 $ adb devices
33* daemon started successfully *
34List of devices attached
357d52318 device
36```
37
38Run site\_utils/test\_droid.py from your autotest checkout to launch a test
39against a given DUT:
40
41```
42 $ ./site_utils/test_droid.py <DUT Serial Number> <Test Name>
43```
44
45For example, to run the brillo\_WhitelistedGtests test:
46
47```
48 $ ./site_utils/test_droid.py 7d52318 brillo_WhitelistedGtests
49```
50
51`test_droid` can run multiple tests at once:
52
53```
54 $ ./site_utils/test_droid.py 7d52318 \
55      brillo_WhitelistedGtests brillo_KernelVersionTest
56```
57
58As well as test suites:
59
60```
61 $ ./site_utils/test_droid.py 7d52318 suite:brillo-bvt
62```
63
64
65### Running tests that require multiple devices under test
66Autotest now supports the concept of testbeds, which are multiple devices being
67controlled by a single test. `test_droid` supports running these tests
68by specifying a comma separated list of serials as the test device:
69
70```
71 $ adb devices
72List of devices attached
73emulator-5554 device
747d52318 device
75
76 $ ./site_utils/test_droid.py emulator-5554,7d52318 testbed_DummyTest
77```
78
79### Running tests against a remote device under test
80`test_droid` can run tests against devices connected to a remote server.  This
81requires passwordless SSH access from the workstation to the remote server.
82If no username is specified, `test_droid` will try the root and adb users.
83If using the adb user, make sure it has passwordless sudo
84rights to run the adb and fastboot commands. You can specify a
85different user in the remote host name (the same passwordless requirement
86applies).
87
88The easiest way to set this up is to use the
89[Chrome OS testing keys](https://www.chromium.org/chromium-os/testing/autotest-developer-faq/ssh-test-keys-setup).
90Add to your SSH config an entry that looks like the following:
91
92```
93HostName <Remote Server IP or Hostname>
94  Port 9222
95  User root
96  CheckHostIP no
97  StrictHostKeyChecking no
98  IdentityFile ~/.ssh/testing_rsa
99  Protocol 2
100```
101
102To run the test:
103
104```
105 $ ./site_utils/test_droid.py \
106       -r <Remote Server IP or Hostname> <Serial Number> \
107       <Test Name>
108
109 $ ./site_utils/test_droid.py \
110       -r <User>@<Remote Server IP or Hostname> \
111       <Serial Number> <Test Name>
112
113 $ ./site_utils/test_droid.py -r 100.96.48.119 7d52318 suite:brillo-bvt
114
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
122Be sure to run pylint on every file you touch:
123
124```
125$ ./utils/run_pylint.py <file name>
126```
127
128Then upload your commit for review:
129
130```
131 $ git push https://chromium.googlesource.com/chromiumos/third_party/autotest \
132     <local branch name>:refs/for/master
133```
134