qa-detect-web-vitals
Measures all 6 Core Web Vitals (LCP, CLS, INP, TBT, TTFB, FCP) via PerformanceObserver injected through Playwright MCP. Compares to Google's official thresholds — same metrics Lighthouse measures, sam
SKILL.mdskills/qa-detect-web-vitals/SKILL.md
GitHubHow the orchestrator runs this (ONE call — no hand-driving)
🚨 This skill is an EXECUTABLE in-page probe, not a prose playbook. Do NOT drive it with separate browser_evaluate / browser_click / browser_wait_for MCP calls. Instead make ONE call:
result = browser_evaluate(<the async function in "## Interactive Probe" below>)
The function installs all 6 PerformanceObservers (with buffered: true to backfill entries already fired during load), waits ~3s in-page for metrics to stabilize, synthesizes a safe interaction (click a benign nav/tab/menu element) to record INP, reads every metric, applies Google's official thresholds, and returns findings[] — all inside the page, in one round-trip. It does its own waits via in-page setTimeout promises, so there is no AI reasoning between steps. It self-skips (returns [] only when the page lifecycle prevents measurement, emitting a single webVitalsNotMeasurable info note). The probe disconnects all observers and removes window.__argusVitals before returning, so the page is left clean for the next skill. Transcribe each returned finding verbatim into the cell JSONL; add only the envelope fields (runId, cellId, route, viewport, …).
Skip the cell entirely if it is the auth/login-flow cell (login navigation invalidates metrics) or the route returned 4xx/5xx — the orchestrator gates this, the probe assumes it is already on a normal page.
Interactive Probe (browser_evaluate, async)
async () => {
const sleep = ms => new Promise(r => setTimeout(r, ms));
const out = [];
const add = o => out.push(Object.assign({ skill: 'qa-detect-web-vitals' }, o));
// ── install observers (buffered backfills entries that already fired) ──
const V = { lcp: 0, cls: 0, inp: 0, fcp: 0, ttfb: 0, longTasks: [], observers: [] };
try {
const lcpObs = new PerformanceObserver(list => {
const es = list.getEntries();
if (es.length) { const l = es[es.length - 1]; V.lcp = Math.round(l.renderTime || l.loadTime || l.startTime); }
});
lcpObs.observe({ type: 'largest-contentful-paint', buffered: true });
V.observers.push(lcpObs);
} catch (_) {}
try {
const clsObs = new PerformanceObserver(list => {
for (const e of list.getEntries()) if (!e.hadRecentInput) V.cls += e.value;
});
clsObs.observe({ type: 'layout-shift', buffered: true });
V.observers.push(clsObs);
} catch (_) {}
try {
const ltObs = new PerformanceObserver(list => {
for (const e of list.getEntries()) V.longTasks.push({ start: Math.round(e.startTime), dur: Math.round(e.duration) });
});
ltObs.observe({ type: 'longtask', buffered: true });
V.observers.push(ltObs);
} catch (_) {}
try {
const evtObs = new PerformanceObserver(list => {
for (const e of list.getEntries()) if (e.interactionId) V.inp = Math.max(V.inp, Math.round(e.duration));
});
evtObs.observe({ type: 'event', buffered: true, durationThreshold: 16 });
V.observers.push(evtObs);
} catch (_) {}
try { for (const e of performance.getEntriesByType('paint')) if (e.name === 'first-contentful-paint') { V.fcp = Math.round(e.startTime); break; } } catch (_) {}
try { const nav = performance.getEntriesByType('navigation')[0]; if (nav) V.ttfb = Math.round(nav.responseStart - nav.requestStart); } catch (_) {}
const cleanup = () => { for (const o of V.observers) { try { o.disconnect(); } catch (_) {} } };
// page lifecycle too short to measure anything?
if (V.observers.length === 0) {
cleanup();
add({ issueType: 'webVitalsNotMeasurable', severity: 'info', description: 'Page lifecycle prevents Core Web Vitals measurement (no PerformanceObserver entry types supported).', evidence: {} });
return out;
}
// ── let metrics stabilize (catches late LCP candidates / layout shifts) ──
await sleep(3000);
// ── synthesize a SAFE interaction for INP (never submit/delete/logout/nav-away) ──
let interacted = false;
try {
const cands = [...document.querySelectorAll(
'button:not([type="submit"]):not([disabled]), [role="button"]:not([disabled]), [role="tab"]:not([aria-selected="true"])'
)].filter(el => {
const r = el.getBoundingClientRect();
if (r.width === 0 || r.height === 0) return false;
if (r.top < 0 || r.bottom > innerHeight) return false;
const txt = (el.innerText || '').toLowerCase();
if (/delete|remove|destroy|cancel|logout|sign\s*out|submit|save/i.test(txt)) return false;
return true;
});
const safe = cands.find(c => /menu|toggle|tab|expand|collapse|nav/i.test(c.className || '')) || cands[0];
if (safe) { safe.click(); interacted = true; await sleep(500); }
} catch (_) {}
// ── read final metrics ──
const m = {
lcp: V.lcp, cls: Math.round(V.cls * 1000) / 1000, inp: V.inp, fcp: V.fcp, ttfb: V.ttfb,
longTasks: V.longTasks, domNodeCount: document.querySelectorAll('*').length
};
cleanup();
// ── apply Google's thresholds ──
if (m.lcp > 4000) add({ issueType: 'poorLCP', severity: 'high', description: `LCP ${m.lcp}ms exceeds Google's "Poor" threshold (>4000ms). Largest element renders too slowly.`, evidence: { metricValue: m.lcp, threshold: 4000 } });
else if (m.lcp > 2500) add({ issueType: 'poorLCP', severity: 'medium', description: `LCP ${m.lcp}ms is in Google's "Needs Improvement" range (2500-4000ms).`, evidence: { metricValue: m.lcp, threshold: 2500 } });
if (m.cls > 0.25) add({ issueType: 'poorCLS', severity: 'high', description: `Cumulative layout shift ${m.cls.toFixed(3)} exceeds Google's "Poor" threshold (>0.25). Content shifts unexpectedly during load.`, evidence: { metricValue: m.cls, threshold: 0.25 } });
else if (m.cls > 0.1) add({ issueType: 'poorCLS', severity: 'medium', description: `Cumulative layout shift ${m.cls.toFixed(3)} is in Google's "Needs Improvement" range (0.1-0.25).`, evidence: { metricValue: m.cls, threshold: 0.1 } });
if (m.inp > 500) add({ issueType: 'poorINP', severity: 'high', description: `INP ${m.inp}ms exceeds Google's "Poor" threshold (>500ms). Interactions feel laggy.`, evidence: { metricValue: m.inp, threshold: 500 } });
else if (m.inp > 200) add({ issueType: 'poorINP', severity: 'medium', description: `INP ${m.inp}ms is in Google's "Needs Improvement" range (200-500ms).`, evidence: { metricValue: m.inp, threshold: 200 } });
else if (m.inp === 0 && !interacted) add({ issueType: 'webVitalsNotMeasurable', severity: 'info', description: 'INP not measured — no safe interactive element was available to click during this cell.', evidence: {} });
const tbt = m.longTasks.reduce((s, t) => s + Math.max(0, t.dur - 50), 0);
if (tbt > 600) add({ issueType: 'highTBT', severity: 'high', description: `Total Blocking Time ${tbt}ms exceeds 600ms — main thread is heavily blocked during load.`, evidence: { metricValue: tbt, threshold: 600 } });
else if (tbt > 200) add({ issueType: 'highTBT', severity: 'medium', description: `Total Blocking Time ${tbt}ms exceeds Lighthouse target (<200ms).`, evidence: { metricValue: tbt, threshold: 200 } });
if (m.ttfb > 1500) add({ issueType: 'slowTTFB', severity: 'high', description: `TTFB ${m.ttfb}ms exceeds Google's "Poor" threshold (>1500ms). Server response is slow.`, evidence: { metricValue: m.ttfb, threshold: 1500 } });
else if (m.ttfb > 600) add({ issueType: 'slowTTFB', severity: 'medium', description: `TTFB ${m.ttfb}ms is in Google's "Needs Improvement" range (600-1500ms).`, evidence: { metricValue: m.ttfb, threshold: 600 } });
if (m.fcp > 3000) add({ issueType: 'slowFCP', severity: 'high', description: `FCP ${m.fcp}ms exceeds Google's "Poor" threshold (>3000ms).`, evidence: { metricValue: m.fcp, threshold: 3000 } });
else if (m.fcp > 1800) add({ issueType: 'slowFCP', severity: 'medium', description: `FCP ${m.fcp}ms is in Google's "Needs Improvement" range (1800-3000ms).`, evidence: { metricValue: m.fcp, threshold: 1800 } });
if (m.longTasks.length > 5) add({ issueType: 'excessiveLongTasks', severity: 'medium', description: `${m.longTasks.length} long tasks (each >50ms) during page lifetime. Combined blocking time: ${tbt}ms.`, evidence: { count: m.longTasks.length, tbt } });
const maxTask = m.longTasks.reduce((mx, t) => Math.max(mx, t.dur), 0);
if (maxTask > 1000) add({ issueType: 'mainThreadBlocked', severity: 'high', description: `Single long task of ${maxTask}ms blocked the main thread. UI frozen for ${(maxTask / 1000).toFixed(1)}s.`, evidence: { maxTaskMs: maxTask } });
if (m.domNodeCount > 3000) add({ issueType: 'domNodeCountExcessive', severity: 'high', description: `${m.domNodeCount} DOM nodes exceeds Lighthouse fail threshold (3000). Page may be slow to render.`, evidence: { domNodeCount: m.domNodeCount, threshold: 3000 } });
else if (m.domNodeCount > 1500) add({ issueType: 'domNodeCountExcessive', severity: 'medium', description: `${m.domNodeCount} DOM nodes exceeds Lighthouse warn threshold (1500).`, evidence: { domNodeCount: m.domNodeCount, threshold: 1500 } });
return out;
}
Issues
| issueType | severity | description |
|---|---|---|
| poorLCP | high if >4.0s, medium if >2.5s | Largest Contentful Paint exceeds Google's threshold (Good <2.5s · NI 2.5-4.0s · Poor >4.0s) |
| poorCLS | high if >0.25, medium if >0.1 | Cumulative Layout Shift exceeds Google's threshold (Good <0.1 · NI 0.1-0.25 · Poor >0.25) |
| poorINP | high if >500ms, medium if >200ms | Interaction to Next Paint exceeds Google's threshold (Good <200ms · NI 200-500ms · Poor >500ms) |
| highTBT | high if >600ms, medium if >200ms | Total Blocking Time exceeds Lighthouse target (<200ms) |
| slowTTFB | high if >1500ms, medium if >600ms | Time to First Byte exceeds Google's threshold (Good <600ms · NI 600-1500ms · Poor >1500ms) |
| slowFCP | high if >3.0s, medium if >1.8s | First Contentful Paint exceeds Google's threshold (Good <1.8s · NI 1.8-3.0s · Poor >3.0s) |
| excessiveLongTasks | medium | More than 5 long tasks (each >50ms) during page lifetime |
| domNodeCountExcessive | medium if >1500, high if >3000 | DOM node count exceeds Lighthouse warn (1500) / fail (3000) thresholds |
| mainThreadBlocked | high | A single long task >1000ms blocks the main thread (frozen UI) |
| webVitalsNotMeasurable | info | Page lifecycle prevents measurement, or no safe element to click for INP — not a bug |
Configuration (customize.toml)
[web_vitals]
enabled = true
interaction_for_inp = true
wait_for_stabilization_ms = 3000
critical_routes = []
Threshold overrides remain available; the probe hard-codes Google's published values (LCP 4000/2500, CLS 0.25/0.1, INP 500/200, TBT 600/200, TTFB 1500/600, FCP 3000/1800, DOM 3000/1500, max-task 1000) — edit the constants in the probe to override.
Notes on this conversion
- This replaces the old 8-step multi-call flow (install → wait → find-target → click → read → threshold → cleanup) with ONE async
browser_evaluate. The 3s stabilization wait and 500ms post-interaction wait now run as in-pagesetTimeoutpromises, so there is no AI reasoning between steps and the skill cannot be partially skipped. - All 10 issueTypes preserved. TBT is still computed client-side from the long-tasks array, now inside the probe.
- INP still requires a real interaction; the probe synthesizes a SAFE click (never submit/delete/logout/save/nav-away) and falls back to the
webVitalsNotMeasurableinfo note when none exists. - Observers are disconnected and
window.__argusVitalsis never persisted (the probe uses a localVinstead of a window global), so cleanup is automatic even on early return.