ftmocks-utils 1.3.4 → 1.3.6

package/README.md

@@ -1,2 +1,89 @@
 # ftmocks-utils
+
 Util functions for FtMocks
+
+## Usage: initiatePlaywrightRoutes
+
+`initiatePlaywrightRoutes` sets up Playwright network route mocks for your tests.
+
+### Example Test
+
+```js
+import { test, expect } from "@playwright/test";
+import { initiatePlaywrightRoutes } from "ftmocks-utils";
+
+test("Sample test case", async ({ page }) => {
+  // Initiate Playwright routes with custom directories and patterns
+  await initiatePlaywrightRoutes(
+    page,
+    {
+      MOCK_DIR: "../ftmocks",
+      FALLBACK_DIR: "../public",
+    },
+    "Sample test case",
+    "**/*" // Pattern(s) to intercept; you can use a string or array of patterns
+  );
+
+  await page.goto("https://example-test.com/");
+
+  // Now your requests will be mocked as per your ftmocks setup
+  // Add your test steps and assertions here
+});
+```
+
+**Parameters**:
+
+- `page`: Playwright page object.
+- `options`: Object with configuration. At minimum, provide `MOCK_DIR` (required). `FALLBACK_DIR` is optional.
+- `testName`: (string) Name of this test, so ftmocks can find the right mock data.
+- `patterns`: (string or array) Glob patterns for requests to intercept.
+
+Make sure your `MOCK_DIR` points to the directory where your FtMocks records are saved.
+
+See more API documentation at [ftmocks.com](https://ftmocks.com) or in the main FtMocks repository.
+
+## Usage: recordPlaywrightRoutes
+
+`recordPlaywrightRoutes` allows you to record network requests and responses from a Playwright test session and save them as FtMocks mocks. This is useful for setting up new mocks or updating existing ones with actual traffic.
+
+### Example Usage
+
+```js
+import { test } from "@playwright/test";
+import { recordPlaywrightRoutes } from "ftmocks-utils";
+
+test("Record API interactions", async ({ page }) => {
+  await recordPlaywrightRoutes(
+    page,
+    {
+      MOCK_DIR: "../ftmocks",
+      FALLBACK_DIR: "../public",
+    },
+    {
+      testName: "Recorded test",
+      mockPath: "**/*", // Intercept all requests by default
+      pattern: "^/api/.*", // Only record requests matching this regex pattern (e.g., API endpoints)
+      avoidDuplicatesInTheTest: true, // Skip duplicates within a single test recording
+      avoidDuplicatesWithDefaultMocks: true, // Skip duplicates with default mocks
+    }
+  );
+
+  await page.goto("https://your-app-under-test.com/");
+  // Interact with your page as needed; API requests will be recorded
+});
+```
+
+**Parameters**:
+
+- `page`: Playwright page object.
+- `ftmocksConifg`: Object, must contain at minimum `MOCK_DIR`. `FALLBACK_DIR` is optional.
+- `config`: Object containing recording options:
+  - `testName`: (string) Name of the test, used for saving the mock data.
+  - `mockPath`: (string|array) Glob pattern(s) for requests to intercept.
+  - `pattern`: (string) Regex string; only requests matching this will be recorded.
+  - `avoidDuplicatesInTheTest`: (boolean) Skip duplicate entries during this run.
+  - `avoidDuplicatesWithDefaultMocks`: (boolean) Skip recording if identical default mocks are present.
+
+After running the test, FtMocks-compatible mock files will be saved to the specified folder for easy reuse.
+
+See more API documentation and advanced usage at [ftmocks.com](https://ftmocks.com).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ftmocks-utils",
-  "version": "1.3.4",
+  "version": "1.3.6",
   "description": "Util functions for FtMocks",
   "main": "src/index.js",
   "scripts": {

package/src/common-utils.js

@@ -134,6 +134,82 @@ const getTestByName = async (ftmocksConifg, testName) => {
   }
 };
 
+/**
+ * Creates a map from an array of objects using `id` property as key.
+ * @param {Array<object>} arr - The array of objects to map.
+ * @returns {Object} Map of id -> object
+ */
+function createIdMap(arr) {
+  if (!Array.isArray(arr)) return {};
+  return arr.reduce((acc, obj) => {
+    if (obj && obj.id !== undefined && obj.id !== null) {
+      acc[obj.id] = obj;
+    }
+    return acc;
+  }, {});
+}
+
+/**
+ * Creates a map where the key is in the format '[method]-[pathname]' and the value is the mock's id.
+ * @param {Array<object>} mocks - Array of mock objects. Each should have fileContent with method and url, and an id.
+ * @returns {Object} Map of '[method]-[pathname]' -> mock.id
+ */
+function createMethodPathnameIdMap(mocks) {
+  if (!Array.isArray(mocks)) return {};
+  const map = {};
+  for (const mock of mocks) {
+    if (
+      mock &&
+      mock.id !== undefined &&
+      mock.fileContent &&
+      typeof mock.fileContent.method === "string" &&
+      typeof mock.fileContent.url === "string"
+    ) {
+      const urlObj = (() => {
+        try {
+          return new URL(mock.fileContent.url, "http://localhost");
+        } catch (e) {
+          // fallback: treat as path only
+          return { pathname: mock.fileContent.url };
+        }
+      })();
+      const key = `${mock.fileContent.method.toUpperCase()}-${urlObj.pathname}`;
+      if (!map[key]) {
+        map[key] = [mock.id];
+      } else {
+        map[key].push(mock.id);
+      }
+    }
+  }
+  return map;
+}
+
+/**
+ * Returns a unique key for the given mock in the format '[METHOD]-[pathname]'.
+ * If the URL can't be parsed, uses the raw URL as pathname.
+ * @param {object} mock - The mock object with at least fileContent.method and fileContent.url
+ * @returns {string|null} The key as '[METHOD]-[pathname]', or null if invalid input
+ */
+function getMockKey(options) {
+  if (
+    !options ||
+    !options.method ||
+    !options.url ||
+    typeof options.method !== "string" ||
+    typeof options.url !== "string"
+  ) {
+    return null;
+  }
+  let pathname;
+  try {
+    const urlObj = new URL(options.url, "http://localhost");
+    pathname = urlObj.pathname;
+  } catch (_) {
+    pathname = options.url;
+  }
+  return `${options.method.toUpperCase()}-${pathname}`;
+}
+
 module.exports = {
   charDifference,
   nameToFolder,
@@ -146,4 +222,7 @@ module.exports = {
   getHeaders,
   countFilesInDirectory,
   getTestByName,
+  createIdMap,
+  createMethodPathnameIdMap,
+  getMockKey,
 };

package/src/file-utils.js

@@ -7,8 +7,43 @@ const saveIfItIsFile = async (route, testName, ftmocksConifg) => {
 
   // Check if URL contains file extension like .js, .png, .css etc
   const fileExtMatch = urlObj.pathname.match(/\.[a-zA-Z0-9]+$/);
-  if (fileExtMatch) {
-    const fileExt = fileExtMatch[0];
+  // Check mime type if extension is not present
+  let fileExt = null;
+  if (!fileExtMatch) {
+    // Try to get extension from content-type header
+    const response = await route.fetch();
+    const contentType = response.headers()["content-type"];
+    if (contentType) {
+      // Map common mime types to extensions
+      const mimeToExt = {
+        "image/png": ".png",
+        "image/jpeg": ".jpg",
+        "image/jpg": ".jpg",
+        "image/gif": ".gif",
+        "image/webp": ".webp",
+        "image/svg+xml": ".svg",
+        "application/javascript": ".js",
+        "application/x-javascript": ".js",
+        "text/javascript": ".js",
+        "text/css": ".css",
+        "font/woff": ".woff",
+        "font/woff2": ".woff2",
+        "font/ttf": ".ttf",
+        "audio/mpeg": ".mp3",
+        "audio/wav": ".wav",
+        "video/mp4": ".mp4",
+        "application/pdf": ".pdf",
+      };
+      // Remove any charset, etc.
+      const mime = contentType.split(";")[0].trim();
+      if (mimeToExt[mime]) {
+        fileExt = mimeToExt[mime];
+      }
+    }
+  } else {
+    fileExt = fileExtMatch[0];
+  }
+  if (fileExt) {
     // Create directory path matching URL structure
     const dirPath = path.join(
       getMockDir(ftmocksConifg),
@@ -21,15 +56,14 @@ const saveIfItIsFile = async (route, testName, ftmocksConifg) => {
     fs.mkdirSync(dirPath, { recursive: true });
 
     // Save file with original name
-    const fileName = path.basename(urlObj.pathname);
+    const fileName = `${id}${fileExt}`;
     const filePath = path.join(dirPath, fileName);
 
     const response = await route.fetch();
     const buffer = await response.body();
     fs.writeFileSync(filePath, buffer);
 
-    await route.continue();
-    return true;
+    return fileName;
   }
   return false;
 };

package/src/match-utils.js

@@ -1,6 +1,12 @@
 const { compareMockToFetchRequest } = require("./compare-utils");
 const { getCompareRankMockToFetchRequest } = require("./rank-compare-utils");
-const { getMockDir, nameToFolder } = require("./common-utils");
+const {
+  getMockDir,
+  nameToFolder,
+  createIdMap,
+  createMethodPathnameIdMap,
+  getMockKey,
+} = require("./common-utils");
 const path = require("path");
 const fs = require("fs");
 
@@ -14,11 +20,23 @@ function getMatchingMockData({
   mode,
 }) {
   let served = false;
+  const testMockIdMap = createIdMap(testMockData);
   let matchedMocks =
     testMockData?.filter((mock) => {
       if (mock.fileContent.waitForPrevious && !served) {
         return false;
       }
+      if (mock.fileContent.waitFor) {
+        const waitForMocks = mock.fileContent.waitFor.filter(
+          (waitForMockId) => {
+            const waitForMock = testMockIdMap[waitForMockId];
+            return waitForMock && !waitForMock.fileContent.served;
+          }
+        );
+        if (waitForMocks.length > 0) {
+          return false;
+        }
+      }
       served = mock.fileContent.served;
       return compareMockToFetchRequest(mock, { url, options });
     }) || [];
@@ -89,6 +107,107 @@ function getMatchingMockData({
   return foundMock ? foundMock.fileContent : null;
 }
 
+function getMatchingMockDataV2({
+  testMockData,
+  defaultMockData,
+  url,
+  options,
+  testConfig,
+  testName,
+  mode,
+}) {
+  const testMockIdMap = createIdMap(testMockData);
+  const testMockMethodPathnameMap = createMethodPathnameIdMap(testMockData);
+  const defaultMockIdMap = createIdMap(defaultMockData);
+  const defaultMockMethodPathnameMap =
+    createMethodPathnameIdMap(defaultMockData);
+  const key = getMockKey(options);
+  let matchedMocks = testMockMethodPathnameMap[key] || [];
+  let defaultMatchedMocks = [];
+  const nonWaitForMocks = matchedMocks.filter((mockId) => {
+    const mock = testMockIdMap[mockId];
+    if (mock.fileContent.waitFor) {
+      const waitForMocks = mock.fileContent.waitFor.filter((waitForMockId) => {
+        const waitForMock = testMockIdMap[waitForMockId];
+        return waitForMock && !waitForMock.fileContent.served;
+      });
+      if (waitForMocks.length > 0) {
+        return false;
+      }
+    }
+    return true;
+  });
+  const nonServedMocks = nonWaitForMocks.filter((mockId) => {
+    const mock = testMockIdMap[mockId];
+    return !mock.fileContent.served;
+  });
+  let foundMock = null;
+  if (nonServedMocks.length > 0) {
+    foundMock = testMockIdMap[nonServedMocks[0]];
+  } else if (nonWaitForMocks.length > 0) {
+    foundMock = testMockIdMap[nonWaitForMocks[nonWaitForMocks.length - 1]];
+  }
+  if (!foundMock) {
+    defaultMatchedMocks = defaultMockMethodPathnameMap[key] || [];
+    if (defaultMatchedMocks.length > 0) {
+      foundMock = defaultMockIdMap[defaultMatchedMocks[0]];
+    }
+  }
+  if (!foundMock && mode !== "strict") {
+    const mockRanks = {};
+    matchedMocks.forEach((mockId) => {
+      const mock = testMockIdMap[mockId];
+      const rank = getCompareRankMockToFetchRequest(mock, {
+        url,
+        options,
+      });
+      if (rank > 0) {
+        mockRanks[mock.id] = rank;
+      }
+    });
+    defaultMatchedMocks.forEach((mockId) => {
+      const mock = defaultMockIdMap[mockId];
+      const rank = getCompareRankMockToFetchRequest(mock, {
+        url,
+        options,
+      });
+      if (rank > 0) {
+        mockRanks[mock.id] = rank;
+      }
+    });
+    // Sort by rank to find the best match
+    const sortedRanks = Object.entries(mockRanks).sort((a, b) => a[1] - b[1]);
+    if (sortedRanks.length > 0) {
+      const bestMockId = sortedRanks?.[0]?.[0];
+      if (bestMockId) {
+        foundMock = testMockIdMap[bestMockId] || defaultMockIdMap[bestMockId];
+      }
+    }
+  }
+  // updating stats to mock file
+  if (foundMock) {
+    let mockFilePath = path.join(
+      getMockDir(testConfig),
+      `test_${nameToFolder(testName)}`,
+      `mock_${foundMock.id}.json`
+    );
+    if (!fs.existsSync(mockFilePath)) {
+      mockFilePath = path.join(
+        getMockDir(testConfig),
+        "defaultMocks",
+        `mock_${foundMock.id}.json`
+      );
+    }
+    foundMock.fileContent.served = true;
+    fs.writeFileSync(
+      mockFilePath,
+      JSON.stringify(foundMock.fileContent, null, 2)
+    );
+  }
+  return foundMock ? foundMock.fileContent : null;
+}
+
 module.exports = {
   getMatchingMockData,
+  getMatchingMockDataV2,
 };

package/src/playwright-utils.js

@@ -14,6 +14,8 @@ const crypto = require("crypto");
 const fs = require("fs");
 
 let logger = null;
+const DEFAULT_EXCLUDED_HEADERS =
+  "cookie,set-cookie,authorization,www-authenticate";
 
 async function initiatePlaywrightRoutes(
   page,
@@ -204,6 +206,22 @@ async function initiatePlaywrightRoutes(
   });
 }
 
+const excludeHeaders = (headers, ftmocksConifg) => {
+  const excludedHeaders =
+    ftmocksConifg.EXCLUDED_HEADERS || DEFAULT_EXCLUDED_HEADERS;
+  if (!excludedHeaders) {
+    return headers;
+  }
+  excludedHeaders.split(",").forEach((header) => {
+    Object.keys(headers).forEach((key) => {
+      if (key.toLowerCase() === header.toLowerCase()) {
+        delete headers[key];
+      }
+    });
+  });
+  return headers;
+};
+
 async function recordPlaywrightRoutes(
   page,
   ftmocksConifg,
@@ -231,16 +249,21 @@ async function recordPlaywrightRoutes(
         await createTest(ftmocksConifg, config.testName);
       }
 
-      if (await saveIfItIsFile(route, config.testName, ftmocksConifg)) {
-        return;
-      }
+      const fileName = await saveIfItIsFile(
+        route,
+        config.testName,
+        ftmocksConifg
+      );
 
       const mockData = {
         url: urlObj.pathname + urlObj.search,
         time: new Date().toString(),
         method: route.request().method(),
         request: {
-          headers: await route.request().headers(),
+          headers: excludeHeaders(
+            await route.request().headers(),
+            ftmocksConifg
+          ),
           queryString: Array.from(urlObj.searchParams.entries()).map(
             ([name, value]) => ({
               name,
@@ -255,9 +278,10 @@ async function recordPlaywrightRoutes(
             : null,
         },
         response: {
+          file: fileName,
           status: (await route.fetch()).status(),
           headers: (await route.fetch()).headers(),
-          content: await (await route.fetch()).text(),
+          content: fileName ? null : await (await route.fetch()).text(),
         },
         id: crypto.randomUUID(),
         served: false,