@wordpress/e2e-test-utils-playwright 1.47.0 → 1.48.0

package/src/metrics/index.ts

@@ -0,0 +1,441 @@
+/**
+ * External dependencies
+ */
+import { mkdir, writeFile } from 'fs/promises';
+import { join } from 'path';
+import type { Page, Browser } from '@playwright/test';
+// resolution-mode support in TypeScript 5.3 will resolve this.
+// See https://devblogs.microsoft.com/typescript/announcing-typescript-5-3-beta/
+// @ts-expect-error
+import type { Metric } from 'web-vitals';
+
+type EventType =
+	| 'click'
+	| 'focus'
+	| 'focusin'
+	| 'keydown'
+	| 'keypress'
+	| 'keyup'
+	| 'mouseout'
+	| 'mouseover';
+
+interface TraceEvent {
+	cat: string;
+	name: string;
+	dur?: number;
+	args: {
+		data?: {
+			type: EventType;
+		};
+	};
+}
+
+interface Trace {
+	traceEvents: TraceEvent[];
+}
+
+type MetricsConstructorProps = {
+	page: Page;
+};
+
+interface WebVitalsMeasurements {
+	CLS?: number;
+	FCP?: number;
+	FID?: number;
+	INP?: number;
+	LCP?: number;
+	TTFB?: number;
+}
+
+export class Metrics {
+	browser: Browser;
+	page: Page;
+	trace: Trace;
+
+	webVitals: WebVitalsMeasurements = {};
+
+	constructor( { page }: MetricsConstructorProps ) {
+		this.page = page;
+		this.browser = page.context().browser()!;
+		this.trace = { traceEvents: [] };
+	}
+
+	/**
+	 * Returns durations from the Server-Timing header.
+	 *
+	 * @param fields Optional fields to filter.
+	 */
+	async getServerTiming( fields: string[] = [] ) {
+		return this.page.evaluate< Record< string, number >, string[] >(
+			( f: string[] ) =>
+				(
+					performance.getEntriesByType(
+						'navigation'
+					) as PerformanceNavigationTiming[]
+				 )[ 0 ].serverTiming.reduce(
+					( acc, entry ) => {
+						if ( f.length === 0 || f.includes( entry.name ) ) {
+							acc[ entry.name ] = entry.duration;
+						}
+						return acc;
+					},
+					{} as Record< string, number >
+				),
+			fields
+		);
+	}
+
+	/**
+	 * Returns time to first byte (TTFB) using the Navigation Timing API.
+	 *
+	 * @see https://web.dev/ttfb/#measure-ttfb-in-javascript
+	 *
+	 * @return TTFB value.
+	 */
+	async getTimeToFirstByte() {
+		return await this.page.evaluate< number >( () => {
+			const { responseStart, startTime } = (
+				performance.getEntriesByType(
+					'navigation'
+				) as PerformanceNavigationTiming[]
+			 )[ 0 ];
+			return responseStart - startTime;
+		} );
+	}
+
+	/**
+	 * Returns the Largest Contentful Paint (LCP) value using the dedicated API.
+	 *
+	 * @see https://w3c.github.io/largest-contentful-paint/
+	 * @see https://web.dev/lcp/#measure-lcp-in-javascript
+	 *
+	 * @return LCP value.
+	 */
+	async getLargestContentfulPaint() {
+		return await this.page.evaluate< number >(
+			() =>
+				new Promise( ( resolve ) => {
+					new PerformanceObserver( ( entryList ) => {
+						const entries = entryList.getEntries();
+						// The last entry is the largest contentful paint.
+						const largestPaintEntry = entries.at( -1 );
+
+						resolve( largestPaintEntry?.startTime || 0 );
+					} ).observe( {
+						type: 'largest-contentful-paint',
+						buffered: true,
+					} );
+				} )
+		);
+	}
+
+	/**
+	 * Returns the Cumulative Layout Shift (CLS) value using the dedicated API.
+	 *
+	 * @see https://github.com/WICG/layout-instability
+	 * @see https://web.dev/cls/#measure-layout-shifts-in-javascript
+	 *
+	 * @return CLS value.
+	 */
+	async getCumulativeLayoutShift() {
+		return await this.page.evaluate< number >(
+			() =>
+				new Promise( ( resolve ) => {
+					let CLS = 0;
+
+					new PerformanceObserver( ( l ) => {
+						const entries = l.getEntries() as LayoutShift[];
+
+						entries.forEach( ( entry ) => {
+							if ( ! entry.hadRecentInput ) {
+								CLS += entry.value;
+							}
+						} );
+
+						resolve( CLS );
+					} ).observe( {
+						type: 'layout-shift',
+						buffered: true,
+					} );
+				} )
+		);
+	}
+
+	/**
+	 * Returns the loading durations using the Navigation Timing API. All the
+	 * durations exclude the server response time.
+	 *
+	 * @return Object with loading metrics durations.
+	 */
+	async getLoadingDurations() {
+		return await this.page.evaluate( () => {
+			const [
+				{
+					requestStart,
+					responseStart,
+					responseEnd,
+					domContentLoadedEventEnd,
+					loadEventEnd,
+				},
+			] = performance.getEntriesByType(
+				'navigation'
+			) as PerformanceNavigationTiming[];
+			const paintTimings = performance.getEntriesByType(
+				'paint'
+			) as PerformancePaintTiming[];
+
+			const firstPaintStartTime = paintTimings.find(
+				( { name } ) => name === 'first-paint'
+			)!.startTime;
+
+			const firstContentfulPaintStartTime = paintTimings.find(
+				( { name } ) => name === 'first-contentful-paint'
+			)!.startTime;
+
+			return {
+				// Server side metric.
+				serverResponse: responseStart - requestStart,
+				// For client side metrics, consider the end of the response (the
+				// browser receives the HTML) as the start time (0).
+				firstPaint: firstPaintStartTime - responseEnd,
+				domContentLoaded: domContentLoadedEventEnd - responseEnd,
+				loaded: loadEventEnd - responseEnd,
+				firstContentfulPaint:
+					firstContentfulPaintStartTime - responseEnd,
+				timeSinceResponseEnd: performance.now() - responseEnd,
+			};
+		} );
+	}
+
+	/**
+	 * Starts Chromium tracing with predefined options for performance testing.
+	 *
+	 * The category set mirrors what Chrome DevTools enables when recording in
+	 * the Performance panel: `devtools.timeline` provides the top-level event
+	 * tree, and the `disabled-by-default-v8.cpu_profiler` + companion
+	 * `devtools.timeline.stack` categories enable the V8 sampler that
+	 * populates JavaScript call stacks. Without the latter, the saved trace
+	 * shows only opaque "Function call" blocks with no JS frames inside.
+	 *
+	 * @param options Options to pass to `browser.startTracing()`.
+	 */
+	async startTracing( options = {} ) {
+		return await this.browser.startTracing( this.page, {
+			screenshots: false,
+			categories: [
+				'devtools.timeline',
+				'disabled-by-default-devtools.timeline',
+				'disabled-by-default-devtools.timeline.stack',
+				'disabled-by-default-v8.cpu_profiler',
+				'v8.execute',
+			],
+			...options,
+		} );
+	}
+
+	/**
+	 * Stops Chromium tracing.
+	 *
+	 * When `name` is a non-empty string and the `WP_ARTIFACTS_PATH` environment
+	 * variable is set, the raw trace is written to
+	 * `${WP_ARTIFACTS_PATH}/traces/<name>.trace.json`. The resulting file can
+	 * be opened in Chrome DevTools (Performance panel → "Load profile…") to
+	 * inspect the flame graph. Pass a falsy value (or omit the argument) to
+	 * just parse the trace into `this.trace` without writing — this is the
+	 * default for iteration loops, where you typically want to save only one
+	 * representative sample. Callers pick which iteration that is, e.g.
+	 * `i === Math.floor( iterations / 2 ) && 'post-editor-first-block'`.
+	 *
+	 * @param name File name (without extension) identifying the scenario, or
+	 *             `false`/`undefined` to skip writing.
+	 */
+	async stopTracing( name?: string | false ) {
+		const traceBuffer = await this.browser.stopTracing();
+		const traceJSON = JSON.parse( traceBuffer.toString() );
+
+		this.trace = traceJSON;
+
+		if ( ! name ) {
+			return;
+		}
+
+		const artifactsPath = process.env.WP_ARTIFACTS_PATH;
+		if ( ! artifactsPath ) {
+			return;
+		}
+
+		// The perf comparison flow runs the same suite against multiple
+		// branches into a single artifacts directory; the comparison branches
+		// set WP_PERF_NO_TRACE so the head branch's traces aren't overwritten.
+		if ( process.env.WP_PERF_NO_TRACE ) {
+			return;
+		}
+
+		// Traces are saved minified. Run the following against a downloaded trace
+		// + matching `build/` directory to rewrite minified `functionName`s back
+		// to their source identifiers:
+		//
+		//   node tools/build-scripts/packages/resolve-trace-source-maps.cjs
+		//
+		// Or via the workspace script:
+		//
+		//   npm run --workspace @wordpress/build-scripts resolve-trace-source-maps -- <trace.json> [--build-dir <dir>]
+		const tracesDir = join( artifactsPath, 'traces' );
+		const filePath = join( tracesDir, `${ name }.trace.json` );
+		await mkdir( tracesDir, { recursive: true } );
+		await writeFile( filePath, JSON.stringify( traceJSON ) );
+	}
+
+	/**
+	 * @return Durations of all traced `keydown`, `keypress`, and `keyup`
+	 * events.
+	 */
+	getTypingEventDurations() {
+		return [
+			this.getEventDurations( 'keydown' ),
+			this.getEventDurations( 'keypress' ),
+			this.getEventDurations( 'keyup' ),
+		];
+	}
+
+	/**
+	 * @return Durations of all traced `focus` and `focusin` events.
+	 */
+	getSelectionEventDurations() {
+		return [
+			this.getEventDurations( 'focus' ),
+			this.getEventDurations( 'focusin' ),
+		];
+	}
+
+	/**
+	 * @return Durations of all traced `click` events.
+	 */
+	getClickEventDurations() {
+		return [ this.getEventDurations( 'click' ) ];
+	}
+
+	/**
+	 * @return Durations of all traced `mouseover` and `mouseout` events.
+	 */
+	getHoverEventDurations() {
+		return [
+			this.getEventDurations( 'mouseover' ),
+			this.getEventDurations( 'mouseout' ),
+		];
+	}
+
+	/**
+	 * @param eventType Type of event to filter.
+	 * @return Durations of all events of a given type.
+	 */
+	getEventDurations( eventType: EventType ) {
+		if ( this.trace.traceEvents.length === 0 ) {
+			throw new Error(
+				'No trace events found. Did you forget to call stopTracing()?'
+			);
+		}
+
+		return this.trace.traceEvents
+			.filter(
+				( item: TraceEvent ): boolean =>
+					item.cat === 'devtools.timeline' &&
+					item.name === 'EventDispatch' &&
+					item?.args?.data?.type === eventType &&
+					!! item.dur
+			)
+			.map( ( item ) => ( item.dur ? item.dur / 1000 : 0 ) );
+	}
+
+	/**
+	 * Initializes the web-vitals library upon next page navigation.
+	 *
+	 * Defaults to automatically triggering the navigation,
+	 * but it can also be done manually.
+	 *
+	 * @example
+	 * ```js
+	 * await metrics.initWebVitals();
+	 * console.log( await metrics.getWebVitals() );
+	 * ```
+	 *
+	 * @example
+	 * ```js
+	 * await metrics.initWebVitals( false );
+	 * await page.goto( '/some-other-page' );
+	 * console.log( await metrics.getWebVitals() );
+	 * ```
+	 *
+	 * @param reload Whether to force navigation by reloading the current page.
+	 */
+	async initWebVitals( reload = true ) {
+		await this.page.addInitScript( {
+			path: join(
+				__dirname,
+				'../../../../node_modules/web-vitals/dist/web-vitals.umd.cjs'
+			),
+		} );
+
+		await this.page.exposeFunction(
+			'__reportVitals__',
+			( data: string ) => {
+				const measurement: Metric = JSON.parse( data );
+				this.webVitals[ measurement.name ] = measurement.value;
+			}
+		);
+
+		await this.page.addInitScript( () => {
+			const reportVitals = ( measurement: unknown ) =>
+				window.__reportVitals__( JSON.stringify( measurement ) );
+
+			window.addEventListener( 'DOMContentLoaded', () => {
+				// @ts-expect-error This is valid but web-vitals does not register the global types.
+				window.webVitals.onCLS( reportVitals );
+				// @ts-expect-error This is valid but web-vitals does not register the global types.
+				window.webVitals.onFCP( reportVitals );
+				// @ts-expect-error This is valid but web-vitals does not register the global types.
+				window.webVitals.onFID( reportVitals );
+				// @ts-expect-error This is valid but web-vitals does not register the global types.
+				window.webVitals.onINP( reportVitals );
+				// @ts-expect-error This is valid but web-vitals does not register the global types.
+				window.webVitals.onLCP( reportVitals );
+				// @ts-expect-error This is valid but web-vitals does not register the global types.
+				window.webVitals.onTTFB( reportVitals );
+			} );
+		} );
+
+		if ( reload ) {
+			// By reloading the page the script will be applied.
+			await this.page.reload();
+		}
+	}
+
+	/**
+	 * Returns web vitals as collected by the web-vitals library.
+	 *
+	 * If the web-vitals library hasn't been loaded on the current page yet,
+	 * it will be initialized with a page reload.
+	 *
+	 * Reloads the page to force web-vitals to report all collected metrics.
+	 *
+	 * @return {WebVitalsMeasurements} Web vitals measurements.
+	 */
+	async getWebVitals() {
+		// Reset values.
+		this.webVitals = {};
+
+		const hasScript = await this.page.evaluate(
+			// @ts-expect-error This is valid but web-vitals does not register the global types.
+			() => typeof window.webVitals !== 'undefined'
+		);
+
+		if ( ! hasScript ) {
+			await this.initWebVitals();
+		}
+
+		// Trigger navigation so the web-vitals library reports values on unload.
+		await this.page.reload();
+
+		return this.webVitals;
+	}
+}

