Files
sim/apps/docs/scripts/test-negotiation-e2e.ts
Emir KarabegandWaleed Latif 7860fbe8cc feat(docs): rebuild documentation with the shared Sim design system (#9459)
* feat(docs): rebuild documentation with the Paper design system

* fix(docs): verify nested tabs and fresh-checkout CI setup

* chore(docs): refresh preservation evidence against latest staging

* fix(docs): align shared navigation and controls with Paper

* fix(docs): share active heading across responsive outlines

* fix(docs): track the final section at the end of the page

* fix(docs): preserve sidebar scroll in a persistent layout

* fix(docs): restore live screenshot backgrounds and framing

* fix(docs): finish layout polish and clean implementation references

* fix(docs): align shared dark theme and overlay states

* fix(docs): remove dark borders from platform screenshots

* test(docs): benchmark production navigation and image delivery in CI

* fix(docs): preserve machine content and production reading contracts

* fix(docs): retain readable tabs without JavaScript and verify current staging

* fix(docs): expose root response schemas and generate clean-checkout types

* fix(docs): resolve no-script tabs in the preflight cascade layer

* perf(docs): import only the search schema constructors

* fix(docs): preserve retrieval excerpts and reduce reading overhead

* fix(docs): reuse in-flight intent prefetches during navigation

* docs: record production readiness evidence and release requirements

* docs: clarify optimizer measurement provenance

* docs: preserve latest staging Search assets and compatibility evidence

* fix(docs): polish responsive controls and keep search indexing current

* test(docs): select the visible API example in browser checks

* test(docs): execute native examples against streaming and binary responses

* fix(docs): stream native API responses without buffering

* test(docs): cover review regressions through public interfaces

* fix(docs): preserve accessible examples and gate index publication

* fix(docs): finish accessible controls and cached content validation

* fix(docs): validate integration parents and report partial search failures

* fix(docs): refine navigation and compact sample controls

* fix(docs): isolate synchronous corpus validation from HTTP readers

* fix(docs): restore Paper interaction styling and verify responsive controls

* fix(docs): score each search page once per retrieval source

* fix(docs): attribute benchmark metrics to their source document

---------

Co-authored-by: Waleed Latif <walif6@gmail.com>
2026-10-30 17:06:09 -07:00

173 lines
5.3 KiB
TypeScript

import { mkdir, writeFile } from 'node:fs/promises'
import { dirname } from 'node:path'
import { createLogger } from '@sim/logger'
import { getErrorMessage } from '@sim/utils/errors'
import { sleep } from '@sim/utils/helpers'
const logger = createLogger('DocsNegotiationE2E')
const origin = process.env.DOCS_E2E_BASE_URL
const reportPath = process.env.DOCS_NEGOTIATION_REPORT_PATH
if (!origin || !reportPath) {
throw new Error('DOCS_E2E_BASE_URL and DOCS_NEGOTIATION_REPORT_PATH are required')
}
const url = new URL('/introduction', origin)
if (!['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)) {
throw new Error('The documentation server must use a loopback origin')
}
interface CheckResult {
name: string
status: 'passed' | 'failed'
durationMs: number
contentType?: string
vary?: string
statusCode?: number
error?: string
}
interface RepresentationCase {
name: string
accept: string
expected: 'text/html' | 'text/markdown'
method?: 'GET' | 'HEAD'
statusCode?: number
useHtmlValidator?: boolean
}
const cases: readonly RepresentationCase[] = [
{
name: 'HTML advertises its representation and router cache dimensions',
accept: 'text/html',
expected: 'text/html',
},
{
name: 'Markdown negotiates at the same URL',
accept: 'text/markdown',
expected: 'text/markdown',
},
{
name: 'HTML remains available after a Markdown request',
accept: 'text/html',
expected: 'text/html',
},
{
name: 'Higher Markdown quality wins',
accept: 'text/html;q=0.4,text/markdown;q=0.8',
expected: 'text/markdown',
},
{
name: 'Equal quality defaults to HTML',
accept: 'text/markdown;q=0.8,text/html;q=0.8',
expected: 'text/html',
},
{
name: 'Explicit Markdown rejection overrides wildcard',
accept: 'text/markdown;q=0,*/*;q=1',
expected: 'text/html',
},
{
name: 'Explicit HTML rejection permits Markdown wildcard',
accept: 'text/html;q=0,text/*;q=0.5',
expected: 'text/markdown',
},
{
name: 'HTML HEAD retains representation headers',
accept: 'text/html',
expected: 'text/html',
method: 'HEAD',
},
{
name: 'Markdown HEAD retains representation headers',
accept: 'text/markdown',
expected: 'text/markdown',
method: 'HEAD',
},
{
name: 'Matching HTML validator returns a 304 with cache dimensions',
accept: 'text/html',
expected: 'text/html',
statusCode: 304,
useHtmlValidator: true,
},
{
name: 'Conditional HTML HEAD returns a 304',
accept: 'text/html',
expected: 'text/html',
method: 'HEAD',
statusCode: 304,
useHtmlValidator: true,
},
{
name: 'An HTML validator cannot suppress the Markdown representation',
accept: 'text/markdown',
expected: 'text/markdown',
useHtmlValidator: true,
},
] as const
for (let attempt = 0; attempt < 20; attempt += 1) {
try {
const response = await fetch(url, { signal: AbortSignal.timeout(1000) })
await response.body?.cancel()
if (response.ok) break
} catch {}
await sleep(250)
}
const checks: CheckResult[] = []
let htmlValidator: string | undefined
for (const entry of cases) {
const started = performance.now()
const result: CheckResult = { name: entry.name, status: 'failed', durationMs: 0 }
try {
const headers = new Headers({ Accept: entry.accept })
if (entry.useHtmlValidator) {
if (!htmlValidator) throw new Error('HTML did not provide a cache validator')
headers.set('If-None-Match', htmlValidator)
}
const response = await fetch(url, {
method: entry.method ?? 'GET',
headers,
signal: AbortSignal.timeout(10000),
})
await response.body?.cancel()
result.statusCode = response.status
result.contentType = response.headers.get('Content-Type') ?? ''
result.vary = response.headers.get('Vary') ?? ''
const fields = result.vary.split(',').map((field) => field.trim().toLowerCase())
if (response.status !== (entry.statusCode ?? 200))
throw new Error(`Unexpected HTTP status ${response.status}`)
if (response.status !== 304 && !result.contentType.startsWith(entry.expected)) {
throw new Error(`Expected ${entry.expected}; received ${result.contentType}`)
}
if (!fields.includes('accept')) throw new Error('The response lost Vary: Accept')
if (entry.expected === 'text/html') {
if (response.status === 200) htmlValidator = response.headers.get('etag') ?? undefined
for (const field of [
'rsc',
'next-router-state-tree',
'next-router-prefetch',
'next-router-segment-prefetch',
]) {
if (!fields.includes(field)) throw new Error(`The response lost Vary: ${field}`)
}
}
if (fields.length !== new Set(fields).size) throw new Error('Vary contains duplicate fields')
result.status = 'passed'
} catch (error) {
result.error = getErrorMessage(error)
}
result.durationMs = Math.round(performance.now() - started)
checks.push(result)
}
await mkdir(dirname(reportPath), { recursive: true })
await writeFile(reportPath, `${JSON.stringify({ checks }, null, 2)}\n`)
const failures = checks.filter((check) => check.status === 'failed')
if (failures.length) {
logger.error('Documentation negotiation failed', { failures })
process.exitCode = 1
} else {
logger.info('Documentation negotiation passed', { checks: checks.length })
}