Continuous Performance Analysis with Lighthouse CI and GitHub Actions | CSS tricks (2023)

Lighthouse is a free and open-source tool for measuring your website's performance, accessibility, Progressive Web App metrics, SEO, and more. The easiest way to use it is through the Chrome DevTools dashboard. After opening DevTools, you will see a "Lighthouse" tab. Clicking the "Generate Report" button will run a series of tests on the webpage and display the results right there in the Lighthouse tab. This makes it easy to test any web page, whether it's public or requires authentication.

If you don't use Chrome or Chromium-based browsers like Microsoft Edge or Brave, you can run Lighthouse through yourweb interfacebut it only works with publicly available web pages. FORnode CLI toolit is also provided for those who want to run Lighthouse audits from the command line.

All of the options listed above require some form of manual intervention. Wouldn't it be great if we could integrate Lighthouse testing into the continuous integration process so that the impact of changes to our code can be displayed inline with each pull request, and so that we can fail builds if certain performance thresholds aren't valid? Well that's exactly whyFarol CIexist!

It's a set of tools that help you identify the impact of specific code changes on your site, not just in terms of performance, but also in terms of SEO, accessibility, offline support, and other best practices. It provides a great way to enforce performance budgets, and it also helps you keep track of each reported metric so you can see how they've changed over time.

In this article, we'll look at how to set up Lighthouse CI and run it locally, making it work as part of a CI workflow using GitHub Actions. Note that Lighthouse CI also works with other CI providers such as Travis CI, GitLab CI, and Circle CI if you prefer not to use GitHub Actions.

Local configuration of Lighthouse CI

In this section, you will configure and run theFarol CIcommand line tool locally on your machine. Before proceeding, make sure you have Node.js v10 LTS or later and Google Chrome (stable) installed on your machine, then install the Lighthouse CI tool globally:

$ npm install -g @lhci/cli

Once the CLI has been successfully installed, rulhci --helpto see all available commands provided by the tool. There are eight commands available at the time of this writing.

$ lhci --helplhci <command> <options>Commands: lhci collect Run Lighthouse and save the output to a local folder lhci upload Save the output to the server lhci assert Confirm that the latest output meets expectations lhci autorun Run collect/ assert/load with sensible defaults lhci healthcheck Run diagnostics to ensure a valid configuration lhci open Open HTML reports of collected runs lhci Wizard Step by step wizard for CI tasks such as creating a project lhci server Run Lighthouse CI server Options: -- help Show help [boolean ] --version Show version number [boolean] --no-lighthouserc Disable automatic use of a .lighthouserc file. [boolean] --config Path to JSON configuration file

At this point, you're ready to configure the CLI for your project. Lighthouse CI configuration can be managed using (in ascending order of priority) a configuration file, environmental variables or CLI flags. use theAPI of Yargsto read its configuration options, which means there's a lot of flexibility in how it can be configured. the fulldocumentationcovers all In this post, we will make use of the configuration file option.

Go ahead and create onefarorc.jsfile in the root of your project directory. Make sure the project is being tracked with Git because Lighthouse CI automatically infers build context settings from the Git repository. If your project doesn't use Git, you can control build context settings viaenvironmental variablesinstead of.

play lighthouserc.js

This is the simplest setup that will run and collect Lighthouse reports for a static website project and upload them to temporary public storage.

// lighthouserc.jsmodule.exports = { ci: { recopilar: { staticDistDir: './public', }, upload: { target: 'temporal-public-storage', }, },};

Heci.collectThe object provides several options for controlling how Lighthouse CI collects test reports. HestaticDistDiris used to indicate the location of your static HTML files, for example,Hugobuild apublicdirectory,jekyllput your build files in a_placedirectory, and so on. All you need to do is update thestaticDistDiroption for wherever your building is located. When Lighthouse CI runs, it starts a server that can run the tests accordingly. Upon completion of the test, the server will automatically shut down.

If your project requires the use of a custom server, you can enter the command used to start the server via theiniciarServerCommandproperty. When using this option, you must also specify the URLs to test via theURLoption. The custom server you specified must be able to serve this URL.

module.exports = { ci: { recopilar: { startServerCommand: 'npm run server', url: ['http://localhost:4000/'], }, upload: { target: 'temporal-public-storage', } ,},};

