Testing Guidelines

The Elements library uses a comprehensive testing strategy with many test types to ensure quality, accessibility, and performance. All tests follow consistent patterns and use shared utilities from @internals/testing and @internals/vite.

Running Tests

Run test scripts from the root directory of the project where the package.json lives.

# Unit tests
pnpm run test

# Single test suite
pnpm run test -- src/badge/badge.test.ts

# Accessibility tests
pnpm run test:axe

# Performance tests
pnpm run test:lighthouse

# Render regression tests (Core)
pnpm run test:render

# WebGPU rendering tests
pnpm run test:webgpu

# Visual regression tests
pnpm run test:visual

# SSR tests
pnpm run test:ssr

Test Types

Unit Tests (.test.ts)

• Unit Tests (.test.ts): Standard behavior tests.
• Accessibility Tests (.test.axe.ts): best practices tests using axe-core.
• Lighthouse Performance Tests (.test.lighthouse.ts): performance audits and best practices via Lighthouse
• Visual Regression Tests (.test.visual.ts): Visual regression tests using Playwright screenshots.
• SSR Tests (.test.ssr.ts): Server-side rendering compatibility tests.
• WebGPU rendering tests (.test.webgpu.ts): External rendering, resource, timing, diagnostic, and lifecycle tests orchestrated by Vitest against a clean Playwright page.

Render regression tests (.test.render.ts)

Core measures Chromium layout and style recalculation counts during interactions on an isolated Playwright page. These counts include legitimate rendering and do not count forced reflows. Use vitest.render.ts with libraryRenderTestConfig. Keep explicit count budgets, readiness, and completion boundaries in each scenario. The shared runner documentation includes the API, a complete grid example, calibration results, commands, and trace investigation guidance.

Test Configuration

Vitest Configs

Each test type has its own Vitest configuration:

• Unit tests: vitest.config.ts using libraryTestConfig
• Axe tests: vitest.axe.ts using libraryAxeTestConfig
• Lighthouse tests: vitest.lighthouse.ts using libraryLighthouseConfig
• Render tests: vitest.render.ts using libraryRenderTestConfig
• WebGPU tests: vitest.webgpu.ts using libraryWebGPUTestConfig
• Visual tests: vitest.visual.ts using libraryVisualTestConfig
• SSR tests: vitest.ssr.ts using libraryLitSSRTestConfig

HTML Templates

Lighthouse, Render, and Visual tests require HTML templates:

• vitest.lighthouse.html - Base template for Lighthouse tests
• vitest.render.html - Base template for Render tests
• vitest.visual.html - Base template for Visual tests

Testing Utilities

@internals/testing

Core testing utilities for DOM manipulation and element stability:

• createFixture: Creates test fixture DOM element
• removeFixture: Removes test fixture DOM
• elementIsStable: Waits for Lit element to be stable
• emulateClick: Triggers native click events
• untilEvent: Creates promise for event results