Cypress Performance Plugin "cypress-performance": A Guide to automate the Web Performance Testing

Introduction

The idea to create this plugin came to my mind when I was struggling to measure the web UI performance and the existing plugins were not providing me with the flexibility I needed. The "cypress-performance" plugin introduces a powerful way to measure and assert web performance metrics directly in your Cypress tests. Unlike traditional end-to-end testing that focuses on functionality, this plugin enables teams to catch performance regressions early and maintain high-performance standards through automated testing.

Web performance testing has become crucial today. Users expect lightning-fast experiences, and slow-loading pages can significantly impact business metrics. While Cypress is an excellent tool for end-to-end testing, it lacks built-in performance measurement capabilities.

Today, I'm excited to introduce "cypress-performance", a new plugin that brings performance measurement capabilities to your Cypress tests.

You can check it out here:

https://www.npmjs.com/package/cypress-performance https://github.com/Valiantsin2021/cypress-performance

Key Features

• Real-time performance metrics collection during test execution
• Built-in retry mechanisms for reliable measurements
• Support for Core Web Vitals and other key performance indicators
• Seamless integration with existing Cypress tests
• Type definitions for TypeScript support
• Configurable thresholds and timing options

Why Another Performance Testing Plugin?

You might be wondering, "Don't we already have "@cypress-audit/lighthouse"?" Yes, we do, and it's an excellent tool. However, "cypress-performance" takes a different approach:

• Real User Metrics: While Lighthouse simulates performance under specific conditions, cypress-performance captures metrics during actual test execution, giving you insights into real user scenarios.
• Test Integration: The plugin seamlessly integrates with your existing tests, allowing you to measure performance while executing your regular test flows, not as a separate audit.
• Granular Control: You get fine-grained control over when and how to measure performance, with built-in retry mechanisms for reliable results.
• Core Web Vitals: Focus on modern performance metrics that matter, including Largest Contentful Paint (LCP), First Input Delay (FID), and Cumulative Layout Shift (CLS).
• Lower overhead - no need for separate Lighthouse runs
• Less configuration - minimal setup required for basic usage
• Specific metrics focus - Core Web Vitals and key timings
• Test integration - natural fit in existing test flows the command is chainable and returns all collected metrics to be asserted
• Retry capability - built-in reliability mechanisms to ensure the metrics are collected
• Resource timing - detailed resource-level metrics
• Total bytes - size of all resources

On the other side - @cypress-audit/lighthouse provides us with

• Comprehensive audits including SEO, accessibility
• Scoring system aligned with Lighthouse
• Static analysis of best practices
• Recommendations for improvements
• Performance simulation under various conditions
• Broader metrics beyond just performance

So what is it and how to use it?

This is a standalone Cypress plugin with 0 external dependencies.

First, install the plugin:

npm install -D cypress-performance        

Add to your cypress/support/e2e.js:

import 'cypress-performance'        

For TypeScript users, include types in tsconfig.json:

{
  "compilerOptions": {
    "types": ["cypress", "cypress-performance"]
  }
}        

Now you're ready to start measuring performance!

Usage

The plugin exposes the single Cypress method:

cy.performance()        

The cy.performance() command itself is retriable, meaning Cypress will retry the command until it either:

• Gets valid metrics
• Reaches the retryTimeout

Default options for the command:

    MetricsOptions{
      startMark?: keyof PerformanceTiming // Default: 'navigationStart'
      endMark?: keyof PerformanceTiming // Default: 'loadEventEnd'
      timeout?: number // Timeout in milliseconds (default: 10000)
      initialDelay?: number // Initial delay in milliseconds (default: 1000)
      retryTimeout?: number // Retry timeout in milliseconds (default: 5000)
    }        

A typical test will look like this:

And her like it will look in the Cypress test runner:

Best Practices

1. Set Realistic Thresholds Consider your users and application when setting performance thresholds: LCP: < 2.5s (good), < 4s (needs improvement) CLS: < 0.1 (good), < 0.25 (needs improvement) TBT: < 300ms (good), < 600ms (needs improvement)
2. Use Custom Marks For single-page applications or complex user flows, use custom performance marks to measure specific interactions.
3. Consider Environment Variations Remember that CI environments might perform differently than local development. Adjust thresholds accordingly or use relative comparisons.

Combine with Other Metrics Use cypress-performance alongside other tools like Lighthouse for a complete performance picture

Conclusion

My "cypress-performance" plugin serves for quick valuable and most important web performance metrics collection and brings performance testing capabilities to your Cypress test suite. By focusing on real user metrics and providing fine-grained control, it helps ensure your application performs well under actual use conditions.

Whether you're monitoring Core Web Vitals, measuring specific user interactions, or ensuring smooth resource loading, "cypress-performance" provides the tools you need to catch performance regressions before they reach production.

The good performance is not just about speed—it's about consistency and reliability. With "cypress-performance", you can ensure your application maintains high-performance standards throughout its development lifecycle.

Give it a try in your project, and let me know how it works for you! The plugin is open source, and I welcome all contributions and feedback.