When Lighthouse CI runs, it runs theservercommand and take care of himto hearoa liststring to determine if the server has started. If it doesn't detect this string after 10 seconds, it assumes the server has started and continues with the test. Then run Lighthouse three times on each URL in theURLtraining. After the test run is complete, it shuts down the server process.

You can configure both the default sequence to watch and the timeout duration via thestartServerReadyPatternystartServerReadyTimeoutoptions respectively. If you want to change the number of times Lighthouse runs on each URL, use thenumber of runsproperty.

// lighthouserc.jsmodule.exports = { ci: { collect: { startServerCommand: 'npm run server', url: ['http://localhost:4000/'], startServerReadyPattern: 'Server is running on PORT 4000 ', startServerReadyTimeout : 20000 // milissegundos numberOfRuns: 5, }, upload: { target: 'armazenamento público temporário', }, },};

Helookproperty within theci.subirThe object is used to configure where Lighthouse CI loads results after a test is completed. Hetemporary public storageThe option indicates that the report will be uploaded to Google's cloud storage and will be retained for a few days. It will also be available to anyone who has the link, without the need for authentication. If you want more control over how reports are stored, see thedocumentation.

At this point, you should be ready to run the Lighthouse CI tool. Use the following command to launch the CLI. Will launch Lighthouse three times on the provided URLs (unless changed via thenumber of runsoption) and load the median result into the configured target.

lhci autorun

The output should be similar to what is shown below:

✅ The .lighthouseci/ directory is writable ✅ Configuration file found ✅ Chrome installation found ⚠️ GitHub token not set. -with-go/Run #1...done.Run #2...done.Run #3...done.Running Lighthouse 3 times at http://localhost:52195/custom-html5-video /Run # 1...done.Run #2...done.Run #3...done.Run Lighthouse Fact! ..success!Open the report at https://storage.googleapis.com/lighthouse-infrastructure.appspot.com/reports/1606403407045-45763.report.htmlUploading median LHR from http://localhost:52195/custom-html5 - video/...success!Open report at https://storage.googleapis.com/lighthouse-infrastructure.appspot.com/reports/1606403400243-5952.report.htmlSaving URL map to GitHub repository ayoisaiah/calouro.. .success !GitHub token not set, bypassing GitHub status check.Autorun completed.

The GitHub token message can be ignored for now. We'll set one up when it comes time to set up Lighthouse CI with a GitHub action. You can open the Lighthouse report link in your browser to see the median URL reach test results.

Assertion Configuration

Using the Lighthouse CI tool to run and collect Lighthouse reports works great, but we can go further and configure the tool to fail a build if the test results don't match certain criteria. The options that control this behavior can be configured through theclaimproperty. Here is an excerpt showing an example configuration:

// lighthouserc.jsmodule.exports = { ci: { assertion: { preset: 'lighthouse: no-pwa', assertions: { 'categories: performance': ['error', { minScore: 0.9 }], 'categories: accessibility ': ['warn', {minimum score: 0.9 }], }, }, },};

HepresetThe option is a quick way to configure Lighthouse assertions. There are three options:

• lighthouse: all: Claims that each audit received a perfect score
• headlamp: recommended– Asserts that all out-of-performance audits received a perfect score and warns when metric values ​​fall below 90 points
• faro: no-pwa: The same asheadlamp: recommendedbut without any of the PWA audits

you can use theaffirmationsobject to override or extend the defaults, or create a custom set of assertions from scratch. The above configuration claims a benchmark score of 90 for theperformanceyaccessibilitycategories. The difference is that failure of the former will result in a non-zero exit code, while the latter will not. The result of any Lighthouse audit can be confirmed, so there's a lot you can do here. Be sure to check thedocumentationto discover all available options.

You can also configure assertions against abudget.jsonfile. This can be created manually or generated viarendimientopresupuesto.io. Once you have your file, feed it into theclaimobject as shown below:

// lighthouserc.jsmodule.exports = { ci: { collect: { staticDistDir: './public', url: ['/'], }, assert: { budgetFile: './budget.json', }, load: { target: 'temporary public storage', }, },};

Running Lighthouse CI with GitHub Actions

A useful way to integrate Lighthouse CI into your development workflow is to generate new reports for every commit or pull request in your project's GitHub repository. this is whereGitHub Actionscome play.

