test(webview): configure Codecov JSDOM coverage ratcheting

Author: edelauna

.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

codecov.yml

@@ -6,13 +6,27 @@ 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
     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
 
 flag_management:
   individual_flags:
+    - name: webview-ui
+      paths:
+        - webview-ui/src/
+      carryforward: true
     - name: core-unit
       paths:
         - packages/core/src/
@@ -22,6 +36,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

webview-ui/AGENTS.md

@@ -2,12 +2,45 @@
 
 This file provides guidance to agents working in `webview-ui/`.
 
+## Testing Strategy Overview
+
+We use a complementary two-layer strategy for testing webview UI code:
+
+1. **Vitest + JSDOM (`*.test.tsx`)**: Unit, hook, state-machine, and interaction tests.
+2. **Playwright Component Testing (`*.visual.tsx`)**: Visual snapshot, VS Code theme variable, layout, and shadow DOM tests.
+
+---
+
+### When to write a JSDOM Test (`*.test.tsx`) vs. a Playwright Visual Test (`*.visual.tsx`)
+
+| Testing Goal                                                          | Recommended Harness                                                   |
+| :-------------------------------------------------------------------- | :-------------------------------------------------------------------- |
+| Component state transitions, reducer actions, custom hook behavior    | **Vitest + JSDOM** (`*.test.tsx`)                                     |
+| User interactions (button clicks, form validation, text typing)       | **Vitest + JSDOM** (`*.test.tsx`) using `@testing-library/user-event` |
+| Conditional DOM rendering or prop wiring                              | **Vitest + JSDOM** (`*.test.tsx`)                                     |
+| Visual layout, flexbox/grid alignment, or padding/margin verification | **Playwright CT** (`*.visual.tsx`)                                    |
+| VS Code dark/light theme CSS tokens (`--vscode-*`)                    | **Playwright CT** (`*.visual.tsx`)                                    |
+| Web component shadow DOM style encapsulation & upgrades               | **Playwright CT** (`*.visual.tsx`)                                    |
+
+---
+
+## Unit & State Tests (Vitest + JSDOM)
+
 - Prefer local `webview-ui` tests for React/webview behavior. If a change is about component rendering, local state, hooks, form dirty-state, validation, or prop wiring inside the webview, add or update Vitest coverage under `webview-ui/src/**/__tests__` instead of reaching for `apps/vscode-e2e`.
 - Use `apps/vscode-e2e` only when the behavior depends on the real VS Code extension environment: extension-host to webview messaging, VS Code workspace APIs, task execution flows, or other end-to-end behavior that needs `@vscode/test-electron`.
 - When a regression can be proven with a component or webview integration test, keep it in `webview-ui`. Do not promote it to e2e just because the UI is hosted inside VS Code.
 - For `SettingsView`, preserve the cached-state pattern from the repo root guidance: inputs should operate on local `cachedState` until the user saves, and tests should distinguish automatic initialization from real user edits.
 
-## Visual Tests
+### Coverage & Codecov Quality Gates
+
+Codecov tracks `webview-ui` coverage under the `webview-ui` flag.
+
+- **Ratcheting (`target: auto`)**: Overall webview coverage will never drop below the current baseline as new tests are added.
+- **Patch Gate (`target: 70%`)**: New or modified lines in PRs touching `webview-ui/src/` must meet minimum test coverage, ensuring state changes and new UI logic stay tested over time.
+
+---
+
+## Visual Tests (Playwright CT)
 
 - Add Playwright screenshot tests selectively for components where layout, styling, VS Code theme variables, or real web-component rendering are part of the behavior under test.
 - Keep behavioral assertions in Vitest. A `*.visual.tsx` test should establish a deterministic state and make a focused screenshot assertion.

webview-ui/vitest.config.ts

@@ -33,6 +33,8 @@ export default defineConfig({
 				"**/*.test.tsx",
 				"**/*.spec.ts",
 				"**/*.spec.tsx",
+				"**/*.visual.ts",
+				"**/*.visual.tsx",
 				"**/vitest.setup.ts",
 				"**/vitest.config.ts",
 				"**/vite.config.ts",