Web performance testing using Lighthouse

Learn to measure and enhance the user experience of your web pages by seamlessly integrating Lighthouse into your Selenium tests.

Google Lighthouse runs a series of audits on your web pages and provides the results across following categories: performance, accessibility, best practices, SEO, and progressive web app (PWA). The generated report helps you measure the Web Vitals and provides insights on optimizing the quality of user experience of your web pages.

To get started with web performance testing using BrowserStack Automate, refer to our getting started page.
This feature is exclusive to the Automate Desktop and Mobile Pro plan. Visit our pricing page for more details.

You can either generate Lighthouse reports and add assertion on the metrics or generate the Lighthouse reports only:

Generate reports and add assertions
Generate reports only

The Lighthouse report generation and assertion is done through JavascriptExecutor. To enable Lighthouse JavascriptExecutor, set the following capability in your configuration file:

Copy

The Lighthouse integration supports generating reports for up to the first 10 web pages (URLs) opened during a test session.
Currently, Lighthouse report generation is supported on browsers Chrome and Edge 90 and above.
Supported operating system versions include Windows 10 and later and macOS Mojave and later.

Ligthouse JavascriptExecutor configuration

You can generate Lighthouse report and add assertions on the Lighthouse categories & metrics using JavascriptExecutor.

Let us look at some configurations of Ligthouse JavaScriptExecutor.

Generate Lighthouse report of URLs

To generate a Lighthouse report of a URL in the current test context through JavascriptExecutor, set the action parameter to lighthouseAudit. To run Lighthouse audit on a specific URL, mention the URL in the arguments object.

In the below example, the current URL in the browser context is picked up.

JavascriptExecutor jse = (JavascriptExecutor) driver;
jse.executeScript("browserstack_executor: {\"action\": \"lighthouseAudit\"}");

await driver.executeScript(
  `browserstack_executor: ${JSON.stringify({
    action: 'lighthouseAudit'
  })}`
);

executor_object = {
  'action': 'lighthouseAudit',
}
browserstack_executor = 'browserstack_executor: {}'.format(json.dumps(executor_object))
driver.execute_script(browserstack_executor)

In the below example, the specified URL is picked up:

JavascriptExecutor jse = (JavascriptExecutor) driver;
jse.executeScript("browserstack_executor: {\"action\": \"lighthouseAudit\", \"arguments\": {\"url\": \"https://bstackdemo.com/\"}}");

await driver.executeScript(
  `browserstack_executor: ${JSON.stringify({
    action: 'lighthouseAudit',
    arguments: {
      url: 'https://bstackdemo.com/'
    }
  })}`
);

executor_object = {
  'action': 'lighthouseAudit',
  'arguments': {
      'url': "https://www.bstackdemo.com"
  }
}
browserstack_executor = 'browserstack_executor: {}'.format(json.dumps(executor_object))
driver.execute_script(browserstack_executor)

Assert Lighthouse results

To assert the Lighthouse audit scores against a specified value, mention your assertion parameters in the assertResult object. In the below example, if the Lighthouse performance category score is below 40, the lighthouse assertion fails. The valid category values are performance, accessibility,best-practices,seo,pwa. The vaild threshold values for category scores are from 0 to 100.

In the metrics object, you can add assertions on the Ligthouse audit parameters. In the below example, the first-contentful-paint metric’s score value should be moreThan 50 to pass the assertion. Similarly, you can add assertions on the numeric value of the Ligthouse audits parameters. For instance, the largest-contentful-paint metric’s numeric value should be lessThan 4000 ms to pass the assertion.

JavascriptExecutor jse = (JavascriptExecutor) driver;
jse.executeScript("browserstack_executor: {\"action\":\"lighthouseAudit\",\"arguments\":{\"url\":\"https://bstackdemo.com/\",\"assertResult\":{\"categories\":{\"performance\":40,\"best-practices\":50},\"metrics\":{\"first-contentful-paint\":{\"moreThan\":50,\"metricUnit\":\"score\"},\"largest-contentful-paint\":{\"lessThan\":4000,\"metricUnit\":\"numeric\"},\"total-blocking-time\":{\"lessThan\":600,\"metricUnit\":\"numeric\"},\"cumulative-layout-shift\":{\"moreThan\":50,\"metricUnit\":\"score\"}}}}}");

