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

package/src/editor/index.ts

@@ -0,0 +1,95 @@
+/**
+ * External dependencies
+ */
+import type {
+	Browser,
+	Page,
+	BrowserContext,
+	FrameLocator,
+} from '@playwright/test';
+
+/**
+ * Internal dependencies
+ */
+import { clickBlockOptionsMenuItem } from './click-block-options-menu-item';
+import { clickBlockToolbarButton } from './click-block-toolbar-button';
+import { getBlocks } from './get-blocks';
+import { getEditedPostContent } from './get-edited-post-content';
+import { insertBlock } from './insert-block';
+import { openDocumentSettingsSidebar } from './open-document-settings-sidebar';
+import { openPreviewPage } from './preview';
+import { publishPost } from './publish-post';
+import { saveDraft } from './save-draft';
+import { selectBlocks } from './select-blocks';
+import { setContent } from './set-content';
+import { setPreferences } from './set-preferences';
+import { showBlockToolbar } from './show-block-toolbar';
+import { saveSiteEditorEntities } from './site-editor';
+import { setIsFixedToolbar } from './set-is-fixed-toolbar';
+import { switchToLegacyCanvas } from './switch-to-legacy-canvas';
+import { transformBlockTo } from './transform-block-to';
+import { switchEditorTool } from './switch-editor-tool';
+
+type EditorConstructorProps = {
+	page: Page;
+};
+
+export class Editor {
+	browser: Browser;
+	page: Page;
+	context: BrowserContext;
+
+	constructor( { page }: EditorConstructorProps ) {
+		this.page = page;
+		this.context = page.context();
+		this.browser = this.context.browser()!;
+	}
+
+	get canvas(): FrameLocator {
+		return this.page.frameLocator( '[name="editor-canvas"]' );
+	}
+
+	/** @borrows clickBlockOptionsMenuItem as this.clickBlockOptionsMenuItem */
+	clickBlockOptionsMenuItem: typeof clickBlockOptionsMenuItem =
+		clickBlockOptionsMenuItem.bind( this );
+	/** @borrows clickBlockToolbarButton as this.clickBlockToolbarButton */
+	clickBlockToolbarButton: typeof clickBlockToolbarButton =
+		clickBlockToolbarButton.bind( this );
+	/** @borrows getBlocks as this.getBlocks */
+	getBlocks: typeof getBlocks = getBlocks.bind( this );
+	/** @borrows getEditedPostContent as this.getEditedPostContent */
+	getEditedPostContent: typeof getEditedPostContent =
+		getEditedPostContent.bind( this );
+	/** @borrows insertBlock as this.insertBlock */
+	insertBlock: typeof insertBlock = insertBlock.bind( this );
+	/** @borrows openDocumentSettingsSidebar as this.openDocumentSettingsSidebar */
+	openDocumentSettingsSidebar: typeof openDocumentSettingsSidebar =
+		openDocumentSettingsSidebar.bind( this );
+	/** @borrows openPreviewPage as this.openPreviewPage */
+	openPreviewPage: typeof openPreviewPage = openPreviewPage.bind( this );
+	/** @borrows publishPost as this.publishPost */
+	publishPost: typeof publishPost = publishPost.bind( this );
+	/** @borrows saveDraft as this.saveDraft */
+	saveDraft: typeof saveDraft = saveDraft.bind( this );
+	/** @borrows saveSiteEditorEntities as this.saveSiteEditorEntities */
+	saveSiteEditorEntities: typeof saveSiteEditorEntities =
+		saveSiteEditorEntities.bind( this );
+	/** @borrows selectBlocks as this.selectBlocks */
+	selectBlocks: typeof selectBlocks = selectBlocks.bind( this );
+	/** @borrows setContent as this.setContent */
+	setContent: typeof setContent = setContent.bind( this );
+	/** @borrows setPreferences as this.setPreferences */
+	setPreferences: typeof setPreferences = setPreferences.bind( this );
+	/** @borrows showBlockToolbar as this.showBlockToolbar */
+	showBlockToolbar: typeof showBlockToolbar = showBlockToolbar.bind( this );
+	/** @borrows setIsFixedToolbar as this.setIsFixedToolbar */
+	setIsFixedToolbar: typeof setIsFixedToolbar =
+		setIsFixedToolbar.bind( this );
+	/** @borrows switchEditorTool as this.switchEditorTool */
+	switchEditorTool: typeof switchEditorTool = switchEditorTool.bind( this );
+	/** @borrows switchToLegacyCanvas as this.switchToLegacyCanvas */
+	switchToLegacyCanvas: typeof switchToLegacyCanvas =
+		switchToLegacyCanvas.bind( this );
+	/** @borrows transformBlockTo as this.transformBlockTo */
+	transformBlockTo: typeof transformBlockTo = transformBlockTo.bind( this );
+}

