happy-dom 12.10.3 → 13.0.1

package/src/browser/types/IBrowserFrame.ts

@@ -0,0 +1,68 @@
+import AsyncTaskManager from '../../async-task-manager/AsyncTaskManager.js';
+import * as PropertySymbol from '../../PropertySymbol.js';
+import IBrowserWindow from '../../window/IBrowserWindow.js';
+import IDocument from '../../nodes/document/IDocument.js';
+import IBrowserPage from './IBrowserPage.js';
+import IResponse from '../../fetch/types/IResponse.js';
+import IGoToOptions from './IGoToOptions.js';
+import { Script } from 'vm';
+import IReloadOptions from './IReloadOptions.js';
+import BrowserFrameExceptionObserver from '../utilities/BrowserFrameExceptionObserver.js';
+import ICrossOriginBrowserWindow from '../../window/ICrossOriginBrowserWindow.js';
+
+/**
+ * Browser frame.
+ */
+export default interface IBrowserFrame {
+	readonly childFrames: IBrowserFrame[];
+	readonly parentFrame: IBrowserFrame | null;
+	readonly page: IBrowserPage;
+	readonly window: IBrowserWindow;
+	readonly document: IDocument;
+	content: string;
+	url: string;
+	[PropertySymbol.asyncTaskManager]: AsyncTaskManager;
+	[PropertySymbol.exceptionObserver]: BrowserFrameExceptionObserver | null;
+	[PropertySymbol.listeners]: { navigation: Array<() => void> };
+	[PropertySymbol.openerFrame]: IBrowserFrame | null;
+	[PropertySymbol.openerWindow]: IBrowserWindow | ICrossOriginBrowserWindow | null;
+	[PropertySymbol.popup]: boolean;
+
+	/**
+	 * Returns a promise that is resolved when all resources has been loaded, fetch has completed, and all async tasks such as timers are complete.
+	 */
+	waitUntilComplete(): Promise<void>;
+
+	/**
+	 * Returns a promise that is resolved when the frame has navigated and the response HTML has been written to the document.
+	 */
+	waitForNavigation(): Promise<void>;
+
+	/**
+	 * Aborts all ongoing operations.
+	 */
+	abort(): Promise<void>;
+
+	/**
+	 * Evaluates code or a VM Script in the page's context.
+	 *
+	 * @param script Script.
+	 * @returns Result.
+	 */
+	evaluate(script: string | Script): any;
+
+	/**
+	 * Go to a page.
+	 *
+	 * @param url URL.
+	 * @param [options] Options.
+	 */
+	goto(url: string, options?: IGoToOptions): Promise<IResponse | null>;
+
+	/**
+	 * Reloads the current frame.
+	 *
+	 * @param [options] Options.
+	 */
+	reload(options: IReloadOptions): Promise<IResponse | null>;
+}

package/src/browser/types/IBrowserPage.ts

@@ -0,0 +1,71 @@
+import IBrowserPageViewport from '../types/IBrowserPageViewport.js';
+import VirtualConsolePrinter from '../../console/VirtualConsolePrinter.js';
+import IBrowserFrame from './IBrowserFrame.js';
+import IBrowserContext from './IBrowserContext.js';
+import { Script } from 'vm';
+import IGoToOptions from './IGoToOptions.js';
+import IResponse from '../../fetch/types/IResponse.js';
+import IReloadOptions from './IReloadOptions.js';
+import IOptionalBrowserPageViewport from './IOptionalBrowserPageViewport.js';
+
+/**
+ * Browser page.
+ */
+export default interface IBrowserPage {
+	readonly virtualConsolePrinter: VirtualConsolePrinter;
+	readonly mainFrame: IBrowserFrame;
+	readonly context: IBrowserContext;
+	readonly console: Console;
+	readonly frames: IBrowserFrame[];
+	readonly viewport: IBrowserPageViewport;
+	content: string;
+	url: string;
+
+	/**
+	 * Aborts all ongoing operations and destroys the page.
+	 */
+	close(): Promise<void>;
+
+	/**
+	 * Returns a promise that is resolved when all resources has been loaded, fetch has completed, and all async tasks such as timers are complete.
+	 */
+	waitUntilComplete(): Promise<void>;
+
+	/**
+	 * Returns a promise that is resolved when the page has navigated and the response HTML has been written to the document.
+	 */
+	waitForNavigation(): Promise<void>;
+
+	/**
+	 * Aborts all ongoing operations.
+	 */
+	abort(): Promise<void>;
+
+	/**
+	 * Evaluates code or a VM Script in the page's context.
+	 */
+	evaluate(script: string | Script): any;
+
+	/**
+	 * Sets the viewport.
+	 *
+	 * @param viewport Viewport.
+	 */
+	setViewport(viewport: IOptionalBrowserPageViewport): void;
+
+	/**
+	 * Go to a page.
+	 *
+	 * @param url URL.
+	 * @param [options] Options.
+	 */
+	goto(url: string, options?: IGoToOptions): Promise<IResponse | null>;
+
+	/**
+	 * Reloads the current page.
+	 *
+	 * @param [options] Options.
+	 * @returns Response.
+	 */
+	reload(options: IReloadOptions): Promise<IResponse | null>;
+}

