⚗️ [POC] Setup e2e tests on Android using emulator

rgaignault · rgaignault · commit 83adaa1e8c85 · 2026-03-02T16:24:41.000+01:00
Setup Android E2E testing using Playwright's experimental Android API
with an emulator running on a macOS Sonoma GitLab runner.

- Boot Android emulator in globalSetup, teardown in globalTeardown
- Install recent Chromium (v147) via snapshot builds to replace outdated system Chrome (v113)
- Reuse device connection and browser context across tests for performance
- Clean up service workers between tests to prevent stale state
- Wire Android fixture into existing createTest() framework
- All existing e2e scenarios run on Android with bundle setup
- Fix scroll test sub-pixel rounding on mobile DPI
- 237/249 tests pass, ~3 flaky (pass on retry)
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
@@ -231,6 +231,25 @@ e2e:
   after_script:
     - node ./scripts/test/export-test-result.ts e2e
 
+e2e-android:
+  extends:
+    - .base-configuration
+    - .feature-branches
+  tags:
+    - 'macos:sonoma'
+    - 'specific:true'
+  interruptible: true
+  timeout: 40 minutes
+  artifacts:
+    when: always
+    reports:
+      junit: test-report/e2e-android/*.xml
+  script:
+    - yarn
+    - yarn build
+    - yarn build:apps
+    - FORCE_COLOR=1 CI_JOB_NAME=e2e-android yarn test:e2e:android
+
 check-licenses:
   extends:
     - .base-configuration
diff --git a/package.json b/package.json
@@ -31,6 +31,7 @@
     "test:e2e:init": "yarn build && yarn build:apps && yarn playwright install chromium --with-deps",
     "test:e2e": "playwright test --config test/e2e/playwright.local.config.ts --project chromium",
     "test:e2e:bs": "node --env-file-if-exists=.env ./scripts/test/bs-wrapper.ts playwright test --config test/e2e/playwright.bs.config.ts",
+    "test:e2e:android": "ANDROID_E2E=true playwright test --config test/e2e/android/playwright.android.config.ts",
     "test:e2e:ci": "yarn test:e2e:init && yarn test:e2e",
     "test:e2e:ci:bs": "yarn build && yarn build:apps && yarn test:e2e:bs",
     "test:compat:tsc": "node scripts/check-typescript-compatibility.ts",
diff --git a/test/e2e/android/androidFixture.ts b/test/e2e/android/androidFixture.ts
@@ -0,0 +1,70 @@
+import type { BrowserContext } from '@playwright/test'
+import { test as base } from '@playwright/test'
+import type { AndroidDevice } from 'playwright'
+import { _android } from 'playwright'
+
+const DEVICE_CONNECTION_TIMEOUT = 30_000
+const DEVICE_CONNECTION_RETRY_INTERVAL = 2_000
+
+let cachedDevice: AndroidDevice | undefined
+let cachedContext: BrowserContext | undefined
+
+async function getOrCreateContext(): Promise<{ device: AndroidDevice; context: BrowserContext }> {
+  if (cachedDevice && cachedContext) {
+    try {
+      // Verify the context is still alive by attempting a simple operation
+      await cachedContext.pages()
+      return { device: cachedDevice, context: cachedContext }
+    } catch {
+      // Context is stale, recreate
+      cachedContext = undefined
+    }
+  }
+
+  if (!cachedDevice) {
+    cachedDevice = await connectDevice()
+  }
+
+  // Use Chromium (org.chromium.chrome) instead of the outdated system Chrome (v113)
+  cachedContext = await cachedDevice.launchBrowser({ pkg: 'org.chromium.chrome' })
+  return { device: cachedDevice, context: cachedContext }
+}
+
+export const test = base.extend<{ context: BrowserContext }>({
+  // eslint-disable-next-line no-empty-pattern
+  context: async ({}, use) => {
+    const { context } = await getOrCreateContext()
+    await use(context)
+  },
+  page: async ({ context }, use) => {
+    const page = await context.newPage()
+    await use(page)
+    // Clean up service workers before closing the page to prevent stale SW state
+    // from interfering with subsequent tests in the shared browser context
+    try {
+      await page.evaluate(async () => {
+        const regs = await navigator.serviceWorker.getRegistrations()
+        await Promise.all(regs.map((r) => r.unregister()))
+      })
+    } catch {
+      // Page might already be in a bad state, ignore cleanup errors
+    }
+    await page.close()
+  },
+})
+
+async function connectDevice() {
+  const startTime = Date.now()
+
+  while (Date.now() - startTime < DEVICE_CONNECTION_TIMEOUT) {
+    const devices = await _android.devices()
+    if (devices.length > 0) {
+      return devices[0]
+    }
+    await new Promise((resolve) => setTimeout(resolve, DEVICE_CONNECTION_RETRY_INTERVAL))
+  }
+
+  throw new Error(`No Android device found within ${DEVICE_CONNECTION_TIMEOUT / 1000}s`)
+}
+
+export { expect } from '@playwright/test'
diff --git a/test/e2e/android/globalSetup.ts b/test/e2e/android/globalSetup.ts
@@ -0,0 +1,131 @@
+import { execSync, spawn } from 'child_process'
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import * as os from 'node:os'
+
+const BOOT_TIMEOUT_MS = 300_000
+const BOOT_POLL_INTERVAL_MS = 2_000
+
+const DEV_SERVER_PORT = 8080
+// Port range matching httpServers.ts
+const PORT_RANGE_START = 9200
+const PORT_RANGE_END = 9400
+
+// eslint-disable-next-line import/no-default-export
+export default async function globalSetup() {
+  console.log('Starting Android emulator...')
+
+  const emulatorProcess = spawn(
+    'emulator',
+    ['-avd', 'test_device', '-no-window', '-no-audio', '-no-snapshot', '-no-boot-anim', '-gpu', 'auto'],
+    {
+      stdio: ['ignore', 'ignore', 'ignore'],
+      detached: true,
+    }
+  )
+  emulatorProcess.unref()
+
+  await waitForBoot()
+  setupAdbReverse()
+  await installChromium()
+
+  process.env.ANDROID_E2E = 'true'
+}
+
+async function waitForBoot() {
+  const startTime = Date.now()
+
+  while (Date.now() - startTime < BOOT_TIMEOUT_MS) {
+    try {
+      const result = execSync('adb shell getprop sys.boot_completed', { encoding: 'utf-8', timeout: 5_000 }).trim()
+      if (result === '1') {
+        console.log(`Emulator booted in ${Math.round((Date.now() - startTime) / 1000)}s`)
+        return
+      }
+    } catch {
+      // adb not yet connected, keep polling
+    }
+    await new Promise((resolve) => setTimeout(resolve, BOOT_POLL_INTERVAL_MS))
+  }
+
+  throw new Error(`Emulator failed to boot within ${BOOT_TIMEOUT_MS / 1000}s`)
+}
+
+function setupAdbReverse() {
+  console.log('Setting up adb reverse port forwarding...')
+
+  // Forward dev server port
+  execSync(`adb reverse tcp:${DEV_SERVER_PORT} tcp:${DEV_SERVER_PORT}`)
+
+  // Forward test server port range
+  for (let port = PORT_RANGE_START; port <= PORT_RANGE_END; port++) {
+    execSync(`adb reverse tcp:${port} tcp:${port}`)
+  }
+
+  console.log(`Forwarded ports: ${DEV_SERVER_PORT}, ${PORT_RANGE_START}-${PORT_RANGE_END}`)
+}
+
+async function installChromium() {
+  // The system Chrome on the emulator is v113, which is too old for many web APIs
+  // (LoAf, modern resource timing, etc.). Install a recent Chromium from snapshots.
+  console.log('Installing Chromium on emulator...')
+
+  try {
+    // Get the latest Chromium snapshot revision for Android ARM64
+    const revisionResponse = await fetch(
+      'https://storage.googleapis.com/chromium-browser-snapshots/Android_Arm64/LAST_CHANGE'
+    )
+    const revision = (await revisionResponse.text()).trim()
+    console.log(`Latest Chromium ARM64 snapshot revision: ${revision}`)
+
+    // Download the Chromium Android ARM64 build
+    const downloadUrl = `https://storage.googleapis.com/chromium-browser-snapshots/Android_Arm64/${revision}/chrome-android.zip`
+    console.log(`Downloading from ${downloadUrl}`)
+
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'chromium-android-'))
+    const zipPath = path.join(tmpDir, 'chrome-android.zip')
+
+    const downloadResponse = await fetch(downloadUrl)
+    if (!downloadResponse.ok) {
+      console.log(`Download failed: ${downloadResponse.status}`)
+      return
+    }
+
+    const buffer = Buffer.from(await downloadResponse.arrayBuffer())
+    fs.writeFileSync(zipPath, buffer)
+    console.log(`Downloaded ${(buffer.length / 1024 / 1024).toFixed(1)}MB`)
+
+    // Extract the zip
+    execSync(`unzip -o "${zipPath}" -d "${tmpDir}"`, { timeout: 60_000 })
+
+    // Find APKs
+    const apks = execSync(`find "${tmpDir}" -name "*.apk"`, { encoding: 'utf-8', timeout: 5_000 })
+      .trim()
+      .split('\n')
+      .filter(Boolean)
+
+    console.log(`Found APKs: ${apks.map((a) => path.basename(a)).join(', ')}`)
+
+    // Install ChromePublic.apk (the main Chromium browser)
+    const chromeApk = apks.find((a) => path.basename(a) === 'ChromePublic.apk')
+    if (!chromeApk) {
+      console.log('ChromePublic.apk not found in download')
+      return
+    }
+
+    const result = execSync(`adb install -r -d "${chromeApk}"`, { encoding: 'utf-8', timeout: 120_000 })
+    console.log(`Install result: ${result.trim()}`)
+
+    // Log the installed Chromium version
+    const versionInfo = execSync('adb shell dumpsys package org.chromium.chrome | grep versionName', {
+      encoding: 'utf-8',
+      timeout: 5_000,
+    }).trim()
+    console.log(`Chromium installed: ${versionInfo}`)
+
+    // Cleanup
+    fs.rmSync(tmpDir, { recursive: true, force: true })
+  } catch (error) {
+    console.log('Chromium install failed (non-fatal):', error)
+  }
+}
diff --git a/test/e2e/android/globalTeardown.ts b/test/e2e/android/globalTeardown.ts
@@ -0,0 +1,12 @@
+import { execSync } from 'child_process'
+
+// eslint-disable-next-line import/no-default-export
+export default function globalTeardown() {
+  console.log('Shutting down Android emulator...')
+  try {
+    execSync('adb emu kill', { timeout: 10_000 })
+    console.log('Emulator stopped')
+  } catch {
+    console.warn('Failed to stop emulator (it may have already exited)')
+  }
+}
diff --git a/test/e2e/android/playwright.android.config.ts b/test/e2e/android/playwright.android.config.ts
@@ -0,0 +1,31 @@
+import path from 'path'
+import type { ReporterDescription } from '@playwright/test'
+import { defineConfig } from '@playwright/test'
+import { getTestReportDirectory } from '../../envUtils'
+
+const testReportDirectory = getTestReportDirectory()
+const reporters: ReporterDescription[] = [['line']]
+
+if (testReportDirectory) {
+  reporters.push(['junit', { outputFile: path.join(process.cwd(), testReportDirectory, 'results.xml') }])
+} else {
+  reporters.push(['html'])
+}
+
+// eslint-disable-next-line import/no-default-export
+export default defineConfig({
+  testDir: '../scenario',
+  testMatch: ['**/*.scenario.ts'],
+  testIgnore: ['**/android/**'],
+  tsconfig: '../tsconfig.json',
+  globalSetup: './globalSetup.ts',
+  globalTeardown: './globalTeardown.ts',
+  fullyParallel: false,
+  workers: 1,
+  retries: 1,
+  timeout: 60_000,
+  reporter: reporters,
+  use: {
+    trace: 'retain-on-failure',
+  },
+})
diff --git a/test/e2e/lib/framework/createTest.ts b/test/e2e/lib/framework/createTest.ts
@@ -9,6 +9,7 @@ import { BrowserLogsManager, deleteAllCookies, getBrowserName, sendXhr } from '.
 import { DEFAULT_LOGS_CONFIGURATION, DEFAULT_RUM_CONFIGURATION } from '../helpers/configuration'
 import { validateRumFormat } from '../helpers/validation'
 import type { BrowserConfiguration } from '../../../browsers.conf'
