feat(functional-tests): add pairing E2E test with marionette authority by vbudhram · Pull Request #20119 · mozilla/fxa

vbudhram · 2026-02-27T18:23:56Z

Because

We have no way currently of testing the pairing flow locally
We used to have a functional test that verified the basic flow worked via desktop

This pull request

Adds a minimal Marionette TCP protocol client (lib/marionette.ts) to drive a real Firefox instance for the authority side of pairing
Adds a Firefox process manager (lib/marionette-firefox.ts) that launches Playwright's bundled Firefox with Marionette enabled, manages temp profiles, and cleans up on teardown
Adds a Playwright fixture (lib/fixtures/pairing.ts) that wires the Marionette authority into the test lifecycle using firefox.executablePath()
Adds the pairing E2E spec (tests/pairing/pairingFlow.spec.ts) exercising: OAuth sign-in via beginOAuthFlow → start pairing → channel handshake → authority approval → supplicant confirm → both sides complete
Extracts shared constants (lib/pairing-constants.ts) and helpers (lib/pairing-helpers.ts) with condition-based waits (no hardcoded sleeps)
Injects CI_WAF_TOKEN bypass header in CI for stage/production runs

Issue that this pull request solves

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

Checklist

Put an x in the boxes that apply

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).

Other information (Optional)

How to test:

# 1. Start the FXA stack
yarn start

# 2. Run pairing test against local (uses Playwright's bundled Firefox)
npx playwright test tests/pairing/pairingFlow.spec.ts --project=local

# 3. Run headed (watch the Marionette Firefox + Playwright browser)
MARIONETTE_HEADLESS=false \
  npx playwright test tests/pairing/pairingFlow.spec.ts --project=local --headed

# 4. Run against stage (requires WAF token from 1Password)
CI_WAF_TOKEN=<token> \
  npx playwright test tests/pairing/pairingFlow.spec.ts --project=stage

# 5. Run against stage, headed
CI_WAF_TOKEN=<token> MARIONETTE_HEADLESS=false \
  npx playwright test tests/pairing/pairingFlow.spec.ts --project=stage --headed

# 6. Override Firefox binary (optional)
FIREFOX_BINARY="/Applications/Firefox Nightly.app/Contents/MacOS/firefox" \
  npx playwright test tests/pairing/pairingFlow.spec.ts --project=local

# 7. Flakiness check (run 5x)
for i in {1..5}; do
  npx playwright test tests/pairing/pairingFlow.spec.ts --project=local
done

Note: Expect ~30-35s per run. MARIONETTE_HEADLESS=false shows the authority Firefox window; --headed shows the Playwright supplicant browser.est.

dschom · 2026-02-27T19:01:21Z

packages/functional-tests/tests/pairing/pairingFlow.spec.ts

+      expect(pairUrl).toBeTruthy();
+      expect(pairUrl).toContain('/pair#');
+      expect(pairUrl).toContain('channel_id=');
+      if (!pairUrl) throw new Error('pairUrl is null');


Add end-to-end test for the Firefox device pairing flow using a Marionette-driven Firefox authority and Playwright supplicant. - Minimal Marionette TCP client (marionette.ts) - Firefox process manager with temp profile lifecycle (marionette-firefox.ts) - Playwright fixture using bundled Firefox (125+) as Marionette authority - Uses beginOAuthFlow for proper PKCE/keys_jwk registration - Condition-based waits replacing hardcoded sleeps

vbudhram · 2026-02-28T01:36:26Z

packages/functional-tests/tests/pairing/pairingFlow.spec.ts