package/src/browser/types/IBrowserPageViewport.ts

@@ -0,0 +1,5 @@
+export default interface IBrowserPageViewport {
+	width: number;
+	height: number;
+	devicePixelRatio: number;
+}

package/src/browser/types/IBrowserSettings.ts

@@ -0,0 +1,100 @@
+import BrowserErrorCaptureEnum from '../enums/BrowserErrorCaptureEnum.js';
+import BrowserNavigationCrossOriginPolicyEnum from '../enums/BrowserNavigationCrossOriginPolicyEnum.js';
+
+/**
+ * Browser settings.
+ */
+export default interface IBrowserSettings {
+	/** Disables JavaScript evaluation. */
+	disableJavaScriptEvaluation: boolean;
+
+	/** Disables JavaScript file loading. */
+	disableJavaScriptFileLoading: boolean;
+
+	/** Disables CSS file loading. */
+	disableCSSFileLoading: boolean;
+
+	/** Disables computed style rendering. */
+	disableComputedStyleRendering: boolean;
+
+	/**
+	 * Disables error capturing.
+	 *
+	 * @deprecated Use errorCapture instead.
+	 */
+	disableErrorCapturing: boolean;
+
+	/**
+	 * Error capturing policy.
+	 */
+	errorCapture: BrowserErrorCaptureEnum;
+
+	/**
+	 * @deprecated Not something that browsers support anymore as it is not secure.
+	 */
+	enableFileSystemHttpRequests: boolean;
+
+	/**
+	 * @deprecated Use navigation.disableChildFrameNavigation instead.
+	 */
+	disableIframePageLoading: boolean;
+
+	/**
+	 * Settings for the browser's navigation (when following links or opening windows).
+	 */
+	navigation: {
+		/** Disables navigation to other pages in the main frame or a page. */
+		disableMainFrameNavigation: boolean;
+
+		/** Disables navigation to other pages in child frames (such as iframes). */
+		disableChildFrameNavigation: boolean;
+
+		/** Disables navigation to other pages in child pages (such as popup windows). */
+		disableChildPageNavigation: boolean;
+
+		/** Disables the fallback to setting the URL when navigating to a page is disabled or when inside a detached browser frame. */
+		disableFallbackToSetURL: boolean;
+
+		/** Sets the policy for cross-origin navigation. */
+		crossOriginPolicy: BrowserNavigationCrossOriginPolicyEnum;
+	};
+
+	/**
+	 * Settings for the browser's navigator.
+	 */
+	navigator: {
+		userAgent: string;
+		maxTouchPoints: number;
+	};
+
+	/**
+	 * Settings for the browser's cache.
+	 */
+	cache: {
+		/** Cache for fetch responses. */
+		response: {
+			/** Disables the cache. */
+			disable: boolean;
+
+			/** Total in memory cache size in bytes. */
+			maxMemorySize: number;
+
+			/** Max in memory cache size for a response in bytes. */
+			maxMemoryResponseSize: number;
+
+			/** Max disk cache size for a response in bytes. */
+			maxDiskResponseSize: number;
+
+			/** Disk cache path. Setting this property will enable the disk cache. */
+			diskPath: string;
+		};
+	};
+
+	/**
+	 * Settings for the browser's device.
+	 */
+	device: {
+		prefersColorScheme: string;
+		mediaType: string;
+	};
+}

package/src/browser/types/IGoToOptions.ts

@@ -0,0 +1,17 @@
+import IRequestReferrerPolicy from '../../fetch/types/IRequestReferrerPolicy.js';
+import IReloadOptions from './IReloadOptions.js';
+
+/**
+ * Go to options.
+ */
+export default interface IGoToOptions extends IReloadOptions {
+	/**
+	 * Referrer.
+	 */
+	referrer?: string;
+
+	/**
+	 * Referrer policy.
+	 */
+	referrerPolicy?: IRequestReferrerPolicy;
+}

package/src/browser/types/IOptionalBrowserPageViewport.ts

