test(functional): add Android/iOS pairing flow E2E tests and docs by vbudhram · Pull Request #20833 · mozilla/fxa

vbudhram · 2026-07-08T18:10:49Z

Because

Developers had no documented way to test and debug the FxA device-pairing (QR sign-in) flows against a local stack, so validating pairing meant reverse-engineering the setup each time.

This pull request

Adds docs/pairing/README.md, a developer guide for exercising pairing by hand on an Android emulator or real device against a local FxA stack.
Covers Android setup (emulator via Android Studio, real device over USB), pointing Fenix at the local stack, triggering a pairing, and the fxawebchannel localhost caveat.
Documents enabling USB/remote debugging and using Firefox DevTools for console, network, and breakpoints; includes the parallel iOS flow (Simulator/device, custom FxA server, Safari Web Inspector).
Docs only; no code or test changes. The automated E2E tests move to a separate branch/PR (fxa-14161).

Issue that this pull request solves

Closes: https://mozilla-hub.atlassian.net/browse/FXA-13884
Closes: https://mozilla-hub.atlassian.net/browse/FXA-13885

Checklist

My commit is GPG signed.
If applicable, I have modified or added tests which pass locally.
I have added necessary documentation (if appropriate).
I have verified that my changes render correctly in RTL (if appropriate).
I have manually reviewed all AI generated code.

Other information

Splits the prior combined PR: this one is documentation only; the Android/iOS pairing E2E tests are in fxa-14161.

Copilot

Pull request overview

Adds new cross-device (desktop authority + mobile supplicant) E2E coverage for the FxA device pairing flow, with platform-specific automation for Android (adb-driven Fenix debug build) and iOS (xcodebuild/XCUITest-driven Firefox iOS Simulator), plus developer docs for running/debugging locally.

Changes:

Add Android pairing flow E2E specs and an adb-based “supplicant” driver (AndroidSupplicant).
Add iOS pairing flow E2E specs that coordinate Marionette with an XCUITest run.
Add a pairing-focused developer/debugging guide (CLAUDE.md) for Android/iOS local runs.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 6 comments.

File	Description
packages/functional-tests/tests/pairing/pairingFlowiOS.spec.ts	New iOS Simulator/XCUITest-driven pairing E2E coverage coordinated with Marionette authority.
packages/functional-tests/tests/pairing/pairingFlowAndroid.spec.ts	New Android emulator/device pairing E2E coverage using adb-driven supplicant automation.
packages/functional-tests/tests/pairing/CLAUDE.md	Local run + debugging documentation for pairing tests across Android and iOS.
packages/functional-tests/lib/android-supplicant.ts	New adb-driven automation helper to drive the Android “supplicant” side of pairing.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+const FIREFOX_IOS_PROJECT_DIR =
+  process.env.FIREFOX_IOS_PROJECT_DIR ||
+  '/Users/vijaybudham/Desktop/working2/firefox-ios';
+const IOS_DESTINATION =
+  process.env.IOS_DESTINATION ||
+  'platform=iOS Simulator,name=iPhone 16,OS=18.0';


+  } else {
+    debug('No xctestrun found, falling back to xcodebuild test (will compile)');
+    args = [
+      'test',
+      '-project',
+      path.join('firefox-ios', 'Client.xcodeproj'),
+      '-scheme',
+      'Fennec',
+      '-destination',
+      IOS_DESTINATION,
+      '-testPlan',
+      'SyncIntegrationTestPlan',
+      `-only-testing:${onlyTesting}`,
+    ];
+  }


+ * The Sync Debug pairing hook is a local debug-only addition to Fenix
+ * (`SyncDebugFragment.setupPairingPreferences`). See
+ * `ai/docs/references/android-local-testing.md` for the app-side change and
+ * build instructions.


+      throw new Error(
+        `${this.pkg} is not installed. Build + install the Fenix debug build ` +
+          `with the Sync Debug pairing hook (see ai/docs/references/android-local-testing.md).`
+      );


+ * Prerequisites:
+ *   - FXA stack running (auth :9000, content :3030) and `yarn adb-reverse` run
+ *     so the emulator's localhost reaches the host stack.
+ *   - Android emulator booted and visible to `adb` (ANDROID_SERIAL to target).
+ *   - Fenix debug build with the Sync Debug pairing hook installed
+ *     (org.mozilla.fenix.debug). See ai/docs/references/android-local-testing.md.
+ *


+      // The supplicant registers its device asynchronously after finishing the
+      // OAuth webchannel login. This requires the fxawebchannel extension to
+      // inject on the local stack — the extension manifest must include
+      // http://localhost/* in its content_scripts matches (see
+      // ai/docs/references/android-local-testing.md, pairing prerequisites).


dschom · 2026-07-14T19:04:51Z

+:9000. The Fenix client id is already in `packages/fxa-auth-server/config/dev.json`.
+
+Build the Fenix debug app from a `mozilla-firefox/firefox` checkout; it has the
+Sync Debug pairing hook (landed in Bug 2053454). The Android bootstrap is a


Is (landed in Bug 2053454) really relevant.

dschom · 2026-07-14T19:08:32Z

+First, bridge the ports so the device's `localhost` reaches your machine:
+`yarn adb-reverse` (works over USB and on the emulator). Then override the FxA
+server: in Fenix, Settings → Sync Debug → "Custom Mozilla account server", set to
+`http://localhost:3030`. Writing the `pref_key_override_fxa_server` pref directly