+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+/**
+ * End-to-end pairing flow test.


This is the most important comment of the PR, we need marionette to access FF internals to get the QR code url. While iterating it turns out you don't need to take a picture and decode the url, you can use the internal libs to get the url.

Once you have the url (channel_id & channel_key) you can build the pairing url and get the flow connected.

vbudhram · 2026-02-28T01:37:08Z

packages/functional-tests/tests/pairing/pairingFlow.spec.ts

+} from '../../lib/pairing-helpers';
+
+// Increase timeout — pairing involves launching a separate Firefox + channel negotiation
+test.setTimeout(120_000);


Locally this test takes about 60s to complete,=

vbudhram · 2026-02-28T01:39:30Z

packages/functional-tests/lib/marionette.ts

+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+/**
+ * Minimal Marionette protocol client over raw TCP.


I probably would have never thought of doing it this way, but I like it. This introduces zero deps and just talks to marionette via tcp.

Interesting... Can you get Claude to write some specific tests for it? There's enough here I think it should be under test. It'd be confusing if something in this layer started failing unexpectedly.

vbudhram · 2026-02-28T01:42:15Z

packages/functional-tests/lib/fixtures/pairing.ts

+export { expect } from '@playwright/test';
+
+/**
+ * Fetch the pairing channel server URI from the target's well-known config.


Lots of tokens were spent trying to figure this out. Turns out that the channel server on local/stage/prod are all different 🤷🏽

Really? What does that even mean? Are they actually different versions, do they just behave differently? Can we get local aligned with prod?

dschom · 2026-03-03T19:01:13Z

packages/functional-tests/lib/marionette.ts

+        this.buffer = Buffer.alloc(0);
+
+        await this.rawConnect();
+        const helloRaw = await this.recvPacket();


Funny variable name

dschom · 2026-03-03T19:10:19Z

packages/functional-tests/lib/marionette-firefox.ts

+  headless?: boolean;
+}
+
+export class MarionetteFirefox {


Add comment explaining what "MarionetteFirefox" is.

dschom · 2026-03-03T19:13:31Z

packages/functional-tests/lib/marionette-firefox.ts

+      await client.connect(10, 2000);
+      for (let attempt = 0; ; attempt++) {
+        try {
+          await client.newSession();


Is this loop really needed? It seems kind of odd that you have to do this for a connection (line 100) and then again for a session...

dschom · 2026-03-03T19:15:13Z

packages/functional-tests/lib/marionette-firefox.ts

+    killProcessOnPort(marionettePort);
+
+    // Create temp profile with FXA + Marionette prefs
+    const profileDir = fs.mkdtempSync(


Do we have to worry about file permissions here? Guessing not since its using os.tempdir()?

dschom · 2026-03-03T19:17:50Z

packages/functional-tests/lib/marionette-firefox.ts

+          resolve();
+        }, 5000)
+      );
+      await Promise.race([exited, timeout]);


I don't get it... So it's trying to kill the process again, if just respond fast enough the first time? If the first kill didn't work, why would the second one?

dschom · 2026-03-03T19:19:54Z

packages/functional-tests/lib/marionette-firefox.ts

+
+    // Create temp profile with FXA + Marionette prefs
+    const profileDir = fs.mkdtempSync(
+      path.join(os.tmpdir(), 'fx-pairing-test-')


You probably want to add a postfix here. This will always return the same directory, which could cause problems if two processes try to run this code concurrently.

dschom · 2026-03-03T19:20:35Z

packages/functional-tests/lib/marionette-firefox.ts

+  ): Promise<MarionetteFirefox> {
+    const {
+      firefoxBinary,
+      marionettePort = 2828,


Does it always run on this port? What if there's a port conflict?

dschom · 2026-03-03T19:22:09Z

packages/functional-tests/lib/marionette-firefox.ts

+        const parsedPid = parseInt(pid.trim(), 10);
+        if (isNaN(parsedPid) || parsedPid <= 0) continue;
+        try {
+          process.kill(parsedPid, 'SIGKILL');


It's hard to know what's running on the port provided here... Should you there be some kinda guard rail here. Like checking for 'marionette' in the process path something?

dschom · 2026-03-03T19:22:38Z

packages/functional-tests/lib/marionette.ts

+    try {
+      await this.sendCommand('WebDriver:DeleteSession');
+    } catch {
+      // Ignore errors during session deletion


Can we log them at least...

dschom · 2026-03-03T19:28:29Z

packages/functional-tests/lib/marionette.ts

+   * Try to extract a complete packet from the buffer.
+   * Packet format: "LENGTH:JSON_BODY"
+   */
+  private tryDeliverPacket(): void {


I'm not so sure about this function... Seems like it works, but I can see it being flaky. I'll outline why...

dschom · 2026-03-03T19:29:29Z

packages/functional-tests/lib/marionette.ts

+    if (!this.pendingResolve) return;
+
+    const colonIdx = this.buffer.indexOf(0x3a); // ':'
+    if (colonIdx === -1) return;


Are we sure the buffer will always contains this? What if the buffer is big, and the ':' is in the next/prev chunk. Maybe this isn't a big deal... and the message format is always small enough to fit in the buffer... just checking though.

dschom · 2026-03-03T19:39:28Z

packages/functional-tests/lib/marionette.ts

+  ): Promise<Record<string, unknown>> {
+    for (let attempt = 0; attempt < retries; attempt++) {
+      try {
+        if (this.sock) {


This implies we don't want two active connections, which makes sense... But multiple MarionetteClient instnaces can be created which means you could have multiple sockets created and bound to the marionette port... If marinonette doesn't support multiple clients, then we should make class a singleton to avoid any future issues.

dschom · 2026-03-03T19:50:24Z

packages/functional-tests/lib/marionette.ts

+    const expectedId = this.msgId;
+    const msg = JSON.stringify([0, expectedId, name, params]);
+    const packet = `${msg.length}:${msg}`;
+    this.sock.write(packet, 'utf-8');


This isn't checking if the write went through. It could have been partial / not fully drained...

dschom · 2026-03-03T19:52:42Z

packages/functional-tests/lib/marionette.ts

+    const packet = `${msg.length}:${msg}`;
+    this.sock.write(packet, 'utf-8');
+
+    const raw = await this.recvPacket();


AFAICT, if the buffer hasn't recieved data yet, this will just return... I'm not sure how this ensures synchronization. I bet this works most the time, but I can also see it failing if marionnette is slow or laggy to respond to the command.

vbudhram force-pushed the react-pair branch 2 times, most recently from de2e451 to 23dda8b Compare February 27, 2026 18:59

dschom reviewed Feb 27, 2026

View reviewed changes

vbudhram force-pushed the react-pair branch 4 times, most recently from 4a66af3 to ee5412b Compare February 27, 2026 19:54

vbudhram self-assigned this Feb 27, 2026

vbudhram force-pushed the react-pair branch 3 times, most recently from a9e9176 to a1dc25e Compare February 28, 2026 00:42

vbudhram force-pushed the react-pair branch from a1dc25e to 078c87d Compare February 28, 2026 01:16

vbudhram commented Feb 28, 2026

View reviewed changes

vbudhram marked this pull request as ready for review February 28, 2026 01:50

vbudhram requested a review from a team as a code owner February 28, 2026 01:50

vbudhram mentioned this pull request Mar 2, 2026

feat(settings): Convert Pairing flow to React #20126

Draft

4 tasks

dschom reviewed Mar 3, 2026

View reviewed changes

Conversation

vbudhram commented Feb 27, 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 (Optional)

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!

dschom Mar 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dschom Mar 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

dschom Mar 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

vbudhram commented Feb 27, 2026 •

edited

Loading

dschom Mar 3, 2026 •

edited

Loading

dschom Mar 3, 2026 •

edited

Loading

dschom Mar 3, 2026 •

edited

Loading