Lighthouse and Pa11y audits directly in Cypress test suites
RunWhy cypress-audit?
We have the chance of being able to use powerful tools to automated and prevent from different kind of regressions:
- Cypress has made business oriented automated verifications easy
- Lighthouse has provided tools and metrics concerning applications performances
- Pa11y has provided tools to analyze and improve the accessibility status of applications
While these tools are amazingly powerful and helpful, I'm always feeling in pain when I try to use all of them in my projects.
For example, how can I verify the performance and accessibility status of a page requiring authentication? I have to tweak Lighthouse and Pa11y configurations (that are different) and adjust my workflows accordingly.
This is cumbersome because I already have my authentication logic and shortcuts managed by Cypress: why should I add more complexity in my tests?
The idea behind cypress-audit
is to aggregate all the underlying configurations behind dedicated Cypress custom commands: you can benefit from your own custom commands and you can run cross-cutting verifications directly inside your tests.
Usage
Preparation
In order to make cypress-audit
commands available in your project, there are 3 steps to follow:
Installing the dependency
In your favorite terminal:
$ yarn add -D cypress-audit
# or
$ npm install --save-dev cypress-audit
Preparing the server configuration
By default, if you try to run Lighthouse or Pa11y from the command line (or from Nodejs), you will see that they both open a new web browser window by default. As you may also know, Cypress also opens a dedicated browser to run its tests.
The following configuration allows Lighthouse, Pa11y and Cypress to make their verifications inside the same browser (controlled by Cypress) instead of opening a new one.
In the cypress/plugins/index.js
file, make sure to have:
const { lighthouse, pa11y, prepareAudit } = require("cypress-audit");
module.exports = (on, config) => {
on("before:browser:launch", (browser = {}, launchOptions) => {
prepareAudit(launchOptions);
});
on("task", {
lighthouse: lighthouse(), // calling the function is important
pa11y: pa11y(), // calling the function is important
});
};
Making Cypress aware of the commands
When adding the following line in the cypress/support/commands.js
file, you will be able to use cy.lighthouse
and cy.pa11y
inside your Cypress tests:
import "cypress-audit/commands";
In your code
After completing the Preparation section, you can use the cy.lighthouse
and cy.pa11y
commands:
it("should pass the audits", function () {
cy.lighthouse();
cy.pa11y();
});
Accessing the raw reports
When using custom tools, it can be convenient to directly access the raw information they provide for doing manual things, such as generating a custom reports.
To do so, you can pass a callback
function to the task initializer. Then, when an audit is run, this callback will we executed with the raw data of the underlying tool.
In the cypress/plugins/index.js
file:
const { lighthouse, pa11y, prepareAudit } = require("cypress-audit");
module.exports = (on, config) => {
on("before:browser:launch", (browser = {}, launchOptions) => {
prepareAudit(launchOptions);
});
on("task", {
lighthouse: lighthouse((lighthouseReport) => {
console.log(lighthouseReport); // raw lighthouse reports
}),
pa11y: pa11y((pa11yReport) => {
console.log(pa11yReport); // raw pa11y reports
}),
});
};