cypress-web-vitals

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
}

Contributing

Please check out the CONTRIBUTING docs.

Changelog

Please check out the CHANGELOG docs.

---

License

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