From 76c8e91d4a74137bba2e05974de2876fdad60ba4 Mon Sep 17 00:00:00 2001
From: Brennan Benson <79079362+brennanb2025@users.noreply.github.com>
Date: Fri, 11 Sep 2026 20:25:49 -0700
Subject: [PATCH] fix(e2e): run worktree first-paint probe on a mapped window
 (#20197)

Co-authored-by: Merge Sim <sim@local>
---
 .github/workflows/e2e.yml                     | 5 +++++
 config/scripts/pr-e2e-gate-contract.test.mjs  | 7 +++++++
 tests/e2e/worktree-switch-first-paint.spec.ts | 7 ++++++-
 3 files changed, 18 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/e2e.yml b/.github/workflows/e2e.yml
index 942f0f34a56..a07bf0991ec 100644
--- a/.github/workflows/e2e.yml
+++ b/.github/workflows/e2e.yml
@@ -173,6 +173,11 @@ jobs:
       - name: Run E2E tests (${{ matrix.shard_name }})
         run: xvfb-run --auto-servernum bash .github/scripts/e2e-with-window-manager.sh env SKIP_BUILD=1 ORCA_E2E_FORWARD_APP_LOGS=1 ORCA_E2E_WEB_CLIENT=1 ORCA_RELAY_PATH="$GITHUB_WORKSPACE/out/relay" pnpm run test:e2e --shard=${{ matrix.shard }}
 
+      # The frame benchmark needs a mapped window, which the headless shards exclude.
+      - name: Run worktree first-paint benchmark
+        if: matrix.shard == '1/14'
+        run: xvfb-run --auto-servernum bash .github/scripts/e2e-with-window-manager.sh env SKIP_BUILD=1 ORCA_E2E_FORWARD_APP_LOGS=1 pnpm exec playwright test tests/e2e/worktree-switch-first-paint.spec.ts --config tests/playwright.config.ts --project=electron-headful --workers=1
+
       # Why: Playwright retains traces/screenshots only on failure. Uploading
       # them as an artifact makes post-mortem debugging on CI possible without
       # re-running locally.
diff --git a/config/scripts/pr-e2e-gate-contract.test.mjs b/config/scripts/pr-e2e-gate-contract.test.mjs
index 4f012b105b4..22677bb152f 100644
--- a/config/scripts/pr-e2e-gate-contract.test.mjs
+++ b/config/scripts/pr-e2e-gate-contract.test.mjs
@@ -179,6 +179,13 @@ describe('PR E2E gate contract', () => {
       'pnpm run test:e2e "${TEST_FILES[@]}" --workers=1 "${E2E_PROJECT_ARGS[@]}"'
     )
     expect(playwrightConfig).toContain('retries: 0')
+    const steps = e2eWorkflow.jobs.e2e.steps.filter((step) =>
+      step.run?.includes('tests/e2e/worktree-switch-first-paint.spec.ts')
+    )
+    expect(steps).toHaveLength(1)
+    expect(steps[0].if).toBe("matrix.shard == '1/14'")
+    expect(steps[0].run).toContain('xvfb-run --auto-servernum')
+    expect(steps[0].run).toContain('--project=electron-headful --workers=1')
   })
 
   it('keeps startup-exec live parity in the isolated SSH lane', () => {
diff --git a/tests/e2e/worktree-switch-first-paint.spec.ts b/tests/e2e/worktree-switch-first-paint.spec.ts
index f062b6e246a..307e179faf6 100644
--- a/tests/e2e/worktree-switch-first-paint.spec.ts
+++ b/tests/e2e/worktree-switch-first-paint.spec.ts
@@ -372,7 +372,12 @@ function median(values: readonly number[]): number {
   return sorted.length % 2 === 0 ? (sorted[middle - 1] + sorted[middle]) / 2 : sorted[middle]
 }
 
-test.describe('Worktree switch first paint', () => {
+// Linux needs a mapped window for animation frames after reload; run on an isolated display.
+test.describe('Worktree switch first paint @headful', () => {
+  test.skip(
+    process.env.ORCA_BACKGROUND_LAUNCH === '1',
+    'First-paint measurement requires a mapped window'
+  )
   test('repaints an unmounted worktree within the switch budget', async ({
     orcaPage,
     testRepoPath