Ha Frontend Testing

HA Frontend Testing

Use this skill when choosing or running validation for frontend changes.

Test Helpers

• Before adding or changing tests, inspect the relevant suite's existing helpers and fixtures. Reuse them instead of duplicating setup, test data, navigation, interactions, waits, or assertions.
• When the same test flow appears more than once, move it into the closest suite-local helper with a focused interface.
• Keep one-off test behaviour in the test unless a helper makes the intent materially clearer. Do not hide the behaviour under test behind broad, configurable abstractions.

Core Commands

pnpm lint          # ESLint + Prettier + TypeScript + Lit
pnpm format        # Auto-fix ESLint + Prettier
pnpm lint:types    # TypeScript compiler, run without file arguments
pnpm test          # Vitest
pnpm build         # Full production build
pnpm dev           # App dev server
pnpm dev:serve     # Local serving dev server

Never run tsc or pnpm lint:types with file arguments. File arguments make tsc ignore tsconfig.json and can emit .js files into src/.

For focused type feedback on one file, use editor diagnostics instead of a file-scoped tsc command.

Production Builds

Production builds support foreground and managed background execution:

pnpm build                         # Full foreground build
pnpm build --background            # Full managed background build
pnpm build --modern                # Modern frontend_latest bundle only
pnpm build --modern --background   # Modern managed background build
pnpm build --status
pnpm build --logs [--follow]
pnpm build --stop

Use pnpm build --modern --background for production bundle-size or browser performance comparisons that only need modern browser output. It runs the normal metadata and static preparation, minifies and compresses the modern frontend_latest bundle and shared static assets, and generates modern-only entry pages and service workers. It deliberately skips the legacy bundle and its service worker.

Do not pass --help, --background, or --modern to script/build_frontend; that raw script does not parse arguments and always starts the full foreground build. Use pnpm build for managed builds. App builds and development servers keep exclusive ownership of hass_frontend/ for their lifetime.

Managed app, demo, gallery, and E2E app workflows share one lifetime lock, so only one build or development server can run at a time.

When To Add Tests

• Write tests for code that computes something: data processing, utilities, config validation, and strategies.
• Do not write rendering tests. This includes views, panels, and components whose text, styles, slots, or option defaults are checked, or that only put context and helper data into a template.
• Do not try to cover every scenario, especially for behaviour that changes often.
• If you are not sure a test is useful, describe it and what it would catch, and let the user decide.
• Tests never talk to a real Home Assistant. Replace callWS, callApi, and the connection with fakes.

Dev Servers

pnpm dev builds and watches the app, served by a running Home Assistant core configured through development_repo.

pnpm dev:serve also serves locally and supports -c for the core URL and -p for the port. The default is 8124, or 8123 in a devcontainer.

Dev server commands support --background, --status, --stop, and --logs [--follow]. pnpm dev, pnpm dev:serve, pnpm dev:demo, and pnpm dev:gallery also support --fetch-translations; this runs translation fetching, including first-time GitHub device authentication, under the workflow lock before starting the watcher. It works in foreground and background modes. Prefer managed background mode while iterating so the watcher stays available across test runs without occupying the terminal. pnpm dev and pnpm dev:serve share one managed process slot because both write the app output.