await driver.executeScript(
  `browserstack_executor: ${JSON.stringify({
    action: 'lighthouseAudit',
    arguments: {
      url: 'https://bstackdemo.com/',
      assertResult: {
        categories: {
          performance: 40,
          'best-practices': 50
        },
        metrics: {
          'first-contentful-paint': {
            moreThan: 50,
            metricUnit: 'score'
          },
          'largest-contentful-paint': {
            lessThan: 4000,
            metricUnit: 'numeric'
          },
          'total-blocking-time': {
            lessThan: 600,
            metricUnit: 'numeric'
          },
          'cumulative-layout-shift': {
            moreThan: 50,
            metricUnit: 'score'
          }
        }
      }
    }
  })}`
);

executor_object = {
  "action": "lighthouseAudit",
  "arguments":{
        "url": "https://www.bstackdemo.com",
        "assertResult": { 
          "sessionFail": True,
          "categories": {
            "performance": 40,
            "best-practices": 50
          },
          "metrics": {
            "first-contentful-paint": {
                "moreThan": 50,
                "metricUnit": "score"             
            },
            "largest-contentful-paint": {
                "lessThan": 4000,
                "metricUnit": "numeric"              
            },
            "total-blocking-time": {
                "lessThan": 600,
                "metricUnit": "numeric"              
            },
            "cumulative-layout-shift": {
                "moreThan": 50,
                "metricUnit": "score"              
            } 
          } 
        }
      }
}
browserstack_executor = 'browserstack_executor: {}'.format(json.dumps(executor_object))
driver.execute_script(browserstack_executor)

Mark test session status as `failed`

Use the code below to mark test sessions as failed if any of the assertions in the assertResult object across any URLs fail:

avascriptExecutor jse = (JavascriptExecutor) driver;
jse.executeScript("browserstack_executor: {\"action\":\"lighthouseAudit\",\"arguments\":{\"url\":\"https://bstackdemo.com/\",\"assertResult\":{\"sessionFail\":true,\"categories\":{\"performance\":40},\"metrics\":{\"largest-contentful-paint\":{\"lessThan\":4000,\"metricUnit\":\"numeric\"}}}}}");

await driver.executeScript(
  `browserstack_executor: ${JSON.stringify({
    action: 'lighthouseAudit',
    arguments: {
      url: 'https://bstackdemo.com/',
      assertResult: {
        sessionFail: true,
        categories: {
          performance: 40
        },
        metrics: {
          'largest-contentful-paint': {
            lessThan: 4000,
            metricUnit: 'numeric'
          }
        }
      }
    }
  })}`
);

executor_object = {
  "action": "lighthouseAudit", 
  "arguments":{
    "url": "https://www.bstackdemo.com",
    "assertResult": { 
      "sessionFail": true,
      "categories": {
        "performance": 40
      }
    }
  }
}
browserstack_executor = 'browserstack_executor: {}'.format(json.dumps(executor_object))
driver.execute_script(browserstack_executor)

With SDK, use the following in your browserstack.yml file to prevent SDK from overriding the failed session status marked by ligthouse assertion:
testContextOptions:
skipSessionStatus: true
If the above configuration is not working, upgrade to the latest SDK version.

Access lighthouse JSON reports in the test script

Add the executorOutput parameter to get the generated Lighthouse report in the JavaScriptExecutor response in JSON format.

JavascriptExecutor jse = (JavascriptExecutor) driver;
jse.executeScript("browserstack_executor: {\"action\":\"lighthouseAudit\",\"arguments\":{\"url\":\"https://bstackdemo.com/\",\"executorOutput\":\"json\"}}");

