Docs Website Tests
The Docusaurus docs site (website/) has its own small Vitest suite, separate
from the five-tier model of the main app. It runs in plain Node with no
mocking — tests exercise real files in real (temp) directories.
npm run docs:test # from the repo root (cd website && npm test)
cd website && npm test # equivalent
npm run test:run (the CI one-shot command) chains docs:test after the
Tier 1–4 suites, so these tests run on every CI pass.
Test files
Tests live in website/tests/ (not co-located — they cover site-wide
concerns, not individual modules).
website/tests/links.test.ts
Static internal-link integrity. Collects every valid route from
website/src/pages/, docs/user/ (/docs/...), and docs/dev/
(/dev/...), then extracts every internal link (](/...) in Markdown,
to="/..." / href="/..." in JSX, code blocks stripped) and asserts each
one resolves to an existing page or doc. One test case per link via
it.each, so a broken link fails with the offending file and target in the
test name.
website/tests/rawMarkdownPlugin.test.ts
End-to-end coverage of website/src/plugins/rawMarkdownPlugin.ts — the
custom plugin that publishes raw .md copies of each doc page plus a
generated /llms.txt index (see
LLM Access to Documentation).
Each test builds a temp siteDir, writes real Markdown source files, feeds
the plugin fake content-docs data (allContentLoaded), runs postBuild
against a temp outDir, and asserts on the actual files written:
| Behaviour | Assertion |
|---|---|
.md written at route path | outDir/docs/guide.md contains the raw source, frontmatter intact |
| Nested permalinks | outDir/docs/legal/privacy.md created (dirs made recursively) |
@site source outside siteDir | @site/../docs/user/intro.md resolves correctly (the real layout) |
| Trailing-slash permalink | / → index.md, not .md |
| Non-default locale pass | outDir stays empty — the en-only guard |
llms.txt sections | /legal/ permalinks under ## Legal, rest under ## Docs |
llms.txt URLs | Absolute, .md-suffixed, no ../, no double slashes |
| Description fallback | Empty description falls back to the doc title |
siteConfig.url normalisation | Trailing slash stripped — no https://host//docs/... |
These assertions mirror the four failure modes observed when the
third-party docusaurus-plugin-llms package was evaluated and rejected
(wrong output paths, ../ in URLs, locale passes overwriting each other,
stray output) — the test suite exists to keep those bugs impossible to
reintroduce silently.
What is NOT covered here
| Scope | Reason / where covered |
|---|---|
| Full Docusaurus builds | Verified manually via npm run build / build:dev (see the verification checklist in LLM Access to Documentation) |
_headers Content-Type rules | Cloudflare Pages behaviour — spot-checked live with curl -sI after deploy |
remarkLocalizeDate.ts | Untested; date formatting is cosmetic and locale output is eyeballed per locale |
| Rendered HTML / theme components | No component tests for the docs site; changes are reviewed in the local preview |