Skip to content

Docs-as-tests validation

Documentation drifts out of date the moment the systems it describes change: a link rots, an API host moves, a copied code sample no longer parses. Docs-as-tests treats your published documentation like a test suite: it checks your content against the live world on a schedule and reports what no longer holds up.

The scan only reports findings. It never edits content. Each finding tells you which topic is affected and what looks wrong, so you can decide whether to fix it.

Docs-as-tests scans published topics only. Draft and In Review topics are skipped, because the goal is to catch problems readers can actually hit.

What it checks

Each run performs three independent checks across every published topic in the project.

Check

What it does

Finding type

Link validation

Sends a request to every external http/https link in a topic and flags any that fail to resolve (connection error, 404, or other non-OK status).

docs_test_link_broken

API endpoint checks

For reference topics only, extracts API base URLs (those containing an api or version segment such as /v1/) and checks that the base URL still responds.

docs_test_api_changed

Code sample validation

Parses fenced code samples by language and flags ones that fail a syntax check.

docs_test_code_invalid

The scan collects every external link in a published topic and requests each one. Internal cross-references (links to other topics) are not checked here. Those are covered by the broken-topic-link Content health indicators. Requests are rate-limited and protected against requests to private or internal network addresses.

A link is flagged when it returns a connection error or any non-OK HTTP status. The finding records the failing URL and the status code.

API endpoint checks

This check runs only on topics whose type is reference, typically API documentation, including topics imported from an OpenAPI spec. It scans the topic text for API URLs, reduces each to its base (scheme, host, and the leading path segments), and checks that the base still responds. A failing or unreachable base URL suggests the documented API may have moved or changed, and that the topic needs review.

Code sample validation

Fenced code blocks with a declared language are checked for syntax problems. Validation is language-aware:

Language

Check

JSON

Must parse as valid JSON

XML

Flags tags that appear to be unclosed

HTML

Flags content that appears to have unclosed tags

YAML

Flags tab characters (YAML requires spaces for indentation)

Code blocks in other languages, or with no declared language, are not validated.

Finding types

All docs-as-tests findings are written to the same place as other quality findings. They appear in the editor's Findings panel for the affected topic, on the Content health tab of Analytics, and in the Demand worklist. Every finding is a warning severity.

Finding type

Meaning

docs_test_link_broken

An external link returned an error or non-OK status

docs_test_api_changed

A documented API base URL failed to respond

docs_test_code_invalid

A code sample failed its language syntax check

Each finding includes the offending value (the URL, base URL, or a preview of the code) so you can locate and fix it without re-running the scan.

When it runs

The scan runs once a week, on Monday, in the background. Each run replaces the previous batch of docs-as-tests findings, so the panel always reflects the most recent scan rather than accumulating stale entries.

Findings that are fixed (a link that starts resolving again, a code sample that now parses) drop off automatically on the next weekly run.

See also

Was this page helpful?