Custom Audits and Assertions
Develop your own Lighthouse audits to enforce specific performance or best practice rules relevant to your project.
Custom Audits and Assertions is a free Web Performance Optimization & Lighthouse lesson on CoddyKit — lesson 2 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Web Performance Optimization & Lighthouse learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.
Extend Lighthouse's Power
Welcome to creating custom Lighthouse audits! While Lighthouse offers many built-in checks, sometimes you need to enforce project-specific rules or validate unique performance requirements.
This lesson shows you how to build your own.
Why Create Custom Audits?
Custom audits allow you to tailor Lighthouse to your exact needs. They help you:
- Enforce Standards: Check for specific coding patterns or component usage.
- Validate Unique Metrics: Measure performance aspects not covered by default.
- Ensure Compliance: Verify project-specific accessibility or SEO rules.
- Automate Checks: Integrate tailored performance feedback directly into your development workflow.
Audit Anatomy: Gatherers & Audits
A custom Lighthouse audit typically has two main parts:
- Gatherer: This component collects raw data about the page. It runs inside the browser and extracts specific information, like DOM elements, network requests, or JavaScript variables.
- Audit: This component analyzes the data collected by the gatherer. It applies logic to determine a score, a pass/fail state, and provides recommendations.
Both are then linked in a Lighthouse configuration file.
Building a Gatherer: Data Collection
A gatherer is responsible for collecting data. It extends Lighthouse.Gatherer and uses methods like afterPass to run JavaScript in the page's context.
Let's create a gatherer that checks for a specific <meta> tag.
Gatherer Code Example
This gatherer looks for an <meta name="author"> tag and returns its content. If not found, it returns null.
// gatherers/author-meta-gatherer.js
'use strict';
const Gatherer = require('lighthouse').Gatherer;
class AuthorMetaGatherer extends Gatherer {
afterPass(options) {
const driver = options.driver;
// Evaluate JS in the browser context
return driver.evaluateAsync(() => {
const metaTag = document.querySelector('meta[name="author"]');
return metaTag ? metaTag.content : null;
});
}
}
module.exports = AuthorMetaGatherer;Building an Audit: Evaluation Logic
An audit takes the data provided by gatherers and applies your custom logic. It extends Lighthouse.Audit and implements a static audit method.
This method receives the collected "artifacts" (data) and determines the audit's result.
Audit Code Example
This audit uses the data from our AuthorMetaGatherer to check if the author meta tag is present and has content. It scores 1 (pass) or 0 (fail).
// audits/author-meta-audit.js
'use strict';
const Audit = require('lighthouse').Audit;
class AuthorMetaAudit extends Audit {
static get meta() {
return {
id: 'author-meta-tag',
title: 'Author meta tag is present',
failureTitle: 'Author meta tag is missing or empty',
description: 'Ensures an author meta tag is present for attribution.',
requiredArtifacts: ['AuthorMetaGatherer'],
};
}
static audit(artifacts) {
const authorMetaContent = artifacts.AuthorMetaGatherer;
const passed = !!authorMetaContent && authorMetaContent.trim().length > 0;
return {
score: passed ? 1 : 0,
details: {
type: 'debuginfo',
headings: [
{key: 'content', itemType: 'text', text: 'Author Meta Content'},
],
items: [{content: authorMetaContent || 'Not found'}],
},
};
}
}
module.exports = AuthorMetaAudit;Integrating into Lighthouse Config
To make Lighthouse aware of your custom gatherer and audit, you need a custom configuration file. This file tells Lighthouse which gatherers to run and which audits to include, often extending the default Lighthouse checks.
// custom-config.js
'use strict';
module.exports = {
extends: 'lighthouse:default', // Inherit default audits
gatherers: [
'./gatherers/author-meta-gatherer.js',
],
audits: [
'./audits/author-meta-audit.js',
],
categories: {
'custom-category': {
title: 'Custom Checks',
description: 'Project-specific performance and best practice audits.',
auditRefs: [
{id: 'author-meta-tag', weight: 1, group: 'metrics'},
],
},
},
};Running Lighthouse with Custom Audits
Finally, you can run Lighthouse programmatically using Node.js, referencing your custom configuration file. This script launches Chrome, runs Lighthouse, and generates a report.
Make sure you have lighthouse and chrome-launcher installed via npm.
// run-custom-audit.js
const lighthouse = require('lighthouse');
const chromeLauncher = require('chrome-launcher');
(async () => {
const chrome = await chromeLauncher.launch({chromeFlags: ['--headless']});
const options = {
logLevel: 'info',
output: 'html',
onlyCategories: ['custom-category'], // Run ONLY our custom category
port: chrome.port
};
const config = require('./custom-config.js'); // Load your custom config
const runnerResult = await lighthouse('https://example.com', options, config);
console.log('Report is done for', runnerResult.lhr.requestedUrl);
// Accessing your custom audit score:
const customAuditScore = runnerResult.lhr.audits['author-meta-tag'].score;
console.log('Author Meta Tag Audit Score:', customAuditScore);
await chrome.kill();
})();Custom Audit Components
You've learned about the key pieces needed to build a custom Lighthouse audit.
Which of the following are essential components when creating a custom Lighthouse audit?
Recap: Your Custom Audit Toolkit
You've successfully learned how to extend Lighthouse's capabilities!
By understanding gatherers, audits, and custom configurations, you can now build powerful, project-specific checks. This allows you to enforce unique best practices and gain deeper, tailored insights into your web performance.
Frequently asked questions
Is the “Custom Audits and Assertions” lesson free?
Yes — the full text of “Custom Audits and Assertions” is free to read here on the web, and the Web Performance Optimization & Lighthouse course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Web Performance Optimization & Lighthouse course, upgrade to CoddyKit PRO.
What will I learn in “Custom Audits and Assertions”?
Develop your own Lighthouse audits to enforce specific performance or best practice rules relevant to your project. You practise Web Performance Optimization & Lighthouse with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start Web Performance Optimization & Lighthouse?
No prior experience is required. Web Performance Optimization & Lighthouse on CoddyKit is structured for beginners through advanced learners; this is — lesson 2 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “Custom Audits and Assertions” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this Web Performance Optimization & Lighthouse lesson?
Yes. Every Web Performance Optimization & Lighthouse lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.
All lessons in this course
- CLI and Programmatic Lighthouse
- Custom Audits and Assertions
- Integrating Lighthouse into CI/CD
- Performance Budgets with Lighthouse