+import { test as androidTest } from '../../android/androidFixture'
 import { IntakeRegistry } from './intakeRegistry'
 import { flushEvents } from './flushEvents'
 import type { Servers } from './httpServers'
@@ -19,7 +20,7 @@ import { createIntakeServerApp } from './serverApps/intake'
 import { createMockServerApp } from './serverApps/mock'
 import type { Extension } from './createExtension'
 import type { Worker } from './createWorker'
-import { isBrowserStack } from './environment'
+import { isAndroid, isBrowserStack } from './environment'
 
 export function createTest(title: string) {
   return new TestBuilder(title, captureCallerLocation())
@@ -53,7 +54,7 @@ class TestBuilder {
   private basePath = ''
   private eventBridge = false
   private setups: Array<{ factory: SetupFactory; name?: string }> = DEFAULT_SETUPS
-  private testFixture: typeof test = test
+  private testFixture: typeof test = isAndroid ? androidTest : test
   private extension: {
     rumConfiguration?: RumInitConfiguration
     logsConfiguration?: LogsInitConfiguration
diff --git a/test/e2e/lib/framework/environment.ts b/test/e2e/lib/framework/environment.ts
@@ -1,2 +1,3 @@
 export const isBrowserStack = Boolean(process.env.BROWSER_STACK)
 export const isContinuousIntegration = Boolean(process.env.CI)
+export const isAndroid = Boolean(process.env.ANDROID_E2E)
diff --git a/test/e2e/lib/framework/pageSetups.ts b/test/e2e/lib/framework/pageSetups.ts
@@ -2,7 +2,7 @@ import { generateUUID, INTAKE_URL_PARAMETERS } from '@datadog/browser-core'
 import type { LogsInitConfiguration } from '@datadog/browser-logs'
 import type { RumInitConfiguration, RemoteConfiguration } from '@datadog/browser-rum-core'
 import type test from '@playwright/test'
-import { isBrowserStack, isContinuousIntegration } from './environment'
+import { isAndroid, isBrowserStack, isContinuousIntegration } from './environment'
 import type { Servers } from './httpServers'
 
 export interface SetupOptions {
@@ -45,9 +45,9 @@ export interface WorkerOptions {
 export type SetupFactory = (options: SetupOptions, servers: Servers) => string
 
 // By default, run tests only with the 'bundle' setup outside of the CI (to run faster on the
-// developer laptop) or with Browser Stack (to limit flakiness).
+// developer laptop), with Browser Stack (to limit flakiness), or with Android (single setup).
 export const DEFAULT_SETUPS =
-  !isContinuousIntegration || isBrowserStack
+  !isContinuousIntegration || isBrowserStack || isAndroid
     ? [{ name: 'bundle', factory: bundleSetup }]
     : [
         { name: 'async', factory: asyncSetup },
diff --git a/test/e2e/playwright.base.config.ts b/test/e2e/playwright.base.config.ts
@@ -21,6 +21,7 @@ if (testReportDirectory) {
 export const config: Config = {
   testDir: './scenario',
   testMatch: ['**/*.scenario.ts'],
+  testIgnore: ['**/android/**'],
   tsconfig: './tsconfig.json',
   fullyParallel: true,
   forbidOnly: isCi,
diff --git a/test/e2e/scenario/recorder/viewports.scenario.ts b/test/e2e/scenario/recorder/viewports.scenario.ts
@@ -284,6 +284,8 @@ async function layoutScrollTo(page: Page, scrollX: number, scrollY: number) {
   )
   const { scrollX: nextScrollX, scrollY: nextScrollY } = await getWindowScroll(page)
   // Ensure our methods are applied correctly
-  expect(scrollX).toBe(nextScrollX)
-  expect(scrollY).toBe(nextScrollY)
+  // On mobile devices with non-integer DPI (e.g. 420 DPI = 2.625 ratio), scroll positions
+  // snap to physical pixels, causing sub-pixel differences (e.g. scrollTo(20) → 20.19)
+  expect(nextScrollX).toBeCloseTo(scrollX, 0)
+  expect(nextScrollY).toBeCloseTo(scrollY, 0)
 }
diff --git a/test/envUtils.ts b/test/envUtils.ts
@@ -1,6 +1,9 @@
 import os from 'os'
 
 export function getIp() {
+  if (process.env.ANDROID_E2E) {
+    return 'localhost'
+  }
   return (Object.values(os.networkInterfaces()) as os.NetworkInterfaceInfo[][])
     .flat()
     .find(({ family, internal }) => family === 'IPv4' && !internal)!.address

Original file line number	Diff line number	Diff line change
`@@ -1,2 +1,3 @@`
`1`	`1`	`export const isBrowserStack = Boolean(process.env.BROWSER_STACK)`
`2`	`2`	`export const isContinuousIntegration = Boolean(process.env.CI)`
	`3`	`+export const isAndroid = Boolean(process.env.ANDROID_E2E)`