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. You have to do this even if your "out" directory is a symlink
 127 pointing to "out_android".
 128
 129 ## INSTALL\_FAILED\_CONTAINER\_ERROR or INSTALL\_FAILED\_INSUFFICIENT\_STORAGE
 130
 131 If you see this error when test\_runner.py is attempting to deploy the test
 132 binaries to the AVD emulator, you may need to resize your userdata partition
 133 with the following commands:
 134
 135 ```shell
 136 # Resize userdata partition to be 1G resize2fs
 137 android_emulator_sdk/sdk/system-images/android-19/x86/userdata.img 1G
 138
 139 # Set filesystem parameter to continue on errors; Android doesn't like some
 140 # things e2fsprogs does.
 141 tune2fs -e continue
 142 android_emulator_sdk/sdk/system-images/android-19/x86/userdata.img
 143 ```
 144
 145 ## Symbolizing Crashes
 146
 147 Crash stacks are logged and can be viewed using adb logcat. To symbolize the
 148 traces, pipe the output through
 149 `third_party/android_platform/development/scripts/stack`. If you build in an
 150 output directory other than "out", pass
 151 `--chrome-symbols-dir=out_directory/{Debug,Release}/lib` to the script as well.
 152
 153 ## Gtests
 154
 155 ```shell
 156 # Build a test suite
 157 ninja -C out/Release content_unittests_apk
 158
 159 # Run a test suite
 160 build/android/test_runner.py gtest -s content_unittests --release -vvv
 161
 162 # Run a subset of tests
 163 build/android/test_runner.py gtest -s content_unittests --release -vvv \
 164 --gtest-filter ByteStreamTest.*
 165 ```
 166
 167 ## Instrumentation Tests
 168
 169 In order to run instrumentation tests, you must leave your device screen ON and
 170 UNLOCKED. Otherwise, the test will timeout trying to launch an intent.
 171 Optionally you can disable screen lock under Settings -> Security -> Screen Lock
 172 -> None.
 173
 174 Next, you need to build the app, build your tests, install the application APK,
 175 and then run your tests (which will install the test APK automatically).
 176
 177 Examples:
 178
 179 ContentShell tests:
 180
 181 ```shell
 182 # Build the code under test
 183 ninja -C out/Release content_shell_apk
 184
 185 # Build the tests themselves
 186 ninja -C out/Release content_shell_test_apk
 187
 188 # Install the code under test
 189 build/android/adb_install_apk.py out/Release/apks/ContentShell.apk
 190
 191 # Run the test (will automagically install the test APK)
 192 build/android/test_runner.py instrumentation --test-apk=ContentShellTest \
 193 --isolate-file-path content/content_shell_test_apk.isolate --release -vv
 194 ```
 195
 196 ChromePublic tests:
 197
 198 ```shell
 199 # Build the code under test
 200 ninja -C out/Release chrome_public_apk
 201
 202 # Build the tests themselves
 203 ninja -C out/Release chrome_public_test_apk
 204
 205 # Install the code under test
 206 build/android/adb_install_apk.py out/Release/apks/ChromePublic.apk
 207
 208 # Run the test (will automagically install the test APK)
 209 build/android/test_runner.py instrumentation --test-apk=ChromePublicTest \
 210 --isolate-file-path chrome/chrome_public_test_apk.isolate --release -vv
 211 ```
 212
 213 AndroidWebView tests:
 214
 215 ```shell
 216 ninja -C out/Release android_webview_apk
 217 ninja -C out/Release android_webview_test_apk
 218 build/android/adb_install_apk.py out/Release/apks/AndroidWebView.apk \
 219 build/android/test_runner.py instrumentation --test-apk=AndroidWebViewTest \
 220 --test_data webview:android_webview/test/data/device_files --release -vvv
 221 ```
 222
 223 Use adb\_install\_apk.py to install the app under test, then run the test
 224 command. In order to run a subset of tests, use -f to filter based on test
 225 class/method or -A/-E to filter using annotations.
 226
 227 Filtering examples:
 228
 229 ```shell
 230 # Run a test suite
 231 build/android/test_runner.py instrumentation --test-apk=ContentShellTest
 232
 233 # Run a specific test class
 234 build/android/test_runner.py instrumentation --test-apk=ContentShellTest -f \
 235 AddressDetectionTest
 236
 237 # Run a specific test method
 238 build/android/test_runner.py instrumentation --test-apk=ContentShellTest -f \
 239 AddressDetectionTest#testAddressLimits
 240
 241 # Run a subset of tests by size (Smoke, SmallTest, MediumTest, LargeTest,
 242 # EnormousTest)
 243 build/android/test_runner.py instrumentation --test-apk=ContentShellTest -A \
 244 Smoke
 245
 246 # Run a subset of tests by annotation, such as filtering by Feature
 247 build/android/test_runner.py instrumentation --test-apk=ContentShellTest -A \
 248 Feature=Navigation
 249 ```
 250
 251 You might want to add stars `*` to each as a regular expression, e.g.
 252 `*`AddressDetectionTest`*`
 253
 254 ## Running Blink Layout Tests
 255
 256 See
 257 https://sites.google.com/a/chromium.org/dev/developers/testing/webkit-layout-tests
 258
 259 ## Running GPU tests
 260
 261 (e.g. the "Android Debug (Nexus 7)" bot on the chromium.gpu waterfall)
 262
 263 See http://www.chromium.org/developers/testing/gpu-testing for details. Use
 264 --browser=android-content-shell. Examine the stdio from the test invocation on
 265 the bots to see arguments to pass to src/content/test/gpu/run\_gpu\_test.py.