System WebView Shell

WebView Shell

WebView team maintains a “shell”—a thin interface over the WebView APIs—to exercise WebView functionality. The System WebView Shell (AKA “shell browser,” “WebView shell”) is a standalone app implemented in chromium. While often used for manual testing, we also use the shell for automated tests (see our layout and page cycler tests).

This relies on the WebView installed on the system. So if you're trying to verify local changes to WebView, or run against a specific WebView build, you must install WebView first.

This is not a production quality browser and does not implement suitable security UI to be used for anything other than testing WebView. This should not be shipped anywhere or used as the basis for implementing a browser.

Setting up the build

WebView shell only requires target_os = "android". The simplest option is to just reuse the same out/ folder and GN args you would normally use for WebView or Chrome for Android.

For the emulator: the emulator comes with WebView shell preinstalled with a different signing key, so installation will fail with INSTALL_FAILED_UPDATE_INCOMPATIBLE: Package ... signatures do not match previously installed version. You can workaround this in your GN args with system_webview_shell_package_name = "org.chromium.my_webview_shell".

Your local build will install alongside the preinstalled WebView shell. You may hide the preinstalled shell by running adb root followed by adb shell pm disable org.chromium.webview_shell in your terminal (copy-paste the command as-written, don't use the package name from the GN arg above).

Building the shell

$ autoninja -C out/Default system_webview_shell_apk

Installing the shell

# Build and install
$ out/Default/bin/system_webview_shell_apk install

Running the shell

# Launch a URL from the commandline, or open the app from the app launcher
$ out/Default/bin/system_webview_shell_apk launch "https://www.google.com/"

# For more commands:
$ out/Default/bin/system_webview_shell_apk --help

Note: system_webview_shell_apk does not support modifying CLI flags. See https://crbug.com/959425. Instead, you should modify WebView's flags by following commandline-flags.md.

Prebuilt APKs

We maintain a public archive of prebuilt WebView shell APKs. This saves you the effort of setting up a chromium checkout just for the sake of compiling this test app. You can download a prebuilt APK from this cloud storage bucket: https://commondatastorage.googleapis.com/chromium-browser-snapshots/index.html?prefix=Android/

The builds are sorted from oldest to newest. You should scroll to the bottom of the page to get the latest revision. Note that the page can take some time to load all the revisions, so you may have to scroll multiple times. Keep scrolling until you see a file named LAST_CHANGE, then pick the numbered folder immediately above it.
- Your WebView shell version does not need to match your device's WebView version. We recommend using the latest WebView shell build regardless of your WebView version to make sure you have the latest features and bug fixes of the shell app itself.
Click chrome-android.zip to download the archived APKs. Unzip this and look for a file named SystemWebViewShell.apk.

Now you can install this like any other APK:

# Install adb if it's not already installed:
$ which adb || sudo apt install adb

# Replace this path with the path to your downloaded APK
$ adb install -d -r ~/Downloads/chrome-android/SystemWebViewShell.apk

Troubleshooting

INSTALL_FAILED_UPDATE_INCOMPATIBLE: Package ... signatures do not match previously installed version

This may be happening because the shell is preinstalled on your device (ex. this is the case on all emulators). The easiest way to workaround this is to change the shell's package name in a local build.

If you don‘t want to (or can’t) change the package name, then you may be able to modify your device's system image. See the manual steps for removing system apps and replace com.google.android.webview with org.chromium.webview_shell.