docs/android_test_instructions.md

   1 # Android Test Instructions
   2
   3 Device Setup Tests are runnable on physical devices or emulators. See the
   4 instructions below for setting up either a physical device or an emulator.
   5
   6 [TOC]
   7
   8 ## Physical Device Setup **ADB Debugging**
   9
  10 In order to allow the ADB to connect to the device, you must enable USB
  11 debugging:
  12
  13 *   Before Android 4.1 (Jelly Bean):
  14     *   Go to "System Settings"
  15     *   Go to "Developer options"
  16     *   Check "USB debugging".
  17     *   Un-check "Verify apps over USB".
  18 *   On Jelly Bean, developer options are hidden by default. To unhide them:
  19     *   Go to "About phone"
  20     *   Tap 10 times on "Build number"
  21     *   The "Developer options" menu will now be available.
  22     *   Check "USB debugging".
  23     *   Un-check "Verify apps over USB".
  24
  25 ### Screen
  26
  27 You MUST ensure that the screen stays on while testing: `adb shell svc power
  28 stayon usb` Or do this manually on the device: Settings -> Developer options
  29 -> Stay Awake.
  30
  31 If this option is greyed out, stay awake is probably disabled by policy. In that
  32 case, get another device or log in with a normal, unmanaged account (because the
  33 tests will break in exciting ways if stay awake is off).
  34
  35 ### Enable Asserts!
  36
  37     adb shell setprop debug.assert 1
  38
  39 ### Disable Verify Apps
  40
  41 You may see a dialog like
  42 [this one](http://www.samsungmobileusa.com/simulators/ATT_GalaxyMega/mobile/screens/06-02_12.jpg),
  43 which states, _Google may regularly check installed apps for potentially harmful
  44 behavior._ This can interfere with the test runner. To disable this dialog, run:
  45 `adb shell settings put global package_verifier_enable 0`
  46
  47 ## Emulator Setup
  48
  49 ### Option 1:
  50
  51 Use an emulator (i.e. Android Virtual Device, AVD): Enabling Intel's
  52 Virtualizaton support provides the fastest, most reliable emulator configuration
  53 available (i.e. x86 emulator with GPU acceleration and KVM support).
  54
  55 1.  Enable Intel Virtualization support in the BIOS.
  56
  57 2.  Set up your environment:
  58
  59     ```shell
  60     . build/android/envsetup.sh
  61     ```
  62
  63 3.  Install emulator deps:
  64
  65     ```shell
  66     build/android/install_emulator_deps.py --api-level=19
  67     ```
  68
  69     This script will download Android SDK and place it a directory called
  70     android\_tools in the same parent directory as your chromium checkout. It
  71     will also download the system-images for the emulators (i.e. arm and x86).
  72     Note that this is a different SDK download than the Android SDK in the
  73     chromium source checkout (i.e. src/third\_party/android\_emulator\_sdk).
  74
  75 4.  Run the avd.py script. To start up _num_ emulators use -n. For non-x86 use
  76     --abi.
  77
  78     ```shell
  79     build/android/avd.py --api-level=19
  80     ```
  81
  82     This script will attempt to use GPU emulation, so you must be running the
  83     emulators in an environment with hardware rendering available. See
  84     `avd.py --help` for more details.
  85
  86 ### Option 2:
  87
  88 Alternatively, you can create an run your own emulator using the tools provided
  89 by the Android SDK. When doing so, be sure to enable GPU emulation in hardware
  90 settings, since Chromium requires it to render.
  91
  92 ## Building Tests
  93
  94 It may not be immediately obvious where your test code gets compiled to, so here
  95 are some general rules:
  96
  97 *  If your test code lives under /content, it will probably be built as part of
  98    the content_shell_test_apk
  99 *  If your test code lives under /chrome (or higher), it will probably be built
 100    as part of the chrome_public_test_apk
 101 *  (Please fill in more details here if you know them).
 102
 103    NB: We used to call the chrome_public_test_apk the
 104    chromium_shell_test_apk. There may still be references to this kicking
 105    around, but wherever you see chromium_shell_test you should replace with
 106    chrome_public_test.
 107
 108 Once you know what to build, just do it like you normally would build anything
 109 else, e.g.: `ninja -C out/Release chrome_public_test_apk`
 110
 111 ## Running Tests
 112
 113 All functional tests are run using `build/android/test_runner.py`.
 114 Tests are sharded across all attached devices. In order to run tests, call:
 115 `build/android/test_runner.py <test_type> [options]`
 116 For a list of valid test types, see `test_runner.py --help`. For
 117 help on a specific test type, run `test_runner.py <test_type> --help`.
 118
 119 The commands used by the buildbots are printed in the logs. Look at
 120 http://build.chromium.org/ to duplicate the same test command as a particular
 121 builder.
 122
 123 If you build in an output directory other than "out", you may have to tell
 124 test\_runner.py where you place it. Say you build your android code in
 125 out\_android, then do `export CHROMIUM_OUT_DIR=out_android` before running the
 126 command below.
 127
 128 ## INSTALL\_FAILED\_CONTAINER\_ERROR or INSTALL\_FAILED\_INSUFFICIENT\_STORAGE
 129
 130 If you see this error when test\_runner.py is attempting to deploy the test
 131 binaries to the AVD emulator, you may need to resize your userdata partition
 132 with the following commands:
 133
 134 ```shell
 135 # Resize userdata partition to be 1G resize2fs
 136 android_emulator_sdk/sdk/system-images/android-19/x86/userdata.img 1G
 137
 138 # Set filesystem parameter to continue on errors; Android doesn't like some
 139 # things e2fsprogs does.
 140 tune2fs -e continue
 141 android_emulator_sdk/sdk/system-images/android-19/x86/userdata.img
 142 ```
 143
 144 ## Symbolizing Crashes
 145
 146 Crash stacks are logged and can be viewed using adb logcat. To symbolize the
 147 traces, pipe the output through
 148 `third_party/android_platform/development/scripts/stack`. If you build in an
 149 output directory other than "out", pass
 150 `--chrome-symbols-dir=out_directory/{Debug,Release}/lib` to the script as well.
 151
 152 ## Gtests
 153
 154 ```shell
 155 # Build a test suite
 156 ninja -C out/Release content_unittests_apk
 157
 158 # Run a test suite
 159 build/android/test_runner.py gtest -s content_unittests --release -vvv
 160
 161 # Run a subset of tests
 162 build/android/test_runner.py gtest -s content_unittests --release -vvv \
 163 --gtest-filter ByteStreamTest.*
 164 ```
 165
 166 ## Instrumentation Tests
 167
 168 In order to run instrumentation tests, you must leave your device screen ON and
 169 UNLOCKED. Otherwise, the test will timeout trying to launch an intent.
 170 Optionally you can disable screen lock under Settings -> Security -> Screen Lock
 171 -> None.
 172
 173 Next, you need to build the app, build your tests, install the application APK,
 174 and then run your tests (which will install the test APK automatically).
 175
 176 Examples:
 177
 178 ContentShell tests:
 179
 180 ```shell
 181 # Build the code under test
 182 ninja -C out/Release content_shell_apk
 183
 184 # Build the tests themselves
 185 ninja -C out/Release content_shell_test_apk
 186
 187 # Install the code under test
 188 build/android/adb_install_apk.py out/Release/apks/ContentShell.apk
 189
 190 # Run the test (will automagically install the test APK)
 191 build/android/test_runner.py instrumentation --test-apk=ContentShellTest \
 192 --isolate-file-path content/content_shell_test_apk.isolate --release -vv
 193 ```
 194
 195 ChromePublic tests:
 196
 197 ```shell
 198 # Build the code under test
 199 ninja -C out/Release chrome_public_apk
 200
 201 # Build the tests themselves
 202 ninja -C out/Release chrome_public_test_apk
 203
 204 # Install the code under test
 205 build/android/adb_install_apk.py out/Release/apks/ChromePublic.apk
 206
 207 # Run the test (will automagically install the test APK)
 208 build/android/test_runner.py instrumentation --test-apk=ChromePublicTest \
 209 --isolate-file-path chrome/chrome_public_test_apk.isolate --release -vv
 210 ```
 211
 212 AndroidWebView tests:
 213
 214 ```shell
 215 ninja -C out/Release android_webview_apk
 216 ninja -C out/Release android_webview_test_apk
 217 build/android/adb_install_apk.py out/Release/apks/AndroidWebView.apk \
 218 build/android/test_runner.py instrumentation --test-apk=AndroidWebViewTest \
 219 --test_data webview:android_webview/test/data/device_files --release -vvv
 220 ```
 221
 222 Use adb\_install\_apk.py to install the app under test, then run the test
 223 command. In order to run a subset of tests, use -f to filter based on test
 224 class/method or -A/-E to filter using annotations.
 225
 226 Filtering examples:
 227
 228 ```shell
 229 # Run a test suite
 230 build/android/test_runner.py instrumentation --test-apk=ContentShellTest
 231
 232 # Run a specific test class
 233 build/android/test_runner.py instrumentation --test-apk=ContentShellTest -f \
 234 AddressDetectionTest
 235
 236 # Run a specific test method
 237 build/android/test_runner.py instrumentation --test-apk=ContentShellTest -f \
 238 AddressDetectionTest#testAddressLimits
 239
 240 # Run a subset of tests by size (Smoke, SmallTest, MediumTest, LargeTest,
 241 # EnormousTest)
 242 build/android/test_runner.py instrumentation --test-apk=ContentShellTest -A \
 243 Smoke
 244
 245 # Run a subset of tests by annotation, such as filtering by Feature
 246 build/android/test_runner.py instrumentation --test-apk=ContentShellTest -A \
 247 Feature=Navigation
 248 ```
 249
 250 You might want to add stars `*` to each as a regular expression, e.g.
 251 `*`AddressDetectionTest`*`
 252
 253 ## Running Blink Layout Tests
 254
 255 See
 256 https://sites.google.com/a/chromium.org/dev/developers/testing/webkit-layout-tests
 257
 258 ## Running GPU tests
 259
 260 (e.g. the "Android Debug (Nexus 7)" bot on the chromium.gpu waterfall)
 261
 262 See http://www.chromium.org/developers/testing/gpu-testing for details. Use
 263 --browser=android-content-shell. Examine the stdio from the test invocation on
 264 the bots to see arguments to pass to src/content/test/gpu/run\_gpu\_test.py.