package/src/page-utils/drag-files.ts

@@ -0,0 +1,173 @@
+/**
+ * External dependencies
+ */
+import { readFile } from 'fs/promises';
+import { basename } from 'path';
+import { getType } from 'mime';
+
+/**
+ * Internal dependencies
+ */
+import type { PageUtils } from './index';
+import type { Locator } from '@playwright/test';
+
+type FileObject = {
+	name: string;
+	mimeType?: string;
+	buffer: Buffer;
+};
+
+type Options = {
+	position?: { x: number; y: number };
+};
+
+/**
+ * Simulate dragging files from outside the current page.
+ *
+ * @param this
+ * @param files The files to be dragged.
+ * @return The methods of the drag operation.
+ */
+async function dragFiles(
+	this: PageUtils,
+	files: string | string[] | FileObject | FileObject[]
+) {
+	const filesList = Array.isArray( files ) ? files : [ files ];
+	const fileObjects = await Promise.all(
+		filesList.map( async ( filePathOrObject ) => {
+			if ( typeof filePathOrObject !== 'string' ) {
+				return {
+					name: filePathOrObject.name,
+					mimeType:
+						filePathOrObject.mimeType ||
+						getType( filePathOrObject.name ),
+					base64: filePathOrObject.buffer.toString( 'base64' ),
+				};
+			}
+			const base64 = await readFile( filePathOrObject, 'base64' );
+			const name = basename( filePathOrObject );
+			return {
+				name,
+				mimeType: getType( filePathOrObject ),
+				base64,
+			};
+		} )
+	);
+
+	// CDP doesn't actually support dragging files, this is only a _good enough_
+	// dummy data so that it will correctly send the relevant events.
+	const dragData = {
+		items: fileObjects.map( ( fileObject ) => ( {
+			mimeType: fileObject.mimeType ?? 'File',
+			data: fileObject.base64,
+		} ) ),
+		files: fileObjects.map( ( fileObject ) => fileObject.name ),
+		// Copy = 1, Link = 2, Move = 16.
+		dragOperationsMask: 1,
+	};
+
+	const cdpSession = await this.context.newCDPSession( this.page );
+
+	const position = {
+		x: 0,
+		y: 0,
+	};
+
+	return {
+		/**
+		 * Drag the files over an element (fires `dragenter` and `dragover` events).
+		 *
+		 * @param selectorOrLocator A selector or a locator to search for an element.
+		 * @param options           The optional options.
+		 * @param options.position  A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the element.
+		 */
+		dragOver: async (
+			selectorOrLocator: string | Locator,
+			options: Options = {}
+		) => {
+			const locator =
+				typeof selectorOrLocator === 'string'
+					? this.page.locator( selectorOrLocator )
+					: selectorOrLocator;
+			const boundingBox = await locator.boundingBox();
+
+			if ( ! boundingBox ) {
+				throw new Error(
+					'Cannot find the element or the element is not visible on the viewport.'
+				);
+			}
+
+			position.x =
+				boundingBox.x +
+				( options.position?.x ?? boundingBox.width / 2 );
+			position.y =
+				boundingBox.y +
+				( options.position?.y ?? boundingBox.height / 2 );
+
+			await cdpSession.send( 'Input.dispatchDragEvent', {
+				type: 'dragEnter',
+				...position,
+				data: dragData,
+			} );
+			await cdpSession.send( 'Input.dispatchDragEvent', {
+				type: 'dragOver',
+				...position,
+				data: dragData,
+			} );
+		},
+
+		/**
+		 * Drop the files at the current position.
+		 */
+		drop: async () => {
+			const topMostElement = await this.page.evaluateHandle(
+				( { x, y } ) => {
+					const element = document.elementFromPoint( x, y );
+					if ( element instanceof HTMLIFrameElement ) {
+						const offsetBox = element.getBoundingClientRect();
+						return element.contentDocument!.elementFromPoint(
+							x - offsetBox.x,
+							y - offsetBox.y
+						);
+					}
+					return element;
+				},
+				position
+			);
+			const elementHandle = topMostElement.asElement();
+
+			if ( ! elementHandle ) {
+				throw new Error( 'Element not found.' );
+			}
+
+			const dataTransfer = await elementHandle.evaluateHandle(
+				async ( _node, _fileObjects ) => {
+					const dt = new DataTransfer();
+					const fileInstances = await Promise.all(
+						_fileObjects.map( async ( fileObject: any ) => {
+							const blob = await fetch(
+								`data:${ fileObject.mimeType };base64,${ fileObject.base64 }`
+							).then( ( res ) => res.blob() );
+							return new File( [ blob ], fileObject.name, {
+								type: fileObject.mimeType ?? undefined,
+							} );
+						} )
+					);
+
+					fileInstances.forEach( ( file ) => {
+						dt.items.add( file );
+					} );
+
+					return dt;
+				},
+				fileObjects
+			);
+
+			await elementHandle.dispatchEvent( 'drop', { dataTransfer } );
+
+			await cdpSession.detach();
+		},
+	};
+}
+
+export { dragFiles };