package/src/editor/insert-block.ts

@@ -0,0 +1,54 @@
+/**
+ * Internal dependencies
+ */
+import type { Editor } from './index';
+
+interface BlockRepresentation {
+	name: string;
+	attributes?: Object;
+	innerBlocks?: BlockRepresentation[];
+}
+
+/**
+ * Insert a block.
+ *
+ * @param blockRepresentation Inserted block representation.
+ * @param options
+ * @param options.clientId    Client ID of the parent block to insert into.
+ */
+async function insertBlock(
+	this: Editor,
+	blockRepresentation: BlockRepresentation,
+	{ clientId }: { clientId?: string } = {}
+) {
+	await this.page.waitForFunction(
+		() => window?.wp?.blocks && window?.wp?.data
+	);
+
+	await this.page.evaluate(
+		( [ _blockRepresentation, _clientId ] ) => {
+			function recursiveCreateBlock( {
+				name,
+				attributes = {},
+				innerBlocks = [],
+			}: BlockRepresentation ): Object {
+				return window.wp.blocks.createBlock(
+					name,
+					attributes,
+					innerBlocks.map( ( innerBlock ) =>
+						recursiveCreateBlock( innerBlock )
+					)
+				);
+			}
+			const block = recursiveCreateBlock( _blockRepresentation );
+
+			window.wp.data
+				.dispatch( 'core/block-editor' )
+				.insertBlock( block, undefined, _clientId );
+		},
+		[ blockRepresentation, clientId ] as const
+	);
+}
+
+export type { BlockRepresentation };
+export { insertBlock };

package/src/editor/open-document-settings-sidebar.ts

@@ -0,0 +1,31 @@
+/**
+ * Internal dependencies
+ */
+import type { Editor } from './index';
+
+/**
+ * Clicks on the button in the header which opens Document Settings sidebar when
+ * it is closed.
+ *
+ * @param this
+ */
+export async function openDocumentSettingsSidebar( this: Editor ) {
+	const toggleButton = this.page
+		.getByRole( 'region', { name: 'Editor top bar' } )
+		.getByRole( 'button', {
+			name: 'Settings',
+			exact: true,
+			disabled: false,
+		} );
+
+	const isClosed =
+		( await toggleButton.getAttribute( 'aria-expanded' ) ) === 'false';
+
+	if ( isClosed ) {
+		await toggleButton.click();
+		await this.page
+			.getByRole( 'region', { name: 'Editor settings' } )
+			.getByRole( 'button', { name: 'Close Settings' } )
+			.waitFor();
+	}
+}

package/src/editor/preview.ts

@@ -0,0 +1,32 @@
+/**
+ * External dependencies
+ */
+import type { Page } from '@playwright/test';
+
+/**
+ * Internal dependencies
+ */
+import type { Editor } from './index';
+
+/**
+ * Opens the preview page of an edited post.
+ *
+ * @param this
+ *
+ * @return preview page.
+ */
+export async function openPreviewPage( this: Editor ): Promise< Page > {
+	const editorTopBar = this.page.locator(
+		'role=region[name="Editor top bar"i]'
+	);
+	const previewButton = editorTopBar.locator( 'role=button[name="View"i]' );
+
+	await previewButton.click();
+
+	const [ previewPage ] = await Promise.all( [
+		this.context.waitForEvent( 'page' ),
+		this.page.click( 'role=menuitem[name="Preview in new tab"i]' ),
+	] );
+
+	return previewPage;
+}

package/src/editor/publish-post.ts

