---
title: "How to test readability in CI: Agent Ready HTML"
description: "Turn the checks into a build step that fails. 6 sourced facts, 5 steps and a check you can run in the viewer. Read 2026-11-04."
canonical: https://agentreadyhtml.com/guides/test-readability-in-ci/
site: "Agent Ready HTML"
last_updated: 2026-11-04
section: "Guides"
---

# How to test readability in CI: Agent Ready HTML

> Turn the checks into a build step that fails. 6 sourced facts, 5 steps and a check you can run in the viewer. Read 2026-11-04.

Source: https://agentreadyhtml.com/guides/test-readability-in-ci/
Site: Agent Ready HTML
Last reviewed: 2026-11-04

# How to test readability in CI

In short

Turn the four plain requests into a script that fails the build: the page returns 200 with an H1, a missing path returns 404, a markdown request returns text/markdown, and llms.txt parses. Docs sites can add AFDocs or the is-agentic command. This site runs its own checks on every build.

A readability regression is easy to ship: a client-side rewrite, a catch-all rewrite, a removed footer link. A build step catches it before an agent does.

## What the evidence says

-   AFDocs runs 28 checks in 7 categories and ships a vitest helper for CI. \[primary source\] [source](https://afdocs.dev/), read 4 November 2026.
-   is-agentic exposes reports through npx is-agentic <domain> and a GET API at /api/v1/report. \[primary source\] [source](https://vercel.com/kb/guide/make-your-site-readable-by-ai-agents), read 4 November 2026.
-   Lighthouse flags a server error on /llms.txt and marks a 404 as not applicable. \[primary source\] [source](https://developer.chrome.com/docs/lighthouse/agentic-browsing/llms-txt), read 4 November 2026.
-   ReadMe scores a sample of published pages against the Agent-Friendly Docs spec in its dashboard. \[primary source\] [source](https://docs.readme.com/main/docs/ai-discoverability), read 4 November 2026.
-   A curl with Accept: text/markdown should return Content-Type text/markdown; anything else means no negotiation. \[primary source\] [source](https://vercel.com/kb/guide/make-your-site-readable-by-ai-agents), read 4 November 2026.
-   Ora's Access layer runs 42 checks worth 30 points. \[vendor claim\] [source](https://ora.ai/methodology?utm_source=agentreadyhtml.com&utm_medium=referral&utm_campaign=guide), read 4 November 2026.

## Steps

1.  Run the build and serve the output locally, or point the script at a preview URL.
2.  Assert the status codes and content types with curl, as in the script below.
3.  Read the first line of llms.txt and fail if it is not an H1.
4.  For documentation, add a scanner that already encodes the checks: AFDocs ships a vitest helper, and is-agentic exposes npx is-agentic with a report API.
5.  Fail the pipeline on any assertion, and keep the assertions in the repository next to the content.

A shell test that exits non-zero on failure

set -eu
URL=${1:-https://example.com}
test "$(curl -s -o /dev/null -w '%{http\_code}' "$URL/agent-ready-html-missing-path-check")" = 404
curl -sL "$URL/" | grep -qi '<h1'
curl -sI -H 'Accept: text/markdown' "$URL/" | grep -qi '^content-type: text/markdown'
curl -s "$URL/llms.txt" | head -1 | grep -q '^# '
echo ok

## Check the result

This site runs fixture tests on the viewer flags and the llms.txt grader, then verify and gate scripts over the built pages, and fails the build if any fails. Open the [viewer](https://agentreadyhtml.com/viewer/) to run it on your own URL.

Related: [all guides](https://agentreadyhtml.com/guides/), [initial HTML](https://agentreadyhtml.com/initial-html/), [llms.txt](https://agentreadyhtml.com/llms-txt/), [checking the initial HTML like an agent](https://agentreadyhtml.com/guides/check-initial-html-like-an-agent/).

## Sources

1.  [AFDocs: Agent-Friendly Documentation spec](https://afdocs.dev/) https://afdocs.dev/, read 4 November 2026
2.  [Vercel and Ora: Make your site readable by AI agents](https://vercel.com/kb/guide/make-your-site-readable-by-ai-agents) https://vercel.com/kb/guide/make-your-site-readable-by-ai-agents, read 4 November 2026
3.  [Chrome Lighthouse: llms.txt audit](https://developer.chrome.com/docs/lighthouse/agentic-browsing/llms-txt) https://developer.chrome.com/docs/lighthouse/agentic-browsing/llms-txt, read 4 November 2026
4.  [ReadMe docs: AI Discoverability](https://docs.readme.com/main/docs/ai-discoverability) https://docs.readme.com/main/docs/ai-discoverability, read 4 November 2026
5.  [Ora methodology](https://ora.ai/methodology?utm_source=agentreadyhtml.com&utm_medium=referral&utm_campaign=guide) https://ora.ai/methodology, read 4 November 2026

Last reviewed 4 November 2026

Edition

Crawl

2026-11-04

Page updated

2026-11-04

Method

How the viewer reads a page, how a file is graded and how a platform is scored: [the method page](https://agentreadyhtml.com/method/).

**Check it**  
Run the [viewer](https://agentreadyhtml.com/viewer/) after each step.