@@ -0,0 +1,5 @@
+export default interface IOptionalBrowserPageViewport {
+	width?: number;
+	height?: number;
+	devicePixelRatio?: number;
+}

package/src/browser/types/IOptionalBrowserSettings.ts

@@ -0,0 +1,74 @@
+import BrowserErrorCaptureEnum from '../enums/BrowserErrorCaptureEnum.js';
+import BrowserNavigationCrossOriginPolicyEnum from '../enums/BrowserNavigationCrossOriginPolicyEnum.js';
+
+export default interface IOptionalBrowserSettings {
+	/** Disables JavaScript evaluation. */
+	disableJavaScriptEvaluation?: boolean;
+
+	/** Disables JavaScript file loading. */
+	disableJavaScriptFileLoading?: boolean;
+
+	/** Disables CSS file loading. */
+	disableCSSFileLoading?: boolean;
+
+	/** Disables computed style rendering. */
+	disableComputedStyleRendering?: boolean;
+
+	/**
+	 * Disables error capturing.
+	 *
+	 * @deprecated Use errorCapture instead.
+	 */
+	disableErrorCapturing?: boolean;
+
+	/**
+	 * Error capturing policy.
+	 */
+	errorCapture?: BrowserErrorCaptureEnum;
+
+	/**
+	 * @deprecated Not something that browsers support anymore as it is not secure.
+	 */
+	enableFileSystemHttpRequests?: boolean;
+
+	/**
+	 * @deprecated Use navigation.disableChildFrameNavigation instead.
+	 */
+	disableIframePageLoading?: boolean;
+
+	/**
+	 * Settings for the browser's navigation (when following links or opening windows).
+	 */
+	navigation?: {
+		/** Disables navigation to other pages in the main frame or a page. */
+		disableMainFrameNavigation?: boolean;
+
+		/** Disables navigation to other pages in child frames (such as iframes). */
+		disableChildFrameNavigation?: boolean;
+
+		/** Disables navigation to other pages in child pages (such as popup windows). */
+		disableChildPageNavigation?: boolean;
+
+		/** Disables the fallback to setting the URL when navigating to a page is disabled or when inside a detached browser frame. */
+		disableFallbackToSetURL?: boolean;
+
+		/** Sets the policy for cross-origin navigation. */
+		crossOriginPolicy?: BrowserNavigationCrossOriginPolicyEnum;
+	};
+
+	/**
+	 * Settings for the browser's navigator.
+	 */
+	navigator?: {
+		userAgent?: string;
+		maxTouchPoints?: number;
+	};
+
+	/**
+	 * Settings for the browser's device.
+	 */
+	device?: {
+		prefersColorScheme?: string;
+		mediaType?: string;
+	};
+}

package/src/browser/types/IReloadOptions.ts

@@ -0,0 +1,14 @@
+/**
+ * Reload options.
+ */
+export default interface IReloadOptions {
+	/**
+	 * Set to true to bypass the cache.
+	 */
+	hard?: boolean;
+
+	/**
+	 * Timeout in ms. Default is 30000ms.
+	 */
+	timeout?: number;
+}

package/src/browser/utilities/BrowserFrameExceptionObserver.ts

