Automated Smoke Testing
Relevant source files
The following files were used as context for generating this wiki page:
Automated Smoke Testing ensures the visual and functional integrity of the HX-UI component library by verifying that pages and components render correctly in a real browser environment. This process complements static checks like TypeScript compilation and design token validation to catch runtime errors that tools like tsc or vite build might miss.
The smoke testing system specifically targets the documentation site, which consists of 38 pages representing live examples of every component. By programmatically opening these pages and inspecting the Document Object Model (DOM), the system detects critical failures such as white-screen errors caused by incorrect Radix UI Provider usage or component API mismatches.
Sources: README.md:1-5, README.md:94-100
Verification Pipeline Architecture
The smoke testing logic resides within the broader verification pipeline. This pipeline executes a series of checks starting from the base component library and extending to the documentation site.
The verification pipeline follows a sequence of build and check scripts to ensure library stability.
Sources: package.json:28-34, README.md:90-93
Smoke Test Implementation
The smoke test identifies rendering failures by simulating user access to the documentation site. The test script extracts the list of pages from the navigation configuration and validates the resulting DOM structure.
Browser Interaction Logic
The test utilizes Chromium to open the browser and navigate through the components. If Chromium is not installed, the test defaults to skipping unless the --strict flag is applied, in which case it results in a failure. This ensures that Continuous Integration (CI) environments strictly enforce browser-level validation.
| Feature | Description | File Reference |
|---|---|---|
| Script Location | scripts/check-smoke.mjs | README.md:99 |
| Page Source | Extracted from docs/src/nav.ts | README.md:99 |
| Strict Mode | Uses --strict to fail CI if Chromium is missing | README.md:100 |
| Detection Target | White-screen errors and DOM rendering failures | README.md:94-98 |
Sources: README.md:94-100, package.json:30-31
Execution Commands
You trigger smoke testing through standard npm scripts defined in the project root.
# Run basic smoke test (skips if no browser)
npm run check:smoke
# Run strict smoke test (fails if no browser)
npm run check:smoke:strict
# Run full verification suite including smoke tests
npm run verify
Sources: package.json:30-34, README.md:90-93
Integrated Safeguards
Smoke testing is one part of a multi-layered validation strategy. Other automated guards ensure that components follow design conventions and maintain synchronization with upstream sources.
Design Token Validation
The check-ui-rules.mjs script acts as a gatekeeper for design tokens. It prevents the use of hard-coded hex values, non-semantic palettes, and non-standard borders. If these rules are violated, the script returns a non-zero exit code, stopping the build.
The rule checker enforces strict adherence to design system tokens.
Sources: README.md:76-80, package.json:33
Synchronization Checks
The library maintains visual consistency with the open-vetta design language through a synchronization script. This script automates the retrieval of upstream source code while preserving visual class names, ensuring that automated tests run against the intended visual state.
# Sync components from upstream path
bash scripts/sync-upstream.sh [upstream_path]
Sources: scripts/sync-upstream.sh:1-20, README.md:107-111
Summary
Automated Smoke Testing provides the final layer of defense for HX-UI by validating the actual rendering output of 38 component pages. By integrating these browser-level checks into the npm run verify workflow alongside design rule enforcement and type checking, the project ensures that code changes do not result in functional regressions or visual breakages in the documentation environment.
Sources: README.md:94-100, package.json:34