API reference screenshot test

This page shows a screenshot of the API reference, captured automatically by Doc Detective rather than pasted in by hand.

Why this matters​

The pipeline test checks static content: markdown that Docusaurus renders once, at build time. This page checks something more fragile — a live, third-party render pipeline. The API reference isn't part of this site's build output. Every time someone loads it, Scalar fetches a script from a CDN, fetches the OpenAPI spec, and renders the whole reference client-side, in the browser, on the spot. Any of those steps can break independently of anything in this repo: the CDN can be unreachable, a Scalar release can change how it renders, the spec file can go missing.

That said, this test proves the pipeline produced something, not that the something is correct. A separate comparison step narrows that gap by checking the rendered output against a reference image, not just its presence.

Latest result​

Screenshot​

How the test works​

The test is defined directly in this page's source as embedded Doc Detective steps and runs the following:

1. Navigate to the API reference.

2. Confirm Scalar mounted its rendered heading element, proving the client-side render pipeline actually produced output instead of an empty or broken page.

3. Capture a screenshot and save it as api-reference.png.

4. Capture a second screenshot and compare it against the reference image saved at api-reference-baseline.png, allowing up to 2% pixel difference. This step doesn't fail the test either way — see the screenshot comparison test for what maxVariation actually does and why it reports WARNING instead of FAIL.

What makes this test fail​

The test fails only if find can't locate an h1.section-header-label element within 20 seconds. In practice that means the CDN script never loaded, the OpenAPI spec never fetched, or Scalar's render broke badly enough to produce no heading at all.

It does not fail if the page renders with broken, wrong, or degraded content, as long as some element matching that selector exists. The comparison step narrows this gap without turning it into a hard failure: because this page rarely changes, a WARNING here is a meaningful signal that something visual actually shifted, worth checking even though it doesn't redden the badge.

Run the test manually​

If you clone this repo, then you can run the test locally.

npm install -g doc-detective
cd website && npm run build && npx docusaurus serve --no-open &
doc-detective --config doc-detective/config.json --input website/src/pages/doc-detective/api-reference-test.mdx

Run the test on GitHub Actions​

The test runs automatically every day and on every push to main that touches the API reference or this page. To trigger it on demand:

1. Go to the Actions tab in the GitHub repository.
2. Select API reference screenshot test.
3. Click Run workflow.