Run Lighthouse tests in Pull Requests for multiple URLs with custom budgets
Run Lighthouse tests in Pull Request URLs with multiple routes. Prevent regressions through custom budgets in a flexible and extensible configuration.
Any Github Check Run, Deployment or Status, including:
There is a disconnect between the state of performance tooling, and the desire teams have to move faster but safer.
On one side, there are several tools to monitor production/staging environments, but on the other side, teams are looking to have full CI/CD integrated where Pull Requests go live upon merge.
This requires that all testing must happen at the Pull Request level on a unique URL per branch and/or commit, and while there are tools that support these types of Performance tests, they all suffer from common problems:
Single URL.
Run and block the CI build process.
If used for multiple URLs manually, there is no consolidated report.
Lightkeeper attempts to solve each one of these issues: 🤞
Multiple URL support.
Decoupled from the CI build process.
Consolidated reports, and expandable comments.
Most importantly, Lightkeeper provides granular control of settings per route, from budgets to the Lighthouse endpoint and its options, including chrome flags in the puppeteer configuration.
See Motivation.
Add a lightkeeper.json
file in a .github
folder. Start from the default configuration.
This is the only file Lightkeeper has access in your code.
There are 3 required fields: baseUrl
, ci
, and type
. Lightkeeper is a budgeting tool, so at least a single type of budget is needed to run sucessfully.
Replace the baseUrl
with a valid URL. Since Pull Request URLs are dynamic, macros are available:
Macro | Details |
---|---|
{pr_number} |
The Pull Request Number. |
{repo} |
A slugified repo name. |
{branch} |
A slugified branch name. |
{commit_hash} |
The full commit SHA. |
{commit_hash:n} |
A trimmed SHA, where n is a digit. |
*{target_url} |
The target url from the Github Response. |
**{environment_url} |
The url from the Deployment status. |
* Available for statuses and deployments.
** Available for deployments only.
Replace ci
and type
for your CI tool. Examples:
{
"ci": "circleci",
"type": "check"
}
CircleCI uses statuses by default, but also provide a Github Checks integration.
If multiple checks are running (e.g: Integration Tests, Mobile Tests, etc)
Use the full name of the specific workflow as it appears in Github, instead of circleci
.
{
"baseUrl": "{target_url}",
"ci": "netlify",
"type": "status"
}
{
"ci": "travis-ci",
"type": "check"
}
{
"baseUrl": "{environment_url}",
"ci": "now",
"type": "deployment"
}
If you're unsure about the name of your CI tool, it's the name displayed under
Developer
in the application page: https://github.com/apps/[app-name]
NOTE: These providers and their settings can change. If the provided ci
name above does not work, use the full visible name:
Visit the wiki for a full list of configuration options.
Additionally, there is a custom configuration example.
Do you have a complex build pipeline that performs several tasks internally? Using the Lightkeeper Bot with the app installed, you can start the process manually without stalling the build:
Install:
npm i --save-dev lightkeeperbot
In your CI tool, run:
npx lightkeeperbot <baseUrl> [--options]
Lightkeeper Bot defaults to Travis CI environment variables.
See the full docs.
Why isn't this part of the Lighthouse Bot?
Lightkeeper
is compatible with their Ligthouse server located at https://builder-dot-lighthouse-ci.appspot.com/ci, if you choose to continue using it.Why isn't this a Github Action?
status
(only run action when a check run completes and is succesful); I'd be more than happy to switch since it removes the need for a server, and allows for securely sharing secrets.I'm getting a Lighthouse error in my reports.
throttling
options, or device emulation.Please open an issue if you have any questions, feature requests or problems, an example configuration for reproduction is deeply appreciatted. 👍
If you find this tool useful, and want me to spend more time on it. Consider Donating.
AGPL, Copyright (c) 2019 Alfredo Lopez