cypress-web-vitals

A web-vitals command for cypress.

Quantifying the quality of user experience on your site.

About

Web Vitals is a Google initiative which provides a set of quality signals and thresholds that are essential to delivering a great user experience on the web.

cypress-web-vitals allows you to test against these signals within your Cypress workflows through a new cy.vitals() custom command.

Getting started

Install the dependencies

In your terminal:

$ yarn add -D cypress-web-vitals cypress-real-events
# or
$ npm install --save-dev cypress-web-vitals cypress-real-events

Note: cypress-web-vitals currently makes use of cypress-real-events to click the page to calculate first input delay. Hence it is needed as a peer-dependency.

Add the commands

Add the following line to your cypress/support/commands.js:

import "cypress-web-vitals";

Write your tests

describe("web-vitals", () => {
  it("should pass the audits", () => {
    cy.vitals({ url: "https://www.google.com/" });
  });
});

Examples

Example Cypress test setups with a variety of tests using cypress-web-vitals for both Cypress 9.x and 10.x are available in the ./examples directory.

API

cy.vitals([WebVitalsConfig])

Performs and audit against the Google web-vitals.

cy.vitals();
cy.vitals(webVitalsConfig);

Example:

cy.vitals({ firstInputSelector: "main" }); // Use the `main` element of the page for clicking to capture the FID.
cy.vitals({ thresholds: { cls: 0.2 } }); // Test the page against against a CLS threshold of 0.2.

WebVitalsConfig:

• Optional firstInputSelector: string - The element to click for capturing FID. The first matching element is used. Default: "body".
• Optional onReport: Function - Callback for custom handling of the report results, e.g. for sending results to application monitoring platforms.
• Optional thresholds: WebVitalsThresholds - The thresholds to audit the web-vitals against. If not provided Google's 'Good' scores will be used (see below). If provided, any missing web-vitals signals will not be audited.
• Optional url: string - The url to audit. If not provided you will need to have called cy.visit(url) prior to the command.
• Optional headers: string - Additional headers that will be provided to cy.visit() if url is provided.
• Optional auth: string - Additional auth that will be provided to cy.visit() if url is provided.
• Optional vitalsReportedTimeout: number - Time in ms to wait for web-vitals to be reported before failing. Default: 10000.

WebVitalsThresholds:

• Optional lcp: number - Threshold for largest contentful paint (LCP).
• Optional fid: number - Threshold for first input delay (FID).
• Optional cls: number - Threshold for cumulative layout shift (CLS).
• Optional fcp: number - Threshold for first contentful paint (FCP).
• Optional ttfb: number - Threshold for time to first byte (TTFB).

Google 'Good' scores

{
  "lcp": 2500,
  "fid": 100,
  "cls": 0.1,
  "fcp": 1800,
  "ttfb": 600
}

Custom Reporting

It can be useful to have direct access to the raw data so you can generate custom reports, send to APM, etc.

This can be achieved through the optional onReport callback which receives the raw report before cypress-web-vitals passes or fails the test.

describe("web-vitals", () => {
  it("should log the report to APM", () => {
    cy.vitals({
      url: "https://www.google.com/",
      onReport({ thresholds, results }) {
        console.log(results); // { lcp: ..., fid: ..., }
      }
    });
  });
});

The report results contains values for all signals, not just the values specified in the provided or default thresholds. Signals that couldn't be obtained are reported as null.

How does it work?

1. The url is visited with the HTML response intercepted and modified by Cypress to include the web-vitals module script and some code to record the web-vitals values.
2. Several elements (if exist) starting with the provided element (based on firstInputSelector) are then clicked in quick succession to simulate a user clicking on the page. Note: if choosing a custom element, don't pick something that will navigate away from the page otherwise the plugin will fail to capture the web-vitals metrics.
3. The audit then waits for the page load event to allow for the values of LCP and CLS to settle; which are subject to change as different parts of the page load into view.
4. Next the audit simulates a page visibility state change which is required for the CLS web-vital to be reported.
5. The audit then attempts to wait for any outstanding web-vitals to be reported for which thresholds have been provided.
6. Finally the web-vitals values are compared against the thresholds, logging successful results and throwing an error for any unsuccessful signals. Note: if the audit was unable to record a web-vital then it is logged, but the test will not fail.

Contributing

Please check out the CONTRIBUTING docs.

Changelog

Please check out the CHANGELOG docs.

License

cypress-web-vitals is licensed under the MIT License.