@@ -0,0 +1,99 @@
+import IBrowserFrame from '../types/IBrowserFrame.js';
+
+/**
+ * Listens for uncaught exceptions coming from Happy DOM on the running Node process and dispatches error events on the Window instance.
+ */
+export default class BrowserFrameExceptionObserver {
+	private static listenerCount = 0;
+	private browserFrame: IBrowserFrame | null = null;
+	private uncaughtExceptionListener: (
+		error: Error,
+		origin: 'uncaughtException' | 'unhandledRejection'
+	) => void | null = null;
+	private uncaughtRejectionListener: (error: Error) => void | null = null;
+
+	/**
+	 * Observes the Node process for uncaught exceptions.
+	 *
+	 * @param browserFrame Browser frame.
+	 */
+	public observe(browserFrame: IBrowserFrame): void {
+		if (this.browserFrame) {
+			throw new Error('Already observing.');
+		}
+
+		this.browserFrame = browserFrame;
+
+		(<typeof BrowserFrameExceptionObserver>this.constructor).listenerCount++;
+
+		this.uncaughtExceptionListener = (
+			error: unknown,
+			origin: 'uncaughtException' | 'unhandledRejection'
+		) => {
+			if (origin === 'unhandledRejection') {
+				return;
+			}
+
+			if (
+				error instanceof this.browserFrame.window.Error ||
+				error instanceof this.browserFrame.window.DOMException
+			) {
+				this.browserFrame.window.console.error(error);
+				this.browserFrame.window.dispatchEvent(
+					new this.browserFrame.window.ErrorEvent('error', { error, message: error.message })
+				);
+			} else if (
+				process.listenerCount('uncaughtException') ===
+				(<typeof BrowserFrameExceptionObserver>this.constructor).listenerCount
+			) {
+				// eslint-disable-next-line no-console
+				console.error(error);
+				// Exit if there are no other listeners handling the error.
+				process.exit(1);
+			}
+		};
+
+		// The "uncaughtException" event is not always triggered for unhandled rejections.
+		// Therefore we want to use the "unhandledRejection" event as well.
+		this.uncaughtRejectionListener = (error: unknown) => {
+			if (
+				error instanceof this.browserFrame.window.Error ||
+				error instanceof this.browserFrame.window.DOMException
+			) {
+				this.browserFrame.window.console.error(error);
+				this.browserFrame.window.dispatchEvent(
+					new this.browserFrame.window.ErrorEvent('error', { error, message: error.message })
+				);
+			} else if (
+				process.listenerCount('unhandledRejection') ===
+				(<typeof BrowserFrameExceptionObserver>this.constructor).listenerCount
+			) {
+				// eslint-disable-next-line no-console
+				console.error(error);
+				// Exit if there are no other listeners handling the error.
+				process.exit(1);
+			}
+		};
+
+		process.on('uncaughtException', this.uncaughtExceptionListener);
+		process.on('unhandledRejection', this.uncaughtRejectionListener);
+	}
+
+	/**
+	 * Disconnects observer.
+	 */
+	public disconnect(): void {
+		if (!this.browserFrame) {
+			return;
+		}
+
+		(<typeof BrowserFrameExceptionObserver>this.constructor).listenerCount--;
+
+		process.off('uncaughtException', this.uncaughtExceptionListener);
+		process.off('unhandledRejection', this.uncaughtRejectionListener);
+
+		this.uncaughtExceptionListener = null;
+		this.uncaughtRejectionListener = null;
+		this.browserFrame = null;
+	}
+}

package/src/browser/utilities/BrowserFrameFactory.ts

@@ -0,0 +1,71 @@
+import IBrowserFrame from '../types/IBrowserFrame.js';
+import * as PropertySymbol from '../../PropertySymbol.js';
+import IBrowserWindow from '../../window/IBrowserWindow.js';
+import IBrowserPage from '../types/IBrowserPage.js';
+/**
+ * Browser frame factory.
+ */
+export default class BrowserFrameFactory {
+	/**
+	 * Creates a new frame.
+	 *
+	 * @param parentFrame Parent frame.
+	 * @returns Frame.
+	 */
+	public static newChildFrame(parentFrame: IBrowserFrame): IBrowserFrame {
+		const frame = new (<new (page: IBrowserPage) => IBrowserFrame>parentFrame.constructor)(
+			parentFrame.page
+		);
+		(<IBrowserFrame>frame.parentFrame) = parentFrame;
+		parentFrame.childFrames.push(frame);
+		return frame;
+	}
+
+	/**
+	 * Aborts all ongoing operations and destroys the frame.
+	 *
+	 * @param frame Frame.
+	 */
+	public static destroyFrame(frame: IBrowserFrame): Promise<void> {
+		// Using Promise instead of async/await to prevent microtask
+		return new Promise((resolve, reject) => {
+			if (!frame.window) {
+				resolve();
+				return;
+			}
+
+			if (frame.parentFrame) {
+				const index = frame.parentFrame.childFrames.indexOf(frame);
+				if (index !== -1) {
+					frame.parentFrame.childFrames.splice(index, 1);
+				}
+			}
+
+			// We need to destroy the Window instance before triggering any async tasks as Window.close() is not async.
+			frame.window[PropertySymbol.destroy]();
+			(<IBrowserPage | null>frame.page) = null;
+			(<IBrowserWindow | null>frame.window) = null;
+			frame[PropertySymbol.openerFrame] = null;
+			frame[PropertySymbol.openerWindow] = null;
+
+			if (!frame.childFrames.length) {
+				return frame[PropertySymbol.asyncTaskManager]
+					.destroy()
+					.then(() => {
+						frame[PropertySymbol.exceptionObserver]?.disconnect();
+						resolve();
+					})
+					.catch((error) => reject(error));
+			}
+
+			Promise.all(frame.childFrames.slice().map((childFrame) => this.destroyFrame(childFrame)))
+				.then(() => {
+					return frame[PropertySymbol.asyncTaskManager].destroy().then(() => {
+						frame[PropertySymbol.exceptionObserver]?.disconnect();
+						resolve();
+					});
+				})
+				.catch((error) => reject(error));
+		});
+	}
+}