chromiumly 2.7.0 → 2.8.0

package/src/chromium/screenshots/tests/markdown.screenshot.test.ts

@@ -0,0 +1,176 @@
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import { createReadStream, promises } from 'fs';
+
+import FormData from 'form-data';
+import fetch from 'node-fetch';
+
+import { MarkdownScreenshot } from '../markdown.screenshot';
+
+const { Response } = jest.requireActual('node-fetch');
+jest.mock('node-fetch', () => jest.fn());
+
+describe('MarkdownScreenshot', () => {
+    const screenshot = new MarkdownScreenshot();
+
+    describe('endpoint', () => {
+        it('should route to Chromium Markdown route', () => {
+            expect(screenshot.endpoint).toEqual(
+                'http://localhost:3000/forms/chromium/screenshot/markdown'
+            );
+        });
+    });
+
+    describe('capture', () => {
+        const mockPromisesAccess = jest.spyOn(promises, 'access');
+        const mockFetch = fetch as jest.MockedFunction<typeof fetch>;
+        const mockFormDataAppend = jest.spyOn(FormData.prototype, 'append');
+
+        beforeEach(() => {
+            (createReadStream as jest.Mock) = jest.fn();
+        });
+
+        afterEach(() => {
+            jest.resetAllMocks();
+        });
+
+        describe('when html and markdown parameters are passed', () => {
+            it('should return a buffer', async () => {
+                mockFetch.mockResolvedValue(new Response('content'));
+                const buffer = await screenshot.capture({
+                    html: Buffer.from('data'),
+                    markdown: Buffer.from('markdown')
+                });
+                expect(buffer).toEqual(Buffer.from('content'));
+            });
+        });
+
+        describe('when image properties parameter is passed', () => {
+            it('should return a buffer', async () => {
+                mockFetch.mockResolvedValue(new Response('content'));
+                const buffer = await screenshot.capture({
+                    html: Buffer.from('data'),
+                    markdown: Buffer.from('markdown'),
+                    properties: { format: 'jpeg', quality: 50 }
+                });
+                expect(mockFormDataAppend).toHaveBeenCalledTimes(4);
+                expect(buffer).toEqual(Buffer.from('content'));
+            });
+        });
+
+        describe('when header parameter is passed', () => {
+            it('should return a buffer', async () => {
+                mockFetch.mockResolvedValue(new Response('content'));
+                const buffer = await screenshot.capture({
+                    html: Buffer.from('data'),
+                    markdown: Buffer.from('markdown'),
+                    header: Buffer.from('header')
+                });
+                expect(mockFormDataAppend).toHaveBeenCalledTimes(3);
+                expect(buffer).toEqual(Buffer.from('content'));
+            });
+        });
+
+        describe('when footer parameter is passed', () => {
+            it('should return a buffer', async () => {
+                mockFetch.mockResolvedValue(new Response('content'));
+                const buffer = await screenshot.capture({
+                    html: Buffer.from('data'),
+                    markdown: Buffer.from('markdown'),
+                    footer: Buffer.from('footer')
+                });
+                expect(mockFormDataAppend).toHaveBeenCalledTimes(3);
+                expect(buffer).toEqual(Buffer.from('content'));
+            });
+        });
+
+        describe('when emulatedMediaType parameter is passed', () => {
+            it('should return a buffer', async () => {
+                mockFetch.mockResolvedValue(new Response('content'));
+                const buffer = await screenshot.capture({
+                    html: Buffer.from('data'),
+                    markdown: Buffer.from('markdown'),
+                    emulatedMediaType: 'screen'
+                });
+
+                expect(mockFormDataAppend).toHaveBeenCalledTimes(3);
+                expect(buffer).toEqual(Buffer.from('content'));
+            });
+        });
+
+        describe('when failOnHttpStatusCodes parameter is passed', () => {
+            it('should return a buffer', async () => {
+                mockFetch.mockResolvedValue(new Response('content'));
+                const buffer = await screenshot.capture({
+                    html: Buffer.from('data'),
+                    markdown: Buffer.from('markdown'),
+                    failOnHttpStatusCodes: [499, 599]
+                });
+                expect(mockFormDataAppend).toHaveBeenCalledTimes(3);
+                expect(buffer).toEqual(Buffer.from('content'));
+            });
+        });
+
+        describe('when skipNetworkIdleEvent parameter is passed', () => {
+            it('should return a buffer', async () => {
+                mockFetch.mockResolvedValue(new Response('content'));
+                const buffer = await screenshot.capture({
+                    html: Buffer.from('data'),
+                    markdown: Buffer.from('markdown'),
+                    skipNetworkIdleEvent: true
+                });
+                expect(mockFormDataAppend).toHaveBeenCalledTimes(3);
+                expect(buffer).toEqual(Buffer.from('content'));
+            });
+        });
+
+        describe('when all parameters are passed', () => {
+            it('should return a buffer', async () => {
+                mockFetch.mockResolvedValue(new Response('content'));
+                const buffer = await screenshot.capture({
+                    html: Buffer.from('data'),
+                    markdown: Buffer.from('markdown'),
+                    header: Buffer.from('header'),
+                    footer: Buffer.from('footer'),
+                    emulatedMediaType: 'screen',
+                    failOnHttpStatusCodes: [499, 599],
+                    skipNetworkIdleEvent: true,
+                    failOnConsoleExceptions: true,
+                    properties: { format: 'jpeg', quality: 50 },
+                    optimizeForSpeed: true
+                });
+                expect(mockFormDataAppend).toHaveBeenCalledTimes(11);
+                expect(buffer).toEqual(Buffer.from('content'));
+            });
+        });
+
+        describe('when file does not exist', () => {
+            it('should throw an error', async () => {
+                const errorMessage =
+                    "ENOENT: no such file or directory, access 'path/to/index.html'";
+                mockPromisesAccess.mockRejectedValue(new Error(errorMessage));
+
+                await expect(() =>
+                    screenshot.capture({
+                        html: 'path/to/index.html',
+                        markdown: 'path/to/file.md'
+                    })
+                ).rejects.toThrow(errorMessage);
+            });
+        });
+
+        describe('when fetch request fails', () => {
+            it('should throw an error', async () => {
+                const errorMessage =
+                    'FetchError: request to http://localhost:3000/forms/chromium/screenshot/html failed';
+                mockPromisesAccess.mockResolvedValue();
+                mockFetch.mockRejectedValue(new Error(errorMessage));
+                await expect(() =>
+                    screenshot.capture({
+                        html: 'path/to/index.html',
+                        markdown: 'path/to/file.md'
+                    })
+                ).rejects.toThrow(errorMessage);
+            });
+        });
+    });
+});

