WIP: Migrate Wiki content over to src/docs

docs/android_test_instructions.md

Index: docs/android_test_instructions.md
diff --git a/docs/android_test_instructions.md b/docs/android_test_instructions.md
new file mode 100644
index 0000000000000000000000000000000000000000..47959e5aa7e6ec29a3b245331eda6885071a0b29
--- /dev/null
+++ b/docs/android_test_instructions.md
@@ -0,0 +1,262 @@
+# Android Test Instructions
+
+Device Setup Tests are runnable on physical devices or emulators. See the
+instructions below for setting up either a physical device or an emulator.
+
+[TOC]
+
+## Physical Device Setup **ADB Debugging**
+
+In order to allow the ADB to connect to the device, you must enable USB
+debugging:
+  * Before Android 4.1 (Jelly Bean):
+      * Go to "System Settings"
+      * Go to "Developer options"
+      * Check "USB debugging".
+      * Un-check "Verify apps over USB".
+  * On Jelly Bean, developer options are hidden by default. To unhide them:
+      * Go to "About phone"
+      * Tap 10 times on "Build number"
+      * The "Developer options" menu will now be available.
+      * Check "USB debugging".
+      * Un-check "Verify apps over USB".
+
+### Screen
+
+You MUST ensure that the screen stays on while testing: `adb shell svc power
+stayon usb` Or do this manually on the device: Settings -> Developer options
+-> Stay Awake.
+
+If this option is greyed out, stay awake is probably disabled by policy. In that
+case, get another device or log in with a normal, unmanaged account (because the
+tests will break in exciting ways if stay awake is off).
+
+### Enable Asserts!
+
+`adb shell setprop debug.assert 1`
+
+### Disable Verify Apps
+
+You may see a dialog like
+[this one](http://www.samsungmobileusa.com/simulators/ATT_GalaxyMega/mobile/screens/06-02_12.jpg),
+which states, _Google may regularly check installed apps for potentially harmful
+behavior._ This can interfere with the test runner. To disable this dialog, run:
+`adb shell settings put global package_verifier_enable 0`
+
+## Emulator Setup
+
+### Option 1:
+
+Use an emulator (i.e. Android Virtual Device, AVD): Enabling Intel's
+Virtualizaton support provides the fastest, most reliable emulator configuration
+available (i.e. x86 emulator with GPU acceleration and KVM support).
+
+1.  Enable Intel Virtualization support in the BIOS.
+
+2.  Set up your environment:
+
+    ```shell
+    . build/android/envsetup.sh
+    ```
+
+3.  Install emulator deps:
+
+    ```shell
+    build/android/install_emulator_deps.py --api-level=19
+    ```
+
+    This script will download Android SDK and place it a directory called
+    android\_tools in the same parent directory as your chromium checkout. It
+    will also download the system-images for the emulators (i.e. arm and x86).
+    Note that this is a different SDK download than the Android SDK in the
+    chromium source checkout (i.e. src/third\_party/android\_emulator\_sdk).
+
+4.  Run the avd.py script. To start up _num_ emulators use -n. For non-x86 use
+    --abi.
+
+    ```shell
+    build/android/avd.py --api-level=19
+    ```
+
+    This script will attempt to use GPU emulation, so you must be running the
+    emulators in an environment with hardware rendering available. See
+    `avd.py --help` for more details.
+
+### Option 2:
+
+Alternatively, you can create an run your own emulator using the tools provided
+by the Android SDK. When doing so, be sure to enable GPU emulation in hardware
+settings, since Chromium requires it to render.
+
+## Building Tests
+
+It may not be immediately obvious where your test code gets compiled to, so here
+are some general rules:
+
+*  If your test code lives under /content, it will probably be built as part of
+   the content\_shell\_test\_apk * If your test code lives under /chrome (or
+   higher), it will probably be built as part of the chrome\_shell\_test\_apk *
+   (Please fill in more details here if you know them).
+
+   NB: We used to call the chrome\_shell\_test\_apk the
+   chromium\_shell\_test\_apk. There may still be references to this kicking
+   around, but wherever you see chromium\_shell\_test you should replace with
+   chrome\_shell\_test.
+
+Once you know what to build, just do it like you normally would build anything
+else, e.g.: `ninja -C out/Release chrome_shell_test_apk`
+
+## Running Tests
+
+All functional tests are run using `build/android/test_runner.py`.
+Tests are sharded across all attached devices. In order to run tests, call:
+`build/android/test_runner.py <test_type> [options]`
+For a list of valid test types, see `test_runner.py --help`. For
+help on a specific test type, run `test_runner.py <test_type> --help`.
+
+The commands used by the buildbots are printed in the logs. Look at
+http://build.chromium.org/ to duplicate the same test command as a particular
+builder.
+
+If you build in an output directory other than "out", you may have to tell
+test\_runner.py where you place it. Say you build your android code in
+out\_android, then do `export CHROMIUM_OUT_DIR=out_android` before running the
+command below.
+
+## INSTALL\_FAILED\_CONTAINER\_ERROR or INSTALL\_FAILED\_INSUFFICIENT\_STORAGE
+
+If you see this error when test\_runner.py is attempting to deploy the test
+binaries to the AVD emulator, you may need to resize your userdata partition
+with the following commands:
+
+```shell
+# Resize userdata partition to be 1G resize2fs
+android_emulator_sdk/sdk/system-images/android-19/x86/userdata.img 1G
+
+# Set filesystem parameter to continue on errors; Android doesn't like some
+# things e2fsprogs does.
+tune2fs -e continue
+android_emulator_sdk/sdk/system-images/android-19/x86/userdata.img
+```
+
+## Symbolizing Crashes
+
+Crash stacks are logged and can be viewed using adb logcat. To symbolize the
+traces, pipe the output through
+`third_party/android_platform/development/scripts/stack`. If you build in an
+output directory other than "out", pass
+`--chrome-symbols-dir=out_directory/{Debug,Release}/lib` to the script as well.
+
+## Gtests
+
+```shell
+# Build a test suite
+ninja -C out/Release content_unittests_apk
+
+# Run a test suite
+build/android/test_runner.py gtest -s content_unittests --release -vvv
+
+# Run a subset of tests
+build/android/test_runner.py gtest -s content_unittests --release -vvv \
+--gtest-filter ByteStreamTest.*
+```
+
+## Instrumentation Tests
+
+In order to run instrumentation tests, you must leave your device screen ON and
+UNLOCKED. Otherwise, the test will timeout trying to launch an intent.
+Optionally you can disable screen lock under Settings -> Security -> Screen Lock
+-> None.
+
+Next, you need to build the app, build your tests, install the application APK,
+and then run your tests (which will install the test APK automatically).
+
+Examples:
+
+ContentShell tests:
+
+```shell
+# Build the code under test
+ninja -C out/Release content_shell_apk
+
+# Build the tests themselves
+ninja -C out/Release content_shell_test_apk
+
+# Install the code under test
+build/android/adb_install_apk.py out/Release/apks/ContentShell.apk
+
+# Run the test (will automagically install the test APK)
+build/android/test_runner.py instrumentation --test-apk=ContentShellTest \
+--isolate-file-path content/content_shell_test_apk.isolate --release -vv
+```
+
+ChromeShell tests:
+
+```shell
+# Build the code under test
+ninja -C out/Release chrome_shell_apk
+
+# Build the tests themselves
+ninja -C out/Release chrome_shell_test_apk
+
+# Install the code under test
+build/android/adb_install_apk.py out/Release/apks/ChromeShell.apk
+
+# Run the test (will automagically install the test APK)
+build/android/test_runner.py instrumentation --test-apk=ChromeShellTest \
+--isolate-file-path chrome/chrome_shell_test_apk.isolate --release -vv
+```
+
+AndroidWebView tests:
+
+```shell
+ninja -C out/Release android_webview_apk
+ninja -C out/Release android_webview_test_apk
+build/android/adb_install_apk.py out/Release/apks/AndroidWebView.apk \
+build/android/test_runner.py instrumentation --test-apk=AndroidWebViewTest \
+--test_data webview:android_webview/test/data/device_files --release -vvv
+```
+
+Use adb\_install\_apk.py to install the app under test, then run the test
+command. In order to run a subset of tests, use -f to filter based on test
+class/method or -A/-E to filter using annotations.
+
+Filtering examples:
+
+```shell
+# Run a test suite
+build/android/test_runner.py instrumentation --test-apk=ContentShellTest
+
+# Run a specific test class
+build/android/test_runner.py instrumentation --test-apk=ContentShellTest -f \
+AddressDetectionTest
+
+# Run a specific test method
+build/android/test_runner.py instrumentation --test-apk=ContentShellTest -f \
+AddressDetectionTest#testAddressLimits
+
+# Run a subset of tests by size (Smoke, SmallTest, MediumTest, LargeTest,
+# EnormousTest)
+build/android/test_runner.py instrumentation --test-apk=ContentShellTest -A \
+Smoke
+
+# Run a subset of tests by annotation, such as filtering by Feature
+build/android/test_runner.py instrumentation --test-apk=ContentShellTest -A \
+Feature=Navigation
+```
+
+You might want to add stars `*` to each as a regular expression, e.g.
+`*`AddressDetectionTest`*`
+
+## Running Blink Layout Tests
+
+See
+https://sites.google.com/a/chromium.org/dev/developers/testing/webkit-layout-tests
+
+## Running GPU tests
+
+(e.g. the "Android Debug (Nexus 7)" bot on the chromium.gpu waterfall)
+
+See http://www.chromium.org/developers/testing/gpu-testing for details. Use
+--browser=android-content-shell. Examine the stdio from the test invocation on
+the bots to see arguments to pass to src/content/test/gpu/run\_gpu\_test.py.