To configure it, you must create a.github/workflowdirectory at the root of your project. This is where all your project workflows will be placed. If you're new to GitHub Actions, you can think of a workflow as a set of one or more actions that run after an event fires (like when a new pull request is made to the repository). Sarah Drasner has a good manual onusing github actions.

mkdir -p .github/workflow

Then create a YAML file in.github/workflowdirectory. You can name it whatever you like, as long as it ends with the.ymlo.yamlextension. This file is where workflow settings for Lighthouse CI will be placed.

cd .github/workflowtouch lighthouse-ci.yaml

the content oflighthouse-us.yamlThe file will vary depending on the type of project. I will describe how I set it up for myselfsite do Hugoso you can adapt it to other types of projects. Here is my complete config file:

# .github/workflow/lighthouse-ci.yamlname: lighthouseon: [push] works: ci: executes: ubuntu-laststeps: -name: checkout code uses: actions/[email protected]com: token: ${{ secrets.PAT }} submodules: recursive - name: Setup Hugo uses: Peaceiris/[email protected]con: hugo-version: "0.76.5" extendido: true - name: Build site run: hugo - name: Use Node.js 15.x uses: actions/[email protected]com: node version: 15.x - name: Run Lighthouse CI run: | npm install -g @lhci/[email protected]lhci autorun

The above configuration creates a workflow calledfaroconsists of a single job (ci) that runs on an Ubuntu instance and fires whenever code is pushed to any repository branch. The work consists of the following steps:

• Check out the repository where Lighthouse CI will run. Hugo uses submodules for its themes, so you need to make sure that all submodules in the repository are also checked out. If any submodules are in a private repository, you need to create a new onepersonal access tokenwith himrepositoryscope enabled and then add it as a repository secret inhttps://github.com/<username>/<repo>/settings/secret. Without this token, this step will fail if it finds a private repository.

• Install Hugo on the GitHub Action virtual machine so that it can be used to build the website. ThatHugo's configuration actionis what I used here. You can find other configuration actions inGitHub Stock Exchange.
• Build the site for apublicpaste through thehugodomain.
• Install and configure Node.js on the virtual machine viaconfiguration nodeAction
• Install the Lighthouse CI tool and run thelhci autorundomain.

After configuring the configuration file, you can commit and push the changes to your GitHub repository. This will activate the workflow you just added, provided its settings have been configured correctly. Go to the Actions tab in the project's repository to see the status of the workflow at its most recent commit.

If you click and expand thecijob, you will see logs for each job step. In my case everything went successfully but my assertions failed hence the failed status. As we saw when we ran the test locally, the results are sent to temporary public storage and you can view them by clicking on the appropriate link in the logs.

Configuring GitHub health checks

Currently, Lighthouse CI is configured to run as soon as code is pushed to the repository, either directly to a branch or via a pull request. Test status is displayed on the confirmation page, but you must click and expand the records to see full details, including links to the report.

You can set up a GitHubhealth check upso that the build reports are displayed directly in the pull request. To configure it, go toLighthouse CI GitHub application page, click the "Configure" option, install and authorize it in your GitHub account or in the organization that owns the GitHub repository you want to use. Then copy the app token given in the confirmation page and add it to your repository secrets with the name field set toLHCI_GITHUB_APP_TOKEN.

The health check is now ready to use. You can test it by opening a new pull request or submitting a commit to an existing pull request.

Historical reporting and comparisons via Lighthouse CI server

Using the temporary public storage option to store your Lighthouse reports is a great way to start, but it's not enough if you want to keep your data private or longer. This is where the Lighthouse CI server can help. It provides a dashboard for exploring historical Lighthouse data and offers a great comparison UI for finding differences between builds.

To use Lighthouse CI Server, you must deploy it on your own infrastructure. Detailed instructions and recipes for deploying to Heroku and Docker can be found here.a GitHub.

Conclusion

When configuring your configuration, it's a good idea to include a few different URLs to ensure good test coverage. For a typical blog, you definitely want to include the homepage, one or two posts representative of the site's content type, and other important pages.

While we haven't covered the full scope of what the Lighthouse CI tool can do, I hope this article will not only help you get started using it, but also give you a good idea of ​​what else it can do. Thanks for reading and happy coding!