package/src/page-utils/emulate-network-conditions.ts

@@ -0,0 +1,101 @@
+/**
+ * Internal dependencies
+ */
+import type { PageUtils } from './';
+
+interface NetworkConditions {
+	/**
+	 * True to emulate internet disconnection.
+	 */
+	offline: boolean;
+	/**
+	 * Minimum latency from request sent to response headers received (ms).
+	 */
+	latency: number;
+	/**
+	 * Maximal aggregated download throughput (bytes/sec). -1 disables download throttling.
+	 */
+	downloadThroughput: number;
+	/**
+	 * Maximal aggregated upload throughput (bytes/sec).  -1 disables upload throttling.
+	 */
+	uploadThroughput: number;
+}
+
+// Defaults from https://github.com/puppeteer/puppeteer/blob/401355610874beac23a51dcb75739a4bb4191a2b/packages/puppeteer-core/src/cdp/PredefinedNetworkConditions.ts.
+const PredefinedNetworkConditions: Record< string, NetworkConditions > = {
+	// Generally aligned with DevTools
+	// https://source.chromium.org/chromium/chromium/src/+/main:third_party/devtools-frontend/src/front_end/core/sdk/NetworkManager.ts;l=398;drc=225e1240f522ca684473f541ae6dae6cd766dd33.
+	'Slow 3G': {
+		offline: false,
+		// ~500Kbps down
+		downloadThroughput: ( ( 500 * 1000 ) / 8 ) * 0.8,
+		// ~500Kbps up
+		uploadThroughput: ( ( 500 * 1000 ) / 8 ) * 0.8,
+		// 400ms RTT
+		latency: 400 * 5,
+	},
+	'Fast 3G': {
+		offline: false,
+		// ~1.6 Mbps down
+		downloadThroughput: ( ( 1.6 * 1000 * 1000 ) / 8 ) * 0.9,
+		// ~0.75 Mbps up
+		uploadThroughput: ( ( 750 * 1000 ) / 8 ) * 0.9,
+		// 150ms RTT
+		latency: 150 * 3.75,
+	},
+	// alias to Fast 3G to align with Lighthouse (crbug.com/342406608)
+	// and DevTools (crbug.com/342406608),
+	'Slow 4G': {
+		offline: false,
+		// ~1.6 Mbps down
+		downloadThroughput: ( ( 1.6 * 1000 * 1000 ) / 8 ) * 0.9,
+		// ~0.75 Mbps up
+		uploadThroughput: ( ( 750 * 1000 ) / 8 ) * 0.9,
+		// 150ms RTT
+		latency: 150 * 3.75,
+	},
+	'Fast 4G': {
+		offline: false,
+		// 9 Mbps down
+		downloadThroughput: ( ( 9 * 1000 * 1000 ) / 8 ) * 0.9,
+		// 1.5 Mbps up
+		uploadThroughput: ( ( 1.5 * 1000 * 1000 ) / 8 ) * 0.9,
+		// 60ms RTT
+		latency: 60 * 2.75,
+	},
+	/**
+	 * Network conditions used for desktop in Lighthouse/PSI.
+	 *
+	 * 10,240 kb/s throughput with 40 ms TCP RTT.
+	 *
+	 * @see https://github.com/paulirish/lighthouse/blob/f0855904aaffaecf3089169449646960782d7e92/core/config/constants.js#L40-L49
+	 * @see https://docs.google.com/document/d/1-p4HSp42REEA5-jCBVB6PqQcVhI1nQIblBCNKhPJUXg/edit?tab=t.0#heading=h.jsap7yf4phk6
+	 */
+	Broadband: {
+		offline: false,
+		downloadThroughput: ( 10240 * 1000 ) / 8,
+		uploadThroughput: ( 10240 * 1000 ) / 8,
+		latency: 40,
+	},
+};
+
+export async function emulateNetworkConditions(
+	this: PageUtils,
+	condition: keyof typeof PredefinedNetworkConditions | NetworkConditions
+) {
+	if ( 'chromium' !== this.browserName ) {
+		throw new Error(
+			'CDP sessions are only supported on Chromium-based browsers'
+		);
+	}
+
+	const session = await this.page.context().newCDPSession( this.page );
+	await session.send(
+		'Network.emulateNetworkConditions',
+		'string' === typeof condition
+			? PredefinedNetworkConditions[ condition ]
+			: condition
+	);
+	await session.detach();
+}