package/src/chromium/screenshots/tests/url.screenshot.test.ts

@@ -0,0 +1,166 @@
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import { createReadStream } from 'fs';
+import FormData from 'form-data';
+import fetch from 'node-fetch';
+
+import { UrlScreenshot } from './../url.screenshot';
+
+const { Response } = jest.requireActual('node-fetch');
+jest.mock('node-fetch', () => jest.fn());
+
+describe('URLScreenshot', () => {
+    const screenshot = new UrlScreenshot();
+
+    describe('endpoint', () => {
+        it('should route to Chromium HTML route', () => {
+            expect(screenshot.endpoint).toEqual(
+                'http://localhost:3000/forms/chromium/screenshot/url'
+            );
+        });
+    });
+
+    describe('capture', () => {
+        const mockFetch = fetch as jest.MockedFunction<typeof fetch>;
+        const mockFormDataAppend = jest.spyOn(FormData.prototype, 'append');
+
+        beforeEach(() => {
+            (createReadStream as jest.Mock) = jest.fn();
+        });
+
+        afterEach(() => {
+            jest.resetAllMocks();
+        });
+
+        describe('when URL is valid', () => {
+            it('should return a buffer', async () => {
+                mockFetch.mockResolvedValueOnce(new Response('content'));
+                const buffer = await screenshot.capture({
+                    url: 'http://www.example.com/'
+                });
+                expect(buffer).toEqual(Buffer.from('content'));
+            });
+        });
+
+        describe('when header parameter is passed', () => {
+            it('should return a buffer', async () => {
+                mockFetch.mockResolvedValueOnce(new Response('content'));
+                const buffer = await screenshot.capture({
+                    url: 'http://www.example.com/',
+                    header: Buffer.from('header')
+                });
+                expect(mockFormDataAppend).toHaveBeenCalledTimes(2);
+                expect(buffer).toEqual(Buffer.from('content'));
+            });
+        });
+
+        describe('when footer parameter is passed', () => {
+            it('should return a buffer', async () => {
+                mockFetch.mockResolvedValueOnce(new Response('content'));
+                const buffer = await screenshot.capture({
+                    url: 'http://www.example.com/',
+                    footer: Buffer.from('footer')
+                });
+                expect(mockFormDataAppend).toHaveBeenCalledTimes(2);
+                expect(buffer).toEqual(Buffer.from('content'));
+            });
+        });
+
+        describe('when image properties parameter is passed', () => {
+            it('should return a buffer', async () => {
+                mockFetch.mockResolvedValueOnce(new Response('content'));
+                const buffer = await screenshot.capture({
+                    url: 'http://www.example.com/',
+                    properties: { format: 'jpeg', quality: 50 }
+                });
+                expect(mockFormDataAppend).toHaveBeenCalledTimes(3);
+                expect(buffer).toEqual(Buffer.from('content'));
+            });
+        });
+
+        describe('when emulatedMediaType parameter is passed', () => {
+            it('should return a buffer', async () => {
+                mockFetch.mockResolvedValue(new Response('content'));
+                const buffer = await screenshot.capture({
+                    url: 'http://www.example.com/',
+                    emulatedMediaType: 'screen'
+                });
+                expect(mockFormDataAppend).toHaveBeenCalledTimes(2);
+                expect(buffer).toEqual(Buffer.from('content'));
+            });
+        });
+
+        describe('when failOnHttpStatusCodes parameter is passed', () => {
+            it('should return a buffer', async () => {
+                mockFetch.mockResolvedValue(new Response('content'));
+                const buffer = await screenshot.capture({
+                    url: 'http://www.example.com/',
+                    failOnHttpStatusCodes: [499, 599]
+                });
+                expect(mockFormDataAppend).toHaveBeenCalledTimes(2);
+                expect(buffer).toEqual(Buffer.from('content'));
+            });
+        });
+
+        describe('when skipNetworkIdleEvent parameter is passed', () => {
+            it('should return a buffer', async () => {
+                mockFetch.mockResolvedValue(new Response('content'));
+                const buffer = await screenshot.capture({
+                    url: 'http://www.example.com/',
+                    skipNetworkIdleEvent: true
+                });
+                expect(mockFormDataAppend).toHaveBeenCalledTimes(2);
+                expect(buffer).toEqual(Buffer.from('content'));
+            });
+        });
+
+        describe('when optimizeForSpeed parameter is passed', () => {
+            it('should return a buffer', async () => {
+                mockFetch.mockResolvedValue(new Response('content'));
+                const buffer = await screenshot.capture({
+                    url: 'http://www.example.com/',
+                    optimizeForSpeed: true
+                });
+                expect(mockFormDataAppend).toHaveBeenCalledTimes(2);
+                expect(buffer).toEqual(Buffer.from('content'));
+            });
+        });
+
+        describe('when all parameters are passed', () => {
+            it('should return a buffer', async () => {
+                mockFetch.mockResolvedValue(new Response('content'));
+                const buffer = await screenshot.capture({
+                    url: 'http://www.example.com/',
+                    header: Buffer.from('header'),
+                    footer: Buffer.from('footer'),
+                    emulatedMediaType: 'screen',
+                    failOnHttpStatusCodes: [499, 599],
+                    skipNetworkIdleEvent: true,
+                    failOnConsoleExceptions: true,
+                    properties: { format: 'jpeg', quality: 50 },
+                    optimizeForSpeed: true
+                });
+                expect(mockFormDataAppend).toHaveBeenCalledTimes(10);
+                expect(buffer).toEqual(Buffer.from('content'));
+            });
+        });
+
+        describe('when URL is invalid', () => {
+            it('should throw an error', async () => {
+                await expect(() =>
+                    screenshot.capture({ url: 'invalid url' })
+                ).rejects.toThrow('Invalid URL');
+            });
+        });
+
+        describe('when fetch request fails', () => {
+            it('should throw an error', async () => {
+                const errorMessage =
+                    'FetchError: request to http://localhost:3000/forms/chromium/convert/html failed';
+                mockFetch.mockRejectedValueOnce(new Error(errorMessage));
+                await expect(() =>
+                    screenshot.capture({ url: 'http://www.example.com/' })
+                ).rejects.toThrow(errorMessage);
+            });
+        });
+    });
+});