await driver.executeScript(
  `browserstack_executor: ${JSON.stringify({
    action: 'lighthouseAudit',
    arguments: {
      url: 'https://bstackdemo.com/',
      executorOutput: 'json'
    }
  })}`
);

executor_object = {
  "action": "lighthouseAudit",
  "arguments":{
    "url": "https://www.bstackdemo.com",
    "executorOutput": "json"
  }
}
browserstack_executor = 'browserstack_executor: {}'.format(json.dumps(executor_object))
driver.execute_script(browserstack_executor)

If any of the above parameters are not passed, the default Lighthouse configuration will be effective. No validation is to be applied to your inputs.

The Ligthouse JavaScriptExecutor returns the assertion results in the response:

browserstack_executor_response: {
    "url": "https://www.browserstack.com",
    "categories": {
        "performance": "passed",
        "best-practices": "failed"
    }
    "metrics": {
        "first-contentful-paint": "passed",
        "largest-contentful-paint": "failed",
        "total-blocking-time": "passed",
        "cumulative-layout-shift": "failed"
    }
}

Description of assertion parameters in the JavascriptExecutor

Object	Mandatory/Optional	Description
categories	Optional	Allows you to add assertion on lighthouse categories’ score, available in the `categories` object in the result JSON - Lighthouse. Valid value(s) for the categories: `performance`, `accessibility`, `best-practices`, `seo`, `pwa`. Valid values for the categories’ score: `null`, integer from `0` to `100`, `50` (default).
metrics	Optional	Allows you to add assertions on lighthouse metrics present in the audits object of Ligthouse JSON report. Valid value(s) for the metrics are the parameters in the `audits` object in the Lighthouse report. `metrics` assertion parameters: a. Either `moreThan` or `lessThan` - allows you to provide the threshold value for assertion. Both parameters are of float type. b. `metricUnit` - allows user to specify the threshold value type. Valid values are: `score`, `numeric`. `score` compares with the `score` parameter and `numeric` compares with `numericValue` in the `audits` object of Lighthouse JSON report.

Set Lighthouse-specific configurations

You can emulate the device for lighthouse audit by passing various configurations that are specific to Lighthouse.

To configure Lighthouse, pass your configurations in the lhConfig object.

Here are some sample scenarios for using the Lighthouse-specific configurations:

Emulate the device for Lighthouse audit

The lhConfig object allows you to pass Lighthouse-specific configurations. By default the view is mobile view.

Lighthouse runs on Slow 4G network and MOTOG4 mobile screens.

Use the code below to emulate the desktop devices for the Lighthouse audit:

JavascriptExecutor jse = (JavascriptExecutor) driver;
jse.executeScript("browserstack_executor: {\"action\":\"lighthouseAudit\",\"arguments\":{\"url\":\"https://bstackdemo.com/\",\"lhConfig\":{\"extends\":\"lighthouse:default\",\"settings\":{\"formFactor\":\"desktop\",\"screenEmulation\":{\"mobile\":false,\"width\":1350,\"height\":940,\"deviceScaleFactor\":1,\"disabled\":false}}},\"assertResult\":{\"categories\":{\"performance\":40},\"metrics\":{\"largest-contentful-paint\":{\"lessThan\":4000,\"metricUnit\":\"numeric\"}}}}}");

await driver.executeScript(
  `browserstack_executor: ${JSON.stringify({
    action: 'lighthouseAudit',
    arguments: {
      url: 'https://bstackdemo.com/',
      lhConfig: {
        extends: 'lighthouse:default',
        settings: {
          formFactor: 'desktop',
          screenEmulation: {
            mobile: false,
            width: 1350,
            height: 940,
            deviceScaleFactor: 1,
            disabled: false
          }
        }
      },
      assertResult: {
        categories: {
          performance: 40
        },
        metrics: {
          'largest-contentful-paint': {
            lessThan: 4000,
            metricUnit: 'numeric'
          }
        }
      }
    }
  })}`
);

