feat(plugin): allow to transform entries before saving a HAR (#182)

You can modify the entries before saving the HAR by using the
`transform` option. This option should be set to a path to a module that
exports a function, similar to the filter option, to change the Entry
object as desired.

```js
cy.recordHar({ transform: '../support/remove-sensitive-data.ts' });
```

Here's a simple example of what the `remove-sensitive-data.ts` module
might look like:

```ts
import { Entry } from 'har-format';

const PASSWORD_REGEXP = /("password":\s*")\w+("\s*)/;

export default async (entry: Entry) => {
  try {
    // Remove sensitive information from the request body
    if (entry.request.postData?.text) {
      entry.request.postData.text = entry.request.postData.text.replace(
        PASSWORD_REGEXP,
        '$1***$2'
      );
    }

    return entry;
  } catch {
    return entry;
  }
};
```


In this example, the transform function will replace any instances of
password with `***` in both the request and response bodies of each
entry.


closes #174

README.md

@@ -242,10 +242,44 @@ export default async (entry: Entry) => {
 };
 ```
 
-> ✴ The plugin also supports files with `.js`, `.mjs` and `.cjs` extensions.
-
 In this example, the `filter` function will only exclude entries in the HAR where the request body contains a JSON object with a password field.
 
+You can also modify the entries before saving the HAR by using the `transform` option. This option should be set to a path to a module that exports a function, similar to the filter option, to change the Entry object as desired.
+
+```js
+cy.recordHar({ transform: '../support/remove-sensitive-data.ts' });
+```
+
+Here's a simple example of what the `remove-sensitive-data.ts` module might look like:
+
+```ts
+import { Entry } from 'har-format';
+
+const PASSWORD_REGEXP = /("password":\s*")\w+("\s*)/;
+
+export default async (entry: Entry) => {
+  try {
+    // Remove sensitive information from the request body
+    if (entry.request.postData?.text) {
+      entry.request.postData.text = entry.request.postData.text.replace(
+        PASSWORD_REGEXP,
+        '$1***$2'
+      );
+    }
+
+    return entry;
+  } catch {
+    return entry;
+  }
+};
+```
+
+The function should take an Entry object as a parameter and return the modified.
+
+In this example, the transform function will replace any occurrences of password with `***` in the request body of each entry.
+
+> ✴ The plugin also supports files with `.js`, `.mjs` and `.cjs` extensions.
+
 By default, the path is relative to the spec folder. But by providing a `rootDir` it will look for the module in the provided directory:
 
 ```js

cypress/e2e/record-har.cy.ts

@@ -41,6 +41,24 @@ describe('Record HAR', () => {
     })
   );
 