@@ -0,0 +1,51 @@
+/**
+ * Internal dependencies
+ */
+import type { Editor } from './index';
+
+/**
+ * Publishes the post, resolving once the request is complete (once a notice
+ * is displayed).
+ *
+ * @param this
+ */
+export async function publishPost( this: Editor ) {
+	// If we have changes in other entities, the label is `Save` instead of `Publish`.
+	const saveButton = this.page
+		.getByRole( 'region', { name: 'Editor top bar' } )
+		.getByRole( 'button', { name: 'Save', exact: true } );
+	const publishButton = this.page
+		.getByRole( 'region', { name: 'Editor top bar' } )
+		.getByRole( 'button', { name: 'Publish', exact: true } );
+	const buttonToClick = ( await saveButton.isVisible() )
+		? saveButton
+		: publishButton;
+	await buttonToClick.click();
+
+	const entitiesSaveButton = this.page
+		.getByRole( 'region', { name: 'Editor publish' } )
+		.getByRole( 'button', { name: 'Save', exact: true } );
+	const isEntitiesSavePanelVisible = await entitiesSaveButton.isVisible();
+
+	// Save any entities.
+	if ( isEntitiesSavePanelVisible ) {
+		// Handle saving entities.
+		await entitiesSaveButton.click();
+	}
+
+	// Handle saving just the post.
+	await this.page
+		.getByRole( 'region', {
+			name: 'Editor publish',
+		} )
+		.getByRole( 'button', { name: 'Publish', exact: true } )
+		.click();
+
+	await this.page
+		.getByRole( 'button', { name: 'Dismiss this notice' } )
+		.filter( { hasText: 'published' } )
+		.waitFor();
+	const postId = new URL( this.page.url() ).searchParams.get( 'post' );
+
+	return typeof postId === 'string' ? parseInt( postId, 10 ) : null;
+}

package/src/editor/save-draft.ts

@@ -0,0 +1,20 @@
+/**
+ * Internal dependencies
+ */
+import type { Editor } from './index';
+
+/**
+ * Saves the post as a draft, resolving once the request is complete (once a notice
+ * is displayed).
+ */
+export async function saveDraft( this: Editor ) {
+	await this.page
+		.getByRole( 'region', { name: 'Editor top bar' } )
+		.getByRole( 'button', { name: 'Save draft' } )
+		.click();
+
+	await this.page
+		.getByRole( 'button', { name: 'Dismiss this notice' } )
+		.filter( { hasText: 'Draft saved' } )
+		.waitFor();
+}

package/src/editor/select-blocks.ts

@@ -0,0 +1,48 @@
+/**
+ * External dependencies
+ */
+import type { Locator } from '@playwright/test';
+
+/**
+ * Internal dependencies
+ */
+import type { Editor } from './index';
+
+export async function selectBlocks(
+	this: Editor,
+	startSelectorOrLocator: string | Locator,
+	endSelectorOrLocator?: string | Locator
+) {
+	const startBlock =
+		typeof startSelectorOrLocator === 'string'
+			? this.canvas.locator( startSelectorOrLocator )
+			: startSelectorOrLocator;
+
+	const endBlock =
+		typeof endSelectorOrLocator === 'string'
+			? this.canvas.locator( endSelectorOrLocator )
+			: endSelectorOrLocator;
+
+	const startClientId = await startBlock.getAttribute( 'data-block' );
+	const endClientId = await endBlock?.getAttribute( 'data-block' );
+
+	if ( endClientId ) {
+		await this.page.evaluate(
+			( [ startId, endId ] ) => {
+				// @ts-ignore
+				wp.data
+					.dispatch( 'core/block-editor' )
+					.multiSelect( startId, endId );
+			},
+			[ startClientId, endClientId ]
+		);
+	} else {
+		await this.page.evaluate(
+			( [ clientId ] ) => {
+				// @ts-ignore
+				wp.data.dispatch( 'core/block-editor' ).selectBlock( clientId );
+			},
+			[ startClientId ]
+		);
+	}
+}

package/src/editor/set-content.ts

@@ -0,0 +1,24 @@
+/**
+ * Internal dependencies
+ */
+import type { Editor } from './index';
+
+/**
+ * Set the content of the editor.
+ *
+ * @param this
+ * @param html Serialized block HTML.
+ */
+async function setContent( this: Editor, html: string ) {
+	await this.page.waitForFunction(
+		() => window?.wp?.blocks && window?.wp?.data
+	);
+
+	await this.page.evaluate( ( _html ) => {
+		const blocks = window.wp.blocks.parse( _html );
+
+		window.wp.data.dispatch( 'core/block-editor' ).resetBlocks( blocks );
+	}, html );
+}
+
+export { setContent };

package/src/editor/set-is-fixed-toolbar.ts

@@ -0,0 +1,20 @@
+/**
+ * Internal dependencies
+ */
+import type { Editor } from './index';
+
+/**
+ * Toggles the fixed toolbar option.
+ *
+ * @param this
+ * @param isFixed Boolean value true/false for on/off.
+ */
+export async function setIsFixedToolbar( this: Editor, isFixed: boolean ) {
+	await this.page.waitForFunction( () => window?.wp?.data );
+
+	await this.page.evaluate( ( _isFixed ) => {
+		window.wp.data
+			.dispatch( 'core/preferences' )
+			.set( 'core', 'fixedToolbar', _isFixed );
+	}, isFixed );
+}

