ftmocks-utils 1.3.3 → 1.3.5

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.3",
+  "version": "1.3.5",
   "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

@@ -0,0 +1,73 @@
+const path = require("path");
+const fs = require("fs");
+const { getMockDir, nameToFolder } = require("./common-utils");
+
+const saveIfItIsFile = async (route, testName, ftmocksConifg) => {
+  const urlObj = new URL(route.request().url());
+
+  // Check if URL contains file extension like .js, .png, .css etc
+  const fileExtMatch = urlObj.pathname.match(/\.[a-zA-Z0-9]+$/);
+  // 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),
+      `test_${nameToFolder(testName)}`,
+      "_files",
+      path.dirname(urlObj.pathname)
+    );
+
+    // Create directories if they don't exist
+    fs.mkdirSync(dirPath, { recursive: true });
+
+    // Save file with original name
+    const fileName = `${id}${fileExt}`;
+    const filePath = path.join(dirPath, fileName);
+
+    const response = await route.fetch();
+    const buffer = await response.body();
+    fs.writeFileSync(filePath, buffer);
+
+    return fileName;
+  }
+  return false;
+};
+
+module.exports = {
+  saveIfItIsFile,
+};