Performance monitoring with Lighthouse CI

How to add Lighthouse to a continuous integration system, like GitHub Actions.

July 27, 2020

It appears in:
Fast loading times

CI headlight is a set of tools to use Lighthouse during continuous integration. Lighthouse CI can be incorporated into developer workflows in many different ways. This guide covers the following topics:

• Using the Lighthouse CI CLI.
• Configuring your CI provider to run Lighthouse CI.
• Set up a GitHub action and
  status check
  for Lighthouse CI. This will automatically show Lighthouse results in GitHub pull requests.
• Create a performance dashboard and data warehouse for Lighthouse reports.

Overview

Lighthouse CI is a set of free tools that make it easy to use Lighthouse for performance monitoring. A single Lighthouse report provides a snapshot of the performance of a web page as it runs; Lighthouse CI shows how these findings have changed over time. This can be used to identify the impact of particular code changes or to ensure that performance thresholds are met during continuous integration processes. Although performance monitoring is the most common use case for Lighthouse CI, it can be used to monitor other aspects of the Lighthouse report, for example SEO or accessibility.

The primary functionality of Lighthouse CI is provided by the Lighthouse CI command line interface. (Note: this is a separate tool from the Lighthouse CLI.) The Lighthouse CI CLI provides a set of
commands
to use Lighthouse CI. For example, him autorun The command runs multiple Lighthouse runs, identifies the Medium Lighthouse report, and loads the report for storage. This behavior can be highly customized by passing additional flags or by customizing the Lighthouse CI configuration file, lighthouserc.js.

Although the core functionality of Lighthouse CI is primarily encapsulated in the Lighthouse CI CLI, Lighthouse CI is typically used through one of the following approaches:

• Running Lighthouse CI as part of continuous integration
• Using a Lighthouse CI GitHub action that runs and comments on every pull request
• Track performance over time through the dashboard provided by Lighthouse Server.

All of these approaches are based on the Lighthouse CI CLI.

Alternatives to Lighthouse CI include third-party performance monitoring services or writing your own script to collect performance data during the CI process. You should consider using a third-party service if you prefer to let someone else take care of managing your performance monitoring server and test devices, or if you want notification capabilities (such as email or Slack integration) without having to create them. features yourself.

Use Lighthouse CI locally

This section explains how to run and install the Lighthouse CI CLI locally and how to configure lighthouserc.js. Running the Lighthouse CI CLI locally is the easiest way to ensure that your lighthouserc.js is configured correctly.

1. Install the Lighthouse CI CLI.

   npm install -g @ lhci / cli

   Lighthouse CI is configured by placing a lighthouserc.js file in the root of your project repository. This file is required and will contain configuration information related to Lighthouse CI. Although Lighthouse CI can configured to be used without a git repository, the instructions in this article assume that your project repository is configured to use git.

2. In the root of your repository, create a lighthouserc.js configuration file.

   touch lighthouserc.js

3. Add the following code to lighthouserc.js. This code is an empty Lighthouse CI configuration. You will add to this configuration in later steps.

   module . exports = {
    ci : {
    collect : {
    } ,
    upload : {
    } ,
    } ,
    } ;

4. Every time Lighthouse CI runs, it starts a server to serve your site. This server is what allows Lighthouse to load your site even when there are no other servers running. When Lighthouse CI finishes running, it will automatically shut down the server. To make sure the publication works correctly, you must configure the
   staticDistDir

   or
   startServerCommand

   properties.

   If your site is static, add the staticDistDir property to ci.collect
   object to indicate where your static files are located. Lighthouse CI will use its own server to serve these files while you test your site. If your site is not static, add the startServerCommand property to
   ci.collect object to indicate the command that starts your server. Lighthouse CI will start a new server process during the test and shut it down afterwards.

   
   collect : {
    staticDistDir : './public' ,
    }

   
   collect : {
    startServerCommand : 'npm run start' ,
    }

5. Add the
   url

   property to ci.collect object to indicate URL (s) where Lighthouse CI should run Lighthouse. The value of the url the property must be provided as a URL array; this array can contain one or more URLs. By default, Lighthouse CI will run Lighthouse three times on each URL.

   collect : {
    url : [ 'http: // localhost: 8080' ]
    }

   Note: The server you configured in the previous step should be able to publish these URLs. So if you are running Lighthouse CI locally these URLs should probably include localhost instead of your production host.

