Skip to content

Chrome DevTools for coding agents

feat: return failing audits and DOM nodes inline from lighthouse_audit (#2930)

Mathias Bynens241fba58c2af
diff --git a/docs/tool-reference.md b/docs/tool-reference.md
index a64e95f9..ec83ce30 100644
--- a/docs/tool-reference.md
+++ b/docs/tool-reference.md
@@ -426,7 +426,7 @@ Results are paginated (10 rules per page by default); use pageIdx to page throug
### `lighthouse_audit`
-**Description:** Get Lighthouse score and reports for accessibility, SEO, best practices, and agentic browsing. This excludes performance. For performance audits, run [`performance_start_trace`](#performance_start_trace)
+**Description:** Get Lighthouse scores, failing audits, and the DOM nodes they flag for accessibility, SEO, best practices, and agentic browsing. Full reports are saved to disk. This excludes performance. For performance audits, run [`performance_start_trace`](#performance_start_trace)
**Parameters:**
diff --git a/src/McpResponse.ts b/src/McpResponse.ts
index 69300164..66048814 100644
--- a/src/McpResponse.ts
+++ b/src/McpResponse.ts
@@ -1196,12 +1196,12 @@ Call ${handleDialog(this.#args).name} to handle it before continuing.`);
if (data.lighthouseResult) {
structuredContent.lighthouseResult = data.lighthouseResult;
- const {summary, reports} = data.lighthouseResult;
- response.push('## Lighthouse Audit Results');
+ const {summary, failedAudits, reports} = data.lighthouseResult;
+ response.push('## Lighthouse audit results');
response.push(`Mode: ${summary.mode}`);
response.push(`Device: ${summary.device}`);
response.push(`URL: ${summary.url}`);
- response.push('### Category Scores');
+ response.push('### Category scores');
for (const score of summary.scores) {
// Lighthouse uses a null score for categories that could not be
// scored and renders scores as Math.round(score * 100).
@@ -1209,10 +1209,56 @@ Call ${handleDialog(this.#args).name} to handle it before continuing.`);
score.score === null ? 'n/a' : Math.round(score.score * 100);
response.push(`- ${score.title}: ${formattedScore} (${score.id})`);
}
- response.push('### Audit Summary');
+ response.push('### Audit summary');
response.push(`Passed: ${summary.audits.passed}`);
response.push(`Failed: ${summary.audits.failed}`);
- response.push(`Total Timing: ${summary.timing.total}ms`);
+ response.push(`Total timing: ${summary.timing.total}ms`);
+ if (failedAudits.length) {
+ response.push('### Failed audits');
+ for (const audit of failedAudits) {
+ const categories = audit.categories.length
+ ? ` [${audit.categories.join(', ')}]`
+ : '';
+ const displayValue = audit.displayValue
+ ? ` (${audit.displayValue})`
+ : '';
+ response.push(
+ `- ${audit.id}${categories}: ${audit.title}${displayValue} (score: ${audit.score})`,
+ );
+ if (audit.description) {
+ response.push(` ${collapseWhitespace(audit.description)}`);
+ }
+ if (audit.totalNodes) {
+ const shown =
+ audit.totalNodes > audit.nodes.length
+ ? `, showing ${audit.nodes.length}`
+ : '';
+ response.push(` Nodes (${audit.totalNodes}${shown}):`);
+ }
+ for (const node of audit.nodes) {
+ // Values are JSON-encoded so that quotes or spaces within them
+ // cannot be confused with the `key=value` delimiters.
+ const parts: string[] = [];
+ if (node.selector) {
+ parts.push(`selector=${JSON.stringify(node.selector)}`);
+ }
+ if (node.nodeLabel) {
+ parts.push(
+ `label=${JSON.stringify(collapseWhitespace(node.nodeLabel))}`,
+ );
+ }
+ if (node.snippet) {
+ parts.push(
+ `snippet=${JSON.stringify(collapseWhitespace(node.snippet))}`,
+ );
+ }
+ response.push(` - ${parts.join(' ')}`);
+ if (node.explanation) {
+ response.push(` ${collapseWhitespace(node.explanation)}`);
+ }
+ }
+ }
+ }
response.push('### Reports');
for (const report of reports) {
response.push(`- ${report}`);
@@ -1739,6 +1785,10 @@ function truncateTitle(title: string, maxLength = 50): string {
return title.slice(0, maxLength - 3) + '...';
}
+const collapseWhitespace = (value: string): string => {
+ return value.replace(/\s+/g, ' ').trim();
+};
+
function createStructuredPage(
mcpPage: McpPage,
context: McpContext,
diff --git a/src/config/cli-options.ts b/src/config/cli-options.ts
index 0325d3b3..d9c393b2 100644
--- a/src/config/cli-options.ts
+++ b/src/config/cli-options.ts
@@ -1046,7 +1046,7 @@ export const commands: Commands = {
},
lighthouse_audit: {
description:
- 'Get Lighthouse score and reports for accessibility, SEO, best practices, and agentic browsing. This excludes performance. For performance audits, run performance_start_trace',
+ 'Get Lighthouse scores, failing audits, and the DOM nodes they flag for accessibility, SEO, best practices, and agentic browsing. Full reports are saved to disk. This excludes performance. For performance audits, run performance_start_trace',
category: 'Debugging',
args: {
pageId: {
diff --git a/src/tools/ToolDefinition.ts b/src/tools/ToolDefinition.ts
index 1003dc8d..684280db 100644
--- a/src/tools/ToolDefinition.ts
+++ b/src/tools/ToolDefinition.ts
@@ -134,6 +134,34 @@ export interface SnapshotParams {
filePath?: string;
}
+export interface LighthouseAuditNode {
+ selector?: string;
+ snippet?: string;
+ nodeLabel?: string;
+ explanation?: string;
+}
+
+export interface LighthouseFailedAudit {
+ id: string;
+ title: string;
+ description?: string;
+ score: number;
+ displayValue?: string;
+ /**
+ * IDs of the categories that reference this audit.
+ */
+ categories: string[];
+ /**
+ * DOM nodes flagged by the audit, capped to a small number.
+ */
+ nodes: LighthouseAuditNode[];
+ /**
+ * Total number of distinct DOM nodes flagged by the audit, which may exceed
+ * the number of entries in `nodes`.
+ */
+ totalNodes: number;
+}
+
export interface LighthouseData {
summary: {
mode: string;
@@ -152,6 +180,7 @@ export interface LighthouseData {
total: number;
};
};
+ failedAudits: LighthouseFailedAudit[];
reports: string[];
}
diff --git a/src/tools/lighthouse.ts b/src/tools/lighthouse.ts
index 2e0db9f7..bb80f15f 100644
--- a/src/tools/lighthouse.ts
+++ b/src/tools/lighthouse.ts
@@ -13,13 +13,18 @@ import {
generateReport,
zod,
type Flags,
+ type Result,
type RunnerResult,
type OutputMode,
} from '../third_party/index.js';
import {ToolCategory} from './categories.js';
import {startTrace} from './performance.js';
-import {definePageTool} from './ToolDefinition.js';
+import {
+ definePageTool,
+ type LighthouseAuditNode,
+ type LighthouseFailedAudit,
+} from './ToolDefinition.js';
// Kept in sync with `constants.userAgents` in Lighthouse's
// core/config/constants.js, which `lighthouse:default` and the `desktop`
@@ -31,9 +36,132 @@ const MOBILE_USER_AGENT =
const DESKTOP_USER_AGENT =
'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Safari/537.36';
+// Caps the number of DOM nodes returned inline per failing audit to keep the
+// response compact. The full list remains available in the saved reports.
+const MAX_NODES_PER_AUDIT = 10;
+
+const isRecord = (value: unknown): value is Record<string, unknown> => {
+ return typeof value === 'object' && value !== null;
+};
+
+const getString = (value: unknown): string | undefined => {
+ return typeof value === 'string' ? value : undefined;
+};
+
+const toAuditNode = (value: Record<string, unknown>): LighthouseAuditNode => {
+ const node: LighthouseAuditNode = {};
+ const selector = getString(value.selector);
+ const snippet = getString(value.snippet);
+ const nodeLabel = getString(value.nodeLabel);
+ const explanation = getString(value.explanation);
+ if (selector) {
+ node.selector = selector;
+ }
+ if (snippet) {
+ node.snippet = snippet;
+ }
+ if (nodeLabel) {
+ node.nodeLabel = nodeLabel;
+ }
+ if (explanation) {
+ node.explanation = explanation;
+ }
+ return node;
+};
+
+const getNodeKey = (
+ value: Record<string, unknown>,
+ nodes: Map<string, LighthouseAuditNode>,
+): string => {
+ const id = getString(value.lhId) ?? getString(value.path);
+ if (id) {
+ return `id:${id}`;
+ }
+ const selector = getString(value.selector);
+ const snippet = getString(value.snippet);
+ if (selector || snippet) {
+ return `selector:${selector ?? ''}|${snippet ?? ''}`;
+ }
+ // Nodes without any identifying fields cannot be deduplicated reliably, so
+ // each one gets a unique key.
+ return `unidentified:${nodes.size}`;
+};
+
+// Recursively collects node values from audit details. Walking the details
+// generically covers tables and lists of tables alike. Sub-items are skipped:
+// for axe audits they hold related context (e.g. the background element for
+// `color-contrast`) rather than failing elements.
+const collectNodes = (
+ value: unknown,
+ nodes: Map<string, LighthouseAuditNode>,
+): void => {
+ if (Array.isArray(value)) {
+ for (const item of value) {
+ collectNodes(item, nodes);
+ }
+ return;
+ }
+ if (
+ !isRecord(value) ||
+ value.type === 'debugdata' ||
+ value.type === 'subitems'
+ ) {
+ return;
+ }
+ if (value.type === 'node') {
+ const key = getNodeKey(value, nodes);
+ // Merge duplicates so that fields such as `explanation` are kept
+ // regardless of which occurrence carries them.
+ nodes.set(key, {...toAuditNode(value), ...nodes.get(key)});
+ return;
+ }
+ for (const [name, child] of Object.entries(value)) {
+ if (name === 'subItems') {
+ continue;
+ }
+ collectNodes(child, nodes);
+ }
+};
+
+const getFailedAudits = (lhr: Result): LighthouseFailedAudit[] => {
+ const categoriesByAudit = new Map<string, string[]>();
+ for (const category of Object.values(lhr.categories)) {
+ for (const ref of category.auditRefs) {
+ const categoryIds = categoriesByAudit.get(ref.id) ?? [];
+ categoryIds.push(category.id);
+ categoriesByAudit.set(ref.id, categoryIds);
+ }
+ }
+
+ const failedAudits: LighthouseFailedAudit[] = [];
+ for (const audit of Object.values(lhr.audits)) {
+ if (audit.score === null || audit.score >= 1) {
+ continue;
+ }
+ const nodes = new Map<string, LighthouseAuditNode>();
+ collectNodes(audit.details, nodes);
+ const failedAudit: LighthouseFailedAudit = {
+ id: audit.id,
+ title: audit.title,
+ score: audit.score,
+ categories: categoriesByAudit.get(audit.id) ?? [],
+ nodes: [...nodes.values()].slice(0, MAX_NODES_PER_AUDIT),
+ totalNodes: nodes.size,
+ };
+ if (audit.description) {
+ failedAudit.description = audit.description;
+ }
+ if (audit.displayValue) {
+ failedAudit.displayValue = audit.displayValue;
+ }
+ failedAudits.push(failedAudit);
+ }
+ return failedAudits;
+};
+
export const lighthouseAudit = definePageTool((args: ParsedArguments) => ({
name: 'lighthouse_audit',
- description: `Get Lighthouse score and reports for accessibility, SEO, best practices, and agentic browsing. This excludes performance. For performance audits, run ${startTrace(args).name}`,
+ description: `Get Lighthouse scores, failing audits, and the DOM nodes they flag for accessibility, SEO, best practices, and agentic browsing. Full reports are saved to disk. This excludes performance. For performance audits, run ${startTrace(args).name}`,
annotations: {
category: ToolCategory.DEBUGGING,
readOnlyHint: false,
@@ -162,9 +290,7 @@ export const lighthouseAudit = definePageTool((args: ParsedArguments) => ({
score: c.score,
}));
- const failedAudits = Object.values(lhr.audits).filter(
- a => a.score !== null && a.score < 1,
- ).length;
+ const failedAudits = getFailedAudits(lhr);
const passedAudits = Object.values(lhr.audits).filter(
a => a.score === 1,
@@ -179,13 +305,14 @@ export const lighthouseAudit = definePageTool((args: ParsedArguments) => ({
url: lhr.finalDisplayedUrl,
scores: categoryScores,
audits: {
- failed: failedAudits,
+ failed: failedAudits.length,
passed: passedAudits,
},
timing: {
total: lhr.timing.total,
},
},
+ failedAudits,
reports: reportPaths,
};
diff --git a/tests/McpResponse.test.js.snapshot b/tests/McpResponse.test.js.snapshot
index 77abaec5..940955cc 100644
--- a/tests/McpResponse.test.js.snapshot
+++ b/tests/McpResponse.test.js.snapshot
@@ -1322,16 +1322,24 @@ exports[`extensions > lists extensions 2`] = `
`;
exports[`lighthouse > includes lighthouse report paths 1`] = `
-## Lighthouse Audit Results
+## Lighthouse audit results
Mode: navigation
Device: desktop
URL: https://example.com
-### Category Scores
+### Category scores
- Performance: 90 (performance)
-### Audit Summary
+### Audit summary
Passed: 10
Failed: 1
-Total Timing: 1000ms
+Total timing: 1000ms
+### Failed audits
+- color-contrast [accessibility]: Background and foreground colors do not have a sufficient contrast ratio. (score: 0)
+ Low-contrast text is difficult to read.
+ Nodes (12, showing 2):
+ - selector="body > p" label="Hello" snippet="<p class=\\"faint\\">"
+ Fix any of the following: Element has insufficient color contrast
+ - selector="a[title=\\"Say \\\\\\"hi\\\\\\"\\"]" label="Say \\"hi\\" now" snippet="<a title=\\"Say &quot;hi&quot;\\">"
+- document-title [accessibility, seo]: Document does not have a \`<title>\` element (score: 0)
### Reports
- /tmp/report.json
- /tmp/report.html
@@ -1359,6 +1367,42 @@ exports[`lighthouse > includes lighthouse report paths 2`] = `
"total": 1000
}
},
+ "failedAudits": [
+ {
+ "id": "color-contrast",
+ "title": "Background and foreground colors do not have a sufficient contrast ratio.",
+ "description": "Low-contrast text is difficult to read.",
+ "score": 0,
+ "categories": [
+ "accessibility"
+ ],
+ "nodes": [
+ {
+ "selector": "body > p",
+ "snippet": "<p class=\\"faint\\">",
+ "nodeLabel": "Hello",
+ "explanation": "Fix any of the following:\\n Element has insufficient color contrast"
+ },
+ {
+ "selector": "a[title=\\"Say \\\\\\"hi\\\\\\"\\"]",
+ "snippet": "<a title=\\"Say &quot;hi&quot;\\">",
+ "nodeLabel": "Say \\"hi\\"\\nnow"
+ }
+ ],
+ "totalNodes": 12
+ },
+ {
+ "id": "document-title",
+ "title": "Document does not have a \`<title>\` element",
+ "score": 0,
+ "categories": [
+ "accessibility",
+ "seo"
+ ],
+ "nodes": [],
+ "totalNodes": 0
+ }
+ ],
"reports": [
"/tmp/report.json",
"/tmp/report.html"
@@ -1368,18 +1412,18 @@ exports[`lighthouse > includes lighthouse report paths 2`] = `
`;
exports[`lighthouse > rounds category scores and shows unscored categories as n/a 1`] = `
-## Lighthouse Audit Results
+## Lighthouse audit results
Mode: navigation
Device: desktop
URL: https://example.com
-### Category Scores
+### Category scores
- Accessibility: 57 (accessibility)
- SEO: 0 (seo)
- Agentic Browsing: n/a (agentic-browsing)
-### Audit Summary
+### Audit summary
Passed: 10
Failed: 1
-Total Timing: 1000ms
+Total timing: 1000ms
### Reports
- /tmp/report.json
- /tmp/report.html
@@ -1417,6 +1461,7 @@ exports[`lighthouse > rounds category scores and shows unscored categories as n/
"total": 1000
}
},
+ "failedAudits": [],
"reports": [
"/tmp/report.json",
"/tmp/report.html"
diff --git a/tests/McpResponse.test.ts b/tests/McpResponse.test.ts
index f5183007..41a79604 100644
--- a/tests/McpResponse.test.ts
+++ b/tests/McpResponse.test.ts
@@ -945,6 +945,39 @@ describe('lighthouse', () => {
total: 1000,
},
},
+ failedAudits: [
+ {
+ id: 'color-contrast',
+ title:
+ 'Background and foreground colors do not have a sufficient contrast ratio.',
+ description: 'Low-contrast text is difficult to read.',
+ score: 0,
+ categories: ['accessibility'],
+ nodes: [
+ {
+ selector: 'body > p',
+ snippet: '<p class="faint">',
+ nodeLabel: 'Hello',
+ explanation:
+ 'Fix any of the following:\n Element has insufficient color contrast',
+ },
+ {
+ selector: 'a[title="Say \\"hi\\""]',
+ snippet: '<a title="Say &quot;hi&quot;">',
+ nodeLabel: 'Say "hi"\nnow',
+ },
+ ],
+ totalNodes: 12,
+ },
+ {
+ id: 'document-title',
+ title: 'Document does not have a `<title>` element',
+ score: 0,
+ categories: ['accessibility', 'seo'],
+ nodes: [],
+ totalNodes: 0,
+ },
+ ],
reports: ['/tmp/report.json', '/tmp/report.html'],
};
@@ -952,6 +985,7 @@ describe('lighthouse', () => {
const {content, structuredContent} = await response.handle(context);
const text = getTextContent(content[0]);
+ assert.ok(text.includes('### Failed audits'));
assert.ok(text.includes('### Reports'));
assert.ok(text.includes('- /tmp/report.json'));
assert.ok(text.includes('- /tmp/report.html'));
@@ -993,6 +1027,7 @@ describe('lighthouse', () => {
total: 1000,
},
},
+ failedAudits: [],
reports: ['/tmp/report.json', '/tmp/report.html'],
};
diff --git a/tests/tools/lighthouse.test.ts b/tests/tools/lighthouse.test.ts
index 56c88405..4de5a50c 100644
--- a/tests/tools/lighthouse.test.ts
+++ b/tests/tools/lighthouse.test.ts
@@ -50,6 +50,7 @@ describe('lighthouse', () => {
assert.equal(data.summary.mode, 'navigation');
assert.equal(data.summary.device, 'desktop');
assert.ok(data.reports.length === 2); // json, html
+ assert.equal(data.failedAudits.length, data.summary.audits.failed);
// Verify files exist
for (const reportPath of data.reports) {
@@ -257,5 +258,164 @@ describe('lighthouse', () => {
assert.equal(summary.device, 'mobile');
assert.deepEqual(reports, [`${reportPath}.json`, `${reportPath}.html`]);
});
+
+ it('returns failing audits with their DOM nodes inline', async () => {
+ const {page, context, response, args} = createHandlerMocks();
+ context.saveTemporaryFile.resolves({filepath: 'report.json'});
+ const node = (
+ id: number,
+ ): {
+ type: 'node';
+ lhId: string;
+ selector: string;
+ snippet: string;
+ nodeLabel: string;
+ } => ({
+ type: 'node',
+ lhId: `node-${id}`,
+ selector: `div.item-${id}`,
+ snippet: `<div class="item-${id}">`,
+ nodeLabel: `Item ${id}`,
+ });
+ sinon.stub(lighthouseRunner, 'snapshot').resolves(
+ createMockRunnerResult({
+ categories: {
+ accessibility: {
+ id: 'accessibility',
+ title: 'Accessibility',
+ score: 0.5,
+ auditRefs: [
+ {id: 'color-contrast', weight: 7},
+ {id: 'document-title', weight: 7},
+ {id: 'html-has-lang', weight: 7},
+ ],
+ },
+ seo: {
+ id: 'seo',
+ title: 'SEO',
+ score: 0.5,
+ auditRefs: [{id: 'document-title', weight: 1}],
+ },
+ },
+ audits: {
+ 'color-contrast': {
+ id: 'color-contrast',
+ title: 'Insufficient contrast',
+ description: 'Low-contrast text is difficult to read.',
+ score: 0,
+ scoreDisplayMode: 'binary',
+ details: {
+ type: 'table',
+ headings: [],
+ items: [
+ // Duplicate node without an explanation, which must be
+ // merged with the copy below.
+ {node: node(1)},
+ {
+ node: {
+ ...node(1),
+ explanation: 'Fix any of the following: contrast',
+ },
+ subItems: {
+ type: 'subitems',
+ items: [{relatedNode: node(2)}],
+ },
+ },
+ ...Array.from({length: 12}, (_, i) => ({node: node(i + 3)})),
+ ],
+ debugData: {type: 'debugdata', node: node(99)},
+ },
+ },
+ 'document-title': {
+ id: 'document-title',
+ title: 'Missing title',
+ description: 'Titles matter.',
+ score: 0,
+ scoreDisplayMode: 'binary',
+ displayValue: '1 issue',
+ details: {
+ type: 'list',
+ items: [
+ {
+ type: 'table',
+ headings: [],
+ items: [
+ {node: node(50)},
+ // Nodes without identifying fields must not be merged.
+ {node: {type: 'node', nodeLabel: 'Unnamed A'}},
+ {node: {type: 'node', nodeLabel: 'Unnamed B'}},
+ ],
+ },
+ ],
+ },
+ },
+ 'html-has-lang': {
+ id: 'html-has-lang',
+ title: 'Has lang',
+ description: '',
+ score: 1,
+ scoreDisplayMode: 'binary',
+ },
+ 'manual-audit': {
+ id: 'manual-audit',
+ title: 'Manual',
+ description: '',
+ score: null,
+ scoreDisplayMode: 'manual',
+ },
+ },
+ }),
+ );
+
+ await lighthouseAudit(args).handler(
+ {params: {mode: 'snapshot', device: 'desktop'}, page},
+ response,
+ context,
+ );
+
+ sinon.assert.calledOnce(response.attachLighthouseResult);
+ const {summary, failedAudits} =
+ response.attachLighthouseResult.firstCall.args[0];
+ assert.deepEqual(summary.audits, {failed: 2, passed: 1});
+ assert.equal(failedAudits.length, 2);
+
+ const [contrast, title] = failedAudits;
+ assert.equal(contrast.id, 'color-contrast');
+ assert.deepEqual(contrast.categories, ['accessibility']);
+ assert.equal(
+ contrast.description,
+ 'Low-contrast text is difficult to read.',
+ );
+ assert.equal(contrast.totalNodes, 13);
+ assert.equal(contrast.nodes.length, 10);
+ assert.deepEqual(contrast.nodes[0], {
+ selector: 'div.item-1',
+ snippet: '<div class="item-1">',
+ nodeLabel: 'Item 1',
+ explanation: 'Fix any of the following: contrast',
+ });
+ assert.equal(contrast.nodes[1].selector, 'div.item-3');
+ assert.ok(!contrast.nodes.some(n => n.selector === 'div.item-2'));
+ assert.ok(!contrast.nodes.some(n => n.selector === 'div.item-99'));
+
+ assert.deepEqual(title, {
+ id: 'document-title',
+ title: 'Missing title',
+ description: 'Titles matter.',
+ score: 0,
+ displayValue: '1 issue',
+ categories: ['accessibility', 'seo'],
+ nodes: [
+ {
+ selector: 'div.item-50',
+ snippet: '<div class="item-50">',
+ nodeLabel: 'Item 50',
+ },
+ {nodeLabel: 'Unnamed A'},
+ {nodeLabel: 'Unnamed B'},
+ ],
+ totalNodes: 3,
+ });
+ });
});
});