url: string

type: string

method: string

prefetch: boolean

status?: number

headers?: Record<string, string>

sizes?: Awaited<ReturnType<Request['sizes']>>

timing?: ReturnType<Request['timing']>

failure?: string

longTasks: Array<{ startTime: number; duration: number }>

shifts: Array<{ startTime: number; value: number; hadRecentInput: boolean }>

events: Array<{ name: string; startTime: number; duration: number }>

lcp: Array<{ startTime: number; size?: number; url?: string; element?: string }>

shell?: Element | null

profile: string

route: string

repetition: number

scenario: string

status: 'completed' | 'failed' | 'unavailable' | 'unverified'

durationMs: number

meaningfulPaintMs?: number

feedbackMs?: number

mediaReadyMs?: number

data?: unknown

error?: string

if (!values.length) return { count: 0, median: null, min: null, max: null, raw: values }

const sorted = [...values].sort((left, right) => left - right)

const middle = Math.floor(sorted.length / 2)

return {

count: sorted.length,

median:

sorted.length % 2 ? sorted[middle] : ((sorted[middle - 1] ?? 0) + (sorted[middle] ?? 0)) / 2,

min: sorted[0],

max: sorted.at(-1),

raw: values,

}

const groups = new Map<string, Measurement[]>()

for (const result of results) {

const key = `${result.profile}:${result.scenario}:${result.route}`

groups.set(key, [...(groups.get(key) ?? []), result])

}

const summary = [...groups].map(([key, samples]) => ({

key,

completed: samples.filter((sample) => sample.status === 'completed').length,

meaningfulPaintMs: stats(

samples.flatMap((sample) =>

sample.meaningfulPaintMs === undefined ? [] : [sample.meaningfulPaintMs]

)

),

feedbackMs: stats(

samples.flatMap((sample) => (sample.feedbackMs === undefined ? [] : [sample.feedbackMs]))

),

mediaReadyMs: stats(

samples.flatMap((sample) => (sample.mediaReadyMs === undefined ? [] : [sample.mediaReadyMs]))

),

}))

