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

package/src/page-utils/index.ts

@@ -0,0 +1,54 @@
+/**
+ * External dependencies
+ */
+import type {
+	Browser,
+	Page,
+	BrowserContext,
+	PlaywrightWorkerOptions,
+} from '@playwright/test';
+
+/**
+ * Internal dependencies
+ */
+import { dragFiles } from './drag-files';
+import { isCurrentURL } from './is-current-url';
+import { setClipboardData, pressKeys } from './press-keys';
+import { setBrowserViewport } from './set-browser-viewport';
+import { emulateNetworkConditions } from './emulate-network-conditions';
+
+type PageUtilConstructorParams = {
+	page: Page;
+	browserName: PlaywrightWorkerOptions[ 'browserName' ];
+};
+
+class PageUtils {
+	browser: Browser;
+	page: Page;
+	context: BrowserContext;
+	browserName: PlaywrightWorkerOptions[ 'browserName' ];
+
+	constructor( { page, browserName }: PageUtilConstructorParams ) {
+		this.page = page;
+		this.context = page.context();
+		this.browser = this.context.browser()!;
+		this.browserName = browserName;
+	}
+
+	/** @borrows dragFiles as this.dragFiles */
+	dragFiles: typeof dragFiles = dragFiles.bind( this );
+	/** @borrows isCurrentURL as this.isCurrentURL */
+	isCurrentURL: typeof isCurrentURL = isCurrentURL.bind( this );
+	/** @borrows pressKeys as this.pressKeys */
+	pressKeys: typeof pressKeys = pressKeys.bind( this );
+	/** @borrows setBrowserViewport as this.setBrowserViewport */
+	setBrowserViewport: typeof setBrowserViewport =
+		setBrowserViewport.bind( this );
+	/** @borrows setClipboardData as this.setClipboardData */
+	setClipboardData: typeof setClipboardData = setClipboardData.bind( this );
+	/** @borrows emulateNetworkConditions as this.emulateNetworkConditions */
+	emulateNetworkConditions: typeof emulateNetworkConditions =
+		emulateNetworkConditions.bind( this );
+}
+
+export { PageUtils };

package/src/page-utils/is-current-url.ts

@@ -0,0 +1,20 @@
+/**
+ * Internal dependencies
+ */
+import { WP_BASE_URL } from '../config';
+import type { PageUtils } from './';
+
+/**
+ * Checks if current path of the URL matches the provided path.
+ *
+ * @param this
+ * @param path String to be serialized as pathname.
+ *
+ * @return Boolean represents whether current URL is or not a WordPress path.
+ */
+export function isCurrentURL( this: PageUtils, path: string ) {
+	const currentURL = new URL( this.page.url() );
+	const expectedURL = new URL( path, WP_BASE_URL );
+
+	return expectedURL.pathname === currentURL.pathname;
+}

package/src/page-utils/keycodes.ts

@@ -0,0 +1,48 @@
+/**
+ * This filed is partially copied from @wordpress/keycodes to keep the package
+ * (internal-)dependencies free.
+ */
+
+/**
+ * Keycode for ALT key.
+ */
+export const ALT = 'alt';
+
+/**
+ * Keycode for CTRL key.
+ */
+export const CTRL = 'ctrl';
+
+/**
+ * Keycode for COMMAND key.
+ */
+export const COMMAND = 'meta';
+
+/**
+ * Keycode for SHIFT key.
+ */
+export const SHIFT = 'shift';
+
+/**
+ * Object that contains functions that return the available modifier
+ * depending on platform.
+ */
+export const modifiers: Record<
+	string,
+	( _isApple: () => boolean ) => string[]
+> = {
+	primary: ( _isApple ) => ( _isApple() ? [ COMMAND ] : [ CTRL ] ),
+	primaryShift: ( _isApple ) =>
+		_isApple() ? [ SHIFT, COMMAND ] : [ CTRL, SHIFT ],
+	primaryAlt: ( _isApple ) =>
+		_isApple() ? [ ALT, COMMAND ] : [ CTRL, ALT ],
+	secondary: ( _isApple ) =>
+		_isApple() ? [ SHIFT, ALT, COMMAND ] : [ CTRL, SHIFT, ALT ],
+	access: ( _isApple ) => ( _isApple() ? [ CTRL, ALT ] : [ SHIFT, ALT ] ),
+	ctrl: () => [ CTRL ],
+	alt: () => [ ALT ],
+	ctrlShift: () => [ CTRL, SHIFT ],
+	shift: () => [ SHIFT ],
+	shiftAlt: () => [ SHIFT, ALT ],
+	undefined: () => [],
+};

package/src/page-utils/press-keys.ts

