playwright-network-metrics 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Denis Bratchikov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,102 @@
+# playwright-network-metrics
+
+[![npm version](https://img.shields.io/npm/v/playwright-network-metrics.svg)](https://www.npmjs.com/package/playwright-network-metrics)
+
+A Playwright instrumentation package that collects and aggregates network performance metrics across your entire test run.
+
+## Features
+
+- **Native Timings**: Uses standard Playwright `request.timing()` for accurate measurement.
+- **Interactive HTML Report**: Visualizes network performance with charts and detailed tables.
+- **Granular Aggregation**: Groups by normalized URL, exact URL, resource type, and custom route groups.
+- **Low Overhead**: Captures only necessary metadata, avoiding request/response body storage.
+- **Flexible Filtering**: Use glob patterns to focus on specific APIs or resource types.
+
+## Installation
+
+```bash
+npm install --save-dev playwright-network-metrics
+```
+
+## Usage
+
+### 1. Add the Reporter
+
+Update your `playwright.config.ts` to include the `NetworkMetricsReporter`. This "plugin" entry point will aggregate metrics from all workers and generate the final report.
+
+```typescript
+import { defineConfig } from "@playwright/test";
+
+export default defineConfig({
+  reporter: [
+    ["list"],
+    [
+      "playwright-network-metrics",
+      {
+        html: true, // Generate an interactive HTML report
+        outDir: "network-metrics-report",
+      },
+    ],
+  ],
+});
+```
+
+### 2. Collect Metrics in Tests
+
+Extend your Playwright `test` with the `networkMetrics` fixture. It is **automatic** by default.
+
+```typescript
+import { test as base } from "@playwright/test";
+import { defineNetworkMetricsFixture } from "playwright-network-metrics";
+
+// Extend the test with our fixture
+export const test = base.extend({
+  networkMetrics: defineNetworkMetricsFixture({
+    urlMatch: "**/api/**",
+  }),
+});
+
+// Use it in your tests
+test("my performance test", async ({ page }) => {
+  await page.goto("/dashboard");
+  // metrics are automatically collected and attached to the report
+});
+```
+
+## Configuration
+
+The `defineNetworkMetricsFixture` function and `NetworkMetricsReporter` accept a configuration object:
+
+| Option              | Type                 | Default                               | Description                                          |
+| ------------------- | -------------------- | ------------------------------------- | ---------------------------------------------------- |
+| `outDir`            | `string`             | `"playwright-report/network-metrics"` | Directory where the reports will be written.         |
+| `html`              | `boolean`            | `false`                               | Whether to generate an interactive HTML report.      |
+| `urlMatch`          | `string \| string[]` | `"**"`                                | Glob pattern(s) to match URLs (e.g., `**/api/**`).   |
+| `resourceTypes`     | `string[]`           | `[...]`                               | List of resource types to track.                     |
+| `redactQueryParams` | `string[]`           | `[]`                                  | List of query parameters to redact from stored URLs. |
+| `redactUrl`         | `function`           | `(url) => url`                        | Custom hook to modify the URL before storage.        |
+| `routeGroupRules`   | `array`              | `[]`                                  | Rules for grouping URLs into logical categories.     |
+| `routeGroupFn`      | `function`           | `undefined`                           | Custom hook for route grouping.                      |
+
+### Custom Route Grouping
+
+You can provide custom rules to group similar URLs together:
+
+```typescript
+{
+  routeGroupRules: [
+    { match: "**/api/v1/users/*", group: "/api/users/:id" },
+    { match: "**/subscriptions/**", group: "Subscriptions" },
+  ],
+}
+```
+
+## Performance Notes
+
+- **Low Overhead**: Does not store request/response bodies.
+- **Memory Efficient**: Uses incremental aggregation and caps memory for percentile calculation.
+- **Atomic Writing**: Writes reports only once at the end of the entire test run.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,133 @@
+import { Request, Fixtures } from '@playwright/test';
+import { Reporter, TestCase, TestResult } from '@playwright/test/reporter';
+
+declare const RESOURCE_TYPES: string[];
+
+/**
+ * Configuration for the network metrics collector.
+ */
+interface NetworkMetricsConfig {
+    /**
+     * Filter requests by URL pattern using glob strings or an array of glob strings.
+     * Wildcards like `** /api/ **` are supported.
+     * @default "**"
+     * @see https://www.npmjs.com/package/micromatch
+     */
+    urlMatch?: string | string[];
+    /**
+     * List of Playwright resource types to track.
+     * @default ["fetch", "xhr", "document", "script", "style", "image", "font", "other"]
+     */
+    resourceTypes?: string[];
+    /**
+     * Custom hook to determine if a specific request should be tracked.
+     * Returning false will skip this request.
+     */
+    shouldTrackRequest?: (request: Request) => boolean;
+    /**
+     * List of query parameter names to redact from the stored URLs.
+     * The values will be replaced with "[REDACTED]".
+     * @default []
+     */
+    redactQueryParams?: string[];
+    /**
+     * Custom hook to redact or modify the entire URL string before it is stored.
+     * This is called before redactQueryParams.
+     * @default (url) => url
+     */
+    redactUrl?: (url: string) => string;
+    /**
+     * Rules for grouping URLs into logical categories (e.g., "/api/users/:id").
+     * Supports glob patterns for matching.
+     */
+    routeGroupRules?: Array<{
+        /**
+         * Glob pattern or array of patterns to match the URL against.
+         */
+        match: string | string[];
+        /**
+         * The name of the group to assign if matched.
+         */
+        group: string;
+    }>;
+    /**
+     * Custom hook for route grouping. Takes precedence over routeGroupRules.
+     * Should return the group name or undefined to use default rules.
+     */
+    routeGroupFn?: (url: string) => string | undefined;
+}
+/**
+ * Configuration for the Playwright reporter plugin.
+ */
+interface NetworkMetricsReporterConfig {
+    /**
+     * Directory where the metrics reports (JSON/HTML) will be saved.
+     * @default "playwright-report/network-metrics"
+     */
+    outDir?: string;
+    /**
+     * Whether to generate an interactive HTML report.
+     * @default false
+     */
+    html?: boolean;
+}
+
+/**
+ * Returns a Playwright fixture tuple with automatic instrumentation.
+ *
+ * When used as a fixture, it automatically attaches to the current page,
+ * collects network metrics throughout the test, and attaches the results
+ * as a JSON file named "network-metrics" to the test report upon completion.
+ *
+ * @param config Optional configuration for the collector (filtering, redaction, grouping).
+ * @returns A Playwright fixture tuple containing the collector and setup/teardown logic.
+ *
+ * @example
+ * ```typescript
+ * import { test as base } from '@playwright/test';
+ * import { defineNetworkMetricsFixture } from 'playwright-network-metrics';
+ *
+ * export const test = base.extend({
+ *   networkMetrics: defineNetworkMetricsFixture({
+ *     urlMatch: "**" + "/api/" + "**",
+ *   })
+ * });
+ * ```
+ */
+declare const defineNetworkMetricsFixture: (config?: NetworkMetricsConfig) => Fixtures;
+
+/**
+ * A Playwright Reporter that aggregates network metrics from all test runs and generates reports.
+ *
+ * It collects metrics from worker processes via test attachments and produces
+ * JSON and optional HTML summaries.
+ */
+declare class NetworkMetricsReporter implements Reporter {
+    /**
+     * Internal store for all collected request metrics from all tests.
+     */
+    private allMetrics;
+    private config;
+    /**
+     * Initializes the reporter with configuration for output and format.
+     *
+     * @param config Configuration for output directory and HTML report generation.
+     */
+    constructor(config?: NetworkMetricsReporterConfig);
+    /**
+     * Playwright lifecycle hook called after each test finishes.
+     * Extracts "network-metrics" attachments and stores them for end-of-run aggregation.
+     */
+    onTestEnd(test: TestCase, result: TestResult): void;
+    /**
+     * Playwright lifecycle hook called after all tests have finished.
+     * Aggregates all collected metrics and writes the final reports to disk.
+     */
+    onEnd(): Promise<void>;
+    /**
+     * Internal helper to trigger HTML report generation.
+     */
+    private generateHtml;
+}
+
+export { RESOURCE_TYPES, NetworkMetricsReporter as default, defineNetworkMetricsFixture };

package/dist/index.d.ts

@@ -0,0 +1,133 @@
+import { Request, Fixtures } from '@playwright/test';
+import { Reporter, TestCase, TestResult } from '@playwright/test/reporter';
+
+declare const RESOURCE_TYPES: string[];
+
+/**
+ * Configuration for the network metrics collector.
+ */
+interface NetworkMetricsConfig {
+    /**
+     * Filter requests by URL pattern using glob strings or an array of glob strings.
+     * Wildcards like `** /api/ **` are supported.
+     * @default "**"
+     * @see https://www.npmjs.com/package/micromatch
+     */
+    urlMatch?: string | string[];
+    /**
+     * List of Playwright resource types to track.
+     * @default ["fetch", "xhr", "document", "script", "style", "image", "font", "other"]
+     */
+    resourceTypes?: string[];
+    /**
+     * Custom hook to determine if a specific request should be tracked.
+     * Returning false will skip this request.
+     */
+    shouldTrackRequest?: (request: Request) => boolean;
+    /**
+     * List of query parameter names to redact from the stored URLs.
+     * The values will be replaced with "[REDACTED]".
+     * @default []
+     */
+    redactQueryParams?: string[];
+    /**
+     * Custom hook to redact or modify the entire URL string before it is stored.
+     * This is called before redactQueryParams.
+     * @default (url) => url
+     */
+    redactUrl?: (url: string) => string;
+    /**
+     * Rules for grouping URLs into logical categories (e.g., "/api/users/:id").
+     * Supports glob patterns for matching.
+     */
+    routeGroupRules?: Array<{
+        /**
+         * Glob pattern or array of patterns to match the URL against.
+         */
+        match: string | string[];
+        /**
+         * The name of the group to assign if matched.
+         */
+        group: string;
+    }>;
+    /**
+     * Custom hook for route grouping. Takes precedence over routeGroupRules.
+     * Should return the group name or undefined to use default rules.
+     */
+    routeGroupFn?: (url: string) => string | undefined;
+}
+/**
+ * Configuration for the Playwright reporter plugin.
+ */
+interface NetworkMetricsReporterConfig {
+    /**
+     * Directory where the metrics reports (JSON/HTML) will be saved.
+     * @default "playwright-report/network-metrics"
+     */
+    outDir?: string;
+    /**
+     * Whether to generate an interactive HTML report.
+     * @default false
+     */
+    html?: boolean;
+}
+
+/**
+ * Returns a Playwright fixture tuple with automatic instrumentation.
+ *
+ * When used as a fixture, it automatically attaches to the current page,
+ * collects network metrics throughout the test, and attaches the results
+ * as a JSON file named "network-metrics" to the test report upon completion.
+ *
+ * @param config Optional configuration for the collector (filtering, redaction, grouping).
+ * @returns A Playwright fixture tuple containing the collector and setup/teardown logic.
+ *
+ * @example
+ * ```typescript
+ * import { test as base } from '@playwright/test';
+ * import { defineNetworkMetricsFixture } from 'playwright-network-metrics';
+ *
+ * export const test = base.extend({
+ *   networkMetrics: defineNetworkMetricsFixture({
+ *     urlMatch: "**" + "/api/" + "**",
+ *   })
+ * });
+ * ```
+ */
+declare const defineNetworkMetricsFixture: (config?: NetworkMetricsConfig) => Fixtures;
+
+/**
+ * A Playwright Reporter that aggregates network metrics from all test runs and generates reports.
+ *
+ * It collects metrics from worker processes via test attachments and produces
+ * JSON and optional HTML summaries.
+ */
+declare class NetworkMetricsReporter implements Reporter {
+    /**
+     * Internal store for all collected request metrics from all tests.
+     */
+    private allMetrics;
+    private config;
+    /**
+     * Initializes the reporter with configuration for output and format.
+     *
+     * @param config Configuration for output directory and HTML report generation.
+     */
+    constructor(config?: NetworkMetricsReporterConfig);
+    /**
+     * Playwright lifecycle hook called after each test finishes.
+     * Extracts "network-metrics" attachments and stores them for end-of-run aggregation.
+     */
+    onTestEnd(test: TestCase, result: TestResult): void;
+    /**
+     * Playwright lifecycle hook called after all tests have finished.
+     * Aggregates all collected metrics and writes the final reports to disk.
+     */
+    onEnd(): Promise<void>;
+    /**
+     * Internal helper to trigger HTML report generation.
+     */
+    private generateHtml;
+}
+
+export { RESOURCE_TYPES, NetworkMetricsReporter as default, defineNetworkMetricsFixture };