{"id":15760,"library":"playwright-performance","title":"Playwright Performance Testing Plugin","description":"playwright-performance is a plugin for Playwright that enables detailed performance analysis of end-to-end test flows, including UI, API, or hybrid scenarios. It measures the 'apparent response time' of key user procedures within your application, helping identify bottlenecks and areas for optimization. The current stable version is 2.0.6, with recent updates introducing HTML chart generation. The library maintains an active release cadence, with a major breaking change in version 2.x.x simplifying its integration model. Its key differentiator is the seamless integration into Playwright's `test.extend` fixture system, allowing developers to easily add performance sampling to existing tests without significant refactoring, and providing configurable output options for results.","status":"active","version":"2.0.6","language":"javascript","source_language":"en","source_url":"https://github.com/tzurp/playwright-performance","tags":["javascript","playwright-plugin","performance","typescript"],"install":[{"cmd":"npm install playwright-performance","lang":"bash","label":"npm"},{"cmd":"yarn add playwright-performance","lang":"bash","label":"yarn"},{"cmd":"pnpm add playwright-performance","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This package is a plugin that extends Playwright's test runner functionality; it is a peer dependency.","package":"@playwright/test","optional":false}],"imports":[{"note":"This is the default export used to extend the Playwright 'test' object. CommonJS 'require()' is not supported since v2.","wrong":"const extendPlaywrightPerformance = require('playwright-performance');","symbol":"extendPlaywrightPerformance","correct":"import extendPlaywrightPerformance from 'playwright-performance';"},{"note":"This type defines the 'performance' fixture added to your extended Playwright test context. It's generally imported as a type.","wrong":"const PlaywrightPerformance = require('playwright-performance').PlaywrightPerformance;","symbol":"PlaywrightPerformance","correct":"import type { PlaywrightPerformance } from 'playwright-performance';"},{"note":"This type defines the configuration options for the performance plugin. It's primarily used for type hints when setting up options.","symbol":"PerformanceOptions","correct":"import type { PerformanceOptions } from 'playwright-performance';"}],"quickstart":{"code":"import { test as base, expect } from '@playwright/test';\nimport extendPlaywrightPerformance, { PerformanceOptions, PlaywrightPerformance } from 'playwright-performance';\n\n// Extend the Playwright test object with performance fixtures\nconst test = base.extend<PlaywrightPerformance, PerformanceOptions>(extendPlaywrightPerformance());\n\ntest.describe('Website Startup Performance', () => {\n  test('should load GitHub and SourceForge within acceptable limits', async ({ page, performance }) => {\n    // Sample startup time for GitHub\n    performance.sampleStart('GH-startup');\n    await page.goto('https://github.com/', { waitUntil: 'domcontentloaded' });\n    performance.sampleEnd('GH-startup');\n\n    // Sample startup time for SourceForge\n    performance.sampleStart('SF-startup');\n    await page.goto('https://sourceforge.net/', { waitUntil: 'domcontentloaded' });\n    performance.sampleEnd('SF-startup');\n\n    // You can also get individual sample times within the test\n    const githubStartupTime = performance.getSampleTime('GH-startup');\n    const sourceForgeStartupTime = performance.getSampleTime('SF-startup');\n\n    // Assertions for performance metrics\n    expect(githubStartupTime).toBeLessThanOrEqual(5000); // Expect GitHub to load in under 5 seconds\n    expect(sourceForgeStartupTime).toBeLessThanOrEqual(8000); // Expect SourceForge to load in under 8 seconds\n\n    console.log(`GitHub Startup Time: ${githubStartupTime}ms`);\n    console.log(`SourceForge Startup Time: ${sourceForgeStartupTime}ms`);\n  });\n});","lang":"typescript","description":"Demonstrates how to extend Playwright's `test` object with performance fixtures, record startup times for multiple URLs, and assert on individual sample durations within an extended test."},"warnings":[{"fix":"Migrate to the new ESM-first import syntax (`import extendPlaywrightPerformance, { ... } from 'playwright-performance'`) and update your `test.extend` call as shown in the updated usage documentation for v2.x.x.","message":"Version 2.x.x introduced significant breaking changes, particularly in how the plugin is imported and used to extend the Playwright `test` object. Existing `require()` statements and older `test.extend` patterns will no longer work.","severity":"breaking","affected_versions":">=2.0.2"},{"fix":"Ensure your project is configured for ESM, and update all imports to use `import` statements. If you strictly require CommonJS, consider using an older version (pre-2.x.x) or transpiling your code.","message":"Starting with version 2.x.x, `playwright-performance` is primarily an ESM module. CommonJS `require()` syntax is no longer supported for importing the plugin.","severity":"breaking","affected_versions":">=2.0.2"},{"fix":"Always define your extended `test` object in a separate, reusable 'test-base' file (e.g., `tests/fixtures/performance-test.ts`) and import it into your individual test files. This ensures consistent fixture application and better maintainability.","message":"Defining the extended `test` object (`const test = base.extend<...>(...)`) directly within each test file can lead to unnecessary setup overhead, redundant code, and potential inconsistencies across tests.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Utilize the `performanceResultsDirectoryName` and `performanceResultsFileName` options within `PerformanceOptions` to specify unique output paths for different test runs or scenarios, preventing data loss.","message":"By default, performance results are saved to `performance-results/performance-results.json`. Running multiple test suites or different performance scenarios without configuring unique filenames or directories will overwrite previous results.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure you are using `import { test as base } from '@playwright/test';` and that your Playwright dependency is up-to-date and compatible with 'playwright-performance' v2.x.x.","cause":"This typically occurs if Playwright's 'test' object is not imported correctly, or if an older version of Playwright is used that doesn't support the 'test.extend' pattern with the plugin's structure.","error":"TypeError: playwright_1.test.extend is not a function"},{"fix":"Run `npm install playwright-performance --save-dev`. Verify your `tsconfig.json` includes `playwright-performance` in `types` or `typeRoots`, and ensure your environment supports ESM imports correctly, especially for Node.js projects.","cause":"The package might not be installed, the import path is incorrect, or your project's TypeScript/module resolution configuration does not properly resolve the package or its types.","error":"Error: Cannot find module 'playwright-performance' or its corresponding type declarations."},{"fix":"Ensure your test file imports and uses the 'test' object that has been extended by `playwright-performance` (e.g., `import { test } from '../path/to/my-extended-test-base';`) and that 'performance' is destructured in your test function signature: `async ({ page, performance }) => { ... }`.","cause":"The 'performance' fixture was not correctly added to your Playwright test context, meaning the 'test' object you are importing or using in your test file is not the extended one.","error":"Property 'performance' does not exist on type 'TestFixture<{ page: Page; ... }>'"}],"ecosystem":"npm"}