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

closes #174

Author: derevnjuk

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

@@ -28,6 +28,7 @@ export interface SaveOptions {
 export type RecordOptions = NetworkObserverOptions & {
   rootDir: string;
   filter?: string;
+  transform?: string;
 };
 
 interface Addr {
@@ -81,10 +82,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 => {

src/network/DefaultHarExporter.spec.ts

@@ -1,11 +1,14 @@
 import { NetworkRequest } from './NetworkRequest';
 import { DefaultHarExporter } from './DefaultHarExporter';
+import type { Logger } from '../utils/Logger';
+import type { DefaultHarExporterOptions } from './DefaultHarExporterOptions';
 import {
   anyString,
   instance,
   match,
   mock,
   reset,
+  spy,
   verify,
   when
 } from 'ts-mockito';
@@ -15,31 +18,47 @@ import type { WriteStream } from 'fs';
 import { EOL } from 'os';
 
 describe('DefaultHarExporter', () => {
-  const buffer = mock<WriteStream>();
+  const streamMock = mock<WriteStream>();
+  const loggerMock = mock<Logger>();
   const networkRequest = new NetworkRequest(
     '1',
     'https://example.com',
     'https://example.com',
     '1'
   );
-  const predicate: jest.Mock<(entry: Entry) => Promise<unknown> | unknown> =
-    jest.fn<(entry: Entry) => Promise<unknown> | unknown>();
+  const predicate = jest.fn<(entry: Entry) => Promise<unknown> | unknown>();
+  const transform = jest.fn<(entry: Entry) => Promise<Entry> | Entry>();
+
   let harExporter!: DefaultHarExporter;
+  let options!: DefaultHarExporterOptions;
+  let optionsSpy!: DefaultHarExporterOptions;
 
   beforeEach(() => {
-    harExporter = new DefaultHarExporter(instance(buffer), predicate);
+    options = {};
+    optionsSpy = spy(options);
+
+    harExporter = new DefaultHarExporter(
+      instance(loggerMock),
+      instance(streamMock),
+      options
+    );
   });
 
   afterEach(() => {
     predicate.mockRestore();
-    reset(buffer);
+    transform.mockRestore();
+    reset<DefaultHarExporterOptions | WriteStream | Logger>(
+      streamMock,
+      optionsSpy,
+      loggerMock
+    );
   });
 
   describe('path', () => {
     it('should return the path serializing buffer', () => {
       // arrange
       const expected = '/path/file';
-      when(buffer.path).thenReturn(Buffer.from(expected));
+      when(streamMock.path).thenReturn(Buffer.from(expected));
 
       // act
       const result = harExporter.path;
@@ -51,7 +70,7 @@ describe('DefaultHarExporter', () => {
     it('should return the path', () => {
       // arrange
       const expected = '/path/file';
-      when(buffer.path).thenReturn(expected);
+      when(streamMock.path).thenReturn(expected);
 
       // act
       const result = harExporter.path;
@@ -67,28 +86,30 @@ describe('DefaultHarExporter', () => {
       harExporter.end();
 
       // assert
-      verify(buffer.end()).once();
+      verify(streamMock.end()).once();
     });
   });
 
   describe('write', () => {
     it('should write the entry to the buffer', async () => {
       // arrange
       // @ts-expect-error type mismatch
-      when(buffer.closed).thenReturn(false);
+      when(streamMock.closed).thenReturn(false);
+      when(optionsSpy.predicate).thenReturn(predicate);
       predicate.mockReturnValue(false);
 
       // act
       await harExporter.write(networkRequest);
 
       // assert
-      verify(buffer.write(match(`${EOL}`))).once();
+      verify(streamMock.write(match(`${EOL}`))).once();
     });
 
     it('should write the entry to the buffer if the predicate returns throws an error', async () => {
       // arrange
       // @ts-expect-error type mismatch
-      when(buffer.closed).thenReturn(false);
+      when(streamMock.closed).thenReturn(false);
+      when(optionsSpy.predicate).thenReturn(predicate);
       predicate.mockReturnValue(
         Promise.reject(new Error('something went wrong'))
       );
@@ -97,33 +118,67 @@ describe('DefaultHarExporter', () => {
       await harExporter.write(networkRequest);
 
       // assert
-      verify(buffer.write(match(`${EOL}`))).once();
+      verify(streamMock.write(match(`${EOL}`))).once();
+    });
+
+    it('should transform the entry before writing to the buffer', async () => {
+      // arrange
+      const entry = { foo: 'bar' } as unknown as Entry;
+      const entryString = JSON.stringify(entry);
+      // @ts-expect-error type mismatch
+      when(streamMock.closed).thenReturn(false);
+      when(optionsSpy.transform).thenReturn(transform);
+      transform.mockReturnValue(Promise.resolve(entry));
+
+      // act
+      await harExporter.write(networkRequest);
+
+      // assert
+      verify(streamMock.write(match(`${entryString}${EOL}`))).once();
+    });
+
+    it('should skip the entry when the transformation is failed with an error', async () => {
+      // arrange
+      // @ts-expect-error type mismatch
+      when(streamMock.closed).thenReturn(false);
+      when(optionsSpy.transform).thenReturn(transform);
+      transform.mockReturnValue(
+        Promise.reject(new Error('Something went wrong.'))
+      );
+
+      // act
+      await harExporter.write(networkRequest);
+
+      // assert
+      verify(streamMock.write(anyString())).never();
     });
 
     it('should not write the entry to the buffer if the predicate returns true', async () => {
       // arrange
       // @ts-expect-error type mismatch
-      when(buffer.closed).thenReturn(false);
+      when(streamMock.closed).thenReturn(false);
+      when(optionsSpy.predicate).thenReturn(predicate);
       predicate.mockReturnValue(true);
 
       // act
       await harExporter.write(networkRequest);
 
       // assert
-      verify(buffer.write(anyString())).never();
+      verify(streamMock.write(anyString())).never();
     });
 
     it('should not write the entry to the buffer if the buffer is closed', async () => {
       // arrange
       // @ts-expect-error type mismatch
-      when(buffer.closed).thenReturn(true);
+      when(streamMock.closed).thenReturn(true);
+      when(optionsSpy.predicate).thenReturn(predicate);
       predicate.mockReturnValue(false);
 
       // act
       await harExporter.write(networkRequest);
 
       // assert
-      verify(buffer.write(anyString())).never();
+      verify(streamMock.write(anyString())).never();
     });
   });
 });

src/network/DefaultHarExporter.ts

@@ -1,9 +1,17 @@
 import { EntryBuilder } from './EntryBuilder';
 import type { NetworkRequest } from './NetworkRequest';
 import type { HarExporter } from './HarExporter';
+import type { Logger } from '../utils/Logger';
+import { ErrorUtils } from '../utils/ErrorUtils';
+import type {
+  DefaultHarExporterOptions,
+  Predicate,
+  Transformer
+} from './DefaultHarExporterOptions';
 import type { Entry } from 'har-format';
 import type { WriteStream } from 'fs';
 import { EOL } from 'os';
+import { format } from 'util';
 
 export class DefaultHarExporter implements HarExporter {
   get path(): string {
@@ -12,9 +20,18 @@ export class DefaultHarExporter implements HarExporter {
     return Buffer.isBuffer(path) ? path.toString('utf-8') : path;
   }
 
+  private get predicate(): Predicate | undefined {
+    return this.options?.predicate;
+  }
+
+  private get transform(): Transformer | undefined {
+    return this.options?.transform;
+  }
+
   constructor(
+    private readonly logger: Logger,
     private readonly buffer: WriteStream,
-    private readonly predicate?: (entry: Entry) => Promise<unknown> | unknown
+    private readonly options?: DefaultHarExporterOptions
   ) {}
 
   public async write(networkRequest: NetworkRequest): Promise<void> {
@@ -24,24 +41,56 @@ export class DefaultHarExporter implements HarExporter {
       return;
     }
 
-    const json = JSON.stringify(entry);
+    const json = await this.serializeEntry(entry);
 
     // @ts-expect-error type mismatch
-    if (!this.buffer.closed) {
+    if (!this.buffer.closed && json) {
       this.buffer.write(`${json}${EOL}`);
     }
   }
 
+  public async serializeEntry(entry: Entry): Promise<string | undefined> {
+    try {
+      const result =
+        typeof this.transform === 'function'
+          ? await this.transform(entry)
+          : entry;
+
+      return JSON.stringify(result);
+    } catch (e) {
+      const stack = ErrorUtils.isError(e) ? e.stack : e;
+      const formattedEntry = format('%j', entry);
+
+      this.logger.err(
+        `The entry is missing as a result of an error in the 'transform' function.
+
+The passed entry:
+${formattedEntry}
+
+The stack trace for this error is: 
+${stack}`
+      );
+
+      return undefined;
+    }
+  }
+
   public end(): void {
     this.buffer.end();
   }
 
-  private async applyPredicate(entry: Entry) {
+  private async applyPredicate(entry: Entry): Promise<unknown> {
     try {
       return (
         typeof this.predicate === 'function' && (await this.predicate?.(entry))
       );
-    } catch {
+    } catch (e) {
+      const message = ErrorUtils.isError(e) ? e.message : e;
+
+      this.logger.debug(
+        `The operation has encountered an error while processing the entry. ${message}`
+      );
+
       return false;
     }
   }