feat: refactor waiting for page to load and update readme

Author: Valiantsin2021

Readme.md

@@ -12,14 +12,13 @@
    <a href="https://github.com/Valiantsin2021/playwright-performance-metrics"><img src="https://img.shields.io/badge/Author-Valentin%20Lutchanka-blue" alt="playwright-performance-metrics author" /></a>
    <a href="https://github.com/Valiantsin2021/playwright-performance-metrics/actions/workflows/ci.yml"><img src="https://github.com/Valiantsin2021/playwright-performance-metrics/actions/workflows/ci.yml/badge.svg?branch=main" alt="playwright-performance-metrics ci tests" /></a>
 </p>
+<h3 align="center">A comprehensive performance metrics collector for Playwright tests. Collect and analyze web vital metrics, network timing, and resource usage in your Playwright tests.</h3>
+<img src="img\performance-UI.png" alt="Performance-UI" />
 
----
-
-A comprehensive performance metrics collector for Playwright tests. Collect and analyze web vital metrics, network timing, and resource usage in your Playwright tests.
 
 ## Features
 
-- Collect Web Vitals (LCP, FID, CLS)
+- Collect Web Vitals (LCP, CLS)
 - Network timing metrics (TTFB, resource timing)
 - Network condition emulation (3G, 4G, WiFi)
 - Resource usage tracking
@@ -117,7 +116,9 @@ npm install -D playwright-performance-metrics
 
 ## Usage
 
-Basic usage:
+**Basic usage:**
+
+* Note: it is important to wait the completion of the page load before collecting metrics.
 
 ```typescript
 import { test } from '@playwright/test';
@@ -126,8 +127,7 @@ import { PerformanceMetricsCollector } from 'playwright-performance-metrics';
 test('measure page performance', async ({ page }) => {
   const collector = new PerformanceMetricsCollector(page);
 
-  await page.goto('https://example.com');
-  
+  await page.goto('https://example.com', { waitUntil: 'networkidle' })
   const metrics = await collector.collectMetrics({
     timeout: 10000,
     initialDelay: 1000
@@ -139,17 +139,37 @@ test('measure page performance', async ({ page }) => {
     'Largest Contentful Paint': metrics.largestContentfulPaint,
     'Cumulative Layout Shift': metrics.cumulativeLayoutShift
   });
+  expect(metrics.pageloadTiming, 'Page load time is less than 2000ms').toBeLessThan(2000)
+  expect(metrics.domCompleteTiming, 'DOM Complete is less than 900ms').toBeLessThan(900)
+  expect(metrics.paint?.firstContentfulPaint, 'First Contentful Paint is less than 2000ms').toBeLessThan(2000)
+  expect(metrics.paint?.firstPaint, 'First Paint is less than 1000ms').toBeLessThan(1000)
+  expect(metrics.largestContentfulPaint, 'Largest Contentful Paint is less than 2500ms').toBeLessThan(2500)
+  expect(metrics.cumulativeLayoutShift, 'Cumulative Layout Shift is less than 0.1').toBeLessThan(0.1)
+  expect(metrics.totalBlockingTime, 'Total Blocking Time is less than 500ms').toBeLessThan(500)
+  expect(metrics.totalBytes, 'Total bytes is less than 1.5 MB').toBeLessThan(1024 * 1024 * 1.5)
+  expect(metrics.timeToFirstByte?.total, 'Time to first byte is less than 900ms').toBeLessThan(900)
+  expect(metrics.timeToFirstByte.dns, 'DNS time is less than 100ms').toBeLessThan(100)
+  expect(metrics.timeToFirstByte.wait, 'Wait time is less than 100ms').toBeLessThan(100)
+  expect(metrics.timeToFirstByte.redirect, 'Redirect time is less than 100ms').toBeLessThan(100)
+  expect(metrics.timeToFirstByte.tls, 'TLS time is less than 100ms').toBeLessThan(100)
+  expect(metrics.timeToFirstByte.connection, 'Connection time is less than 100ms').toBeLessThan(100)
 });
 ```
 