package/src/chromium/screenshots/url.screenshot.ts

@@ -0,0 +1,91 @@
+import { URL } from 'url';
+import FormData from 'form-data';
+import { GotenbergUtils, PathLikeOrReadStream } from '../../common';
+import { ImageProperties } from '../interfaces/screenshot.types';
+import { ScreenshotUtils } from '../utils/screenshot.utils';
+import { Screenshot } from './screenshot';
+import { ChromiumRoute } from '../../main.config';
+import { EmulatedMediaType } from '../interfaces/common.types';
+
+/**
+ * Class representing a URL screenshot that extends the base screenshot class.
+ * This class is used to screenshot a URL using Gotenberg service.
+ *
+ * @extends Screenshot
+ */
+export class UrlScreenshot extends Screenshot {
+    /**
+     * Creates an instance of UrlScreenshot.
+     * Initializes the screenshot with the URL screenshot route.
+     */
+    constructor() {
+        super(ChromiumRoute.URL);
+    }
+
+    /**
+     * Screenshots URL.
+     *
+     * @param {Object} options - Screenshot options.
+     * @param {string} options.url - The URL of the content to be screenshoted
+     * @param {PathLikeOrReadStream} [options.header] - PathLike or ReadStream of the header HTML content.
+     * @param {PathLikeOrReadStream} [options.footer] - PathLike or ReadStream of the footer HTML content.
+     * @param {ImageProperties} [options.properties] - Image properties for the screenshot.
+     * @param {EmulatedMediaType} [options.emulatedMediaType] - Emulated media type for the screenshot.
+     * @param {string} [options.waitDelay] - Delay before the screenshot process starts.
+     * @param {string} [options.waitForExpression] - JavaScript expression to wait for before completing the screenshot.
+     * @param {Record<string, string>} [options.extraHttpHeaders] - Additional HTTP headers for the screenshot.
+     * @param {number []} [options.failOnHttpStatusCodes] - Whether to fail on HTTP status code.
+     * @param {boolean} [options.failOnConsoleExceptions] - Whether to fail on console exceptions during screenshot.
+     * @param {boolean} [options.skipNetworkIdleEvent] - Whether to skip network idle event.
+     * @param {boolean} [options.optimizeForSpeed] - Whether to optimize for speed.
+     * @returns {Promise<Buffer>} A Promise resolving to the image buffer.
+     */
+    async capture({
+        url,
+        header,
+        footer,
+        properties,
+        emulatedMediaType,
+        waitDelay,
+        waitForExpression,
+        extraHttpHeaders,
+        failOnHttpStatusCodes,
+        failOnConsoleExceptions,
+        skipNetworkIdleEvent,
+        optimizeForSpeed
+    }: {
+        url: string;
+        header?: PathLikeOrReadStream;
+        footer?: PathLikeOrReadStream;
+        properties?: ImageProperties;
+        emulatedMediaType?: EmulatedMediaType;
+        waitDelay?: string;
+        waitForExpression?: string;
+        extraHttpHeaders?: Record<string, string>;
+        failOnHttpStatusCodes?: number[];
+        failOnConsoleExceptions?: boolean;
+        skipNetworkIdleEvent?: boolean;
+        optimizeForSpeed?: boolean;
+    }): Promise<Buffer> {
+        const _url = new URL(url);
+        const data = new FormData();
+
+        data.append('url', _url.href);
+
+        await ScreenshotUtils.customize(data, {
+            header,
+            footer,
+            properties,
+            emulatedMediaType,
+            waitDelay,
+            waitForExpression,
+            extraHttpHeaders,
+            failOnHttpStatusCodes,
+            failOnConsoleExceptions,
+            skipNetworkIdleEvent,
+            optimizeForSpeed
+        });
+
+        return GotenbergUtils.fetch(this.endpoint, data);
+    }
+}

