Testing Web Apps on Android

This document describes how to test Android Web Apps (WebAPKs and TWAs) manually and via automated tests.

Manual Testing on Emulator

To test manually using an emulator:

1. Setup a Test PWA

You can use a public PWA (like https://pokedex.org) or serve one locally.

  • Using a public PWA: No server setup needed! Just use the URL https://pokedex.org.
  • Serving locally:
    1. Use Python to serve a directory with a manifest: python3 -m http.server 8000.
    2. Forward the port to the emulator: adb reverse tcp:8000 tcp:8000.

2. Disable Verification for Testing

To trust a TWA or WebAPK during local testing with developer builds, you must bypass Chrome's security checks.

For TWAs (Digital Asset Links)

Chrome requires DAL verification to run a TWA in app mode. To bypass this for a test URL:

  • Pass the flag to Chrome: --disable-digital-asset-link-verification-for-url="https://pokedex.org"
  • Example using build wrapper: out/Default/bin/chrome_public_apk launch --args="--disable-digital-asset-link-verification-for-url=https://pokedex.org"
  • Example using adb command line (requires “Enable command line on non-rooted devices” in chrome://flags): adb shell "echo '_ --disable-digital-asset-link-verification-for-url=https://pokedex.org' > /data/local/tmp/chrome-command-line"

For WebAPKs (Signature Verification)

Chrome verifies that WebAPKs are signed by the trusted WebAPK minting server. Locally built debug WebAPKs will fail this check. To bypass this:

  • Pass the flag to Chrome: --skip-webapk-verification
  • Example using build wrapper: out/Default/bin/chrome_public_apk launch --args="--skip-webapk-verification"

3. Install a Test TWA (via Bubblewrap)

You can use Bubblewrap to generate an APK for your test site and install it: adb install path/to/generated.apk

4. Install a Test WebAPK (via Chrome)

To test WebAPK installation:

  1. Open Chrome on the emulator.
  2. Navigate to your test PWA URL (e.g., https://pokedex.org).
  3. Wait for the install prompt or select “Install app” from the Chrome menu.
  4. Verify that the app is installed and appears in the app drawer.

5. Verify in Chrome Site Settings

  1. Open the installed TWA or WebAPK on the emulator.
  2. Go to Chrome > Settings > Site Settings > All Sites.
  3. Look for your test site and see if it shows that it is managed by an app or has delegated permissions.

Automated Tests

Chromium has several test suites that cover Web App functionality on Android. To keep this guide maintainable, tests are grouped by directory and feature area.

1. Instrumentation Tests (Java/JUnit4)

These tests run on an emulator or physical device to test UI, integration, and lifecycle. Unlike host-side JUnit tests below, instrumentation tests cannot run without an active device.

Emulator Prerequisite

To start the recommended local development emulator (x64 image, emulator window, and networking enabled):

tools/android/avd/avd.py start -v \
    --avd-config tools/android/avd/proto/android_google_apis_x64_local.textpb \
    --emulator-window --no-read-only --enable-network

For more options and configuration details, see:

How to Run: Use tools/autotest.py to automatically compile and execute a test file:

tools/autotest.py -C out/Android chrome/android/javatests/src/org/chromium/chrome/browser/webapps/WebappActivityTest.java

Or build and run all tests in a directory via the test runner script:

autoninja -C out/Android chrome_public_test_apk
out/Android/bin/run_chrome_public_test_apk -f "org.chromium.chrome.browser.webapps.*"
out/Android/bin/run_chrome_public_test_apk -f "org.chromium.chrome.browser.browserservices.*"

2. Host-Side JUnit Tests (Java)

These unit tests run on the development host JVM and test business logic, storage, and utility classes without requiring an emulator or device.

How to Run: Use tools/autotest.py:

tools/autotest.py -C out/Android chrome/android/junit/src/org/chromium/chrome/browser/webapps/WebappAuthenticatorTest.java

Or build and run via the test runner script:

autoninja -C out/Android chrome_junit_tests
out/Android/bin/run_chrome_junit_tests -f "org.chromium.chrome.browser.webapps.*"
out/Android/bin/run_chrome_junit_tests -f "org.chromium.chrome.browser.browserservices.*"

3. WebAPK Shell & Client Library Tests

These tests focus on the WebAPK client-side library and the shell APK code.

How to Run: Check chrome/android/webapk/README.md for instructions on running these specialized tests.

4. C++ Unit Tests (Android-specific)

These tests cover the shared native code integration.

How to Run: Build and run components_unittests on Android: autoninja -C out/Default components_unittests out/Default/bin/run_components_unittests --gtest_filter="*AddToHomescreen*"