Playwright Performance Testing Plugin

Common errors

• TypeError: playwright_1.test.extend is not a function

  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.
  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.

• Error: Cannot find module 'playwright-performance' or its corresponding type declarations.

  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.
  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.

• Property 'performance' does not exist on type 'TestFixture<{ page: Page; ... }>'

  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.
  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 }) => { ... }`.

Warnings

• breaking 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.
  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.
• breaking Starting with version 2.x.x, `playwright-performance` is primarily an ESM module. CommonJS `require()` syntax is no longer supported for importing the plugin.
  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.
• gotcha 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.
  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.
• gotcha 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.
  Fix: Utilize the `performanceResultsDirectoryName` and `performanceResultsFileName` options within `PerformanceOptions` to specify unique output paths for different test runs or scenarios, preventing data loss.

Install

• npm install playwright-performance npm
• yarn add playwright-performance yarn
• pnpm add playwright-performance pnpm

Imports

• extendPlaywrightPerformance
  wrong:

  const extendPlaywrightPerformance = require('playwright-performance');

  correct:

  import extendPlaywrightPerformance from 'playwright-performance';

  This is the default export used to extend the Playwright 'test' object. CommonJS 'require()' is not supported since v2.
• PlaywrightPerformance
  wrong:

  const PlaywrightPerformance = require('playwright-performance').PlaywrightPerformance;

  correct:

  import type { PlaywrightPerformance } from 'playwright-performance';

  This type defines the 'performance' fixture added to your extended Playwright test context. It's generally imported as a type.
• PerformanceOptions

  import type { PerformanceOptions } from 'playwright-performance';

  This type defines the configuration options for the performance plugin. It's primarily used for type hints when setting up options.

Quickstart

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.

import { test as base, expect } from '@playwright/test';
import extendPlaywrightPerformance, { PerformanceOptions, PlaywrightPerformance } from 'playwright-performance';

// Extend the Playwright test object with performance fixtures
const test = base.extend<PlaywrightPerformance, PerformanceOptions>(extendPlaywrightPerformance());

test.describe('Website Startup Performance', () => {
  test('should load GitHub and SourceForge within acceptable limits', async ({ page, performance }) => {
    // Sample startup time for GitHub
    performance.sampleStart('GH-startup');
    await page.goto('https://github.com/', { waitUntil: 'domcontentloaded' });
    performance.sampleEnd('GH-startup');

    // Sample startup time for SourceForge
    performance.sampleStart('SF-startup');
    await page.goto('https://sourceforge.net/', { waitUntil: 'domcontentloaded' });
    performance.sampleEnd('SF-startup');

    // You can also get individual sample times within the test
    const githubStartupTime = performance.getSampleTime('GH-startup');
    const sourceForgeStartupTime = performance.getSampleTime('SF-startup');

    // Assertions for performance metrics
    expect(githubStartupTime).toBeLessThanOrEqual(5000); // Expect GitHub to load in under 5 seconds
    expect(sourceForgeStartupTime).toBeLessThanOrEqual(8000); // Expect SourceForge to load in under 8 seconds

    console.log(`GitHub Startup Time: ${githubStartupTime}ms`);
    console.log(`SourceForge Startup Time: ${sourceForgeStartupTime}ms`);
  });
});