happy-dom/src/browser/types/IOptionalBrowserSettings.ts

Happy DOM is a JavaScript implementation of a web browser without its graphical user interface. It includes many web standards from WHATWG DOM and HTML.

import type BrowserErrorCaptureEnum from '../enums/BrowserErrorCaptureEnum.js';
import type BrowserNavigationCrossOriginPolicyEnum from '../enums/BrowserNavigationCrossOriginPolicyEnum.js';
import type IFetchInterceptor from '../../fetch/types/IFetchInterceptor.js';
import type IVirtualServer from '../../fetch/types/IVirtualServer.js';
import type IFetchRequestHeaders from '../../fetch/types/IFetchRequestHeaders.js';
import type IOptionalBrowserPageViewport from './IOptionalBrowserPageViewport.js';
import type IOptionalTimerLoopsLimit from '../../window/IOptionalTimerLoopsLimit.js';
import type BrowserWindow from '../../window/BrowserWindow.js';
import type IResolveNodeModules from '../../module/types/IResolveNodeModules.js';

export default interface IOptionalBrowserSettings {
	/**
	 * Disables JavaScript evaluation.
	 *
	 * @deprecated Javascript evaluation is now disabled by default. Use "enableJavaScriptEvaluation" if you want to enable it.
	 */
	disableJavaScriptEvaluation?: boolean;

	/**
	 * Enables JavaScript evaluation.
	 *
	 * A VM Context is not an isolated environment, and if you run untrusted code you are at risk of RCE (Remote Code Execution) attacks.
	 * It is recommended to disable code generation at process level by running node with the "--disallow-code-generation-from-strings" flag enabled to protect against these types of attacks.
	 *
	 * @see https://github.com/capricorn86/happy-dom/wiki/Code-Generation-From-Strings-Warning
	 */
	enableJavaScriptEvaluation?: boolean;

	/** Disables JavaScript file loading. */
	disableJavaScriptFileLoading?: boolean;

	/** Disables CSS file loading. */
	disableCSSFileLoading?: boolean;

	/** Disables computed style rendering. */
	disableComputedStyleRendering?: boolean;

	/** Handle disabled file loading as success */
	handleDisabledFileLoadingAsSuccess?: boolean;

	/**
	 * Suppresses the warning that is printed when code generation from strings is enabled at process level.
	 *
	 * @deprecated Use "suppressInsecureJavaScriptEnvironmentWarning" instead.
	 */
	suppressCodeGenerationFromStringsWarning?: boolean;

	/** Suppresses the warning that is printed when the JavaScript execution environment is insecure. */
	suppressInsecureJavaScriptEnvironmentWarning?: boolean;

	/** Settings for timers */
	timer?: {
		maxTimeout?: number;
		maxIntervalTime?: number;
		maxIntervalIterations?: number;
		preventTimerLoops?: boolean | IOptionalTimerLoopsLimit;
	};

	/**
	 * Settings for fetch
	 */
	fetch?: {
		/**
		 * Disables same-origin policy (CORS)
		 *
		 * @see https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy
		 */
		disableSameOriginPolicy?: boolean;

		/**
		 * Disables validation of certificates against the list of supplied CAs.
		 *
		 * Disabling this feature makes it possible to use self-signed certificates or certificates that are not signed by a trusted CA.
		 */
		disableStrictSSL?: boolean;

		/**
		 * Fetch interceptor.
		 */
		interceptor?: IFetchInterceptor | null;

		/**
		 * Add request headers to specific URLs.
		 */
		requestHeaders?: IFetchRequestHeaders[] | null;

		/**
		 * Virtual servers used for simulating a server that reads from the file system.
		 */
		virtualServers?: IVirtualServer[] | null;
	};

	/**
	 * Settings for modules
	 */
	module?: {
		/** Resolve node modules to the defined URL */
		resolveNodeModules?: IResolveNodeModules | null;
		/** Sets a custom URL resolver */
		urlResolver?:
			| ((options: { url: string; parentURL: string; window: BrowserWindow }) => string)
			| null;
		/** Disables module compilation caching */
		disableCache?: 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;

		/** Triggered before content is loaded into the document */
		beforeContentCallback?: ((window: BrowserWindow) => void) | null;
	};

	/**
	 * Settings for the browser's navigator.
	 */
	navigator?: {
		userAgent?: string;
		maxTouchPoints?: number;
	};

	/**
	 * Settings for the browser's device.
	 */
	device?: {
		prefersColorScheme?: string;
		prefersReducedMotion?: string;
		mediaType?: string;
		forcedColors?: string;
	};

	/**
	 * Debug settings.
	 */
	debug?: {
		traceWaitUntilComplete?: number;
	};

	/**
	 * Default page viewport.
	 */
	viewport?: IOptionalBrowserPageViewport;
}