Skip to content

Broaden test coverage of the docs build #3

Open

Description

@pimlock

Problem

#1 adds the first tests: the format readers in assembler/adapters.mjs, and one end-to-end test of assembler/assemble.mjs against two small local git repos (link rewriting, repo:// links, redirects, warnings versus errors, --local). Much of the build is still untested, so a change can break the published site without failing CI.

Not covered yet

  • Markdown for agents (assemble.mjs, step 6): converting MDX components (callouts, tabs, cards, ParamField, CommandTerminal) to Markdown, <llms-only> and <llms-ignore>, and the fallback when conversion fails.
  • Fern details: folder: entries and their position ordering, {#custom-id} heading anchors, and imports of Fern's _components.
  • Assets and relative links: links to files next to a page, and the missing-file problem.
  • Topic overview pages: generated when a topic has several docsets, with an optional intro from this repository.
  • site/scripts/sync.mjs: version banners (dev, not latest), the pagefind: false flag, component imports, and Mermaid rendering.
  • scripts/redirects.mjs: /<mount>/latest/ pages and redirect pages.
  • site/src/versioning.ts: sidebar, version picker (same page versus first page), topic tabs, and sub-tabs.
  • The built site: a smoke test that serves site/dist and checks a few pages, the version picker, search, and the Markdown copies. The prototype had a Playwright script for this.

Proposal

  • Split assemble.mjs into functions (fetch, read, links, outputs) so link resolution and Markdown conversion can be unit-tested without a full run.
  • Add fixtures for each case above, and measure coverage with node --test --experimental-test-coverage.
  • Add the site smoke test as a CI step after the build.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions