test(webview): add Playwright visual regression harness (#526)

* test(webview): add visual regression harness

* fix(webview): resolve relative compose path & font race in visual tests

* test(webview): configure Codecov JSDOM coverage ratcheting

* feat(webview): add Playwright CT coverage ratcheting

* fix(webview): swap visual regression target off deprecated toolkit

* chore(webview): address CodeRabbit review feedback

* fix(webview): emit Playwright CT coverage LCOV

* fix(webview): address code review feedback for Playwright CT harness

* docs: prefer committed visual snapshots; split videos into their own lane

* revert(RooHero): removing on hover test - can't make it deterministic

Author: edelauna

.github/pull_request_template.md

@@ -38,14 +38,35 @@ Detail the steps to test your changes. This helps reviewers verify your work.
 - [ ] **Scope**: My changes are focused on the linked issue (one major feature/fix per PR).
 - [ ] **Self-Review**: I have performed a thorough self-review of my code.
 - [ ] **Testing**: New and/or updated tests have been added to cover my changes (if applicable).
+- [ ] **Visual Snapshot** (UI changes only): If a user would notice this change at a glance (layout, theme tokens, brand elements, empty/error states), I've added or updated a `*.visual.tsx` snapshot in `webview-ui/`. See `webview-ui/AGENTS.md` → "When a UI change needs a snapshot".
 - [ ] **Documentation Impact**: I have considered if my changes require documentation updates (see "Documentation Updates" section below).
 - [ ] **Contribution Guidelines**: I have read and agree to the [Contributor Guidelines](/CONTRIBUTING.md).
 
-### Screenshots / Videos
+### Visual Snapshots
 
 <!--
-For UI changes, please provide before-and-after screenshots or a short video of the *actual results*.
-This greatly helps in understanding the visual impact of your changes.
+For UI changes to static rendered state, the primary artifact is a committed
+Playwright CT snapshot (`*.visual.tsx` in `webview-ui/`) — that baseline
+becomes durable regression coverage for the surface. See
+`webview-ui/AGENTS.md` for what deserves a snapshot.
+
+Before/after screenshots pasted here are welcome as a review aid but are not a
+substitute for the committed baseline. If a snapshot is possible, prefer the
+snapshot.
+-->
+
+### Videos (interaction / animation only)
+
+<!--
+Snapshots cannot capture motion or multi-step flows. Attach a short screen
+recording here when reviewers need to see:
+  - A new interactive flow (dropdown, form, dialog progression)
+  - Animation, transition, or timing behavior
+  - A regression that only manifests during interaction
+
+Videos are a review aid, not regression coverage. If the *result* of the
+interaction has a distinct rendered state worth protecting, still commit a
+`*.visual.tsx` snapshot of that end-state alongside the video.
 -->
 
 ### Documentation Updates

.github/workflows/code-qa.yml

@@ -135,25 +135,32 @@ jobs:
             # lanes for behavioral confidence, but duplicating coverage uploads
             # there mostly adds Codecov overhead without changing pass/fail
             # behavior.
-            # Coverage is uploaded in three separate steps so each LCOV gets the
+            # Coverage is uploaded in separate steps so each LCOV gets the
             # correct flag set. Codecov double-counts overlapping lines when a
             # single upload carries multiple flags whose paths overlap, so the
-            # two core lanes (which both cover packages/core/src/**) must be
-            # uploaded individually with their own lane flag.
+            # core lanes and webview lane must be uploaded individually with
+            # their own flag.
             # See https://docs.codecov.com/docs/flags
             - name: Upload non-core coverage to Codecov
               if: matrix.upload-coverage
               uses: codecov/codecov-action@b9fd7d16f6d7d1b5d2bec1a2887e65ceed900238 # v4
               with:
                   files: >-
                       src/coverage/lcov.info,
-                      webview-ui/coverage/lcov.info,
                       packages/cloud/coverage/lcov.info,
                       packages/telemetry/coverage/lcov.info,
                       apps/cli/coverage/lcov.info
                   disable_search: true
                   flags: ${{ matrix.codecov-flag }}
                   token: ${{ secrets.CODECOV_TOKEN }}
+            - name: Upload webview JSDOM coverage to Codecov
+              if: matrix.upload-coverage
+              uses: codecov/codecov-action@b9fd7d16f6d7d1b5d2bec1a2887e65ceed900238 # v4
+              with:
+                  files: webview-ui/coverage/lcov.info
+                  disable_search: true
+                  flags: webview-ui
+                  token: ${{ secrets.CODECOV_TOKEN }}
             - name: Upload core unit coverage to Codecov
               if: matrix.upload-coverage
               uses: codecov/codecov-action@b9fd7d16f6d7d1b5d2bec1a2887e65ceed900238 # v4

.github/workflows/visual-regression.yml

@@ -0,0 +1,57 @@
+name: Webview Visual Regression
+
+on:
+    workflow_dispatch:
+    pull_request:
+        types: [opened, reopened, ready_for_review, synchronize]
+        paths:
+            - "webview-ui/**"
+            - "src/shared/**"
+            - "package.json"
+            - "pnpm-lock.yaml"
+            - ".github/workflows/visual-regression.yml"
+    merge_group:
+        types: [checks_requested]
+
+concurrency:
+    group: ${{ github.workflow }}-${{ github.ref }}
+    cancel-in-progress: true
+
+permissions:
+    contents: read
+
+jobs:
+    webview-visual:
+        runs-on: ubuntu-latest
+        timeout-minutes: 10
+        container:
+            image: mcr.microsoft.com/playwright:v1.60.0-noble@sha256:9bd26ad900bb5e0f4dee75839e957a89ae89c2b7ab1e76050e559790e946b948
+            options: --ipc=host
+        steps:
+            - name: Checkout code
+              uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+              with:
+                  persist-credentials: false
+            - name: Setup Node.js and pnpm
+              uses: ./.github/actions/setup-node-pnpm
+              with:
+                  install-args: "--frozen-lockfile"
+            - name: Run webview visual tests
+              run: pnpm --filter @roo-code/vscode-webview test:visual
+            - name: Upload visual test coverage to Codecov
+              if: always()
+              uses: codecov/codecov-action@b9fd7d16f6d7d1b5d2bec1a2887e65ceed900238 # v4
+              with:
+                  files: webview-ui/coverage-ct/lcov.info
+                  disable_search: true
+                  flags: webview-ui-ct
+                  token: ${{ secrets.CODECOV_TOKEN }}
+            - name: Upload visual test artifacts
+              if: failure()
+              uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+              with:
+                  name: webview-visual-regression
+                  path: |
+                      webview-ui/playwright-report
+                      webview-ui/test-results
+                  if-no-files-found: ignore

codecov.yml

@@ -6,13 +6,33 @@ coverage:
       default:
         target: auto      # never regress below current baseline
         threshold: 1%
+      webview:
+        target: auto      # webview project ratchet: never drop below current baseline
+        threshold: 0.5%
+        flags:
+          - webview-ui
+          - webview-ui-ct
     patch:
       default:
         target: 80%       # new lines must be 80% covered
         threshold: 0%
+      webview-patch:
+        target: 70%       # new lines in webview must be 70% covered
+        threshold: 0%
+        flags:
+          - webview-ui
+          - webview-ui-ct
 
 flag_management:
   individual_flags:
+    - name: webview-ui
+      paths:
+        - webview-ui/src/
+      carryforward: true
+    - name: webview-ui-ct
+      paths:
+        - webview-ui/src/
+      carryforward: true
     - name: core-unit
       paths:
         - packages/core/src/
@@ -22,6 +42,18 @@ flag_management:
         - packages/core/src/
       carryforward: true
 
+component_management:
+  individual_components:
+    - component_id: webview_components
+      name: "Webview UI Components"
+      paths:
+        - webview-ui/src/components/
+    - component_id: webview_state
+      name: "Webview State & Context"
+      paths:
+        - webview-ui/src/context/
+        - webview-ui/src/state/
+
 comment:
-  layout: "diff, flags"
+  layout: "diff, flags, components"
   behavior: default

knip.json

@@ -1,8 +1,10 @@
 {
 	"$schema": "https://unpkg.com/knip@5/schema.json",
 	"ignore": ["**/__tests__/**", "apps/vscode-e2e/**", "scripts/**", "apps/cli/scripts/**"],
-	"ignoreDependencies": ["lint-staged", "ovsx"],
+	"ignoreDependencies": ["lint-staged"],
 	"ignoreExportsUsedInFile": true,
+	"playwright": false,
+	"playwright-ct": false,
 	"workspaces": {
 		"src": {
 			"entry": ["extension.ts", "extension/api.ts", "workers/countTokens.ts"],
@@ -30,7 +32,7 @@
 				"source-map",
 				"tailwindcss",
 				"tailwindcss-animate",
-				"vscode"
+				"monocart-reporter"
 			]
 		},
 		"apps/cli": {