How does one do this: " Writing the pref_key_override_fxa_server pref"

dschom

I'm still validating the iOS build and android build process, but everthing else seems about right. We can also file a follow up if someone has a specific issue. Thanks for the docs!

dschom · 2026-07-14T19:10:21Z

+Sync Debug pairing hook (landed in Bug 2053454). The Android bootstrap is a
+one-time step:
+
+```bash


It'd be nice to add the git clone / checkout / pull commands here too.

dschom · 2026-07-14T19:11:02Z

+
+### Using an emulator (Android Studio)
+
+Create an AVD in Android Studio's Device Manager, or launch one from the SDK:


Is there a place we can install apks from?

dschom · 2026-07-14T19:18:15Z

+Docker isn't up). That gives you content-server on :3030 and auth-server on
+:9000. The Fenix client id is already in `packages/fxa-auth-server/config/dev.json`.
+
+Build the Fenix debug app from a `mozilla-firefox/firefox` checkout; it has the


It'd be nice to list the git commands. Or link to the repo.

dschom · 2026-07-14T19:35:13Z

+debugging. Turn it on once in Fenix (Settings → "Remote debugging via USB"), then
+on desktop Firefox open `about:debugging` → This Firefox / Setup, connect to the
+device, and Inspect the pairing tab. That gives you the full Firefox DevTools
+against the live on-device page, which is where the console, network, and


Might be worth noting / explaining you can see the logs and web requests for the paring tab, but you can also see the logs / requests from Firefox itself by selecting the 'Multiprocess Toolbox' at the bottom of the page. This can be useful to sanity check other calls made by Firefox to our APIs or even other APIs like sync.

dschom · 2026-07-14T19:38:10Z

+The iOS supplicant is Firefox iOS, on a Simulator or a registered device. Same
+ideas as Android, different tools: Xcode and Safari Web Inspector.
+
+> Heads up: the iOS steps here come from earlier debugging notes and the


Is this stray ai stuff? To close FXA-13885 we will need to validate this all still works correctly.

dschom · 2026-07-14T19:40:05Z

+and cold-starting is more reliable than the on-screen field, which tends not to
+stick.
+
+There's one more catch for local runs. The built-in `fxawebchannel` extension


I think it'd be nice for FxA to maintain some APKs with patch in them. It saves everyone else from having to build the code which is kind of a hastle and probably uncessary in many cases.

We could but probably better to defer for now. The building the code locally might be hastle first time but its pretty quick on subsequent calls.

dschom · 2026-07-14T20:43:48Z

+
+### Trigger a pairing
+
+1. In a signed-in desktop Firefox (the authority), open the pairing page and show


Maybe provide a little more info about this for some one who is knew and doesn't know how to do this.

dschom · 2026-07-14T20:46:41Z

+`Invalid pairing configuration`: the `channel_id` and `channel_key` drop out of
+the URL fragment before the React app reads `window.location.hash`. If you see it,
+check the loaded URL's fragment in Safari Web Inspector first, then the app's URL
+handling.


What do you do to address this? Is this intermittent, or is there some kind of work around or bug fix needed?

This was stale note, its been fixed.

vbudhram self-assigned this Jul 8, 2026

github-advanced-security AI found potential problems Jul 8, 2026

View reviewed changes

Comment thread packages/functional-tests/lib/android-supplicant.ts Fixed

vbudhram force-pushed the fxa-13884 branch from ed5f396 to 2036acc Compare July 8, 2026 19:05

vbudhram mentioned this pull request Jul 10, 2026

Add FXIOS-16258 [Debug] Launch FxA pairing from a URL mozilla-mobile/firefox-ios#34598

Open

7 tasks

vbudhram force-pushed the fxa-13884 branch 3 times, most recently from 57d3d71 to 6981fb3 Compare July 13, 2026 18:17

vbudhram marked this pull request as ready for review July 13, 2026 18:17

vbudhram requested a review from a team as a code owner July 13, 2026 18:17

Copilot AI review requested due to automatic review settings July 13, 2026 18:17

Copilot started reviewing on behalf of vbudhram July 13, 2026 18:17 View session

Copilot AI reviewed Jul 13, 2026

View reviewed changes

vbudhram force-pushed the fxa-13884 branch 3 times, most recently from 45bdb0e to 534183c Compare July 14, 2026 18:11

dschom reviewed Jul 14, 2026

View reviewed changes

dschom approved these changes Jul 14, 2026

View reviewed changes

vbudhram force-pushed the fxa-13884 branch from 534183c to 96fedbf Compare July 15, 2026 14:54

docs(pairing): add pairing flow testing and debugging guide

2373e21

vbudhram force-pushed the fxa-13884 branch from 96fedbf to 2373e21 Compare July 15, 2026 15:22

vbudhram merged commit 2ec90d7 into main Jul 15, 2026
5 of 8 checks passed

vbudhram deleted the fxa-13884 branch July 15, 2026 15:24


		### Using an emulator (Android Studio)

		Create an AVD in Android Studio's Device Manager, or launch one from the SDK:


		### Trigger a pairing

		1. In a signed-in desktop Firefox (the authority), open the pairing page and show

Uh oh!

Conversation

vbudhram commented Jul 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Because

This pull request

Issue that this pull request solves

Checklist

Other information

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dschom left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

vbudhram commented Jul 8, 2026 •

edited

Loading