package/src/chromium/utils/screenshot.utils.ts

@@ -0,0 +1,115 @@
+import {
+    ImageProperties,
+    ScreenshotOptions
+} from './../interfaces/screenshot.types';
+import FormData from 'form-data';
+
+import { GotenbergUtils } from '../../common';
+
+/**
+ * Utility class for handling common tasks related to screenshot.
+ */
+export class ScreenshotUtils {
+    /**
+     * Adds page properties to the FormData object based on the provided imageProperties.
+     *
+     * @param {FormData} data - The FormData object to which page properties will be added.
+     * @param {ImageProperties} imageProperties - The page properties to be added to the FormData.
+     */
+    public static addImageProperties(
+        data: FormData,
+        imageProperties: ImageProperties
+    ): void {
+        data.append('format', imageProperties.format);
+
+        if (imageProperties.quality) {
+            GotenbergUtils.assert(
+                imageProperties.format === 'jpeg',
+                'Compression quality is exclusively supported for JPEG format.'
+            );
+            GotenbergUtils.assert(
+                imageProperties.quality >= 0 && imageProperties.quality <= 100,
+                'Invalid compression quality. Please provide a value between 0 and 100.'
+            );
+
+            data.append('quality', imageProperties.quality);
+        }
+
+        if (imageProperties.omitBackground) {
+            data.append(
+                'omitBackground',
+                String(imageProperties.omitBackground)
+            );
+        }
+    }
+
+    /**
+     * Customizes the FormData object based on the provided screenshot options.
+     *
+     * @param {FormData} data - The FormData object to be customized.
+     * @param {ScreenshotOptions} options - The screenshot options to apply to the FormData.
+     * @returns {Promise<void>} A Promise that resolves once the customization is complete.
+     */
+    public static async customize(
+        data: FormData,
+        options: ScreenshotOptions
+    ): Promise<void> {
+        if (options.header) {
+            const { header } = options;
+            await GotenbergUtils.addFile(data, header, 'header.html');
+        }
+
+        if (options.footer) {
+            const { footer } = options;
+            await GotenbergUtils.addFile(data, footer, 'footer.html');
+        }
+
+        if (options.emulatedMediaType) {
+            data.append('emulatedMediaType', options.emulatedMediaType);
+        }
+
+        if (options.properties) {
+            ScreenshotUtils.addImageProperties(data, options.properties);
+        }
+
+        if (options.waitDelay) {
+            data.append('waitDelay', options.waitDelay);
+        }
+
+        if (options.waitForExpression) {
+            data.append('waitForExpression', options.waitForExpression);
+        }
+
+        if (options.extraHttpHeaders) {
+            data.append(
+                'extraHttpHeaders',
+                JSON.stringify(options.extraHttpHeaders)
+            );
+        }
+
+        if (options.failOnHttpStatusCodes) {
+            data.append(
+                'failOnHttpStatusCodes',
+                JSON.stringify(options.failOnHttpStatusCodes)
+            );
+        }
+
+        if (options.failOnConsoleExceptions) {
+            data.append(
+                'failOnConsoleExceptions',
+                String(options.failOnConsoleExceptions)
+            );
+        }
+
+        if (options.skipNetworkIdleEvent) {
+            data.append(
+                'skipNetworkIdleEvent',
+                String(options.skipNetworkIdleEvent)
+            );
+        }
+
+        if (options.optimizeForSpeed) {
+            data.append('optimizeForSpeed', String(options.optimizeForSpeed));
+        }
+    }
+}

package/src/chromium/utils/tests/converter.utils.test.ts

@@ -365,9 +365,11 @@ describe('GotenbergUtils', () => {
                     userAgent:
                         'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.36',
                     extraHttpHeaders: { 'X-Custom-Header': 'value' },
+                    failOnHttpStatusCodes: [499, 599],
+                    skipNetworkIdleEvent: true,
                     failOnConsoleExceptions: true
                 });
-                expect(mockFormDataAppend).toHaveBeenCalledTimes(12);
+                expect(mockFormDataAppend).toHaveBeenCalledTimes(14);
                 expect(data.append).toHaveBeenNthCalledWith(
                     1,
                     'pdfa',
@@ -423,9 +425,19 @@ describe('GotenbergUtils', () => {
                 );
                 expect(data.append).toHaveBeenNthCalledWith(
                     12,
+                    'failOnHttpStatusCodes',
+                    JSON.stringify([499, 599])
+                );
+                expect(data.append).toHaveBeenNthCalledWith(
+                    13,
                     'failOnConsoleExceptions',
                     'true'
                 );
+                expect(data.append).toHaveBeenNthCalledWith(
+                    14,
+                    'skipNetworkIdleEvent',
+                    'true'
+                );
             });
         });
     });