-With network emulation:
+**With network emulation:**
+
+Library provides predefined presets for network conditions.
+
+- REGULAR_4G
+- SLOW_3G
+- FAST_WIFI
 
 ```typescript
 import { DefaultNetworkPresets } from 'playwright-performance-metrics';
 
 test('measure performance with slow 3G', async ({ page }) => {
   const collector = new PerformanceMetricsCollector(page);
-  
+  await page.goto('https://example.com', { waitUntil: 'networkidle' })
   const metrics = await collector.collectMetrics({
     networkConditions: DefaultNetworkPresets.SLOW_3G,
     timeout: 30000
@@ -159,6 +179,34 @@ test('measure performance with slow 3G', async ({ page }) => {
 });
 ```
 
+**With fixtures:**
+
+```typescript
+// fixture.ts
+
+import { test as base, expect } from '@playwright/test'
+import { PerformanceMetricsCollector } from 'playwright-performance-metrics'
+
+const test = base.extend({
+  collector: async ({ page }, use) => {
+    const collector = new PerformanceMetricsCollector(page)
+    await use(collector)
+  }
+})
+
+export { test, expect }
+
+// test.spec.ts
+
+import { expect, test } from './fixture.ts'
+
+test('measure page performance', async ({ page, collector }) => {
+  await page.goto('https://example.com', { waitUntil: 'networkidle' })
+  const metrics = await collector.collectMetrics()
+  expect(metrics.domCompleteTiming, 'DOM Complete is less than 900ms').toBeLessThan(900)
+  expect(metrics.paint?.firstContentfulPaint, 'First Contentful Paint is less than 2000ms').toBeLessThan(2000)})
+})
+```
 ## API Reference
 
 ### PerformanceMetricsCollector
@@ -173,15 +221,25 @@ constructor(page: Page)
 
 #### Methods
 
-##### collectMetrics(options?: PerformanceOptions): Promise<PerformanceMetrics>
+- ##### collectMetrics(options?: PerformanceOptions): Promise<PerformanceMetrics>
 
-Collects performance metrics from the page.
+```typescript
+  /**
+   * Collect performance metrics from the page.
+   * @param options - Options for metric collection.
+   * @returns Collected performance metrics.
+   */
+```
 
-Options:
-- `timeout`: Collection timeout in milliseconds
-- `initialDelay`: Initial delay before starting collection
-- `retryTimeout`: Maximum time to retry collecting metrics
-- `networkConditions`: Network conditions to emulate
+- ##### options:
+```typescript
+  /** Maximum time to wait for metrics collection (ms) */
+  timeout?: number
+  /** Maximum time to retry collecting metrics (ms) */
+  retryTimeout?: number
+  /** Network emulation settings */
+  networkConditions?: NetworkConditions
+```
 
 ### Network Presets
 

dist/performance-metrics.js

