also looking at this
Harden AnalyticsHQ release and dashboard quality
#52
34 files
+1236
-340
| @@ -0,0 +1,364 @@ | ||
| 1 | import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs' | |
| 2 | import { tmpdir } from 'node:os' | |
| 3 | import { join, resolve } from 'node:path' | |
| 4 | ||
| 5 | interface Viewport { | |
| 6 | name: string | |
| 7 | width: number | |
| 8 | height: number | |
| 9 | mobile: boolean | |
| 10 | } | |
| 11 | ||
| 12 | interface PageAudit { | |
| 13 | contrast: string[] | |
| 14 | focusable: number | |
| 15 | imagesWithoutAlt: number | |
| 16 | overflow: number | |
| 17 | undersizedDashboardControls: string[] | |
| 18 | wrappedDashboardValues: string[] | |
| 19 | unresolved: boolean | |
| 20 | unnamedControls: string[] | |
| 21 | } | |
| 22 | ||
| 23 | interface Pending { | |
| 24 | reject: (error: Error) => void | |
| 25 | resolve: (value: any) => void | |
| 26 | timer: ReturnType<typeof setTimeout> | |
| 27 | } | |
| 28 | ||
| 29 | const DIST = resolve('dist') | |
| 30 | const SSR_OUTPUT = resolve('.output') | |
| 31 | const SSR_PAGES = resolve(SSR_OUTPUT, 'server/pages') | |
| 32 | const SSR_PUBLIC = resolve(SSR_OUTPUT, 'public') | |
| 33 | const OUTPUT = resolve('storage/logs/visual-contract') | |
| 34 | const VIEWPORTS: Viewport[] = [ | |
| 35 | { name: 'desktop', width: 1440, height: 1000, mobile: false }, | |
| 36 | { name: 'tablet', width: 768, height: 1024, mobile: false }, | |
| 37 | { name: 'mobile', width: 390, height: 844, mobile: true }, | |
| 38 | ] | |
| 39 | const THEMES = ['light', 'dark'] as const | |
| 40 | const ROUTE_CANDIDATES = [ | |
| 41 | '/', | |
| 42 | '/login', | |
| 43 | '/register', | |
| 44 | '/dashboard', | |
| 45 | '/dashboard/commshq', | |
| 46 | '/reports', | |
| 47 | '/projects', | |
| 48 | ] | |
| 49 | ||
| 50 | function chromePath(): string { | |
| 51 | const candidates = [ | |
| 52 | process.env.CHROME_PATH, | |
| 53 | '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome', | |
| 54 | '/usr/bin/google-chrome', | |
| 55 | '/usr/bin/google-chrome-stable', | |
| 56 | '/usr/bin/chromium', | |
| 57 | '/usr/bin/chromium-browser', | |
| 58 | ] | |
| 59 | const found = candidates.find(candidate => candidate && existsSync(candidate)) | |
| 60 | if (!found) throw new Error('Chrome was not found. Set CHROME_PATH to a Chrome or Chromium executable.') | |
| 61 | return found | |
| 62 | } | |
| 63 | ||
| 64 | async function waitFor<T>(read: () => Promise<T> | T, timeout = 12_000): Promise<T> { | |
| 65 | const started = Date.now() | |
| 66 | let value = await read() | |
| 67 | while (!value && Date.now() - started < timeout) { | |
| 68 | await Bun.sleep(100) | |
| 69 | value = await read() | |
| 70 | } | |
| 71 | if (!value) throw new Error(`Timed out after ${timeout}ms`) | |
| 72 | return value | |
| 73 | } | |
| 74 | ||
| 75 | class Cdp { | |
| 76 | private id = 0 | |
| 77 | private pending = new Map<number, Pending>() | |
| 78 | ||
| 79 | constructor(private socket: WebSocket) { | |
| 80 | socket.addEventListener('message', (event) => { | |
| 81 | const message = JSON.parse(String(event.data)) | |
| 82 | if (!message.id) return | |
| 83 | const pending = this.pending.get(message.id) | |
| 84 | if (!pending) return | |
| 85 | this.pending.delete(message.id) | |
| 86 | clearTimeout(pending.timer) | |
| 87 | if (message.error) pending.reject(new Error(message.error.message)) | |
| 88 | else pending.resolve(message.result) | |
| 89 | }) | |
| 90 | } | |
| 91 | ||
| 92 | send(method: string, params: Record<string, any> = {}): Promise<any> { | |
| 93 | const id = ++this.id | |
| 94 | return new Promise((resolve, reject) => { | |
| 95 | const timer = setTimeout(() => { | |
| 96 | this.pending.delete(id) | |
| 97 | reject(new Error(`Chrome command timed out: ${method}`)) | |
| 98 | }, 15_000) | |
| 99 | this.pending.set(id, { reject, resolve, timer }) | |
| 100 | this.socket.send(JSON.stringify({ id, method, params })) | |
| 101 | }) | |
| 102 | } | |
| 103 | ||
| 104 | async evaluate<T>(expression: string): Promise<T> { | |
| 105 | const result = await this.send('Runtime.evaluate', { expression, awaitPromise: true, returnByValue: true }) | |
| 106 | if (result.exceptionDetails) | |
| 107 | throw new Error(result.exceptionDetails.exception?.description || result.exceptionDetails.text) | |
| 108 | return result.result?.value as T | |
| 109 | } | |
| 110 | } | |
| 111 | ||
| 112 | async function connect(url: string): Promise<Cdp> { | |
| 113 | const socket = new WebSocket(url) | |
| 114 | await new Promise<void>((resolve, reject) => { | |
| 115 | socket.addEventListener('open', () => resolve(), { once: true }) | |
| 116 | socket.addEventListener('error', () => reject(new Error('Could not connect to Chrome')), { once: true }) | |
| 117 | }) | |
| 118 | return new Cdp(socket) | |
| 119 | } | |
| 120 | ||
| 121 | function routeName(route: string): string { | |
| 122 | return route === '/' ? 'home' : route.slice(1).replaceAll('/', '-') | |
| 123 | } | |
| 124 | ||
| 125 | function routeFile(route: string): { kind: 'html' | 'ssr', path: string } | undefined { | |
| 126 | if (existsSync(DIST)) { | |
| 127 | const base = route === '/' ? join(DIST, 'index.html') : join(DIST, `${route.slice(1)}.html`) | |
| 128 | if (existsSync(base)) return { kind: 'html', path: base } | |
| 129 | const index = join(DIST, route.slice(1), 'index.html') | |
| 130 | if (existsSync(index)) return { kind: 'html', path: index } | |
| 131 | } | |
| 132 | ||
| 133 | const name = route === '/' ? 'index' : route.slice(1).replaceAll('/', '-') | |
| 134 | const compiled = join(SSR_PAGES, `${name}.compiled.json`) | |
| 135 | return existsSync(compiled) ? { kind: 'ssr', path: compiled } : undefined | |
| 136 | } | |
| 137 | ||
| 138 | function pageResponse(page: { kind: 'html' | 'ssr', path: string }): Response { | |
| 139 | if (page.kind === 'html') return new Response(Bun.file(page.path)) | |
| 140 | const compiled = JSON.parse(readFileSync(page.path, 'utf8')) as { html?: string } | |
| 141 | return new Response(compiled.html || '', { headers: { 'content-type': 'text/html; charset=utf-8' } }) | |
| 142 | } | |
| 143 | ||
| 144 | const auditExpression = `(() => { | |
| 145 | const visible = element => { | |
| 146 | const style = getComputedStyle(element) | |
| 147 | const rect = element.getBoundingClientRect() | |
| 148 | if (element.closest('details:not([open])') && element.tagName !== 'SUMMARY') return false | |
| 149 | return style.display !== 'none' && style.visibility !== 'hidden' && Number(style.opacity) > 0 | |
| 150 | && rect.width > 0 && rect.height > 0 | |
| 151 | } | |
| 152 | const label = element => { | |
| 153 | if (element.getAttribute('aria-label')) return element.getAttribute('aria-label') | |
| 154 | const labelledBy = element.getAttribute('aria-labelledby') | |
| 155 | if (labelledBy && labelledBy.split(/\\s+/).some(id => document.getElementById(id)?.textContent?.trim())) return labelledBy | |
| 156 | if (element.id && document.querySelector('label[for="' + CSS.escape(element.id) + '"]')?.textContent?.trim()) return element.id | |
| 157 | if (element.closest('label')?.textContent?.trim()) return 'wrapped' | |
| 158 | if (element.tagName === 'BUTTON' && element.textContent?.trim()) return 'text' | |
| 159 | if (element.tagName === 'A' && element.textContent?.trim()) return 'text' | |
| 160 | if (element.getAttribute('title')) return element.getAttribute('title') | |
| 161 | return '' | |
| 162 | } | |
| 163 | const parseRgb = value => { | |
| 164 | const match = value.match(/rgba?\\(([^)]+)\\)/) | |
| 165 | if (!match) return null | |
| 166 | const parts = match[1].split(/[ ,/]+/).filter(Boolean).map(Number) | |
| 167 | if (parts.length < 3 || parts.some(Number.isNaN)) return null | |
| 168 | return { r: parts[0], g: parts[1], b: parts[2], a: parts[3] ?? 1 } | |
| 169 | } | |
| 170 | const luminance = color => { | |
| 171 | const channel = value => { | |
| 172 | const normalized = value / 255 | |
| 173 | return normalized <= 0.03928 ? normalized / 12.92 : ((normalized + 0.055) / 1.055) ** 2.4 | |
| 174 | } | |
| 175 | return 0.2126 * channel(color.r) + 0.7152 * channel(color.g) + 0.0722 * channel(color.b) | |
| 176 | } | |
| 177 | const background = element => { | |
| 178 | let current = element | |
| 179 | while (current) { | |
| 180 | const color = parseRgb(getComputedStyle(current).backgroundColor) | |
| 181 | if (color && color.a >= 0.98) return color | |
| 182 | current = current.parentElement | |
| 183 | } | |
| 184 | return { r: 255, g: 255, b: 255, a: 1 } | |
| 185 | } | |
| 186 | const controls = [...document.querySelectorAll('a[href], button, input:not([type="hidden"]), select, textarea')].filter(visible) | |
| 187 | const dashboardControls = [...document.querySelectorAll('.site-switcher, .range-link, .range-tool, .chrome-btn, .ga-row, .goal-form input, .goal-form select, .goal-form button')].filter(visible) | |
| 188 | const undersizedDashboardControls = dashboardControls.flatMap(element => { | |
| 189 | const rect = element.getBoundingClientRect() | |
| 190 | if (rect.width >= 44 && rect.height >= 44) return [] | |
| 191 | const name = element.getAttribute('aria-label') || element.textContent?.trim().replace(/\\s+/g, ' ').slice(0, 32) || element.tagName.toLowerCase() | |
| 192 | return [name + ' (' + Math.round(rect.width) + 'x' + Math.round(rect.height) + ')'] | |
| 193 | }) | |
| 194 | const wrappedDashboardValues = [...document.querySelectorAll('.kpi-value')].filter(visible).flatMap(element => { | |
| 195 | const rect = element.getBoundingClientRect() | |
| 196 | const lineHeight = Number.parseFloat(getComputedStyle(element).lineHeight) | |
| 197 | return rect.height > lineHeight * 1.5 || element.scrollWidth > element.clientWidth + 1 | |
| 198 | ? [element.textContent?.trim() || 'metric value'] | |
| 199 | : [] | |
| 200 | }) | |
| 201 | const unnamedControls = controls.filter(element => !label(element)).map(element => { | |
| 202 | const identity = element.id ? '#' + element.id : element.getAttribute('name') ? '[name="' + element.getAttribute('name') + '"]' : '' | |
| 203 | return element.tagName.toLowerCase() + identity | |
| 204 | }) | |
| 205 | const contrast = [] | |
| 206 | const textElements = [...document.querySelectorAll('h1, h2, h3, h4, p, label, button, a, summary, span')] | |
| 207 | for (const element of textElements) { | |
| 208 | if (!visible(element) || !element.textContent?.trim()) continue | |
| 209 | if (element.children.length && !['A', 'BUTTON', 'SUMMARY'].includes(element.tagName)) continue | |
| 210 | const style = getComputedStyle(element) | |
| 211 | const foreground = parseRgb(style.color) | |
| 212 | const behind = background(element) | |
| 213 | if (!foreground || foreground.a < 0.98) continue | |
| 214 | const lighter = Math.max(luminance(foreground), luminance(behind)) | |
| 215 | const darker = Math.min(luminance(foreground), luminance(behind)) | |
| 216 | const ratio = (lighter + 0.05) / (darker + 0.05) | |
| 217 | const large = Number.parseFloat(style.fontSize) >= 24 || (Number.parseFloat(style.fontSize) >= 18.66 && Number(style.fontWeight) >= 700) | |
| 218 | if (ratio + 0.01 < (large ? 3 : 4.5)) { | |
| 219 | const sample = element.textContent.trim().replace(/\\s+/g, ' ').slice(0, 42) | |
| 220 | contrast.push(sample + ' (' + ratio.toFixed(2) + ':1)') | |
| 221 | } | |
| 222 | if (contrast.length >= 10) break | |
| 223 | } | |
| 224 | return { | |
| 225 | contrast, | |
| 226 | focusable: controls.length, | |
| 227 | imagesWithoutAlt: [...document.images].filter(image => !image.hasAttribute('alt')).length, | |
| 228 | overflow: Math.max(0, document.documentElement.scrollWidth - document.documentElement.clientWidth), | |
| 229 | undersizedDashboardControls, | |
| 230 | wrappedDashboardValues, | |
| 231 | unresolved: document.body.innerText.includes('{{') || document.body.innerText.includes('@if'), | |
| 232 | unnamedControls, | |
| 233 | } | |
| 234 | })()` | |
| 235 | ||
| 236 | const dashboardFixtureExpression = `(() => { | |
| 237 | const fixture = document.createElement('section') | |
| 238 | fixture.id = 'visual-dashboard-fixture' | |
| 239 | fixture.setAttribute('aria-hidden', 'true') | |
| 240 | fixture.style.cssText = 'position:absolute;left:1rem;top:0;width:calc(100vw - 2rem);opacity:0.001;pointer-events:none;z-index:-1' | |
| 241 | const columns = Array.from({ length: 90 }, (_, index) => '<div class="relative flex-1 ga-col"><div class="ga-tip">Day ' + index + '</div></div>').join('') | |
| 242 | fixture.innerHTML = '<select class="panel site-switcher" aria-label="Switch site"><option>example.com</option></select><a class="range-link" href="#">24h</a><button class="range-tool">Export</button><a class="chrome-btn" href="#">Account</a><a class="ga-row" href="#">Page row</a><form class="goal-form"><input aria-label="Goal name"></form><section class="grid grid-cols-2"><div class="px-5"><div class="kpi-label">Average visit time</div><div class="text-3xl kpi-value mono">27m 47s</div></div></section><div class="p-5 panel"><div class="relative h-44 w-full ga-chart"><div class="flex absolute inset-0">' + columns + '</div></div></div>' | |
| 243 | document.body.appendChild(fixture) | |
| 244 | })()` | |
| 245 | ||
| 246 | async function main(): Promise<void> { | |
| 247 | if (!existsSync(DIST) && !existsSync(SSR_PAGES)) | |
| 248 | throw new Error(`Built site not found at ${DIST} or ${SSR_OUTPUT}. Run bun run build first.`) | |
| 249 | const routes = ROUTE_CANDIDATES.filter(route => routeFile(route)) | |
| 250 | if (routes.length < 3) throw new Error(`Expected at least three visual routes, found ${routes.join(', ') || 'none'}.`) | |
| 251 | ||
| 252 | mkdirSync(OUTPUT, { recursive: true }) | |
| 253 | const server = Bun.serve({ | |
| 254 | hostname: '127.0.0.1', | |
| 255 | port: 0, | |
| 256 | fetch(request) { | |
| 257 | const url = new URL(request.url) | |
| 258 | const route = decodeURIComponent(url.pathname) | |
| 259 | const page = routeFile(route) | |
| 260 | if (page) return pageResponse(page) | |
| 261 | const publicRoot = existsSync(DIST) ? DIST : SSR_PUBLIC | |
| 262 | const asset = resolve(publicRoot, `.${route}`) | |
| 263 | const file = asset.startsWith(`${publicRoot}/`) && existsSync(asset) ? asset : undefined | |
| 264 | return file ? new Response(Bun.file(file)) : new Response('Not found', { status: 404 }) | |
| 265 | }, | |
| 266 | }) | |
| 267 | const profile = mkdtempSync(join(tmpdir(), 'hq-visual-')) | |
| 268 | const chrome = Bun.spawn([ | |
| 269 | chromePath(), | |
| 270 | '--headless=new', | |
| 271 | '--remote-debugging-port=0', | |
| 272 | `--user-data-dir=${profile}`, | |
| 273 | '--no-first-run', | |
| 274 | '--no-default-browser-check', | |
| 275 | '--disable-background-networking', | |
| 276 | '--disable-component-update', | |
| 277 | '--disable-extensions', | |
| 278 | '--hide-scrollbars', | |
| 279 | '--no-sandbox', | |
| 280 | 'about:blank', | |
| 281 | ], { stdout: 'ignore', stderr: 'ignore' }) | |
| 282 | ||
| 283 | const failures: string[] = [] | |
| 284 | let screenshots = 0 | |
| 285 | try { | |
| 286 | const portFile = join(profile, 'DevToolsActivePort') | |
| 287 | await waitFor(() => existsSync(portFile), 10_000) | |
| 288 | const port = Number(readFileSync(portFile, 'utf8').split('\n')[0]) | |
| 289 | const targets = await waitFor(async () => { | |
| 290 | const items = await fetch(`http://127.0.0.1:${port}/json/list`).then(response => response.json()).catch(() => []) | |
| 291 | return Array.isArray(items) && items.length ? items : null | |
| 292 | }) as Array<{ type: string, url: string, webSocketDebuggerUrl: string }> | |
| 293 | const target = targets.find(item => item.type === 'page' && item.url === 'about:blank') || targets.find(item => item.type === 'page') | |
| 294 | if (!target) throw new Error('Chrome did not expose a page target.') | |
| 295 | ||
| 296 | const cdp = await connect(target.webSocketDebuggerUrl) | |
| 297 | await cdp.send('Page.enable') | |
| 298 | await cdp.send('Runtime.enable') | |
| 299 | await cdp.send('Emulation.setScriptExecutionDisabled', { value: true }) | |
| 300 | ||
| 301 | for (const route of routes) { | |
| 302 | for (const viewport of VIEWPORTS) { | |
| 303 | await cdp.send('Emulation.setDeviceMetricsOverride', { | |
| 304 | width: viewport.width, | |
| 305 | height: viewport.height, | |
| 306 | deviceScaleFactor: 1, | |
| 307 | mobile: viewport.mobile, | |
| 308 | }) | |
| 309 | await cdp.send('Page.navigate', { url: `http://127.0.0.1:${server.port}${route}` }) | |
| 310 | await waitFor(() => cdp.evaluate("document.readyState === 'complete'")) | |
| 311 | await Bun.sleep(100) | |
| 312 | for (const theme of THEMES) { | |
| 313 | await cdp.evaluate(`(() => { | |
| 314 | const theme = ${JSON.stringify(theme)} | |
| 315 | document.documentElement.classList.toggle('dark', theme === 'dark') | |
| 316 | document.documentElement.setAttribute('data-theme', theme) | |
| 317 | document.documentElement.setAttribute('data-color-mode', theme) | |
| 318 | document.documentElement.setAttribute('color-mode', theme) | |
| 319 | })()`) | |
| 320 | await Bun.sleep(500) | |
| 321 | if (route === '/dashboard') await cdp.evaluate(dashboardFixtureExpression) | |
| 322 | const audit = await cdp.evaluate<PageAudit>(auditExpression) | |
| 323 | if (route === '/dashboard') await cdp.evaluate("document.getElementById('visual-dashboard-fixture')?.remove()") | |
| 324 | const key = `${route} at ${viewport.name}/${theme}` | |
| 325 | if (audit.overflow > 1) failures.push(`${key}: ${audit.overflow}px horizontal overflow`) | |
| 326 | if (viewport.mobile && audit.undersizedDashboardControls.length) | |
| 327 | failures.push(`${key}: undersized dashboard controls ${audit.undersizedDashboardControls.join(', ')}`) | |
| 328 | if (viewport.mobile && audit.wrappedDashboardValues.length) | |
| 329 | failures.push(`${key}: wrapped dashboard metric values ${audit.wrappedDashboardValues.join(', ')}`) | |
| 330 | if (audit.unresolved) failures.push(`${key}: unresolved template expression is visible`) | |
| 331 | if (audit.imagesWithoutAlt) failures.push(`${key}: ${audit.imagesWithoutAlt} image(s) have no alt attribute`) | |
| 332 | if (audit.unnamedControls.length) failures.push(`${key}: unnamed controls ${audit.unnamedControls.join(', ')}`) | |
| 333 | for (const issue of audit.contrast) failures.push(`${key}: low text contrast ${issue}`) | |
| 334 | ||
| 335 | if (audit.focusable) { | |
| 336 | await cdp.evaluate("document.body.setAttribute('tabindex', '-1'); document.body.focus()") | |
| 337 | await cdp.send('Input.dispatchKeyEvent', { type: 'keyDown', key: 'Tab', code: 'Tab', windowsVirtualKeyCode: 9 }) | |
| 338 | await cdp.send('Input.dispatchKeyEvent', { type: 'keyUp', key: 'Tab', code: 'Tab', windowsVirtualKeyCode: 9 }) | |
| 339 | const focused = await cdp.evaluate("document.activeElement && document.activeElement !== document.body && document.activeElement !== document.documentElement") | |
| 340 | if (!focused) failures.push(`${key}: Tab did not move focus to a control`) | |
| 341 | } | |
| 342 | ||
| 343 | const shot = await cdp.send('Page.captureScreenshot', { format: 'png', captureBeyondViewport: true, fromSurface: true }) | |
| 344 | writeFileSync(join(OUTPUT, `${routeName(route)}-${theme}-${viewport.name}.png`), Buffer.from(shot.data, 'base64')) | |
| 345 | screenshots += 1 | |
| 346 | } | |
| 347 | } | |
| 348 | } | |
| 349 | } | |
| 350 | finally { | |
| 351 | chrome.kill() | |
| 352 | await chrome.exited | |
| 353 | server.stop(true) | |
| 354 | rmSync(profile, { force: true, recursive: true }) | |
| 355 | } | |
| 356 | ||
| 357 | console.log(`Rendered ${routes.length} routes in ${THEMES.length} themes at ${VIEWPORTS.length} viewports and wrote ${screenshots} screenshots.`) | |
| 358 | if (failures.length) { | |
| 359 | for (const failure of failures) console.error(`- ${failure}`) | |
| 360 | process.exit(1) | |
| 361 | } | |
| 362 | } | |
| 363 | ||
| 364 | await main() | |