http-snapshotter 0.2.3 → 0.3.0

package/README.md

@@ -53,6 +53,8 @@ There is also a `SNAPSHOT=ignore` option to neither read nor write from snapshot
 
 Tip: When you do `SNAPSHOT=update` to create snapshots, run it against a single test, so you know what exact snapshots that one test created/updated.
 
+Log read/saved snapshots by setting LOG_SNAPSHOT=1 env variable. Log requests with LOG_REQ=1 or LOG_REQ=summary (to just print request HTTP method, url and snapshot file that it would use).
+
 Once you are done writing your tests, run your test runner on all your tests and then take a look at `<snapshots directory>/unused-snapshots.log` file to see which snapshot files haven't been used by your final test suite. You can delete unused snapshot files.
 
 The tests of this library uses this library itself, check the `tests/` directory and try the tests `npm ci; npm test`.
@@ -116,44 +118,42 @@ There are scenarios where one needs to test varied response for the same call (e
 
 There are 2 ways to go about this:
 
-Method 1: The easy way it to not touch the existing snapshot file, and use `attachResponseTransformer` to
-change the response on runtime for the specific test:
+Method 1: The easy way is to [intercept the function](https://gist.github.com/Munawwar/c1d024d20b78f19b3714ab09b62a0e1f) with your other test utilities:
 
 ```js
-import {
-  // ...
-  attachResponseTransformer,
-  resetResponseTransformer,
-} from "http-snapshotter";
+// setupIntercepts.js
+// Using intercept.js (https://gist.github.com/Munawwar/c1d024d20b78f19b3714ab09b62a0e1f)
+// Write all your intercepts in a single file for all tests.
+// This is safe because the default behavior of an intercept is
+// to call the original function.
+import { intercept } from "./intercept.js";
+import methods from './account.js';
+// intercept the get() method
+export const accountGet = intercept(methods, 'get');
+
+// test.js
+import { accountGet } from './setupIntercepts.js';
+// Next import the root function that you want to test, which
+// internally calls get() function from './account.js'
+import { enablePaidFeature } from './routes.js';
 
 test('Test behavior on a free account', async (t) => {
-  /**
-   * @param {Response} response https://developer.mozilla.org/en-US/docs/Web/API/Response
-   * @param {Request} request https://developer.mozilla.org/en-US/docs/Web/API/Request
-   */
-  const interceptResponse = async (response, request) => {
-    const url = new URL(request.url);
-    if (request.method === 'GET' && url.pathname === '/account') {
-      return new Response(
-        JSON.stringify({
-          ...(await response.clone().json()),
-          free_user: true,
-        }),
-        {
-          headers: response.headers
-        }
-      )
-    }
- 
-    return response;
-  };
-  attachResponseTransformer(interceptResponse);
+  // Setup mock to simulate a free user
+  accountGet.mock(async (originalAccountGetFunction, ...args) => {
+    const result = await originalAccountGetFunction(...args); // this will use the existing http snapshot
+    return {
+      ...result,
+      free_user: true,
+    };
+  });
 
-  // make fetch() call here
-  // assert the test
+  // write the test here
+  // t.assert(await enablePaidFeature(), { error: 'Free accounts do not have access to this paid feature' })
 
-  // cleanup before moving to next test
-  resetResponseTransformer();
+  // cleanup before moving to next test by calling undoMock()
+  // This won't destroy the intercept, but will revert the account get()
+  // function to call the original account get() function
+  accountGet.undoMock();
 });
 ```
 

package/index.d.ts

@@ -1,12 +1,13 @@
 export type SnapshotText = {
-    responseType: 'text';
     fileSuffixKey: string;
+    requestType: 'json' | 'text';
     request: {
         method: string;
         url: string;
         headers: string[][];
-        body: string | undefined;
+        body: string | object | undefined;
     };
+    responseType: 'text';
     response: {
         status: number;
         statusText: string;
@@ -15,14 +16,15 @@ export type SnapshotText = {
     };
 };
 export type SnapshotJson = {
-    responseType: 'json';
     fileSuffixKey: string;
+    requestType: 'json' | 'text';
     request: {
         method: string;
         url: string;
         headers: string[][];
-        body: string | undefined;
+        body: string | object | undefined;
     };
+    responseType: 'json';
     response: {
         status: number;
         statusText: string;
@@ -31,6 +33,11 @@ export type SnapshotJson = {
     };
 };
 export type Snapshot = SnapshotText | SnapshotJson;
+export type ReadSnapshotReturnType = Promise<{
+    snapshot: Snapshot;
+    absoluteFilePath: string;
+    fileName: string;
+}>;
 export type ClientRequestInterceptorType = import('@mswjs/interceptors/ClientRequest').ClientRequestInterceptor;
 export type FetchInterceptorType = import('@mswjs/interceptors/fetch').FetchInterceptor;
 /**
@@ -66,20 +73,6 @@ export function attachSnapshotFilenameGenerator(func: (req: Request) => Promise<
 }>): void;
 /** Reset snapshot filename generator to default */
 export function resetSnapshotFilenameGenerator(): void;
-/**
- * Attach response transformer function.
- *
- * Here is an opportunity to modify the response (loaded from snapshot) on-the-fly right before
- * the response is sent to consumers.
- *
- * WARNING: Attaching a function on a per-test basis may not be concurrent safe. i.e. If you 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 {(response: Response, request: Request) => Promise<Response>} func
- */
-export function attachResponseTransformer(func: (response: Response, request: Request) => Promise<Response>): void;
-/** Reset response transformer */
-export function resetResponseTransformer(): void;
 /**
  * Start the interceptor
  * @param {object} opts

package/index.js

@@ -13,11 +13,13 @@
  * Here onwards run test runner without SNAPSHOT env variable or SNAPSHOT=read
  * You can use SNAPSHOT=ignore to neither read not write snapshots, for testing on real
  * network operations.
+ * 
+ * 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'.
  * You can delete those files manually.
- *
- * Log requests with LOG_REQ=1 env variable
+ * 
+ * Log requests with LOG_REQ=1 or LOG_REQ=summary (to just print summary) env variable
  * or node.js built-in NODE_DEBUG=http,http2
  *
  * More docs at the end of this file, find the exported methods.
@@ -33,7 +35,7 @@ const { resolve } = require('node:path');
 
 // Environment variable SNAPSHOT = update / ignore / read (default)
 const SNAPSHOT = process.env.SNAPSHOT || 'read';
-const LOG_REQ = process.env.LOG_REQ === '1' || process.env.LOG_REQ === 'true';
+const { LOG_REQ, LOG_SNAPSHOT } = process.env;
 const unusedSnapshotsLogFile = 'unused-snapshots.log';
 /**
  * @type {import("node:fs").PathLike | null}
@@ -77,8 +79,6 @@ let snapshotDirectory = null;
  * @typedef {SnapshotText | SnapshotJson} Snapshot
  */
 
-/** @type {(res: any) => any} */
-const identity = (response) => response;
 
 const defaultKeyDerivationProps = ['method', 'url', 'body'];
 /**
@@ -110,10 +110,6 @@ async function defaultSnapshotFileNameGenerator(request) {
 }
 
 // Dynamically changeable props
-/**
- * @type {(response: Response, request: Request) => Promise<Response>}
- */
-let responseTransformer = identity;
 /**
  * @type {(req: Request) => Promise<{ filePrefix: string, fileSuffixKey: string }>}
  */
@@ -159,13 +155,16 @@ const readFiles = new Set();
  */
 async function saveSnapshot(request, response) {
   const { absoluteFilePath, fileName, fileSuffixKey } = await getSnapshotFileName(request);
-  // console.log(fileName);
 
   // Prevent multiple tests from having same snapshot
   if (alreadyWrittenFiles.has(absoluteFilePath)) {
     return /** @type {ReadSnapshotReturnType} */ (alreadyWrittenFiles.get(absoluteFilePath));
   }
 
+  if (LOG_SNAPSHOT) {
+    console.debug('Writing:', fileName);
+  }
+
   /** @returns {ReadSnapshotReturnType} */
   const saveFreshSnapshot = async () => {
     let requestBody;
@@ -238,9 +237,11 @@ const snapshotCache = {};
  */
 async function readSnapshot(request) {
   const { absoluteFilePath, fileName, fileSuffixKey } = await getSnapshotFileName(request);
-  // console.log(fileName);
 
   if (!snapshotCache[absoluteFilePath]) {
+    if (LOG_SNAPSHOT) {
+      console.debug('Reading:', fileName);
+    }
     let json;
     try {
       json = await fs.readFile(absoluteFilePath, 'utf-8');
@@ -256,8 +257,8 @@ async function readSnapshot(request) {
             headers: Object.fromEntries([...request.headers.entries()]),
             body: reqBody,
           },
-          wouldBeFileSuffixKey: fileSuffixKey,
-          wouldBeFileName: fileName,
+          fileName,
+          fileSuffixKey,
         });
         throw new Error('Network request not mocked');
       } else {
@@ -289,7 +290,7 @@ async function sendResponse(request, snapshot) {
     },
   } = snapshot;
 
-  let newResponse = new Response(
+  const newResponse = new Response(
     responseType === 'json'
       ? JSON.stringify(body)
       : /** @type {string} */ (body),
@@ -300,8 +301,6 @@ async function sendResponse(request, snapshot) {
     },
   );
 
-  newResponse = await responseTransformer(newResponse, request);
-
   // respondWith is a method added by @mswjs/interceptors
   // @ts-ignore
   request.respondWith(newResponse);
@@ -395,26 +394,6 @@ function resetSnapshotFilenameGenerator() {
   snapshotFileNameGenerator = defaultSnapshotFileNameGenerator;
 }
 
-/**
- * Attach response transformer function.
- * 
- * Here is an opportunity to modify the response (loaded from snapshot) on-the-fly right before
- * the response is sent to consumers.
- *
- * WARNING: Attaching a function on a per-test basis may not be concurrent safe. i.e. If you 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 {(response: Response, request: Request) => Promise<Response>} func
- */
-function attachResponseTransformer(func) {
-  responseTransformer = func;
-}
-
-/** Reset response transformer */
-function resetResponseTransformer() {
-  responseTransformer = identity;
-}
-
 /**
  * Start the interceptor
  * @param {object} opts
@@ -453,16 +432,26 @@ function start({
     async ({ request, response }) => {
       if (LOG_REQ) {
         const { fileName, fileSuffixKey } = await getSnapshotFileName(request);
-        console.debug('Request', {
-          request: {
-            url: request.url,
-            method: request.method,
-            headers: Object.fromEntries([...request.headers.entries()]),
-            body: await request.clone().text(),
-          },
-          wouldBeFileName: fileName,
-          wouldBeFileSuffixKey: fileSuffixKey,
-        });
+        const summary = `----------\n${request.method} ${request.url}\nWould use file name: ${fileName}`;
+        if (LOG_REQ === 'summary') {
+          console.debug(summary);
+        } else {
+          console.debug(`${summary}\n----------\n`, {
+            request: {
+              url: request.url,
+              method: request.method,
+              headers: Object.fromEntries([...request.headers.entries()]),
+              body: await request.clone().text(),
+            },
+            response: {
+              status: response.status,
+              statusText: response.statusText,
+              headers: Object.fromEntries([...response.headers.entries()]),
+              body: await response.clone().text(),
+            },
+            wouldUseFileSuffixKey: fileSuffixKey,
+          });
+        }
       }
       if (SNAPSHOT === 'update') {
         if (!dirCreatePromise) {
@@ -489,8 +478,6 @@ module.exports = {
   defaultSnapshotFileNameGenerator,
   attachSnapshotFilenameGenerator,
   resetSnapshotFilenameGenerator,
-  attachResponseTransformer,
-  resetResponseTransformer,
   start,
   stop,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "http-snapshotter",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "Snapshot HTTP requests for tests (node.js)",
   "main": "index.cjs",
   "types": "index.d.ts",