# Lit Webview Testing

> Write or review browser component tests for Lit webviews and VSCode Elements. Use for Playwright component harnesses, fake Effect services, accessibility locators, shadow DOM boundaries, lifecycle tests, and deciding what belongs in component tests versus VS Code E2E.

- Skill: `forcedotcom/lit-webview-testing` (Agent Skill)
- Install (CLI): `npx skillmds@latest add forcedotcom/lit-webview-testing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/forcedotcom/lit-webview-testing/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: forcedotcom (https://skillmd.com/u/forcedotcom)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/forcedotcom/lit-webview-testing

---


# Lit webview browser testing

Real browser required for Lit updates, custom elements, popovers, shadow DOM, accessibility trees, and `ElementInternals`.

## Harness boundary

- Real Lit components, controller, and Effect application lifecycle; only extension backend replaced with a fake service layer.
- No emulated `acquireVsCodeApi()` or local server.
- Fake types derived from their factory/service source of truth—not handwritten copies.
- Fakes support deterministic state emission, action recording, typed stream/dispatch failures, controllable latency, and resource counters.
- Fake latency via Effect `Clock`; `TestClock` in Effect tests, not wall-clock waits.

## What to test here

- Component contracts and state/action flows: initial, loading, disabled, empty/no-match, invalid/recoverable, restored, external update, success, failure.
- Action count/payload, including rapid or latent actions when cancellation/serialization matters.
- Connect, disconnect, reconnect, listener/subscription cleanup, scoped finalization.
- Keyboard, focus, theme, and form behavior where browser semantics matter.
- Thin extension-host E2E: VS Code wiring, packaging, CSP/resources, desktop/web integration, critical journeys.

## Interaction rules

- Controls located by accessible role/name/label; documented public `value`/`checked` set before dispatching the public event.
- Observable UI/application assertions—not private state or arbitrary render delays. Mount helper may await `updateComplete` to establish readiness.
- Unavoidable shadow traversal isolated in 1 named helper, only for otherwise unobservable contracts such as `ElementInternals` form association.
- Wrapper adapting an inaccessible nested node: user-visible accessibility assertion first; narrowly scoped implementation assertion only if needed.

## Repository integration

- Compile, fixture bundle, and browser execution in the package Wireit graph and relevant CI `test:web` path.
- Package compile, lint, unit tests, and focused browser suite run from repository root.
- General syntax/reliability: [playwright-e2e](../playwright-e2e/SKILL.md). This skill owns the component-test boundary.

Examples: `packages/soql-builder-ui/test/browser/`, `packages/soql-builder-ui/src/testing/fakeEffectService.ts`.