http-snapshotter 0.2.4 → 0.3.1

package/README.md

@@ -49,9 +49,9 @@ You will see a file named `get-xkcd-com-info-0-arAlFb5gfcr9aCN.json` created in
 Then onwards running: `node test.js` or `SNAPSHOT=read node test.js` will ensure HTTP network calls are all read from a snapshot file.
 In this mode, http-snapshotter will prevent any real HTTP calls from happening by failing the test (if it didn't have a snapshot file) and print out the request details and the snapshot file name it should have had.
 
-There is also a `SNAPSHOT=ignore` option to neither read nor write from snapshot files and do real network requests instead. This could be useful while writing a new test.
+For adding new snapshots without touching existing snapshots use `SNAPSHOT=append`. There is also a `SNAPSHOT=ignore` option to neither read nor write from snapshot files and do real network requests instead. These could be useful while writing a new test.
 
-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.
+Tip: When you do `SNAPSHOT=update` or `SNAPHOT=append` 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).
 
@@ -118,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

@@ -10,7 +10,9 @@
  * SNAPSHOT=update <test runner command>
  * e.g. SNAPSHOT=update tape tests/**\/*.js | tap-diff
  *
- * Here onwards run test runner without SNAPSHOT env variable or SNAPSHOT=read
+ * Here onwards run test runner without SNAPSHOT env variable or SNAPSHOT=read.
+ * For adding new snapshots without touching existing snapshots use SNAPSHOT=append.
+ *
  * You can use SNAPSHOT=ignore to neither read not write snapshots, for testing on real
  * network operations.
  * 
@@ -33,7 +35,7 @@ const { createHash } = require('node:crypto');
 const { promises: fs } = require('node:fs');
 const { resolve } = require('node:path');
 
-// Environment variable SNAPSHOT = update / ignore / read (default)
+// Environment variable SNAPSHOT = update / append / ignore / read (default)
 const SNAPSHOT = process.env.SNAPSHOT || 'read';
 const { LOG_REQ, LOG_SNAPSHOT } = process.env;
 const unusedSnapshotsLogFile = 'unused-snapshots.log';
@@ -79,8 +81,6 @@ let snapshotDirectory = null;
  * @typedef {SnapshotText | SnapshotJson} Snapshot
  */
 
-/** @type {(res: any) => any} */
-const identity = (response) => response;
 
 const defaultKeyDerivationProps = ['method', 'url', 'body'];
 /**
@@ -112,10 +112,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 }>}
  */
@@ -255,6 +251,7 @@ async function readSnapshot(request) {
       // Fail any test that fires a real network request (without snapshot)
       // @ts-ignore
       if (err.code === 'ENOENT') {
+        if (SNAPSHOT === 'append') return {};
         const reqBody = await request.clone().text();
         console.error('No network snapshot found for request with cache keys:', {
           request: {
@@ -296,7 +293,7 @@ async function sendResponse(request, snapshot) {
     },
   } = snapshot;
 
-  let newResponse = new Response(
+  const newResponse = new Response(
     responseType === 'json'
       ? JSON.stringify(body)
       : /** @type {string} */ (body),
@@ -307,8 +304,6 @@ async function sendResponse(request, snapshot) {
     },
   );
 
-  newResponse = await responseTransformer(newResponse, request);
-
   // respondWith is a method added by @mswjs/interceptors
   // @ts-ignore
   request.respondWith(newResponse);
@@ -320,7 +315,10 @@ async function sendResponse(request, snapshot) {
  */
 async function readSnapshotAndSendResponse(request) {
   const { snapshot } = await readSnapshot(request);
-  return sendResponse(request, snapshot);
+  if (snapshot) {
+    return sendResponse(request, snapshot);
+  }
+  return undefined;
 }
 
 /**
@@ -402,26 +400,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
@@ -449,7 +427,7 @@ function start({
 
   // @ts-ignore
   interceptor.on('request', async ({ request }) => {
-    if (SNAPSHOT === 'read') {
+    if (['read', 'append'].includes(SNAPSHOT)) {
       await readSnapshotAndSendResponse(request);
     }
   });
@@ -458,8 +436,8 @@ function start({
     'response',
     /** @type {(params: { request: Request, response: Response }) => Promise<void>} */
     async ({ request, response }) => {
+      const { fileName, fileSuffixKey } = await getSnapshotFileName(request);
       if (LOG_REQ) {
-        const { fileName, fileSuffixKey } = await getSnapshotFileName(request);
         const summary = `----------\n${request.method} ${request.url}\nWould use file name: ${fileName}`;
         if (LOG_REQ === 'summary') {
           console.debug(summary);
@@ -481,7 +459,7 @@ function start({
           });
         }
       }
-      if (SNAPSHOT === 'update') {
+      if (SNAPSHOT === 'update' || (SNAPSHOT === 'append' && !readFiles.has(fileName))) {
         if (!dirCreatePromise) {
           dirCreatePromise = fs.mkdir( /** @type {string} */(snapshotDirectory), { recursive: true });
         }
@@ -506,8 +484,6 @@ module.exports = {
   defaultSnapshotFileNameGenerator,
   attachSnapshotFilenameGenerator,
   resetSnapshotFilenameGenerator,
-  attachResponseTransformer,
-  resetResponseTransformer,
   start,
   stop,
 };

package/package.json

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