On this page
Tests and CI
Unit tests, end-to-end tests with axe, the visual comparison script and the CI sequence.
Unit tests
$ pnpm build:pkg
$ pnpm test:unitNode's test runner runs packages/docsp/test/*.test.mjs against the compiled package: color contrast, configuration
error messages, the theme.css guard, Markdown directives, code themes, SCIP decoding, symbol ids, nm linker edges
and TLA+ exports. test/scip-fixture.mjs builds synthetic SCIP indexes for the tests and for the example site.
End-to-end tests
$ pnpm build
$ npx playwright install chromium
$ pnpm test:e2ePlaywright serves examples/site/dist on port 4321 and tests, in Chromium:
- real pages and the component catalog at several widths, in light and dark mode, with axe;
- no horizontal scroll at 390 px, and touch targets of at least 44 by 44 px;
- no request to another origin;
- search, menus, versions, languages, banners, feedback, Copy for LLM and the API reference;
- client-side navigation between pages, projects, versions and locales;
- symbol links, symbol pages and code themes.
SCREENSHOT_DIR=<dir> pnpm test:e2e saves screenshots.
Visual comparison
pnpm compare --ref <reference pages dir> --out <dir> captures each page of the design specification and the
matching rebuilt page at 1440 and 390 px, in light and dark mode, and writes side-by-side images with a pixel diff.
--only 01,08 limits the run. The reference pages are not in the repository, so this does not run in CI. Remaining
differences and their reasons are listed in docs/visual-differences.md.
CI
.github/workflows/ci.yml runs on every pull request and on pushes to main, in this order:
1. Install
pnpm install --frozen-lockfile, with the full git history (fetch-depth: 0) for page dates.
2. Build and unit-test the package
pnpm build:pkg, then pnpm test:unit.
3. Check generated files
pnpm tokens and docs:config, then git diff --exit-code on the tokens and on configuration.md.
4. Lint tokens
pnpm lint:tokens.
5. Check and build the example site
docsp check, then docsp build on examples/site.
6. Check and build this site
docsp check, then docsp build on site, so broken documentation fails CI.
7. End-to-end tests
Install Chromium and run pnpm test:e2e. On failure, the Playwright results are uploaded as an artifact.
.github/workflows/docs.yml deploys this site to Cloudflare Workers on pushes to main that touch site/,
packages/ or the lockfile; see Deployment.