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