executor_object = {
  "action": "lighthouseAudit",
  "arguments":{
    "url": "https://www.bstackdemo.com",
    "lhConfig": {
      "extends": "lighthouse:default",
      "settings": {
        "formFactor": "desktop",
        "screenEmulation": {
          "mobile": False,
          "width": 1350,
          "height": 940,
          "deviceScaleFactor": 1,
          "disabled": False
        },
      },
    },
    "assertResult": { 
      "categories": {
        "performance": 40
      },
      "metrics": {
        "largest-contentful-paint": {
            "lessThan": 4000,
            "metricUnit": "numeric"              
        }
      } 
    }
  }
}
browserstack_executor = 'browserstack_executor: {}'.format(json.dumps(executor_object))
driver.execute_script(browserstack_executor)

Use the code below to emulate the mobile devices for the Lighthouse audit:

JavascriptExecutor jse = (JavascriptExecutor) driver;
jse.executeScript("browserstack_executor: {\"action\":\"lighthouseAudit\",\"arguments\":{\"url\":\"https://bstackdemo.com/\",\"lhConfig\":{\"extends\":\"lighthouse:default\",\"settings\":{\"formFactor\":\"mobile\",\"screenEmulation\":{\"mobile\":true,\"width\":412,\"height\":843,\"deviceScaleFactor\":1.75,\"disabled\":false}}},\"assertResult\":{\"categories\":{\"performance\":40},\"metrics\":{\"largest-contentful-paint\":{\"lessThan\":4000,\"metricUnit\":\"numeric\"}}}}}");

await driver.executeScript(
  `browserstack_executor: ${JSON.stringify({
    action: 'lighthouseAudit',
    arguments: {
      url: 'https://bstackdemo.com/',
      lhConfig: {
        extends: 'lighthouse:default',
        settings: {
          formFactor: 'mobile',
          screenEmulation: {
            mobile: true,
            width: 412,
            height: 843,
            deviceScaleFactor: 1.75,
            disabled: false
          }
        }
      },
      assertResult: {
        categories: {
          performance: 40
        },
        metrics: {
          'largest-contentful-paint': {
            lessThan: 4000,
            metricUnit: 'numeric'
          }
        }
      }
    }
  })}`
);

executor_object = {
  "action": "lighthouseAudit",
  "arguments":{
    "url": "https://www.google.com",
    "lhConfig": {
      "extends": "lighthouse:default",
      "settings": {
        "formFactor": "mobile",
        "screenEmulation":{
          "mobile": True,
          "width": 412,
          "height": 843,
          "deviceScaleFactor": 1.75,
          "disabled": True
        }
      }
    },
    "assertResult": { 
      "categories": {
        "performance": 40
      },
      "metrics": {
        "largest-contentful-paint": {
            "lessThan": 4000,
            "metricUnit": "numeric"              
        }
      } 
    }
  }
}
browserstack_executor = 'browserstack_executor: {}'.format(json.dumps(executor_object))
driver.execute_script(browserstack_executor)

Simulate the network connection for Lighthouse audit

Use the code below to simulate the network connection for predefined settings, using the mobileRegular3G, desktopDense4G, and mobileSlow4G settings.

{
    "action": "lighthouseAudit", 
    "arguments":{
      "throttling": "mobileRegular3G"
    }  
}

Use the code below to simulate the network connection by adding customised settings for the Lighthouse audit or disable the default network simulation by Lighthouse:

JavascriptExecutor jse = (JavascriptExecutor) driver;
jse.executeScript("browserstack_executor: {\"action\":\"lighthouseAudit\",\"arguments\":{\"url\":\"https://bstackdemo.com/\",\"lhConfig\":{\"extends\":\"lighthouse:default\",\"settings\":{\"throttling\":{\"rttMs\":150,\"throughputKbps\":1638.4,\"cpuSlowdownMultiplier\":4,\"requestLatencyMs\":562.5,\"downloadThroughputKbps\":1474.56,\"uploadThroughputKbps\":675}}},\"assertResult\":{\"categories\":{\"performance\":40},\"metrics\":{\"largest-contentful-paint\":{\"lessThan\":4000,\"metricUnit\":\"numeric\"}}}}}");