await writeFile(

reportPath,

`${JSON.stringify(

)

profile: Profile,

route: string,

repetition: number,

scenario: string,

action: () => Promise<

Omit<Measurement, 'profile' | 'route' | 'repetition' | 'scenario' | 'durationMs'>

>

) {

if (originBlocked) {

results.push({

profile: profile.name,

route,

repetition,

scenario,

status: 'unverified',

durationMs: 0,

error: 'Origin returned HTTP 403; no further requests were attempted.',

data: originBlocked,

})

await save()

return

}

const start = performance.now()

logger.info('Measuring', { profile: profile.name, route, repetition, scenario })

try {

const observation = await action()

results.push({

profile: profile.name,

route,

repetition,

scenario,

durationMs: performance.now() - start,

...observation,

})

} catch (error) {

results.push({

profile: profile.name,

route,

repetition,

scenario,

status: 'failed',

durationMs: performance.now() - start,

error: getErrorMessage(error),

})

logger.error('Measurement failed', { route, scenario, error: getErrorMessage(error) })

}

await save()

await context.addInitScript(() => {

const state: BrowserObservations = { longTasks: [], shifts: [], events: [], lcp: [] }

;(window as BrowserWindow).docsBenchmark = state

performance.setResourceTimingBufferSize(5000)

for (const type of ['longtask', 'layout-shift', 'event', 'largest-contentful-paint']) {

if (!PerformanceObserver.supportedEntryTypes.includes(type)) continue

new PerformanceObserver((list) => {

for (const entry of list.getEntries()) {

if (type === 'longtask' && state.longTasks.length < 2000)

state.longTasks.push({ startTime: entry.startTime, duration: entry.duration })

else if (type === 'layout-shift' && state.shifts.length < 2000) {

const shift = entry as PerformanceEntry & { value: number; hadRecentInput: boolean }

state.shifts.push({

startTime: entry.startTime,

value: shift.value,

hadRecentInput: shift.hadRecentInput,

})

} else if (type === 'event' && state.events.length < 2000)

state.events.push({

name: entry.name,

startTime: entry.startTime,

duration: entry.duration,

})

else if (type === 'largest-contentful-paint') {

const paint = entry as PerformanceEntry & {

size?: number

url?: string

element?: Element

}

state.lcp.push({

startTime: entry.startTime,

size: paint.size,

url: paint.url,

element: paint.element?.tagName,

})

}

}

}).observe({ type, buffered: true, ...(type === 'event' ? { durationThreshold: 16 } : {}) })

}

})

const context = await browser.newContext({

viewport: { width: profile.width, height: profile.height },

deviceScaleFactor: profile.dpr,

isMobile: profile.mobile,

hasTouch: profile.mobile,

colorScheme: 'light',

reducedMotion: 'reduce',

serviceWorkers: 'block',

})

if (disablePrefetch)

await context.route('**/*', async (route) => {

const headers = route.request().headers()

if (

headers['next-router-prefetch'] ||

headers['next-router-segment-prefetch'] ||

headers.purpose === 'prefetch'

)

await route.abort()

else await route.continue()

})

await instrument(context)

const page = await context.newPage()

page.setDefaultTimeout(30_000)

page.setDefaultNavigationTimeout(60_000)

const cdp = await context.newCDPSession(page)

await cdp.send('Performance.enable')

if (profile.mobile) {

await cdp.send('Network.enable')

await cdp.send('Network.emulateNetworkConditions', {

offline: false,

latency: 150,

downloadThroughput: 1_600_000 / 8,

uploadThroughput: 750_000 / 8,

})

await cdp.send('Emulation.setCPUThrottlingRate', { rate: profile.cpu })

}

const network: NetworkRecord[] = []

const requests = new Map<Request, NetworkRecord>()

const pending: Promise<void>[] = []

page.on('request', (request) => {

if (network.length >= 5000) return

const headers = request.headers()

const record = {

url: request.url(),

type: request.resourceType(),

method: request.method(),

prefetch: Boolean(

headers['next-router-prefetch'] ||

headers['next-router-segment-prefetch'] ||

headers.purpose === 'prefetch'

),

}

requests.set(request, record)

network.push(record)

})

page.on('response', (response) => {

const request = response.request()

if (

response.status() === 403 &&

new URL(response.url()).origin === base.origin &&

request.isNavigationRequest() &&

request.frame() === page.mainFrame()

) {

originBlocked = { url: response.url(), status: 403, observedAt: new Date().toISOString() }

void context.close().catch(() => {})

}

const record = requests.get(request)

if (!record) return

record.status = response.status()

const headers = response.headers()

record.headers = Object.fromEntries(

[

'content-type',

'content-encoding',

'content-length',

'cache-control',

'etag',

'last-modified',

'age',

'vary',

'x-vercel-cache',

'cf-cache-status',

].flatMap((key) => (headers[key] ? [[key, headers[key]]] : []))

)

})

page.on('requestfinished', (request) => {

const record = requests.get(request)

if (record)

pending.push(

request

.sizes()

.then((sizes) => {

record.sizes = sizes

record.timing = request.timing()

})

.catch(() => {})

)

})

page.on('requestfailed', (request) => {

const record = requests.get(request)

if (record) record.failure = request.failure()?.errorText

})

return { context, page, network, pending, cdp }

await page.evaluate(

() =>

new Promise<void>((resolve) =>

requestAnimationFrame(() => requestAnimationFrame(() => resolve()))

)

)

await page.waitForFunction(

({ expectedPath, expectedTitle, previous }) => {

const heading = document.querySelector('main h1') ?? document.querySelector('h1')

const article =

document.querySelector('main article') ??

document.querySelector('article') ??

document.querySelector('main')

return (

location.pathname.replace(/\/$/, '') === expectedPath.replace(/\/$/, '') &&

heading instanceof HTMLElement &&

heading.getClientRects().length > 0 &&

(!expectedTitle || heading.textContent?.trim() === expectedTitle) &&

(!previous || Boolean(expectedTitle) || heading.textContent?.trim() !== previous) &&

article instanceof HTMLElement &&

article.getClientRects().length > 0 &&

(article.textContent?.trim().length ?? 0) > 80

)

},

{ expectedPath: path, expectedTitle: title, previous: previousTitle }

)

await painted(page)

return page.evaluate(async () => {

const images = [...document.querySelectorAll<HTMLImageElement>('main img, article img')].filter(

(image) => {

const bounds = image.getBoundingClientRect()

return (

bounds.width > 0 && bounds.height > 0 && bounds.top < innerHeight && bounds.bottom > 0

)

}

)

await Promise.race([

Promise.all(images.map((image) => image.decode().catch(() => {}))),

new Promise<void>((_, reject) =>

setTimeout(

() => reject(new Error('Visible media did not decode within 20 seconds')),

20_000

)

),

])

await new Promise<void>((resolve) => requestAnimationFrame(() => resolve()))

return images.map((image) => ({

src: image.currentSrc,

loaded: image.complete && image.naturalWidth > 0,

}))

})

return page.evaluate((start) => {

const state = (window as BrowserWindow).docsBenchmark

const resources = performance

.getEntriesByType('resource')

.filter((entry) => entry.startTime >= start)

.map((entry) => entry.toJSON())

return {

url: location.href,

title: document.querySelector('h1')?.textContent?.trim(),

now: performance.now(),

timeOrigin: performance.timeOrigin,

domElements: document.getElementsByTagName('*').length,

horizontalOverflow: document.documentElement.scrollWidth - innerWidth,

shellPreserved: state?.shell

? state.shell === document.querySelector('body header')

: undefined,

activeElement:

document.activeElement?.getAttribute('aria-label') ?? document.activeElement?.tagName,

navigation: performance.getEntriesByType('navigation').map((entry) => entry.toJSON()),

resources,

longTasks: state?.longTasks.filter((entry) => entry.startTime >= start),

eventTimings: state?.events.filter((entry) => entry.startTime >= start),

layoutShifts: state?.shifts.filter((entry) => entry.startTime >= start),

documentLcp: {

url: performance.getEntriesByType('navigation')[0]?.name,

entries: state?.lcp,

},

images: [...document.images].slice(0, 100).map((image) => {

const bounds = image.getBoundingClientRect()

return {

src: image.src,

currentSrc: image.currentSrc,

srcset: image.srcset,

sizes: image.sizes,

alt: image.alt,

naturalWidth: image.naturalWidth,

naturalHeight: image.naturalHeight,

width: bounds.width,

height: bounds.height,

dpr: devicePixelRatio,

loading: image.loading,

fetchPriority: image.fetchPriority,

complete: image.complete,

objectFit: getComputedStyle(image).objectFit,

objectPosition: getComputedStyle(image).objectPosition,

}

}),

}

}, since)

await page.waitForLoadState('load')

const exact = page.locator(`a[href="${route}"]`)

const visited = new Set<string>()

const folders = route.split('/').filter(Boolean).slice(0, -1)

for (let attempt = 0; attempt < 14; attempt++) {

const visible = exact.filter({ visible: true }).first()

if (await visible.count()) return visible

const menu = page

.getByRole('button', { name: /^(Menu|Open menu|Open navigation|Open sidebar)$/i })

.filter({ visible: true })

.first()

if (!visited.has('menu') && (await menu.count())) {

visited.add('menu')

await menu.click()

await painted(page)

continue

}

if (await exact.count()) {

const dialogTarget = page

.getByRole('dialog')

.filter({ visible: true })

.locator(`a[href="${route}"]`)

.first()

const hiddenTarget = (await dialogTarget.count()) ? dialogTarget : exact.first()

const controls = await hiddenTarget.evaluate((element) => {

const labels: string[] = []

let parent = element.parentElement

while (parent) {

if (parent.matches('aside, [role=dialog]')) break

if (getComputedStyle(parent).display === 'none' || parent.hidden) {

const trigger = parent.id

? document.querySelector<HTMLButtonElement>(

`button[aria-controls="${CSS.escape(parent.id)}"]`

)

: null

const candidate =

trigger ??

parent.parentElement?.querySelector<HTMLButtonElement>(

'button[aria-expanded="false"]'

)

const label = candidate?.getAttribute('aria-label') ?? candidate?.textContent?.trim()

if (label) labels.unshift(label)

}

parent = parent.parentElement

}

return labels

})

let opened = false

for (const control of controls) {

const button = page

.getByRole('button', { name: control, exact: true })

.filter({ visible: true })

.first()

if (await button.count()) {

await button.click()

await painted(page)

opened = true

break

}

}

if (opened) continue

}

let opened = false

for (const folder of folders) {

const label =

folder === 'api-reference' ? 'API(?: reference)?' : folder.replaceAll('-', '[ -]')

const branch = page

.getByRole('button', { name: new RegExp(`^(?:Expand )?${label}$`, 'i') })

.filter({ visible: true })

.first()

if ((await branch.count()) && (await branch.getAttribute('aria-expanded')) === 'false') {

await branch.click()

await painted(page)

opened = true

break

}

const path = `/${folders.slice(0, folders.indexOf(folder) + 1).join('/')}`

const ancestor = page.locator(`a[href="${path}"]`).filter({ visible: true }).first()

if (!visited.has(path) && (await ancestor.count())) {

visited.add(path)

await ancestor.click()

await meaningful(page, path)

opened = true

break

}

}

if (opened) continue

const section = route.startsWith('/api-reference/')

? /^API(?: reference)?$/i

: route.startsWith('/mcp/')

? /^MCP$/i

: route.startsWith('/cli')

? /^CLI$/i

: /^Documentation$/i

const sectionLink = page.getByRole('link', { name: section }).filter({ visible: true }).first()

const closeNavigation = page

.getByRole('button', { name: /^(Close navigation|Close sidebar)$/i })

.filter({ visible: true })

.first()

if (!(await sectionLink.count()) && (await closeNavigation.count())) {

await closeNavigation.click()

await painted(page)

continue

}

const sectionHref = (await sectionLink.count()) ? await sectionLink.getAttribute('href') : null

if (sectionHref && !visited.has(`section:${sectionHref}`)) {

visited.add(`section:${sectionHref}`)

const previousTitle = (await page.locator('h1').first().textContent())?.trim()

await sectionLink.click()

await meaningful(page, new URL(sectionHref, base).pathname, undefined, previousTitle)

visited.delete('menu')

continue

}

return null

}

return null

return page

.getByRole('combobox', { name: /Search/i })

.or(page.getByRole('searchbox', { name: /Search/i }))

.or(page.getByPlaceholder(/Search/))

.filter({ visible: true })

.first()

await page.waitForLoadState('load')

const input = searchInput(page)

if (!(await input.isVisible())) {

await page

.getByRole('button', {

name: /^(Search docs|Search documentation|Open Search|Search(?:\.\.\.)?(?:.*))$/i,

})

.filter({ visible: true })

.first()

.click()

}

await input.waitFor()

await expect(input).toBeFocused()

await page.keyboard.press('Escape')

await input.waitFor({ state: 'hidden' })

browser: Browser,

profile: Profile,

route: string,

repetition: number

) {

const run = await contextFor(browser, profile)

try {

for (const scenario of ['cold', 'warm']) {

if (!scenarios.has(scenario)) continue

await measure(profile, route, repetition, scenario, async () => {

const networkStart = run.network.length

const response =

scenario === 'cold' || run.page.url() === 'about:blank'

? await run.page.goto(new URL(route, base).href, { waitUntil: 'commit' })

: await run.page.reload({ waitUntil: 'commit' })

if (!response?.ok()) throw new Error(`Document returned ${response?.status()}`)

await meaningful(run.page, new URL(route, base).pathname)

const meaningfulPaintMs = await run.page.evaluate(() => performance.now())

const media = await visibleMedia(run.page)

const mediaReadyMs = await run.page.evaluate(() => performance.now())