@@ -62,13 +62,13 @@ class PerformanceMetricsCollector {
    * @returns Collected performance metrics.
    */
   async collectMetrics(options = {}) {
-    const { timeout = 10000, initialDelay = 1000, retryTimeout = 5000, networkConditions } = options
+    const { timeout = 10000, retryTimeout = 5000, networkConditions } = options
     // Initialize network conditions if provided
     if (networkConditions) {
       await this.initialize(networkConditions)
     }
-    // Wait for initial delay
-    await this.page.waitForTimeout(initialDelay)
+    // Wait for page to load
+    await this.page.waitForLoadState('networkidle', { timeout })
     const results = {}
     // Collect navigation timing metrics
     const navigationTiming = await this.page.evaluate(() => {

dist/types.d.ts

@@ -17,18 +17,13 @@ export interface NetworkConditions {
 }
 /**
  * Configuration options for performance metrics collection
- * @property startMark - Performance mark to start measuring from
- * @property endMark - Performance mark to end measuring at
  * @property timeout - Maximum time to wait for metrics collection
- * @property initialDelay - Initial delay before starting collection
  * @property retryTimeout - Maximum time to retry collecting metrics
  * @property networkConditions - Network emulation settings
  */
 export interface PerformanceOptions {
   /** Maximum time to wait for metrics collection (ms) */
   timeout?: number
-  /** Initial delay before starting collection (ms) */
-  initialDelay?: number
   /** Maximum time to retry collecting metrics (ms) */
   retryTimeout?: number
   /** Network emulation settings */

img/performance-UI.png

@@ -1,11 +1,11 @@
 // @ts-check
-import { defineConfig } from '@playwright/test'
+import { defineConfig, devices } from '@playwright/test'
 
 /**
  * @see https://playwright.dev/docs/test-configuration
  */
 export default defineConfig({
-  // workers: 3,
+  workers: 1,
   timeout: 45_000,
   expect: {
     timeout: 25_000
@@ -37,9 +37,7 @@ export default defineConfig({
     {
       name: 'Performance_tests',
       testMatch: /.*.spec.ts/,
-      use: {
-        channel: 'chrome'
-      }
+      use: { ...devices['Desktop Chrome'], channel: 'chrome' }
     }
   ]
 })

package-lock.json

@@ -69,15 +69,15 @@ export class PerformanceMetricsCollector implements IPerformanceMetricsCollector
    * @returns Collected performance metrics.
    */
   async collectMetrics(options: PerformanceOptions = {}): Promise<PerformanceMetrics> {
-    const { timeout = 10000, initialDelay = 1000, retryTimeout = 5000, networkConditions } = options
+    const { timeout = 10000, retryTimeout = 5000, networkConditions } = options
 
     // Initialize network conditions if provided
     if (networkConditions) {
       await this.initialize(networkConditions)
     }
 
-    // Wait for initial delay
-    await this.page.waitForTimeout(initialDelay)
+    // Wait for page to load
+    await this.page.waitForLoadState('networkidle', { timeout })
 
     const results: PerformanceMetrics = {}
 

playwright.config.js

@@ -18,18 +18,13 @@ export interface NetworkConditions {
 
 /**
  * Configuration options for performance metrics collection
- * @property startMark - Performance mark to start measuring from
- * @property endMark - Performance mark to end measuring at
  * @property timeout - Maximum time to wait for metrics collection
- * @property initialDelay - Initial delay before starting collection
  * @property retryTimeout - Maximum time to retry collecting metrics
  * @property networkConditions - Network emulation settings
  */
 export interface PerformanceOptions {
   /** Maximum time to wait for metrics collection (ms) */
   timeout?: number
-  /** Initial delay before starting collection (ms) */
-  initialDelay?: number
   /** Maximum time to retry collecting metrics (ms) */
   retryTimeout?: number
   /** Network emulation settings */

src/performance-metrics.ts

@@ -0,0 +1,77 @@
+// @ts-nocheck
+import { expect, test } from '@playwright/test'
+import fs from 'fs'
+import { PerformanceMetricsCollector } from '../src/performance-metrics'
+const results = []
+for (let i = 1; i < 2; i++) {
+  test.describe('Performance with one unified command ' + i, async () => {
+    const url = `https://playwright.dev`
+    test.beforeEach(async ({ page }) => {
+      await page.goto(url, { waitUntil: 'networkidle' })
+    })
+    test(i + ` Should load ${url} page in less than 2 second`, async ({ page }) => {
+      const collector = new PerformanceMetricsCollector(page)
+      const metrics = await collector.collectMetrics()
+      results.push(metrics)
+      fs.appendFileSync('results.json', JSON.stringify(metrics) + '\n')
+      expect(metrics.pageloadTiming).toBeLessThan(2000)
+      expect(metrics.domCompleteTiming).toBeLessThan(2000)
+    })
+    test(i + ` Should load ${url} page with timeToFirstByte less than 500ms`, async ({ page }) => {
+      const collector = new PerformanceMetricsCollector(page)
+      const metrics = await collector.collectMetrics()
+      results.push(metrics)
+      fs.appendFileSync('results.json', JSON.stringify(metrics) + '\n')
+      expect(metrics.timeToFirstByte.total, 'Time to first byte is less than 500ms').toBeLessThan(500)
+      expect(metrics.timeToFirstByte.dns, 'DNS time is less than 200ms').toBeLessThan(200)
+      expect(metrics.timeToFirstByte.wait, 'Wait time is less than 200ms').toBeLessThan(200)
+      expect(metrics.timeToFirstByte.redirect, 'Redirect time is less than 200ms').toBeLessThan(200)
+      expect(metrics.timeToFirstByte.tls, 'TLS time is less than 200ms').toBeLessThan(200)
+      expect(metrics.timeToFirstByte.connection, 'Connection time is less than 200ms').toBeLessThan(200)
+    })
+    test(i + ` Should load ${url} page with resourceTiming less than 500ms`, async ({ page }) => {
+      const collector = new PerformanceMetricsCollector(page)
+      const metrics = await collector.collectMetrics()
+      results.push(metrics)
+      fs.appendFileSync('results.json', JSON.stringify(metrics) + '\n')
+      const resourceTiming = await metrics.resourceTiming('redirection.js')
+      expect(resourceTiming?.duration, 'Resource timing is less than 500ms').toBeLessThan(500)
+    })
+    test(i + ` Should load ${url} page with size less than 1.5 MB`, async ({ page }) => {
+      const collector = new PerformanceMetricsCollector(page)
+      const metrics = await collector.collectMetrics()
+      results.push(metrics)
+      fs.appendFileSync('results.json', JSON.stringify(metrics) + '\n')
+      expect(metrics.totalBytes, 'Total bytes is less than 1.5 MB').toBeLessThan(1024 * 1024 * 1.5)
+    })
+    test(i + ` Should measure paint timings for ${url}`, async ({ page }) => {
+      const collector = new PerformanceMetricsCollector(page)
+      const metrics = await collector.collectMetrics()
+      results.push(metrics)
+      fs.appendFileSync('results.json', JSON.stringify(metrics) + '\n')
+      expect(metrics.paint.firstContentfulPaint, 'First Contentful Paint is less than 1500ms').toBeLessThan(1500)
+      expect(metrics.paint.firstPaint, 'First Paint is less than 1500ms').toBeLessThan(1500)
+    })
+    test(i + ` Should measure largestContentfulPaint for ${url}`, async ({ page }) => {
+      const collector = new PerformanceMetricsCollector(page)
+      const metrics = await collector.collectMetrics()
+      results.push(metrics)
+      fs.appendFileSync('results.json', JSON.stringify(metrics) + '\n')
+      expect(metrics.largestContentfulPaint, `Largest Contentful Paint (${metrics.largestContentfulPaint}ms) should be less than 500ms`).toBeLessThan(500)
+    })
+    test(i + ` Should measure cumulativeLayoutShift for ${url}`, async ({ page }) => {
+      const collector = new PerformanceMetricsCollector(page)
+      const metrics = await collector.collectMetrics()
+      results.push(metrics)
+      fs.appendFileSync('results.json', JSON.stringify(metrics) + '\n')
+      expect(metrics.cumulativeLayoutShift, `Cumulative Layout Shift (${metrics.cumulativeLayoutShift}) should be less than 0.1`).toBeLessThan(0.1)
+    })
+    test(i + ` Should measure totalBlockingTime for ${url}`, async ({ page }) => {
+      const collector = new PerformanceMetricsCollector(page)
+      const metrics = await collector.collectMetrics()
+      results.push(metrics)
+      fs.appendFileSync('results.json', JSON.stringify(metrics) + '\n')
+      expect(metrics.totalBlockingTime, `Total Blocking Time (${metrics.totalBlockingTime}ms) should be less than 500ms`).toBeLessThan(500)
+    })
+  })
+}

src/types.ts

@@ -10,9 +10,8 @@ test('Measure website performance default options', async () => {
   await page.goto('')
   const basicMetrics = await collector.collectMetrics({
     timeout: 15000,
-    initialDelay: 2000
+    retryTimeout: 500
   })
-
   console.log('Basic Metrics:', {
     'Time to First Byte': basicMetrics.timeToFirstByte?.total,
     'DOM Complete': basicMetrics.domCompleteTiming,
@@ -42,8 +41,7 @@ test('Slow Network metrics', async () => {
   const collector = new PerformanceMetricsCollector(page)
   const slowNetworkMetrics = await collector.collectMetrics({
     networkConditions: DefaultNetworkPresets.SLOW_3G,
-    timeout: 30000,
-    initialDelay: 1000
+    timeout: 30000
   })
 
   console.log('Slow 3G Metrics:', {