In one of my previous articles I explained how we can use Lighthouse to put our website on a budget and why monitoring your website performance its an important aspect of web development. In this article, we will go deeper into Lighthouse building blocks, its architecture and learn how we can start auditing and collecting custom metrics for our web pages.
\nLighthouse is an audit tool developed by Google which collects different metrics of your website. After collecting the metrics it will present a series of scores for your webpage. The scoring is divided into five main auditing areas.
\nLighthouse\narchitecture is built around Chrome Debugging\nProtocol which is a set of low-level API to interact with a Chrome instance. It interfaces a Chrome instance through the Driver. The Gatherers collect data from the page using the Driver. The output of a Gatherer is an Artifact, a collection of grouped metrics. An Artifact then is used by an Audit to test for a metric. The Audits asserts and assign a score to a specific metric. The output of an Audit is used to generate the lighthouse report that we are familiar with.
\nWe will now take a close look at two of the Lighthouse building blocks by creating a simple audit tracking the internal rendering of a webpage. Creating an application is necessary in order to include a custom Gatherer or Audit since it is not possible to add any custom Gatherer or Audit directly into the Chrome panel.
\nLet’s create our project and install lighthouse as a dependency
\nmkdir custom-audit && cd custom-audit\nnpm i --save lighthouseTo start auditing our website we will then create a new file scan.js where we will import Lighthouse and start scanning the webpage of choice. We will use programmatic access to Lighthouse by importing it inside our project
const lighthouse = require('lighthouse');\nconst chromeLauncher = require('chrome-launcher');\n\nasync function launchChromeAndRunLighthouse(url, opts, config = null) {\n const chrome = await chromeLauncher.launch({chromeFlags: opts.chromeFlags});\n opts.port = chrome.port;\n const { lhr } = await lighthouse(url, opts, config);\n await chrome.kill()\n return lhr;\n}\n\nconst opts = {};\n\n// Usage:\n(async () => {\n try {\n const results = await launchChromeAndRunLighthouse('https://izifortune.github.io/lighthouse-custom-gatherer', opts);\n console.log(results);\n } catch (e) {\n console.log(e);\n }\n})();If we now try to run our file we should be able to see the results coming from a lighthouse scan in the console:
\nnode scan.jsNow that we have a project with Lighthouse up and running we can start looking at how a Gatherer works and how we can use it in our project. We will use a webpage that I’ve created for this demo. In the page, I’m fetching todo list items from an API and rendering on the page. I’m measuring the action using PerformanceAPI as follows:
\nconst getDataFromServer = async () => {\n performance.mark('start');\n const todos = await getTodos();\n renderTodos(todos);\n performance.mark('end');\n performance.measure('Render todos', 'start', 'end');\n const measure = performance.getEntriesByName('Render todos')[0];\n}A Gatherer is used by Lighthouse to collect data on the page. In fact, any data that is currently needed to perform the default lighthouse audits is collected through a Gatherer. We can extend the Gatherer base class and start creating custom ones:
\nconst { Gatherer } = require('lighthouse');\n\nclass MyGatherer extends Gatherer {\n ...\n}The class Gatherer defines three different lifecycle hooks that we can implement in our class:
\nA lifecycle hook is expected to return either directly an Artifact or a Promise which resolve to the desired Artifact. Depending on what data are we looking to collect from the Driver and at what time we can use any of the hooks just described.
\nLet’s now create a custom Gatherer which will collect the measurements from the PerformanceAPI. The Gatherer needs then to collect entryType measure using a PerformanceObserver. We will proceed to create the file todos-gatherer.js
'use strict';\n\nconst { Gatherer } = require('lighthouse');\n\n\nfunction performance() {\n return new Promise((res) => {\n let logger = (list) => {\n const entries = list.getEntries();\n window.todosPerformance = entries[0].duration\n res(entries[0].duration);\n }\n let observer = new PerformanceObserver(logger);\n observer.observe({ entryTypes: ['measure'], buffered: true });\n });\n}\n\n\nclass TodosGatherer extends Gatherer {\n beforePass(options) {\n const driver = options.driver;\n return driver.evaluateScriptOnNewDocument(`(${performance.toString()})()`)\n }\n\n afterPass(options) {\n const driver = options.driver;\n return driver.evaluateAsync('window.todosPerformance')\n }\n}\n\nmodule.exports = TodosGatherer;Inside TodosGatherer we are using both the beforePass and afterPass hook to contact the Driver and then execute a javascript function inside the context of the current page returning a promise. Inside the beforePass we are registering a PerformanceObserver just after the page will load, since the observers are not buffered we might encounter in a race condition. In the afterPass then we collect the previously registered measure.\nTo get an idea of all the methods that you use on the driver object you can have a look\nhere.
\nNow we need to include it in our scan.js file:
const lighthouse = require('lighthouse');\nconst chromeLauncher = require('chrome-launcher');\n\nconst config = {\n passes: [{\n passName: 'defaultPass', //Needed to run custom Gatherers/Audits in the same pass\n gatherers: [\n `todos-gatherer`,\n ],\n }],\n}\n...If we try to run scan.js at this moment we will receive an error that there are no audits to run. A Gatherer on its own doesn’t provide any information but rather output Artifacts used on the Audits to define metrics. To proceed then we will have a look at the Audits then.
An Audit defines a metric or score, it takes the Artifacts as an input and calculates the desired score. The different audits that Lighthouse is performing such as FirstMeaningfulPaint or SpeedIndex are all in fact defined as an audit internally.\nTo create a custom Audit, similar to a Gatherer, we will extend a base class Audit and implements the basic methods:
To create a custom Audit, similar to a Gatherer, we will extend a\nbase class Audit and implements the basic methods:
const { Audit } = require('lighthouse');\n\nclass MyAudit extends Audit {\n static get meta() {\n ..\n }\n\n static audit(artifacts) {\n ...\n }\n}The class Audit defines two methods that need to be overridden:
\nWith this information in mind, we can now implement our custom Audit and start collecting the performance of the todo list. The name of the custom audit file will be todos-audit.js and will contain:
'use strict';\n\nconst Audit = require('lighthouse').Audit;\n\nclass TodosAudit extends Audit {\n static get meta() {\n return {\n id: 'todos-audit',\n title: 'Todos are loaded and rendered',\n scoreDisplayMode: Audit.SCORING_MODES.NUMERIC,\n failureTitle: 'Todos loading is too slow.',\n description: 'Used to measure time for fetching and rendering todos list',\n requiredArtifacts: ['TodosGatherer'],\n };\n }\n\n static audit(artifacts) {\n const measure = artifacts.TodosGatherer;\n\n return {\n rawValue: measure,\n score: Math.max(1 - (measure / 1500), 0),\n displayValue: `Todos rendering is: ${measure}ms`\n };\n }\n}\nmodule.exports = TodosAudit;Inside the method meta we are defining information describing the Audit itself such as id, title, scoreDisplayMode and description. Also, we are configuring the Artifacts which are needed by the Audit in this case TodosGatherer is the name of the Gatherer of interest.
And now we need to add it in the configuration inside scan.js similar to what we did previously to the Gatherer.
const config = {\n passes: [{\n passName: 'defaultPass’,\n gatherers: [\n `todos-gatherer`,\n ],\n }],\n audits: [\n 'todos-audit',\n ],\n categories: {\n todos: {\n title: 'Todos metrics',\n description: 'Performance metrics for todos',\n auditRefs: [\n // When we add more custom audits, `weight` controls how they're averaged together.\n {id: 'todos-audit', weight: 1},\n ],\n },\n },\n}Launching now our scan we can notice our custom audit being logged into the console.
\nAnd running it now we will have an HTML report inside We can include also the standards Lighthouse audits together with our custom one by adding to the configuration object the following key: After the introduction to the Lighthouse architecture, we can start customising the Lighthouse audits by measuring and reporting metrics which are relevant to us. We will explore now how we can use the Gatherers to overcome a common problem while performing the scans on a CI environment. In Ryanair, we are using Lighthouse extensively to audit our webpages as part of an automated job performing scans at regular intervals and then we analyse the results of the scans on a regular basis. One of the main problems that we encountered when you are running an automated scan is how to perform audits on pages behind an authentication or user session. While with manual scans we can easily generate a session before starting the audit; if we are running Lighthouse from a CI environment we will need to generate a session programmatically and pass the information to Lighthouse. A common approach for user session authentications management for a web application is to generate tokens, often JWT, on the server after a successful login and store the result token in the browser. You can store the token in different storage available in the browser such as LocalStorage, SessionStorage, Cookies. I will not judge here where is the best place to store a token what is interesting to us is how we can write to any of that browser storage so that Lighthouse can access the token and perform an audit. By using a custom Gatherer we can create a user session by leveraging the lifecycle hook beforePass which triggers before the navigation to the page URL. In the hook, we call an API to generate a session and then through one of the Driver methods For the purpose of this demo, I’ve created another page where I’m basically rendering the todos only if the user is authenticated. To fake the authentication I’m checking that a specific token is present in LocalStorage and then start fetching and rendering todos. Let’s create a new Gatherer called SessionGatherer in the file\n Once we have created the gatherer we need to tell Lighthouse to include it in the list so that it will be running alongside all the other gatherers while performing an audit. We need to will create another file Now we can start running our scans on the pages behind a user session and monitor their performance. Which record the default Lighthouse metrics plus the custom Todos metrics which on this case are behind a user authentication. I’ve collected the examples presented here in this repository https://github.com/izifortune/lighthouse-custom-gatherer The initial idea came by looking at the custom audit recipe from the Lighthouse team that you can find here.\nThe recipe served as an inspiration and a first example to create a custom Gatherer/Audit. I also would like to thanks @patrickhulce for his time and prompt answers on Gitter.report.html which will look similar to the following one:const config = {\n extends: 'lighthouse:default', // Include Lighthouse default audits\n passes: [{\n passName: 'defaultPass’,\n gatherers: [\n `todos-gatherer`,\n ],\n }],\n...Session guard pages
\nevaluateScriptOnNewDocument we can pass any function to be executed in the browser instance.session-gatherer.jsconst { Gatherer } = require('lighthouse');\n\nconst TOKEN = 'iOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImp0aSI6IjkzZDU0MDBiLTQ5MzgtNDNmZS1iMjY4LTY2MDJlNDIxMjFiYiIsImlhdCI6MTU1MjkwNjc0NywiZXhwIjoxNTUyOTEwMzQ3fQ.qEJflkN2ntXrQFalBkkw4duCh55HdNBLGXZOV-dS3KQ';\n\nfunction createSession(token) {\n localStorage.setItem('token', token);\n}\n\nclass SessionGatherer extends Gatherer {\n\n async beforePass(options) {\n const driver = options.driver;\n return driver.evaluateScriptOnNewDocument(`(${createSession.toString()})('${TOKEN}')`);\n }\n}\n\nmodule.exports = SessionGatherer;scan-auth.js as following:const lighthouse = require('lighthouse');\nconst chromeLauncher = require('chrome-launcher');\nconst { promisify } = require('util');\nconst { writeFile } = require('fs');\nconst pWriteFile = promisify(writeFile);\n\nconst config = {\n extends: 'lighthouse:default',\n passes: [{\n passName: 'defaultPass',\n gatherers: [\n `session-gatherer`,\n `todos-gatherer`\n ],\n }],\n audits: [\n 'todos-audit'\n ],\n categories: {\n todos: {\n title: 'Todos metrics',\n description: 'Performance metrics for todos',\n auditRefs: [\n // When we add more custom audits, `weight` controls how they're averaged together.\n {id: 'todos-audit', weight: 1},\n ],\n },\n },\n}\n\nasync function launchChromeAndRunLighthouse(url, opts, config = null) {\n const chrome = await chromeLauncher.launch({chromeFlags: opts.chromeFlags});\n opts.port = chrome.port;\n const { lhr, report } = await lighthouse(url, opts, config);\n await chrome.kill()\n return report;\n}\n\nconst opts = {\n output: 'html'\n};\n\n// Usage:\n(async () => {\n try {\n const results = await launchChromeAndRunLighthouse('https://izifortune.github.io/lighthouse-custom-gatherer/auth', opts, config);\n await pWriteFile('report.html', results)\n } catch (e) {\n console.log(e);\n }\n})();node scan-auth.jsCredits
\n