package/src/editor/set-preferences.ts

@@ -0,0 +1,37 @@
+/**
+ * Internal dependencies
+ */
+import type { Editor } from './index';
+
+type PreferencesContext =
+	| 'core/edit-post'
+	| 'core/edit-site'
+	| 'core/customize-widgets';
+
+/**
+ * Set the preferences of the editor.
+ *
+ * @param this
+ * @param context     Context to set preferences for.
+ * @param preferences Preferences to set.
+ */
+export async function setPreferences(
+	this: Editor,
+	context: PreferencesContext,
+	preferences: Record< string, any >
+) {
+	await this.page.waitForFunction( () => window?.wp?.data );
+
+	await this.page.evaluate(
+		async ( props ) => {
+			for ( const [ key, value ] of Object.entries(
+				props.preferences
+			) ) {
+				await window.wp.data
+					.dispatch( 'core/preferences' )
+					.set( props.context, key, value );
+			}
+		},
+		{ context, preferences }
+	);
+}

package/src/editor/show-block-toolbar.ts

@@ -0,0 +1,20 @@
+/**
+ * Internal dependencies
+ */
+import type { Editor } from './index';
+
+/**
+ * The block toolbar is not always visible while typing.
+ * Call this function to reveal it.
+ *
+ * @param this
+ */
+export async function showBlockToolbar( this: Editor ) {
+	// Move the mouse to disable the isTyping mode. We need at least three
+	// mousemove events for it to work across windows (iframe). With three
+	// moves, it's a guarantee that at least two will be in the same window.
+	// Two events are required for the flag to be unset.
+	await this.page.mouse.move( 50, 50 );
+	await this.page.mouse.move( 75, 75 );
+	await this.page.mouse.move( 100, 100 );
+}

package/src/editor/site-editor.ts

@@ -0,0 +1,55 @@
+/**
+ * Internal dependencies
+ */
+import type { Editor } from './index';
+
+interface Options {
+	// If the only dirty entity is the current one, skip opening the save panel.
+	isOnlyCurrentEntityDirty?: boolean;
+}
+
+/**
+ * Save entities in the site editor. Assumes the editor is in a dirty state.
+ *
+ * @param this
+ * @param options
+ */
+export async function saveSiteEditorEntities(
+	this: Editor,
+	options: Options = {}
+) {
+	const editorTopBar = this.page.getByRole( 'region', {
+		name: 'Editor top bar',
+	} );
+
+	// If we have changes in a single entity which can be published the label is `Publish`.
+	const saveButton = editorTopBar.getByRole( 'button', {
+		name: 'Save',
+		exact: true,
+	} );
+	const publishButton = editorTopBar.getByRole( 'button', {
+		name: 'Publish',
+	} );
+	const publishButtonIsVisible = ! ( await saveButton.isVisible() );
+	// First Save button in the top bar.
+	const buttonToClick = publishButtonIsVisible ? publishButton : saveButton;
+	await buttonToClick.click();
+
+	if ( ! options.isOnlyCurrentEntityDirty ) {
+		// Second Save button in the entities panel.
+		await this.page
+			.getByRole( 'region', {
+				name: /(Editor publish|Save panel)/,
+			} )
+			.getByRole( 'button', { name: 'Save', exact: true } )
+			.click();
+	}
+	// The text in the notice can be different based on the edited entity, whether
+	// we are saving multiple entities and whether we publish or update. So for now,
+	// we locate it based on the last part.
+	await this.page
+		.getByRole( 'button', { name: 'Dismiss this notice' } )
+		.getByText( /(updated|published)\./ )
+		.first()
+		.waitFor();
+}

package/src/editor/switch-editor-tool.ts

@@ -0,0 +1,34 @@
+/**
+ * Internal dependencies
+ */
+import type { Editor } from './index';
+
+/**
+ * Switch the editor tool being used.
+ *
+ * @param this
+ * @param label The text string of the button label.
+ */
+export async function switchEditorTool( this: Editor, label: string ) {
+	const toolsToolbar = this.page.getByRole( 'toolbar', {
+		name: 'Document tools',
+	} );
+	await toolsToolbar
+		.getByRole( 'button', {
+			name: 'Tools',
+		} )
+		.click();
+	const menu = this.page.getByRole( 'menu', {
+		name: 'Tools',
+	} );
+	await menu
+		.getByRole( 'menuitemradio', {
+			name: label,
+		} )
+		.click();
+	await toolsToolbar
+		.getByRole( 'button', {
+			name: 'Tools',
+		} )
+		.click();
+}

