http-snapshotter 0.5.2 → 0.5.3

package/README.md

@@ -62,6 +62,12 @@ Once you are done writing your tests, run your test runner on all your tests and
 
 The tests of this library uses this library itself, check the `tests/` directory and try the tests `npm ci; npm test`.
 
+## Limitations
+
+1. MSW interceptor cannot mock `GET` calls with body. So trying to mock elasticsearch / opensearch `GET /<index>/_search` calls with body breaks. I ended up using `POST` only when unit testing, as `GET` is the right way to use with AWS `AmazonOpenSearchServiceReadOnlyAccess` IAM permission 🤷‍♂️.
+
+2. Stripe SDK uses node http module in a way MSW interceptor cannot mock - [reference](https://github.com/mswjs/msw/issues/2259#issuecomment-2379379566). Solution mentioned in a comment there is to use Stripe SDK with `fetch` client - [reference](https://github.com/mswjs/msw/issues/2259#issuecomment-2422672039). Another workaround is to mock Stripe SDK's methods with your testing library of choice.
+
 ## About snapshot files and its names
 
 A snapshot file name uniquely identifies a request. By default it is a combination of HTTP method + URL + body that makes a request unique (headers are ignored).
@@ -200,3 +206,24 @@ WARNING: This module isn't concurrent or thread safe. Make sure that:
 1. within one worker only one test is being executed at a time. e.g. If you use `ava`, and you have multiple `test()` blocks in one file, you need to change it to run serially with `test.serial()`.
 
 2. parallel tests don't update the same snapshot file at the same time (i.e. while you run with SNAPSHOT=update). Regardless, updating snapshots of multiple tests at the same time is not a great idea in my opinion, because reviewing the snapshots files are a pain, escpecially if you have a shared snapshot files.
+
+## Ignoring requests from snapshots
+
+Sometimes you may want certain requests to not be snapshotted (e.g., file uploads to S3 / object storage) so that you can layer function / result snapshotting on top. Use `attachSnapshotIgnoreRules()` to provide a function that determines which requests should be ignored:
+
+```js
+import { attachSnapshotIgnoreRules, resetSnapshotIgnoreRules } from "http-snapshotter";
+
+// Ignore analytics and health check requests
+attachSnapshotIgnoreRules((request) => {
+  const url = new URL(request.url);
+  return url.hostname.includes('/upload');
+});
+
+// Reset to default (no requests ignored)
+resetSnapshotIgnoreRules();
+```
+
+**Behavior varies by mode:**
+- `SNAPSHOT=update/append`: Ignored requests make real network calls but don't create snapshots
+- `SNAPSHOT=read`: Ignored requests throw an error (tests shouldn't make real network calls)

package/index.js

@@ -16,6 +16,10 @@
  * You can use SNAPSHOT=ignore to neither read not write snapshots, for testing on real
  * network operations.
  * 
+ * To ignore specific requests from being snapshotted in SNAPSHOT=update or SNAPSHOT=append mode,
+ * use attachSnapshotIgnoreRules() to provide a function that receives the request object and
+ * returns true if the request should be ignored from snapshotting.
+ * 
  * Log read/saved snapshots by setting LOG_SNAPSHOT=1 env variable.
  *
  * Unused snapshot files will be written into a log file named 'unused-snapshots.log'.
@@ -135,6 +139,15 @@ async function defaultSnapshotFileNameGenerator(request) {
   };
 }
 
+/**
+ * Default snapshot ignore rules - by default no requests are ignored
+ * @param {Request} request 
+ * @returns {boolean}
+ */
+function defaultSnapshotIgnoreRules(request) {
+  return false;
+}
+
 // Dynamically changeable props
 /**
  * @type {(req: Request) => Promise<{ filePrefix: string, fileSuffixKey: string }>}
@@ -142,6 +155,11 @@ async function defaultSnapshotFileNameGenerator(request) {
 let snapshotFileNameGenerator = defaultSnapshotFileNameGenerator;
 let snapshotSubDirectory = '';
 
+/**
+ * @type {(req: Request) => boolean}
+ */
+let snapshotIgnoreRules = defaultSnapshotIgnoreRules;
+
 /**
  * @typedef SnapshotFileInfo
  * @property {string} absoluteFilePath
@@ -595,6 +613,36 @@ function resetSnapshotFilenameGenerator() {
   snapshotFileNameGenerator = defaultSnapshotFileNameGenerator;
 }
 
+/**
+ * Attach snapshot ignore rules function
+ * 
+ * Here's your opportunity to define custom rules for ignoring requests from being snapshotted.
+ * The function receives the Request object and should return true if the request should be ignored.
+ *
+ * IMPORTANT: Behavior varies by SNAPSHOT mode:
+ * - SNAPSHOT=update/append: Ignored requests make real network calls but don't create snapshots
+ * - SNAPSHOT=read: Ignored requests throw an error (tests shouldn't make real network calls)
+ *
+ * Use cases (not limited to):
+ * 1. Ignore requests with specific headers (e.g., x-debug-mode: no-snapshot)
+ * 2. Ignore requests to specific URLs or domains
+ * 3. Ignore requests with specific HTTP methods
+ * 4. Ignore requests based on request body content
+ *
+ * WARNING: Attaching a function on a per-test basis may not be concurrent safe. i.e. If your tests
+ * run sequentially, then it is safe. But if your test runner runs test suites concurrently,
+ * then it is better to attach a function only once ever.
+ * @param {(req: Request) => boolean} func
+ */
+function attachSnapshotIgnoreRules(func) {
+  snapshotIgnoreRules = func;
+}
+
+/** Reset snapshot ignore rules to default (no requests ignored) */
+function resetSnapshotIgnoreRules() {
+  snapshotIgnoreRules = defaultSnapshotIgnoreRules;
+}
+
 /**
  * Start the interceptor
  * @param {object} opts
@@ -621,10 +669,35 @@ function start({
   });
 
   const cache = /** @type {WeakMap<Request, SnapshotFileInfo>} */ (new WeakMap());
+  const ignoredRequests = /** @type {WeakSet<Request>} */ (new WeakSet());
 
   //@ts-ignore
   interceptor.on('request', async ({ request, controller }) => {
-    if (['read', 'append'].includes(SNAPSHOT)) {
+    // Check if request should be ignored from snapshotting using ignore rules
+    const shouldIgnoreSnapshot = snapshotIgnoreRules(request);
+    
+    // Track ignored requests
+    if (shouldIgnoreSnapshot) {
+      ignoredRequests.add(request);
+      
+      // In read mode, we should not allow ignored requests to make real network calls
+      if (SNAPSHOT === 'read') {
+        console.error(
+          `${colors.red}Request ignored by snapshot ignore rules but SNAPSHOT=read mode doesn't allow real network requests:${colors.reset}`,
+          {
+            request: {
+              url: request.url,
+              method: request.method,
+              headers: Object.fromEntries([...request.headers.entries()]),
+              body: await request.clone().text(),
+            }
+          }
+        );
+        throw new Error('Request ignored by snapshot ignore rules but SNAPSHOT=read mode doesn\'t allow real network requests');
+      }
+    }
+    
+    if (['read', 'append'].includes(SNAPSHOT) && !shouldIgnoreSnapshot) {
       const snapshotFileInfo = await getSnapshotFileInfo(request);
       cache.set(request, snapshotFileInfo);
       await readSnapshotAndSendResponse(request, controller, snapshotFileInfo);
@@ -635,15 +708,23 @@ function start({
     'response',
     /** @type {(params: { request: Request, response: Response }) => Promise<void>} */
     async ({ request, response }) => {
+      // Check if this request was marked to ignore snapshots
+      const shouldIgnoreSnapshot = ignoredRequests.has(request);
+      
       const snapshotFileInfo = cache.get(request) || (await getSnapshotFileInfo(request));
       cache.delete(request);
+      
       const {
         // absoluteFilePath,
         fileName,
         fileSuffixKey,
       } = snapshotFileInfo;
       if (LOG_REQ) {
-        const summary = `----------\n${request.method} ${request.url}\nWould use file name: ${fileName}`;
+        const summary = `----------\n${request.method} ${request.url}\n${
+          shouldIgnoreSnapshot
+            ? 'ignored from snapshotting by ignore rules'
+            : `Would use file name: ${fileName}`
+        }`;
         if (LOG_REQ === '1' || LOG_REQ === 'summary') {
           console.debug(summary);
         } else if (LOG_REQ === 'detailed') {
@@ -664,7 +745,7 @@ function start({
           });
         }
       }
-      if (SNAPSHOT === 'update' || (SNAPSHOT === 'append' && !readFiles.has(fileName))) {
+      if (!shouldIgnoreSnapshot && (SNAPSHOT === 'update' || (SNAPSHOT === 'append' && !readFiles.has(fileName)))) {
         if (!dirCreatePromise) {
           dirCreatePromise = fs.mkdir( /** @type {string} */(snapshotDirectory), { recursive: true });
         }
@@ -691,6 +772,9 @@ module.exports = {
   defaultSnapshotFileNameGenerator,
   attachSnapshotFilenameGenerator,
   resetSnapshotFilenameGenerator,
+  defaultSnapshotIgnoreRules,
+  attachSnapshotIgnoreRules,
+  resetSnapshotIgnoreRules,
   start,
   stop,
 };

package/intercept.js

@@ -0,0 +1,78 @@
+/*
+ * This function was created with a realization that once you override a method for mocking
+ * and run a test, you can't undo the override, because shared code (test runner without
+ * test isolation) will hold on to closures to the overridden function.
+ *
+ * So a solution it to intercept once before all tests, mock for a test and "undoMock()" at
+ * end of a test will cause the intercept to "proxy" future calls to the original method.
+ */
+
+const mocked = new Set();
+
+/**
+ * Extracts the keys of an object where the values of the keys are functions.
+ * @template T The object type.
+ * @typedef {Extract<
+ *   keyof T,
+ *   { [K in keyof T]: T[K] extends Function ? K : never }[keyof T]
+ * >} FunctionKeys
+ */
+
+/**
+ * @template T
+ * @template {FunctionKeys<T>} K
+ * @param {T} object
+ * @param {K} methodName
+ */
+function intercept(object, methodName) {
+  let mockHandler = null;
+  const originalMethod = object[methodName];
+  // @ts-ignore
+  const boundedMethod = object[methodName].bind(object);
+
+  // @ts-ignore
+  // eslint-disable-next-line no-param-reassign
+  object[methodName] = function interceptedFunction(...args) {
+    return mockHandler
+      ? mockHandler(boundedMethod, ...args)
+      // @ts-ignore
+      : originalMethod.apply(object, args);
+  };
+
+  return {
+    /**
+     * @param {(originalMethod: T[K], ...args: Parameters<T[K]>) => any} mockFunction
+     */
+    mock(mockFunction) {
+      mockHandler = mockFunction;
+      mocked.add(this);
+    },
+    undoMock() {
+      mockHandler = null;
+      mocked.delete(this);
+    },
+    /**
+     * Un-intercepting will not get rid of closures to interceptedFunction
+     */
+    destroy() {
+      mockHandler = null;
+      // eslint-disable-next-line no-param-reassign
+      object[methodName] = originalMethod;
+    },
+  };
+}
+
+function undoAllMocks() {
+  [...mocked].forEach((methods) => methods.undoMock());
+}
+
+const interceptAllMethods = (object) => Object.fromEntries(
+  Object
+    .keys(object)
+    .filter((key) => typeof object[key] === 'function')
+    .map(
+      (key) => [key, intercept(object, key)],
+    ),
+);
+
+module.exports = { intercept, undoAllMocks, interceptAllMethods };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "http-snapshotter",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "description": "Snapshot HTTP requests for tests (node.js)",
   "main": "index.js",
   "types": "index.d.ts",
@@ -9,6 +9,9 @@
     "require": "./index.js",
     "types": "./index.d.ts"
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "test": "tape tests/**/*.test.* | tap-arc",
     "tsc": "tsc"