Skip to content
docsp
On this page

Tests and CI

Unit tests, end-to-end tests with axe, the visual comparison script and the CI sequence.

Unit tests

Terminal
$ pnpm build:pkg
$ pnpm test:unit

Node'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

Terminal
$ pnpm build
$ npx playwright install chromium
$ pnpm test:e2e

Playwright 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.

↑ ↓ to move↵ to openSearching docsp