@@ -0,0 +1,195 @@
+/**
+ * External dependencies
+ */
+import { capitalCase } from 'change-case';
+import type { Page } from '@playwright/test';
+
+/**
+ * Internal dependencies
+ */
+import type { PageUtils } from './';
+import { modifiers as baseModifiers, SHIFT, ALT, CTRL } from './keycodes';
+
+let clipboardDataHolder: {
+	'text/plain': string;
+	'text/html': string;
+	'rich-text': string;
+} = {
+	'text/plain': '',
+	'text/html': '',
+	'rich-text': '',
+};
+
+/**
+ * Sets the clipboard data that can be pasted with
+ * `pressKeys( 'primary+v' )`.
+ *
+ * @param clipboardData
+ * @param clipboardData.plainText
+ * @param clipboardData.html
+ */
+export function setClipboardData(
+	this: PageUtils,
+	{ plainText = '', html = '' }
+) {
+	clipboardDataHolder = {
+		'text/plain': plainText,
+		'text/html': html,
+		'rich-text': '',
+	};
+}
+
+async function emulateClipboard( page: Page, type: 'copy' | 'cut' | 'paste' ) {
+	const output = await page.evaluate(
+		( [ _type, _clipboardData ] ) => {
+			const canvasDoc =
+				// @ts-ignore
+				document.activeElement?.contentDocument ?? document;
+			const event = new ClipboardEvent( _type, {
+				bubbles: true,
+				cancelable: true,
+				clipboardData: new DataTransfer(),
+			} );
+
+			if ( ! event.clipboardData ) {
+				throw new Error( 'ClipboardEvent.clipboardData is null' );
+			}
+
+			if ( _type === 'paste' ) {
+				event.clipboardData.setData(
+					'text/plain',
+					_clipboardData[ 'text/plain' ]
+				);
+				event.clipboardData.setData(
+					'text/html',
+					_clipboardData[ 'text/html' ]
+				);
+				event.clipboardData.setData(
+					'rich-text',
+					_clipboardData[ 'rich-text' ]
+				);
+			} else {
+				const selection = canvasDoc.defaultView.getSelection()!;
+				const plainText = selection.toString();
+				let html = plainText;
+				if ( selection.rangeCount ) {
+					const range = selection.getRangeAt( 0 );
+					const fragment = range.cloneContents();
+					html = Array.from( fragment.childNodes )
+						.map(
+							( node ) =>
+								( node as Element ).outerHTML ??
+								( node as Element ).nodeValue
+						)
+						.join( '' );
+				}
+				event.clipboardData.setData( 'text/plain', plainText );
+				event.clipboardData.setData( 'text/html', html );
+			}
+
+			canvasDoc.activeElement.dispatchEvent( event );
+
+			if ( _type === 'paste' ) {
+				return event.defaultPrevented;
+			}
+
+			return {
+				'text/plain': event.clipboardData.getData( 'text/plain' ),
+				'text/html': event.clipboardData.getData( 'text/html' ),
+				'rich-text': event.clipboardData.getData( 'rich-text' ),
+			};
+		},
+		[ type, clipboardDataHolder ] as const
+	);
+
+	if ( typeof output === 'object' ) {
+		clipboardDataHolder = output;
+	}
+
+	if ( output === false ) {
+		// Emulate paste by typing the clipboard content, which works across all
+		// elements and documents (keyboard.type does uses the nested active
+		// element automatically).
+		await page.keyboard.type( clipboardDataHolder[ 'text/plain' ] );
+	}
+}
+
+const isAppleOS = () => process.platform === 'darwin';
+
+const isWebkit = ( page: Page ) =>
+	page.context().browser()!.browserType().name() === 'webkit';
+
+const browserCache = new WeakMap();
+const getHasNaturalTabNavigation = async ( page: Page ) => {
+	if ( ! isAppleOS() || ! isWebkit( page ) ) {
+		return true;
+	}
+	if ( browserCache.has( page.context().browser()! ) ) {
+		return browserCache.get( page.context().browser()! );
+	}
+	const testPage = await page.context().newPage();
+	await testPage.setContent( `<button>1</button><button>2</button>` );
+	await testPage.getByText( '1' ).focus();
+	await testPage.keyboard.press( 'Tab' );
+	const featureDetected = await testPage
+		.getByText( '2' )
+		.evaluate( ( node ) => node === document.activeElement );
+	browserCache.set( page.context().browser()!, featureDetected );
+	await testPage.close();
+	return featureDetected;
+};
+
+type Options = {
+	times?: number;
+	delay?: number;
+};
+
+const modifiers = {
+	...baseModifiers,
+	shiftAlt: ( _isApple: () => boolean ) =>
+		_isApple() ? [ SHIFT, ALT ] : [ SHIFT, CTRL ],
+};
+
+export async function pressKeys(
+	this: PageUtils,
+	key: string,
+	{ times, ...pressOptions }: Options = {}
+) {
+	const hasNaturalTabNavigation = await getHasNaturalTabNavigation(
+		this.page
+	);
+
+	let command: () => Promise< void >;
+
+	if ( key.toLowerCase() === 'primary+c' ) {
+		command = () => emulateClipboard( this.page, 'copy' );
+	} else if ( key.toLowerCase() === 'primary+x' ) {
+		command = () => emulateClipboard( this.page, 'cut' );
+	} else if ( key.toLowerCase() === 'primary+v' ) {
+		command = () => emulateClipboard( this.page, 'paste' );
+	} else {
+		const keys = key.split( '+' ).flatMap( ( keyCode ) => {
+			if ( Object.prototype.hasOwnProperty.call( modifiers, keyCode ) ) {
+				return modifiers[ keyCode as keyof typeof modifiers ](
+					isAppleOS
+				).map( ( modifier ) =>
+					modifier === CTRL ? 'Control' : capitalCase( modifier )
+				);
+			} else if ( keyCode === 'Tab' && ! hasNaturalTabNavigation ) {
+				return [ 'Alt', 'Tab' ];
+			}
+			return keyCode;
+		} );
+		const normalizedKeys = keys.join( '+' );
+		command = () => this.page.keyboard.press( normalizedKeys );
+	}
+
+	times = times ?? 1;
+	for ( let i = 0; i < times; i += 1 ) {
+		await command();
+
+		if ( times > 1 && pressOptions.delay ) {
+			await this.page.waitForTimeout( pressOptions.delay );
+		}
+	}
+}