6. Add the
   target

   property to ci.upload object and set the value to
   'temporary-public-storage'. The Lighthouse reports collected by Lighthouese CI will be uploaded to temporary public storage. The report will stay there for seven days and then it will be automatically deleted. This configuration guide uses the "temporary public storage" upload option because it is quick to configure. For information on other ways to store Lighthouse reports, see the
   documentation.

   upload : {
    target : 'temporary-public-storage' ,
    }

   The report storage location will look like this:

   https://storage.googleapis.com/lighthouse-infrastructure.appspot.com/reports/1580152437799-46441.report.html

   (This URL will not work because the report has already been removed.)

7. Run the Lighthouse CI CLI from the terminal using the autorun command. This will run Lighthouse three times and load the Medium Lighthouse report.

   lhci autorun

   If you have successfully configured Lighthouse CI, running this command should produce output similar to this:

   ✅ .lighthouseci / directory writable
    ✅ Configuration file found
    ✅ Chrome installation found
    ⚠️ GitHub token not set
    Healthcheck passed !
    Started a web server on port 65324 ...
    Running Lighthouse 3 time ( s ) on http: // localhost: 65324 / index.html
    Run
    Run
    Run
    Donate running Lighthouse !
    Uploading via LHR of http: // localhost: 65324 / index.html .. .success !
    Open the report at https://storage.googleapis.com/lighthouse-infrastructure.appspot.com/reports/1591720514021-82403.report.html
    No GitHub token set, skipping GitHub status check.
    Donate running autorun.

   You can ignore the GitHub token not set message in the console output. A GitHub token is only required if you want to use Lighthouse CI with a GitHub action. How to configure a GitHub action is explained later in this article.

   By clicking the link in the output that begins with
   https: //storage.googleapis.com ... will take you to the Lighthouse report for Lighthouse's medium run.

   The default values used by autorun can be overridden via command line or
   lighthouserc.js. For example, him lighthouserc.js The following configuration indicates that five Lighthouse executions should be collected at a time autorun
   run.

8. To update lighthouserc.js use the numberOfRuns property:

   module . exports = {
    collect : {
    numberOfRuns : 5
    } ,
    } ,
    } ;

9. Run the autorun command:

   lhci autorun

   The terminal output should show that Lighthouse has been run five times instead of the default three:

   ✅ .lighthouseci / directory writable
    ✅ Configuration file found
    ✅ Chrome installation found
    ⚠️ GitHub token not set
    Healthcheck passed !
    Automatically Determined ./dist as `` staticDistDir.
    Set it explicitly in lighthouserc.json if incorrect.
    Started a web server on port 64444 ...
    Running Lighthouse 5 time ( s ) on http: // localhost: 64444 / index.html
    Run
    Run
    Run
    Run
    Run
    Donate running Lighthouse !
    Uploading via LHR of http: // localhost: 64444 / index.html .. .success !
    Open the report at https://storage.googleapis.com/lighthouse-infrastructure.appspot.com/reports/1591716944028-6048.report.html
    No GitHub token set, skipping GitHub status check.
    Donate running autorun.

   For other configuration options, see Lighthouse CI
   setup documentation.

Configure your CI process to run Lighthouse CI

Lighthouse CI can be used with your favorite CI tool. the Configure your CI provider
The Lighthouse CI documentation section contains code samples showing how to incorporate Lighthouse CI into common CI tools configuration files. Specifically, these code samples show how to run Lighthouse CI to collect performance metrics during the CI process.

Using Lighthouse CI to collect performance metrics is a good place to start with performance monitoring. However, advanced users may want to go one step further and use Lighthouse CI to fail builds if they don't meet predefined criteria, such as passing specific Lighthouse audits or meeting all performance budgets. This behavior is configured through the
assert

property of the lighthouserc.js proceedings.

Lighthouse CI supports three levels of assertions:

• off: ignore assertions
• warn: print faults in stderr
• error- Print faults to stderr and exit Lighthouse CI with a non-zero value
  exit code

Below is an example of lighthouserc.js configuration that includes assertions. Set claims for Lighthouse performance and accessibility category scores. To test this, add the affirmations shown below to your lighthouserc.js and then run Lighthouse CI again.