await driver.executeScript(
  `browserstack_executor: ${JSON.stringify({
    action: 'lighthouseAudit',
    arguments: {
      url: 'https://bstackdemo.com/',
      lhConfig: {
        extends: 'lighthouse:default',
        settings: {
          throttling: {
            rttMs: 150,
            throughputKbps: 1638.4,
            cpuSlowdownMultiplier: 4,
            requestLatencyMs: 562.5,
            downloadThroughputKbps: 1474.56,
            uploadThroughputKbps: 675
          }
        }
      },
      assertResult: {
        categories: {
          performance: 40
        },
        metrics: {
          'largest-contentful-paint': {
            lessThan: 4000,
            metricUnit: 'numeric'
          }
        }
      }
    }
  })}`
);

executor_object = {
  "action": "lighthouseAudit", 
  "arguments":{
    "url": "https://www.bstackdemo.com",
    "lhConfig":{
      extends: "lighthouse:default",
      settings: {
        "throttlingMethod": "simulate",      
        "throttling": {         
          "rttMs": 150,
          "throughputKbps": 1638.4,
          "requestLatencyMs": 562.5,
          "downloadThroughputKbps": 1474.5600000000002,
          "uploadThroughputKbps": 675,
          "cpuSlowdownMultiplier": 4
        }
      }
    },
    assertResult: {
      categories: {
        performance: 40
      },
      metrics: {
        'largest-contentful-paint': {
          lessThan: 4000,
          metricUnit: 'numeric'
        }
      }
    }
  }
}  
browserstack_executor = 'browserstack_executor: {}'.format(json.dumps(executor_object))
driver.execute_script(browserstack_executor)

Click here for the description of the Lighthouse parameters.

View reports on the Automate dashboard

On your Automate dashboard, select the Web Performance tab to view the report generated by Lighthouse.

You can view the assertion results and the config parameters passed under the Text Logs tab. You can view the report by clicking the View Report link.

Text Logs

Lighthouse Performance results

To view all the reports of the web performance in one place, select the Web Performance tab.

Lighthouse report

Generate Lighthouse reports

To generate a Lighthouse report for the open URLs in a session, set the following capabilities in your test script or configuration file:

For a Lighthouse report to generate, a test session must be at least 30-60 seconds long. If your test is likely to take less time, consider introducing the required amount of artificial delay.
To successfully generate Lighthouse report for more than one URL, ensure 30 to 60 seconds processing time after each opened URL.

Copy

The Lighthouse integration supports generating reports for up to the first 10 web pages (URLs) opened during a test session.
Currently, Lighthouse report generation is supported on browsers Chrome 85 and above and Edge 85 and above.
Supported operating system versions include Windows 10 and later and macOS Mojave and later.

Important points to remember:

The setting is false by default. You can see the Web Performance tab on the Automate dashboard only when you set the capability to true.
If a pop-up appears on the web page of your website under test when Lighthouse launches, the report does not get generated.
If you incorporate two consecutive open URLs in your code, the system generates a report solely for the first open URL session. To acquire a report for subsequent open URLs, ensure you utilize the wait command for 30 seconds after each open URL.
The web performance feature is currently available for desktop browsers only.

View reports on the Automate dashboard

On your Automate dashboard, select the Web Performance tab to view the report generated by Lighthouse.

Lighthouse report

Did this page help you?

We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked

This page has exactly what I am looking for
This content & code samples are accurate and up-to-date
The content on this page is easy to understand
Other (please tell us more below)

Any additional feedback?

Thank you for your valuable feedback

Is this page helping you?

Yes

We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked

This page has exactly what I am looking for
This content & code samples are accurate and up-to-date
The content on this page is easy to understand
Other (please tell us more below)

Any additional feedback?

Thank you for your valuable feedback!