package/src/editor/switch-to-legacy-canvas.ts

@@ -0,0 +1,20 @@
+/**
+ * Internal dependencies
+ */
+import type { Editor } from './index';
+
+/**
+ * Switches to legacy (non-iframed) canvas.
+ *
+ * @param this
+ */
+export async function switchToLegacyCanvas( this: Editor ) {
+	await this.page.waitForFunction( () => window?.wp?.blocks );
+
+	await this.page.evaluate( () => {
+		window.wp.blocks.registerBlockType( 'test/v2', {
+			apiVersion: '2',
+			title: 'test',
+		} );
+	} );
+}

package/src/editor/transform-block-to.ts

@@ -0,0 +1,34 @@
+/**
+ * Internal dependencies
+ */
+import type { Editor } from './index';
+
+/**
+ * Clicks the default block appender.
+ *
+ * @param this
+ * @param name Block name.
+ */
+export async function transformBlockTo( this: Editor, name: string ) {
+	await this.page.waitForFunction(
+		() => window?.wp?.blocks && window?.wp?.data
+	);
+
+	await this.page.evaluate(
+		( [ blockName ] ) => {
+			const clientIds = window.wp.data
+				.select( 'core/block-editor' )
+				.getSelectedBlockClientIds();
+			const blocks = window.wp.data
+				.select( 'core/block-editor' )
+				.getBlocksByClientId( clientIds );
+			window.wp.data
+				.dispatch( 'core/block-editor' )
+				.replaceBlocks(
+					clientIds,
+					window.wp.blocks.switchToBlockType( blocks, blockName )
+				);
+		},
+		[ name ]
+	);
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export type * from './types';
+export { Admin } from './admin';
+export { Editor } from './editor';
+export { PageUtils } from './page-utils';
+export { RequestUtils } from './request-utils';
+export { Metrics } from './metrics';
+export { Lighthouse } from './lighthouse';
+export { test, expect } from './test';

package/src/lighthouse/index.ts

@@ -0,0 +1,75 @@
+/**
+ * External dependencies
+ */
+import type { Page } from '@playwright/test';
+import lighthouse from 'lighthouse/core/index.cjs';
+
+type LighthouseConstructorProps = {
+	page: Page;
+	port: number;
+};
+
+export class Lighthouse {
+	page: Page;
+	port: number;
+
+	constructor( { page, port }: LighthouseConstructorProps ) {
+		this.page = page;
+		this.port = port;
+	}
+
+	/**
+	 * Returns the Lighthouse report for the current URL.
+	 *
+	 * Runs several Lighthouse audits in a separate browser window and returns
+	 * the summary.
+	 */
+	async getReport() {
+		// From https://github.com/GoogleChrome/lighthouse/blob/36cac182a6c637b1671c57326d7c0241633d0076/core/config/default-config.js#L381-L446
+		const audits = {
+			'largest-contentful-paint': 'LCP',
+			'total-blocking-time': 'TBT',
+			interactive: 'TTI',
+			'cumulative-layout-shift': 'CLS',
+			'interaction-to-next-paint': 'INP',
+		};
+
+		const report = await lighthouse(
+			this.page.url(),
+			{ port: this.port },
+			{
+				extends: 'lighthouse:default',
+				settings: {
+					// "provided" means no throttling.
+					// TODO: Make configurable.
+					throttlingMethod: 'provided',
+					// Default is "mobile".
+					// See https://github.com/GoogleChrome/lighthouse/blob/main/docs/emulation.md
+					// TODO: Make configurable.
+					formFactor: 'desktop',
+					screenEmulation: {
+						disabled: true,
+					},
+					// Speeds up the report.
+					disableFullPageScreenshot: true,
+					// Only run certain audits to speed things up.
+					onlyAudits: Object.keys( audits ),
+				},
+			}
+		);
+
+		const result: Record< string, number > = {};
+
+		if ( ! report ) {
+			return result;
+		}
+
+		const { lhr } = report;
+
+		for ( const [ audit, acronym ] of Object.entries( audits ) ) {
+			result[ acronym ] = lhr.audits[ audit ]?.numericValue || 0;
+		}
+
+		return result;
+	}
+}