package/{build → src}/page-utils/set-browser-viewport.js

@@ -1,11 +1,9 @@
-"use strict";
 /**
  * Named viewport options.
  *
  * @typedef {"large"|"medium"|"small"} WPDimensionsName
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.setBrowserViewport = setBrowserViewport;
+
 /**
  * Viewport dimensions object.
  *
@@ -14,6 +12,7 @@ exports.setBrowserViewport = setBrowserViewport;
  * @property {number} width  Width, in pixels.
  * @property {number} height Height, in pixels.
  */
+
 /**
  * Predefined viewport dimensions to reference by name.
  *
@@ -22,25 +21,28 @@ exports.setBrowserViewport = setBrowserViewport;
  * @type {Record<WPDimensionsName, WPViewportDimensions>}
  */
 const PREDEFINED_DIMENSIONS = {
-    large: { width: 960, height: 700 },
-    medium: { width: 768, height: 700 },
-    small: { width: 600, height: 700 },
+	large: { width: 960, height: 700 },
+	medium: { width: 768, height: 700 },
+	small: { width: 600, height: 700 },
 };
+
 /**
  * Valid argument argument type from which to derive viewport dimensions.
  *
  * @typedef {WPDimensionsName|WPViewportDimensions} WPViewport
  */
+
 /**
  * Sets browser viewport to specified type.
  *
  * @this {import('./').PageUtils}
  * @param {WPViewport} viewport Viewport name or dimensions object to assign.
  */
