happy-dom 12.10.2 → 13.0.0

package/src/browser/types/IBrowserFrame.ts

@@ -0,0 +1,65 @@
+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';
+
+/**
+ * Browser frame.
+ */
+export default interface IBrowserFrame {
+	readonly childFrames: IBrowserFrame[];
+	readonly parentFrame: IBrowserFrame | null;
+	readonly opener: 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> };
+
+	/**
+	 * 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,69 @@
+import IBrowserPageViewport from './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';
+
+/**
+ * Browser page.
+ */
+export default interface IBrowserPage {
+	readonly virtualConsolePrinter: VirtualConsolePrinter;
+	readonly mainFrame: IBrowserFrame;
+	readonly context: IBrowserContext;
+	readonly console: Console;
+	readonly frames: IBrowserFrame[];
+	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: IBrowserPageViewport): 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/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,70 @@
+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;
+			(<IBrowserFrame | null>frame.opener) = 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));
+		});
+	}
+}

package/src/browser/utilities/BrowserFrameNavigator.ts

@@ -0,0 +1,179 @@
+import IBrowserFrame from '../types/IBrowserFrame.js';
+import * as PropertySymbol from '../../PropertySymbol.js';
+import IGoToOptions from '../types/IGoToOptions.js';
+import IResponse from '../../fetch/types/IResponse.js';
+import DocumentReadyStateManager from '../../nodes/document/DocumentReadyStateManager.js';
+import IBrowserWindow from '../../window/IBrowserWindow.js';
+import WindowErrorUtility from '../../window/WindowErrorUtility.js';
+import Location from '../../location/Location.js';
+import AbortController from '../../fetch/AbortController.js';
+import BrowserFrameFactory from './BrowserFrameFactory.js';
+import BrowserFrameURL from './BrowserFrameURL.js';
+import BrowserFrameValidator from './BrowserFrameValidator.js';
+import AsyncTaskManager from '../../async-task-manager/AsyncTaskManager.js';
+import BrowserErrorCaptureEnum from '../enums/BrowserErrorCaptureEnum.js';
+
+/**
+ * Browser frame navigation utility.
+ */
+export default class BrowserFrameNavigator {
+	/**
+	 * Go to a page.
+	 *
+	 * @throws Error if the request can't be resolved (because of SSL error or similar). It will not throw if the response is not ok.
+	 * @param windowClass Window class.
+	 * @param frame Frame.
+	 * @param url URL.
+	 * @param [options] Options.
+	 * @returns Response.
+	 */
+	public static async goto(
+		windowClass: new (
+			browserFrame: IBrowserFrame,
+			options?: { url?: string; width?: number; height?: number }
+		) => IBrowserWindow,
+		frame: IBrowserFrame,
+		url: string,
+		options?: IGoToOptions
+	): Promise<IResponse | null> {
+		const targetURL = BrowserFrameURL.getRelativeURL(frame, url);
+
+		if (!frame.window) {
+			throw new Error('The frame has been destroyed, the "window" property is not set.');
+		}
+
+		if (targetURL.protocol === 'javascript:') {
+			if (frame && !frame.page.context.browser.settings.disableJavaScriptEvaluation) {
+				const readyStateManager = (<
+					{ [PropertySymbol.readyStateManager]: DocumentReadyStateManager }
+				>(<unknown>frame.window))[PropertySymbol.readyStateManager];
+
+				readyStateManager.startTask();
+
+				// The browser will wait for the next tick before executing the script.
+				await new Promise((resolve) => frame.page.mainFrame.window.setTimeout(resolve));
+
+				const code =
+					'//# sourceURL=' + frame.url + '\n' + targetURL.href.replace('javascript:', '');
+
+				if (
+					frame.page.context.browser.settings.disableErrorCapturing ||
+					frame.page.context.browser.settings.errorCapture !== BrowserErrorCaptureEnum.tryAndCatch
+				) {
+					frame.window.eval(code);
+				} else {
+					WindowErrorUtility.captureError(frame.window, () => frame.window.eval(code));
+				}
+
+				readyStateManager.endTask();
+			}
+
+			return null;
+		}
+
+		if (!BrowserFrameValidator.validateCrossOriginPolicy(frame, targetURL)) {
+			return null;
+		}
+
+		if (!BrowserFrameValidator.validateFrameNavigation(frame)) {
+			if (!frame.page.context.browser.settings.navigation.disableFallbackToSetURL) {
+				(<Location>frame.window.location) = new Location(frame, targetURL.href);
+			}
+
+			return null;
+		}
+
+		const width = frame.window.innerWidth;
+		const height = frame.window.innerHeight;
+		const devicePixelRatio = frame.window.devicePixelRatio;
+
+		for (const childFrame of frame.childFrames) {
+			BrowserFrameFactory.destroyFrame(childFrame);
+		}
+
+		(<IBrowserFrame[]>frame.childFrames) = [];
+		frame.window[PropertySymbol.destroy]();
+		frame[PropertySymbol.asyncTaskManager].destroy();
+		frame[PropertySymbol.asyncTaskManager] = new AsyncTaskManager();
+
+		(<IBrowserWindow>frame.window) = new windowClass(frame, { url: targetURL.href, width, height });
+		(<number>frame.window.devicePixelRatio) = devicePixelRatio;
+
+		if (options?.referrer) {
+			(<string>frame.window.document.referrer) = options.referrer;
+		}
+
+		if (targetURL.protocol === 'about:') {
+			return null;
+		}
+
+		const readyStateManager = (<{ [PropertySymbol.readyStateManager]: DocumentReadyStateManager }>(
+			(<unknown>frame.window)
+		))[PropertySymbol.readyStateManager];
+
+		readyStateManager.startTask();
+
+		const abortController = new AbortController();
+		let response: IResponse;
+		let responseText: string;
+
+		const timeout = frame.window.setTimeout(
+			() => abortController.abort('Request timed out.'),
+			options?.timeout ?? 30000
+		);
+		const finalize = (): void => {
+			frame.window.clearTimeout(timeout);
+			readyStateManager.endTask();
+			const listeners = frame[PropertySymbol.listeners].navigation;
+			frame[PropertySymbol.listeners].navigation = [];
+			for (const listener of listeners) {
+				listener();
+			}
+		};
+
+		try {
+			response = await frame.window.fetch(targetURL.href, {
+				referrer: options?.referrer,
+				referrerPolicy: options?.referrerPolicy,
+				signal: abortController.signal,
+				headers: options?.hard ? { 'Cache-Control': 'no-cache' } : undefined
+			});
+
+			// Handles the "X-Frame-Options" header for child frames.
+			if (frame.parentFrame) {
+				const originURL = frame.parentFrame.window.location;
+				const xFrameOptions = response.headers.get('X-Frame-Options')?.toLowerCase();
+				const isSameOrigin = originURL.origin === targetURL.origin || targetURL.origin === 'null';
+
+				if (xFrameOptions === 'deny' || (xFrameOptions === 'sameorigin' && !isSameOrigin)) {
+					throw new Error(
+						`Refused to display '${url}' in a frame because it set 'X-Frame-Options' to '${xFrameOptions}'.`
+					);
+				}
+			}
+
+			responseText = await response.text();
+		} catch (error) {
+			finalize();
+			throw error;
+		}
+
+		if (!response.ok) {
+			frame.page.console.error(`GET ${targetURL.href} ${response.status} (${response.statusText})`);
+		}
+
+		// Fixes issue where evaluating the response can throw an error.
+		// By using requestAnimationFrame() the error will not reject the promise.
+		// The error will be caught by process error level listener or a try and catch in the requestAnimationFrame().
+		frame.window.requestAnimationFrame(() => (frame.content = responseText));
+
+		await new Promise((resolve) =>
+			frame.window.requestAnimationFrame(() => {
+				finalize();
+				resolve(null);
+			})
+		);
+
+		return response;
+	}
+}