@gravity-ui/playwright-tools 1.0.0 → 1.1.1

package/README.md

@@ -3,7 +3,7 @@
 A library of additional utilities for writing tests using Playwright Test.
 
 ```
-npm i -D playwright-tools
+npm i -D @gravity-ui/playwright-tools
 ```
 
 The package contains several subdirectories with utilities for different purposes. You should import from these subdirectories, for example:

package/fixtures/mock-network/har-patcher.d.ts

@@ -1,8 +1,8 @@
 import type { MockNetworkFixtureBuilderParams } from './types';
-export type HarPatcherParams = Pick<MockNetworkFixtureBuilderParams, 'headersToRemove' | 'setCookieToRemove' | 'onHarEntryWillRead' | 'onHarEntryWillWrite' | 'onTransformHarLookupParams' | 'onTransformHarLookupResult'> & {
+export type HarPatcherParams = Pick<MockNetworkFixtureBuilderParams, 'headersToRemove' | 'setCookieToRemove' | 'onHarEntryWillRead' | 'onHarEntryWillWrite' | 'onTransformHarLookupParams' | 'onTransformHarLookupResult' | 'shouldMarkIdenticalRequests'> & {
     /**
      * Base url of the test
      */
     baseURL: string;
 };
-export declare function harPatcher({ baseURL, headersToRemove: additionalHeadersToRemove, setCookieToRemove: additionalSetCookieToRemove, onHarEntryWillWrite, onHarEntryWillRead, onTransformHarLookupParams, onTransformHarLookupResult, }: HarPatcherParams): void;
+export declare function harPatcher({ baseURL, headersToRemove: additionalHeadersToRemove, setCookieToRemove: additionalSetCookieToRemove, onHarEntryWillWrite, onHarEntryWillRead, onTransformHarLookupParams, onTransformHarLookupResult, shouldMarkIdenticalRequests, }: HarPatcherParams): void;

package/fixtures/mock-network/har-patcher.js

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.harPatcher = harPatcher;
 const har_1 = require("../../har");
+const createDuplicateIdTransform_1 = require("../../utils/createDuplicateIdTransform");
+const markIdenticalRequests_1 = require("../../utils/markIdenticalRequests");
 const DEFAULT_REMOVE_HEADERS = new Set([
     'cookie',
     'x-csrf-token',
@@ -10,7 +12,7 @@ const DEFAULT_REMOVE_HEADERS = new Set([
 ]);
 const DEFAULT_REMOVE_SET_COOKIE_FOR = new Set(['CSRF-TOKEN']);
 const baseUrlPLaceholder = 'https://base.url.placeholder';
-function harPatcher({ baseURL, headersToRemove: additionalHeadersToRemove = [], setCookieToRemove: additionalSetCookieToRemove = [], onHarEntryWillWrite, onHarEntryWillRead, onTransformHarLookupParams, onTransformHarLookupResult, }) {
+function harPatcher({ baseURL, headersToRemove: additionalHeadersToRemove = [], setCookieToRemove: additionalSetCookieToRemove = [], onHarEntryWillWrite, onHarEntryWillRead, onTransformHarLookupParams, onTransformHarLookupResult, shouldMarkIdenticalRequests = false, }) {
     const headersToRemove = new Set([...DEFAULT_REMOVE_HEADERS, ...additionalHeadersToRemove]);
     const setCookieToRemove = new Set([
         ...DEFAULT_REMOVE_SET_COOKIE_FOR,
@@ -27,16 +29,39 @@ function harPatcher({ baseURL, headersToRemove: additionalHeadersToRemove = [],
             removeSetCookieFor: setCookieToRemove,
         });
         (0, har_1.replaceBaseUrlInEntry)(entry, baseURL, baseUrlPLaceholder);
-        onHarEntryWillWrite?.(entry);
+        onHarEntryWillWrite?.(entry, baseURL);
     });
     (0, har_1.addHarOpenTransform)((harFile) => {
         const entries = harFile.log.entries;
         for (const entry of entries) {
             (0, har_1.replaceBaseUrlInEntry)(entry, baseUrlPLaceholder, baseURL);
-            onHarEntryWillRead?.(entry);
+            onHarEntryWillRead?.(entry, baseURL);
         }
     });
-    (0, har_1.addHarLookupTransform)(onTransformHarLookupParams, onTransformHarLookupResult);
-    // Filter out canceled requests before writing to har file
-    (0, har_1.addFlushTransform)((entries) => entries.filter((entry) => entry.time !== -1));
+    // Create duplicate ID transformer once to preserve state between calls
+    const duplicateIdTransform = shouldMarkIdenticalRequests ? (0, createDuplicateIdTransform_1.createDuplicateIdTransform)() : null;
+    const onTransformHarLookupParamsFinal = (params) => {
+        // Apply duplicate ID transform first (if enabled)
+        const modifiedParams = duplicateIdTransform ? duplicateIdTransform(params) : params;
+        // Then apply custom transformer (if provided)
+        return onTransformHarLookupParams
+            ? onTransformHarLookupParams(modifiedParams, baseURL)
+            : modifiedParams;
+    };
+    const onTransformHarLookupResultFinal = (result, params) => {
+        return onTransformHarLookupResult
+            ? onTransformHarLookupResult(result, params, baseURL)
+            : result;
+    };
+    (0, har_1.addHarLookupTransform)(onTransformHarLookupParamsFinal, onTransformHarLookupResultFinal);
+    // Transform requests before writing to har file
+    (0, har_1.addFlushTransform)((entries) => {
+        // Before writing to har file, filter out canceled requests
+        const filteredEntries = entries.filter((entry) => entry.time !== -1);
+        // Add x-tests-duplicate-id header for identical requests (if enabled)
+        if (shouldMarkIdenticalRequests) {
+            return (0, markIdenticalRequests_1.markIdenticalRequests)(filteredEntries);
+        }
+        return filteredEntries;
+    });
 }

package/fixtures/mock-network/mock-network-fixture.d.ts

@@ -1,6 +1,6 @@
 import type { PlaywrightTestArgs, PlaywrightTestOptions, TestFixture } from '@playwright/test';
 import type { MockNetworkFixtureBuilderParams } from './types';
-export declare function mockNetworkFixtureBuilder({ shouldUpdate, forceUpdateIfHarMissing, updateTimeout, zip, url: urlMatcherBuilder, dumpsFilePath, ...harPatcherParams }: MockNetworkFixtureBuilderParams): [TestFixture<boolean, PlaywrightTestArgs & PlaywrightTestOptions>, {
+export declare function mockNetworkFixtureBuilder<TestArgs extends PlaywrightTestArgs & PlaywrightTestOptions = PlaywrightTestArgs & PlaywrightTestOptions>({ shouldUpdate, forceUpdateIfHarMissing, updateTimeout, zip, url, dumpsFilePath, optionallyEnabled, ...harPatcherParams }: MockNetworkFixtureBuilderParams): [TestFixture<boolean, TestArgs>, {
     auto: boolean;
     scope: "test";
 }];

package/fixtures/mock-network/mock-network-fixture.js

@@ -3,34 +3,59 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.mockNetworkFixtureBuilder = mockNetworkFixtureBuilder;
 const har_1 = require("../../har");
 const har_patcher_1 = require("./har-patcher");
-function mockNetworkFixtureBuilder({ shouldUpdate, forceUpdateIfHarMissing, updateTimeout, zip = true, url: urlMatcherBuilder, dumpsFilePath, ...harPatcherParams }) {
-    const mockNetworkFixture = async ({ baseURL: rawBaseURL, page }, use, testInfo) => {
-        if (!rawBaseURL) {
-            throw new Error('baseURL should be specified in playwright config');
-        }
-        const baseURL = rawBaseURL.replace(/\/+$/, '');
-        (0, har_patcher_1.harPatcher)({
-            baseURL,
-            ...harPatcherParams,
-        });
-        const update = Boolean(shouldUpdate);
-        const url = urlMatcherBuilder(baseURL);
-        await (0, har_1.initDumps)(page, testInfo, {
-            dumpsFilePath,
+const fixtureFunction = async ({ baseURL: rawBaseURL, page, }, { shouldUpdate, forceUpdateIfHarMissing, updateTimeout, zip = true, url: urlMatcherBuilder, dumpsFilePath, ...harPatcherParams }, use, testInfo) => {
+    if (!rawBaseURL) {
+        throw new Error('baseURL should be specified in playwright config');
+    }
+    const baseURL = rawBaseURL.replace(/\/+$/, '');
+    (0, har_patcher_1.harPatcher)({
+        baseURL,
+        ...harPatcherParams,
+    });
+    const update = Boolean(shouldUpdate);
+    const url = urlMatcherBuilder(baseURL);
+    await (0, har_1.initDumps)(page, testInfo, {
+        dumpsFilePath,
+        forceUpdateIfHarMissing,
+        updateTimeout,
+        update,
+        url,
+        zip,
+    });
+    await use(!update);
+};
+function mockNetworkFixtureBuilder({ shouldUpdate, forceUpdateIfHarMissing, updateTimeout, zip = true, url, dumpsFilePath, optionallyEnabled, ...harPatcherParams }) {
+    const mockNetworkFixture = async ({ baseURL, page }, use, testInfo) => {
+        return fixtureFunction({ baseURL, page }, {
+            shouldUpdate,
             forceUpdateIfHarMissing,
             updateTimeout,
-            update,
+            zip,
             url,
+            dumpsFilePath,
+            ...harPatcherParams,
+        }, use, testInfo);
+    };
+    const mockNetworkFixtureWithOptionalParam = async ({ baseURL, page, enableNetworkMocking }, use, testInfo) => {
+        if (!enableNetworkMocking) {
+            return use(false);
+        }
+        return fixtureFunction({ baseURL, page }, {
+            shouldUpdate,
+            forceUpdateIfHarMissing,
+            updateTimeout,
             zip,
-        });
-        await use(!update);
+            url,
+            dumpsFilePath,
+            ...harPatcherParams,
+        }, use, testInfo);
     };
     const fixtureOptions = {
         auto: true,
         scope: 'test',
     };
     const mockNetwork = [
-        mockNetworkFixture,
+        optionallyEnabled ? mockNetworkFixtureWithOptionalParam : mockNetworkFixture,
         fixtureOptions,
     ];
     return mockNetwork;

package/fixtures/mock-network/types.d.ts

@@ -53,21 +53,43 @@ export type MockNetworkFixtureBuilderParams = {
      * Callback for processing requests and responses by saving to .har. Useful for various post-processing of requests: cleaning, changing format, etc.
      * By default, sensitive headers are removed + the base url of the request is changed to a stub
      * @param entry The entry in .har that will be written
+     * @param baseURL The base URL of the test
      */
-    onHarEntryWillWrite?: (entry: Entry) => void;
+    onHarEntryWillWrite?: (entry: Entry, baseURL: string) => void;
     /**
      * Callback to process requests and responses written in .har before they are used
      * Useful for reverting changes made in onHarEntryWillWrite
      * By default, the base url templates are replaced with the actual baseUrl of the test
      * @param entry The entry in .har that will be used
+     * @param baseURL The base URL of the test
      */
-    onHarEntryWillRead?: (entry: Entry) => void;
+    onHarEntryWillRead?: (entry: Entry, baseURL: string) => void;
     /**
      * Callback for changing search parameters of queries in .har
+     * @param params The lookup parameters
+     * @param baseURL The base URL of the test
      */
-    onTransformHarLookupParams?: HarLookupParamsTransformFunction;
+    onTransformHarLookupParams?: (params: Parameters<HarLookupParamsTransformFunction>[0], baseURL: string) => ReturnType<HarLookupParamsTransformFunction>;
     /**
      * Callback for transforming the search query result into .har
+     * @param result The lookup result
+     * @param params The lookup parameters
+     * @param baseURL The base URL of the test
      */
-    onTransformHarLookupResult?: HarLookupResultTransformFunction;
+    onTransformHarLookupResult?: (result: Parameters<HarLookupResultTransformFunction>[0], params: Parameters<HarLookupResultTransformFunction>[1], baseURL: string) => ReturnType<HarLookupResultTransformFunction>;
+    /**
+     * Allow optionally enable fixture.
+     * Set "enableNetworkMocking" fixture to turn on/off network mocking
+     * @defaultValue false `
+     */
+    optionallyEnabled?: boolean;
+    /**
+     * Flag to enable or disable adding the x-tests-duplicate-id header for identical requests
+     * By default, the header is not added
+     * @defaultValue `false`
+     */
+    shouldMarkIdenticalRequests?: boolean;
+};
+export type OptionallyEnabledTestArgs = {
+    enableNetworkMocking?: boolean;
 };

package/har/index.d.ts

@@ -10,5 +10,5 @@ export { clearHeaders } from './clearHeaders';
 export { initDumps } from './initDumps';
 export { replaceBaseUrlInEntry } from './replaceBaseUrlInEntry';
 export { setExtraHash } from './setExtraHash';
-export type { HARFile, Entry } from './types';
+export type { HARFile, Entry, Header, LocalUtilsHarLookupParams, LocalUtilsHarLookupResult, QueryParameter, } from './types';
 export { defaultDumpsFilePathBuilder, dumpsPathBuldeWithSlugBuilder } from './dumpsFilePathBulders';

package/har/replaceBaseUrlInEntry.d.ts

@@ -2,7 +2,7 @@ import type { Entry } from './types';
 /**
  * Replaces the base URL in the HAR file request entry
  *
- * @param entry ЗRecording from HAR file
+ * @param entry Recording from HAR file
  * @param fromUrl URL to replace
  * @param toUrl URL to replace with
  */

package/har/replaceBaseUrlInEntry.js

@@ -8,7 +8,7 @@ const escape_string_regexp_1 = __importDefault(require("escape-string-regexp"));
 /**
  * Replaces the base URL in the HAR file request entry
  *
- * @param entry ЗRecording from HAR file
+ * @param entry Recording from HAR file
  * @param fromUrl URL to replace
  * @param toUrl URL to replace with
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gravity-ui/playwright-tools",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "Tools for Playwright Test",
   "keywords": [
     "playwright",

package/utils/createDuplicateIdTransform.d.ts

@@ -0,0 +1,11 @@
+import type { LocalUtilsHarLookupParams } from '../har';
+/**
+ * Creates a transformer for automatically adding the x-tests-duplicate-id header
+ * to requests when searching in a HAR file.
+ *
+ * This allows distinguishing identical requests without changing test code.
+ *
+ * The header is NOT added to the first request (for backward compatibility with old HARs),
+ * and is added starting from the second: 2, 3, 4...
+ */
+export declare function createDuplicateIdTransform(): (params: LocalUtilsHarLookupParams) => LocalUtilsHarLookupParams;

package/utils/createDuplicateIdTransform.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDuplicateIdTransform = createDuplicateIdTransform;
+const requestKeyService_1 = require("./requestKeyService");
+/**
+ * Creates a transformer for automatically adding the x-tests-duplicate-id header
+ * to requests when searching in a HAR file.
+ *
+ * This allows distinguishing identical requests without changing test code.
+ *
+ * The header is NOT added to the first request (for backward compatibility with old HARs),
+ * and is added starting from the second: 2, 3, 4...
+ */
+function createDuplicateIdTransform() {
+    const requestCounts = new Map();
+    return (params) => {
+        const key = (0, requestKeyService_1.createRequestKeyFromLookupParams)(params);
+        // Increment the counter for this request
+        const count = (requestCounts.get(key) || 0) + 1;
+        requestCounts.set(key, count);
+        // Add header only starting from the second call
+        // This ensures backward compatibility with old HAR files,
+        // where requests did not have the x-tests-duplicate-id header
+        if (count > 1) {
+            params.headers.push({
+                name: 'x-tests-duplicate-id',
+                value: String(count),
+            });
+        }
+        return params;
+    };
+}

package/utils/markIdenticalRequests.d.ts

@@ -0,0 +1,9 @@
+import type { Entry } from '../har';
+/**
+ * Adds the x-tests-duplicate-id header only for duplicate requests.
+ *
+ * The first request remains without a header for backward compatibility with old HAR files.
+ * Starting from the second, requests receive headers: 2, 3, 4...
+ *
+ */
+export declare const markIdenticalRequests: (entries: Entry[]) => Entry[];

package/utils/markIdenticalRequests.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.markIdenticalRequests = void 0;
+const requestKeyService_1 = require("./requestKeyService");
+/**
+ * Adds the x-tests-duplicate-id header only for duplicate requests.
+ *
+ * The first request remains without a header for backward compatibility with old HAR files.
+ * Starting from the second, requests receive headers: 2, 3, 4...
+ *
+ */
+const markIdenticalRequests = (entries) => {
+    const currentCounts = new Map();
+    entries.forEach((entry) => {
+        const key = (0, requestKeyService_1.createRequestKeyFromEntry)(entry);
+        const currentCount = (currentCounts.get(key) || 0) + 1;
+        currentCounts.set(key, currentCount);
+        // Add header only if this is not the first instance (currentCount > 1)
+        if (currentCount > 1) {
+            entry.request.headers.push({
+                name: 'x-tests-duplicate-id',
+                value: String(currentCount),
+            });
+        }
+    });
+    return entries;
+};
+exports.markIdenticalRequests = markIdenticalRequests;

package/utils/requestKeyService.d.ts

@@ -0,0 +1,30 @@
+import type { Entry, Header, LocalUtilsHarLookupParams, QueryParameter } from '../har';
+/**
+ * Creates a unique request key based on its parameters.
+ * Used to identify identical requests when working with HAR files.
+ *
+ * The key is formed based on:
+ * - HTTP method
+ * - URL (without query parameters)
+ * - Query parameters (sorted)
+ * - Headers (sorted, excluding service headers)
+ */
+export declare function createRequestKey(params: RequestKeyParams): string;
+/**
+ * Parameters for creating a request key
+ */
+type RequestKeyParams = {
+    method: string;
+    url: string;
+    headers: Header[];
+    queryString?: QueryParameter[];
+};
+/**
+ * Creates a key from Entry (when writing HAR)
+ */
+export declare function createRequestKeyFromEntry(entry: Entry): string;
+/**
+ * Creates a key from LocalUtilsHarLookupParams (when replaying)
+ */
+export declare function createRequestKeyFromLookupParams(params: LocalUtilsHarLookupParams): string;
+export {};

package/utils/requestKeyService.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRequestKey = createRequestKey;
+exports.createRequestKeyFromEntry = createRequestKeyFromEntry;
+exports.createRequestKeyFromLookupParams = createRequestKeyFromLookupParams;
+/**
+ * Creates a unique request key based on its parameters.
+ * Used to identify identical requests when working with HAR files.
+ *
+ * The key is formed based on:
+ * - HTTP method
+ * - URL (without query parameters)
+ * - Query parameters (sorted)
+ * - Headers (sorted, excluding service headers)
+ */
+function createRequestKey(params) {
+    const method = params.method;
+    const url = params.url;
+    // Parse URL to extract the base part and query parameters
+    const urlObj = new URL(url);
+    // Get sorted query parameters
+    const sortedQueryString = params.queryString
+        ? sortQueryStringFromArray(params.queryString)
+        : sortQueryStringFromUrl(urlObj);
+    // Get sorted headers (excluding service headers)
+    const sortedHeaders = sortHeaders(params.headers);
+    // Form the key: method + URL without query + query parameters + headers
+    return `${method}:${urlObj.origin}${urlObj.pathname}:${sortedQueryString}:${sortedHeaders}`;
+}
+/**
+ * Creates a key from Entry (when writing HAR)
+ */
+function createRequestKeyFromEntry(entry) {
+    return createRequestKey({
+        method: entry.request.method,
+        url: entry.request.url,
+        headers: entry.request.headers,
+        queryString: entry.request.queryString,
+    });
+}
+/**
+ * Creates a key from LocalUtilsHarLookupParams (when replaying)
+ */
+function createRequestKeyFromLookupParams(params) {
+    return createRequestKey({
+        method: params.method,
+        url: params.url,
+        headers: params.headers,
+        // queryString is automatically extracted from URL
+    });
+}
+/**
+ * Sorts query parameters from QueryParameter array
+ */
+function sortQueryStringFromArray(queryString) {
+    return [...queryString]
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .map((queryParameter) => `${queryParameter.name}=${queryParameter.value}`)
+        .join('&');
+}
+/**
+ * Sorts query parameters from URL
+ */
+function sortQueryStringFromUrl(urlObj) {
+    return Array.from(urlObj.searchParams.entries())
+        .sort((a, b) => a[0].localeCompare(b[0]))
+        .map(([key, value]) => `${key}=${value}`)
+        .join('&');
+}
+/**
+ * Sorts headers, excluding service headers
+ */
+function sortHeaders(headers) {
+    return [...headers]
+        .filter((header) => header.name.toLowerCase() !== 'x-tests-duplicate-id')
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .map((header) => `${header.name.toLowerCase()}:${header.value}`)
+        .join('|');
+}