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

An example Cypress test setup with a variety of tests using cypress-web-vitals is 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 url: string - The url to audit. If not provided you will need to have called cy.visit(url) prior to the command.
• Optional firstInputSelector: string - The element to click for capturing FID. Default: "body".
• 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.

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
}

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. The body or provided element (based on firstInputSelector) is then clicked several times 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.