+  ['.js', '.ts', '.cjs'].forEach(ext =>
+    it(`transforms a request using the custom postprocessor from ${ext} file`, () => {
+      cy.recordHar({ transform: `../fixtures/transform${ext}` });
+
+      cy.get('a[href$=fetch]').click();
+
+      cy.saveHar({ waitForIdle: true });
+
+      cy.findHar()
+        .its('log.entries')
+        .should('contain.something.like', {
+          response: {
+            content: { text: /\{"items":\[/ }
+          }
+        });
+    })
+  );
+
   it('excludes a request by its path', () => {
     cy.recordHar({ excludePaths: [/^\/api\/products$/, '^\\/api\\/users$'] });
 

cypress/fixtures/filter.cjs

@@ -1,6 +1,6 @@
-module.exports = async req => {
+module.exports = async entry => {
   try {
-    return /\{"products":\[/.test(req.response.content.text ?? '');
+    return /\{"products":\[/.test(entry.response.content.text ?? '');
   } catch {
     return false;
   }

cypress/fixtures/filter.js

@@ -1,6 +1,6 @@
-module.exports = async req => {
+module.exports = async entry => {
   try {
-    return /\{"products":\[/.test(req.response.content.text ?? '');
+    return /\{"products":\[/.test(entry.response.content.text ?? '');
   } catch {
     return false;
   }

cypress/fixtures/filter.mjs

@@ -1,6 +1,6 @@
-export default async req => {
+export default async entry => {
   try {
-    return /\{"products":\[/.test(req.response.content.text ?? '');
+    return /\{"products":\[/.test(entry.response.content.text ?? '');
   } catch {
     return false;
   }

cypress/fixtures/filter.ts

@@ -1,8 +1,8 @@
 import { Entry } from 'har-format';
 
-export default async (req: Entry) => {
+export default async (entry: Entry) => {
   try {
-    return /\{"products":\[/.test(req.response.content.text ?? '');
+    return /\{"products":\[/.test(entry.response.content.text ?? '');
   } catch {
     return false;
   }

cypress/fixtures/transform.cjs

@@ -0,0 +1,19 @@
+module.exports = async entry => {
+  try {
+    if (entry.response.content?.text) {
+      entry.response.content = {
+        ...entry.response.content,
+        text: entry.response.content.text.replace(
+          /"products":\s*(.+)/g,
+          `"items":$1`
+        )
+      };
+    }
+
+    return entry;
+  } catch {
+    return entry;
+  }
+};
+
+

cypress/fixtures/transform.js

@@ -0,0 +1,17 @@
+module.exports = async entry => {
+  try {
+    if (entry.response.content?.text) {
+      entry.response.content = {
+        ...entry.response.content,
+        text: entry.response.content.text.replace(
+          /"products":\s*(.+)/g,
+          `"items":$1`
+        )
+      };
+    }
+
+    return entry;
+  } catch {
+    return entry;
+  }
+};

cypress/fixtures/transform.mjs

@@ -0,0 +1,17 @@
+export async entry => {
+  try {
+    if (entry.response.content?.text) {
+      entry.response.content = {
+        ...entry.response.content,
+        text: entry.response.content.text.replace(
+          /"products":\s*(.+)/g,
+          `"items":$1`
+        )
+      };
+    }
+
+    return entry;
+  } catch {
+    return entry;
+  }
+};

cypress/fixtures/transform.ts

@@ -0,0 +1,19 @@
+import { Entry } from 'har-format';
+
+export default async (entry: Entry) => {
+  try {
+    if (entry.response.content?.text) {
+      entry.response.content = {
+        ...entry.response.content,
+        text: entry.response.content.text.replace(
+          /"products":\s*(.+)/g,
+          `"items":$1`
+        )
+      };
+    }
+
+    return entry;
+  } catch {
+    return entry;
+  }
+};

src/Plugin.spec.ts

@@ -1,7 +1,7 @@
 import type { RecordOptions, SaveOptions } from './Plugin';
 import { Plugin } from './Plugin';
-import { Logger } from './utils/Logger';
-import { FileManager } from './utils/FileManager';
+import type { Logger } from './utils/Logger';
+import type { FileManager } from './utils/FileManager';
 import type {
   Observer,
   ObserverFactory,

src/Plugin.ts

@@ -5,7 +5,8 @@ import type {
   HarExporterFactory,
   NetworkObserverOptions,
   Observer,
-  ObserverFactory
+  ObserverFactory,
+  HarExporterOptions
 } from './network';
 import { HarBuilder, NetworkIdleMonitor, NetworkRequest } from './network';
 import { ErrorUtils } from './utils/ErrorUtils';
@@ -25,10 +26,7 @@ export interface SaveOptions {
   waitForIdle?: boolean;
 }
 
-export type RecordOptions = NetworkObserverOptions & {
-  rootDir: string;
-  filter?: string;
-};
+export type RecordOptions = NetworkObserverOptions & HarExporterOptions;
 
 interface Addr {
   port: number;
@@ -81,10 +79,7 @@ export class Plugin {
       );
     }
 
-    this.exporter = await this.exporterFactory.create({
-      predicatePath: options.filter,
-      rootDir: options.rootDir
-    });
+    this.exporter = await this.exporterFactory.create(options);
     this._connection = this.connectionFactory.create({
       ...this.addr,
       maxRetries: 20,

src/cdp/DefaultNetwork.ts

@@ -1,6 +1,6 @@
 import type { Network, NetworkEvent } from '../network';
 import { ErrorUtils } from '../utils/ErrorUtils';
-import { Logger } from '../utils/Logger';
+import type { Logger } from '../utils/Logger';
 import {
   TARGET_OR_BROWSER_CLOSED,
   UNABLE_TO_ATTACH_TO_TARGET

src/index.ts

@@ -22,7 +22,7 @@ const plugin = new Plugin(
   FileManager.Instance,
   new DefaultConnectionFactory(Logger.Instance),
   new DefaultObserverFactory(Logger.Instance),
-  new DefaultHarExporterFactory(FileManager.Instance)
+  new DefaultHarExporterFactory(FileManager.Instance, Logger.Instance)
 );
 
 export const install = (on: Cypress.PluginEvents): void => {