# 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:

::::steps
## Install

`pnpm install --frozen-lockfile`, with the full git history (`fetch-depth: 0`) for page dates.

## Build and unit-test the package

`pnpm build:pkg`, then `pnpm test:unit`.

## Check generated files

`pnpm tokens` and `docs:config`, then `git diff --exit-code` on the tokens and on `configuration.md`.

## Lint tokens

`pnpm lint:tokens`.

## Check and build the example site

`docsp check`, then `docsp build` on `examples/site`.

## Check and build this site

`docsp check`, then `docsp build` on `site`, so broken documentation fails CI.

## 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](../guides/deployment.md).