module . exports = {
 ci : {
 collect : {
 } ,
 assert : {
 assertions : {
 'categories: performance' : [ 'warn' , { minScore : 1 } ] ,
 'categories: accessibility' : [ 'error' , { minScore : 1 } ]
 }
 } ,
 upload : {
 } ,
 } ,
 } ;

The console output it generates looks like this:

For more information on the claims of Lighthouse CI, see the
documentation.

Configure a GitHub Action to Run Lighthouse CI

A GitHub action can be used to run Lighthouse CI. This will generate a new Lighthouse report every time a code change is pushed to any branch in a GitHub repository. Use this in conjunction with a status check
to display these results on every pull request.

1. At the root of your repository, create a directory called
   .github / workflows. the
   workflows
   for your project it will go in this directory. A workflow is a process that runs at a predetermined time (for example, when code is submitted) and is made up of one or more actions.

   mkdir .github
    mkdir .github / workflows

2. In .github / workflows create a file called lighthouse-ci.yaml. This file will contain the settings for a new workflow.

   touch lighthouse-ci.yaml

3. Add the following text to lighthouse-ci.yaml.

   name : Build project and run Lighthouse CI
    on : [ push ]
    jobs :
    lhci :
    name : Lighthouse CI
    runs-on : ubuntu - latest
    steps :
    - uses : actions / checkout @ v1
    - name : Use Node.js 10.x
    uses : actions / setup - node @ v1
    with :
    node-version : 10.x
    - name : npm install
    run : | 
   npm install
    - name : run Lighthouse CI
    run : | 
   npm install -g @ lhci / cli @ 0.3.x
    lhci autorun --upload.target = temporary-public-storage || echo "LHCI failed!"

   This configuration establishes a workflow consisting of a single job that will run each time new code is submitted to the repository. This job has four steps:

   • Check the repository where Lighthouse CI will run
   • Install and configure Node
   • Install the required npm packages
   • Run Lighthouse CI and upload the results to temporary public storage.

4. Commit these changes and submit them to GitHub. If you have followed the steps above correctly, submitting code to GitHub will trigger the execution of the workflow you just added.

5. To confirm that Lighthouse CI has been activated and view the report it generated, go to Behavior tab of your project. You should see the
   Build project and run Lighthouse CI workflow listed in your most recent commit.

   
   

   You can navigate to the Lighthouse report for a particular commit from the Behavior tongue. Click the commitment, click the CI headlight
   step of the workflow, then expand the results of the run Lighthouse CI He passed.

   
   

   You have just configured a GitHub action to run Lighthouse CI. This will be most useful when used in conjunction with a GitHub status check.

Set up a GitHub health check

A health check, if configured, is a message that appears on every RP and typically includes information such as the results of a test or the success of a build.

The following steps explain how to configure a health check for Lighthouse CI.

1. Go to the Lighthouse CI GitHub App Page and click Set up.

2. (Optional) If you are part of multiple organizations on GitHub, choose the organization that owns the repository for which you want to use Lighthouse CI.

3. Please select All repositories if you want to enable Lighthouse CI in all repositories or select Select only repositories if you only want to use it on specific repositories, and then select the repositories. Then click
   Install and authorize.

4. Copy the token that is displayed. You will use it in the next step.

5. To add the token, navigate to Configurations page of your GitHub repository, click Mysteries, then click Add a new secret.

   
   

6. Select the Name field to LHCI_GITHUB_APP_TOKEN and configure the Value
   field to the token you copied in the last step and then click the Add secret button.

7. The health check is ready to use. To prove it, create a new pull request
   or send a confirmation to an existing pull request.

Configure the Lighthouse CI Server

The Lighthouse CI server provides a dashboard to explore the Lighthouse historical reports. It can also act as a long-term private data warehouse for Lighthouse reports.

1. Choose which commitments to compare.
2. The amount that Lighthouse's score changed between the two commits.
3. This section only shows the metrics that have changed between the two commits.
4. Regressions are highlighted in pink.
5. Improvements are highlighted in blue.

Lighthouse CI Server is best suited for users who are comfortable implementing and managing their own infrastructure.

For information on how to configure the Lighthouse CI server, including recipes for using Heroku and Docker for deployment, see these
instructions.

Know more