-async function setBrowserViewport(viewport) {
-    const dimensions = typeof viewport === 'string'
-        ? PREDEFINED_DIMENSIONS[viewport]
-        : viewport;
-    await this.page.setViewportSize(dimensions);
+export async function setBrowserViewport( viewport ) {
+	const dimensions =
+		typeof viewport === 'string'
+			? PREDEFINED_DIMENSIONS[ viewport ]
+			: viewport;
+
+	await this.page.setViewportSize( dimensions );
 }
-//# sourceMappingURL=set-browser-viewport.js.map

package/src/request-utils/blocks.ts

@@ -0,0 +1,58 @@
+/**
+ * Internal dependencies
+ */
+import type { RequestUtils } from './index';
+
+type CreateBlockPayload = {
+	date?: string;
+	date_gmt?: string;
+	slug?: string;
+	title: string;
+	status: 'publish' | 'future' | 'draft' | 'pending' | 'private';
+	content?: string;
+	meta?: unknown;
+	wp_pattern_category?: number[];
+};
+
+/**
+ * Delete all blocks using REST API.
+ *
+ * @see https://developer.wordpress.org/rest-api/reference/blocks/#list-editor-blocks
+ * @param this
+ */
+export async function deleteAllBlocks( this: RequestUtils ) {
+	// List all blocks.
+	// https://developer.wordpress.org/rest-api/reference/blocks/#list-editor-blocks
+	const blocks = await this.rest( {
+		path: '/wp/v2/blocks',
+		params: {
+			per_page: 100,
+			// All possible statuses.
+			status: 'publish,future,draft,pending,private,trash',
+		},
+	} );
+
+	// Delete blocks.
+	// https://developer.wordpress.org/rest-api/reference/blocks/#delete-a-editor-block
+	// "/wp/v2/posts" not yet supports batch requests.
+	await this.batchRest(
+		blocks.map( ( block: { id: number } ) => ( {
+			method: 'DELETE',
+			path: `/wp/v2/blocks/${ block.id }?force=true`,
+		} ) )
+	);
+}
+
+/**
+ * Creates a new block using the REST API.
+ *
+ * @see https://developer.wordpress.org/rest-api/reference/blocks/#create-a-editor-block.
+ * @param this
+ * @param payload Block payload.
+ */
+export async function createBlock(
+	this: RequestUtils,
+	payload: CreateBlockPayload
+) {
+	return this.createRecord( 'blocks', { ...payload } );
+}

package/src/request-utils/comments.ts

@@ -0,0 +1,80 @@
+/**
+ * Internal dependencies
+ */
+import type { RequestUtils } from './index';
+
+export interface Comment {
+	id: number;
+	author: number;
+	content: string;
+	post: number;
+}
+
+export interface CreateCommentPayload {
+	content: string;
+	post: number;
+}
+
+export interface User {
+	id: number;
+}
+
+/**
+ * Create new comment using the REST API.
+ *
+ * @param this
+ * @param payload
+ */
+export async function createComment(
+	this: RequestUtils,
+	payload: CreateCommentPayload
+) {
+	const currentUser = await this.rest< User >( {
+		path: '/wp/v2/users/me',
+		method: 'GET',
+	} );
+
+	const author = currentUser.id;
+
+	const comment = await this.rest< Comment >( {
+		method: 'POST',
+		path: '/wp/v2/comments',
+		data: { ...payload, author },
+	} );
+
+	return comment;
+}
+
+/**
+ * Delete all comments using the REST API.
+ *
+ * @param this
+ * @param type - Optional comment type to delete.
+ */
+export async function deleteAllComments( this: RequestUtils, type?: string ) {
+	// List all comments.
+	// https://developer.wordpress.org/rest-api/reference/comments/#list-comments
+	const comments = await this.rest( {
+		path: '/wp/v2/comments',
+		params: {
+			per_page: 100,
+			status: 'all',
+			type: type || 'comment',
+		},
+	} );
+
+	// Delete all comments one by one.
+	// https://developer.wordpress.org/rest-api/reference/comments/#delete-a-comment
+	// "/wp/v2/comments" doesn't support batch requests yet.
+	await Promise.all(
+		comments.map( ( comment: Comment ) =>
+			this.rest( {
+				method: 'DELETE',
+				path: `/wp/v2/comments/${ comment.id }`,
+				params: {
+					force: true,
+				},
+			} )
+		)
+	);
+}

package/src/request-utils/gutenberg-experiments.ts

@@ -0,0 +1,62 @@
+/**
+ * Internal dependencies
+ */
+import type { RequestUtils } from './index';
+
+/**
+ * Sets the Gutenberg experiments.
+ *
+ * @param this
+ * @param experiments Array of experimental flags to enable. Pass in an empty array to disable all experiments.
+ *                    Use 'active_templates' for the template activation feature.
+ */
+async function setGutenbergExperiments(
+	this: RequestUtils,
+	experiments: string[]
+) {
+	// Separate regular experiments from active_templates.
+	// active_templates is stored as a separate option, not in the experiments array.
+	const regularExperiments = experiments.filter(
+		( exp ) => exp !== 'active_templates'
+	);
+	const hasActiveTemplates = experiments.includes( 'active_templates' );
+
+	// Build the experiments object with boolean values.
+	// When empty array is passed, we send an empty object to disable all experiments.
+	const experimentsData: Record< string, boolean > = {};
+
+	for ( const experiment of regularExperiments ) {
+		experimentsData[ experiment ] = true;
+	}
+
+	const settingsData: Record< string, unknown > = {
+		'gutenberg-experiments': experimentsData,
+	};
+
+	// active_templates lives in a separate top-level option. Sending `{}`
+	// enables the experiment; sending `null` deletes the option and disables
+	// it.
+	if ( hasActiveTemplates ) {
+		settingsData.active_templates = {};
+	} else {
+		// WP_REST_Settings_Controller rejects null updates when the stored
+		// value does not match the `type: 'object'` schema (including when the
+		// option is absent and `get_option` falls back to `false`), so we only
+		// send null when the option actually exists.
+		const currentSiteSettings =
+			( await this.getSiteSettings() ) as unknown as {
+				active_templates?: unknown;
+			};
+		if ( currentSiteSettings.active_templates !== null ) {
+			settingsData.active_templates = null;
+		}
+	}
+
+	await this.rest( {
+		path: '/wp/v2/settings',
+		method: 'POST',
+		data: settingsData,
+	} );
+}
+
+export { setGutenbergExperiments };