---
name: ha-frontend-testing
description: Home Assistant frontend testing and validation workflow. Use when adding or updating tests, running lint, TypeScript checks, Vitest, Playwright e2e suites, dev servers, or chart-data benchmarks.
---

# 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

```bash
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:

```bash
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.

## Playwright E2E

Each suite has its own dev server port. Playwright reuses an existing server locally when its configured URL responds; otherwise it performs a slow full build. When a development watcher is being reused, rspack recompiles on save and reruns should not need a restart.

Start the relevant suite server, then run that suite:

| Suite   | Background server                            | Test command            |
| ------- | -------------------------------------------- | ----------------------- |
| App     | `pnpm test:e2e:app:dev --background` on 8095 | `pnpm test:e2e:app`     |
| Demo    | `pnpm dev:demo --background` on 8090         | `pnpm test:e2e:demo`    |
| Gallery | `pnpm dev:gallery --background` on 8100      | `pnpm test:e2e:gallery` |

The custom development wrappers use `/__ha_dev_status` to identify and manage their own suites. Playwright server reuse checks the configured URL instead. Wrapper start and stop operations are idempotent for a matching suite and reject an unrelated process occupying the port.

Local runs against a watched development server do not always match CI's clean build artifacts, environment, sharding, or worker configuration. Use background servers for the fast iteration loop, but confirm the relevant CI jobs complete successfully before considering E2E changes verified.

Use `-g "<title>" --project=chromium` to narrow a run. `pnpm test:e2e` runs suites sequentially when managed servers are unavailable to prevent cold builds racing over shared generated assets. Run suites directly; piping through output truncation hides progress and failures.

The app suite uses a stripped-down harness for e2e. Demo and gallery use their normal dev servers.

## Benchmarks

For chart data transforms such as history, statistics, energy, and downsampling, read and follow the complete workflow in `test/benchmarks/README.md` before making benchmark or optimization changes.

That workflow owns the baseline, noise analysis, guardrails, acceptance thresholds, and reporting requirements. In particular, optimizations must keep output bit-identical; never update snapshots or modify fixtures to make an optimization pass.

## Verification Selection

- Documentation-only change: no code test required unless examples or commands changed.
- Type-only or utility change: run focused Vitest if available, then `pnpm lint:types` if practical.
- Lit component change: run relevant tests plus lint or typecheck depending on scope.
- E2E-sensitive flow: start the relevant e2e dev server and run the narrow Playwright suite.
- Broad refactor: run `pnpm lint` and relevant test suites when practical.