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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wordpress/e2e-test-utils-playwright",
-	"version": "1.47.0",
+	"version": "1.48.0",
 	"description": "End-To-End (E2E) test utils for WordPress.",
 	"author": "The WordPress Contributors",
 	"license": "GPL-2.0-or-later",
@@ -25,7 +25,7 @@
 		"npm": ">=8.19.2"
 	},
 	"files": [
-		"build",
+		"src",
 		"build-types"
 	],
 	"exports": {
@@ -54,5 +54,5 @@
 	"publishConfig": {
 		"access": "public"
 	},
-	"gitHead": "d653c5fd6161571a0c2ebde28553d6e25624eacc"
+	"gitHead": "e7856693aeb4e2522d13608cd32c994e4a97cb9c"
 }

package/src/admin/create-new-post.ts

@@ -0,0 +1,47 @@
+/**
+ * Internal dependencies
+ */
+import type { Admin } from './';
+
+interface NewPostOptions {
+	postType?: string;
+	title?: string;
+	content?: string;
+	excerpt?: string;
+	showWelcomeGuide?: boolean;
+	fullscreenMode?: boolean;
+}
+
+/**
+ * Creates new post.
+ *
+ * @param this
+ * @param options Options to create new post.
+ */
+export async function createNewPost(
+	this: Admin,
+	options: NewPostOptions = {}
+) {
+	const query = new URLSearchParams();
+	const { postType, title, content, excerpt } = options;
+
+	if ( postType ) {
+		query.set( 'post_type', postType );
+	}
+	if ( title ) {
+		query.set( 'post_title', title );
+	}
+	if ( content ) {
+		query.set( 'content', content );
+	}
+	if ( excerpt ) {
+		query.set( 'excerpt', excerpt );
+	}
+
+	await this.visitAdminPage( 'post-new.php', query.toString() );
+
+	await this.editor.setPreferences( 'core/edit-post', {
+		welcomeGuide: options.showWelcomeGuide ?? false,
+		fullscreenMode: options.fullscreenMode ?? false,
+	} );
+}

package/src/admin/edit-post.ts

@@ -0,0 +1,24 @@
+/**
+ * Internal dependencies
+ */
+import type { Admin } from '.';
+
+/**
+ * Open the post with given ID in the editor.
+ *
+ * @param this
+ * @param postId Post ID to visit.
+ */
+export async function editPost( this: Admin, postId: string | number ) {
+	const query = new URLSearchParams();
+
+	query.set( 'post', String( postId ) );
+	query.set( 'action', 'edit' );
+
+	await this.visitAdminPage( 'post.php', query.toString() );
+
+	await this.editor.setPreferences( 'core/edit-post', {
+		welcomeGuide: false,
+		fullscreenMode: false,
+	} );
+}

package/{build/admin/get-page-error.js → src/admin/get-page-error.ts}

@@ -1,12 +1,16 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.getPageError = getPageError;
+/**
+ * Internal dependencies
+ */
+import type { Admin } from './';
+
 /**
  * Regular expression matching a displayed PHP error within a markup string.
  *
  * @see https://github.com/php/php-src/blob/598175e/main/main.c#L1257-L1297
  */
-const REGEXP_PHP_ERROR = /(<b>)?(Fatal error|Recoverable fatal error|Warning|Parse error|Notice|Strict Standards|Deprecated|Unknown error)(<\/b>)?: (.*?) in (.*?) on line (<b>)?\d+(<\/b>)?/;
+const REGEXP_PHP_ERROR =
+	/(<b>)?(Fatal error|Recoverable fatal error|Warning|Parse error|Notice|Strict Standards|Deprecated|Unknown error)(<\/b>)?: (.*?) in (.*?) on line (<b>)?\d+(<\/b>)?/;
+
 /**
  * Returns a promise resolving to one of either a string or null. A string will
  * be resolved if an error message is present in the contents of the page. If no
@@ -18,9 +22,8 @@ const REGEXP_PHP_ERROR = /(<b>)?(Fatal error|Recoverable fatal error|Warning|Par
  * @param this
  * @return Promise resolving to a string or null, depending whether a page error is present.
  */
-async function getPageError() {
-    const content = await this.page.content();
-    const match = content.match(REGEXP_PHP_ERROR);
-    return match ? match[0] : null;
+export async function getPageError( this: Admin ) {
+	const content = await this.page.content();
+	const match = content.match( REGEXP_PHP_ERROR );
+	return match ? match[ 0 ] : null;
 }
-//# sourceMappingURL=get-page-error.js.map

package/src/admin/index.ts

@@ -0,0 +1,52 @@
+/**
+ * External dependencies
+ */
+import type { Browser, Page, BrowserContext } from '@playwright/test';
+
+/**
+ * Internal dependencies
+ */
+import { createNewPost } from './create-new-post';
+import { getPageError } from './get-page-error';
+import { visitAdminPage } from './visit-admin-page';
+import { editPost } from './edit-post';
+import { visitSiteEditor } from './visit-site-editor';
+import { waitForSiteEditor } from './wait-for-site-editor';
+import type { PageUtils } from '../page-utils';
+import type { Editor } from '../editor';
+
+type AdminConstructorProps = {
+	page: Page;
+	pageUtils: PageUtils;
+	editor: Editor;
+};
+
+export class Admin {
+	page: Page;
+	context: BrowserContext;
+	browser: Browser;
+	pageUtils: PageUtils;
+	editor: Editor;
+
+	constructor( { page, pageUtils, editor }: AdminConstructorProps ) {
+		this.page = page;
+		this.context = page.context();
+		this.browser = this.context.browser()!;
+		this.pageUtils = pageUtils;
+		this.editor = editor;
+	}
+
+	/** @borrows createNewPost as this.createNewPost */
+	createNewPost: typeof createNewPost = createNewPost.bind( this );
+	/** @borrows editPost as this.editPost */
+	editPost: typeof editPost = editPost.bind( this );
+	/** @borrows getPageError as this.getPageError */
+	getPageError: typeof getPageError = getPageError.bind( this );
+	/** @borrows visitAdminPage as this.visitAdminPage */
+	visitAdminPage: typeof visitAdminPage = visitAdminPage.bind( this );
+	/** @borrows visitSiteEditor as this.visitSiteEditor */
+	visitSiteEditor: typeof visitSiteEditor = visitSiteEditor.bind( this );
+	/** @borrows waitForSiteEditor as this.waitForSiteEditor */
+	waitForSiteEditor: typeof waitForSiteEditor =
+		waitForSiteEditor.bind( this );
+}

package/src/admin/visit-admin-page.ts

@@ -0,0 +1,43 @@
+/**
+ * External dependencies
+ */
+import { join } from 'path';
+
+/**
+ * Internal dependencies
+ */
+import type { Admin } from './';
+
+/**
+ * Visits admin page and handle errors.
+ *
+ * @param this
+ * @param adminPath String to be serialized as pathname.
+ * @param query     String to be serialized as query portion of URL.
+ */
+export async function visitAdminPage(
+	this: Admin,
+	adminPath: string,
+	query?: string
+) {
+	await this.page.goto(
+		join( 'wp-admin', adminPath ) + ( query ? `?${ query }` : '' )
+	);
+
+	// Handle upgrade required screen
+	if ( this.pageUtils.isCurrentURL( 'wp-admin/upgrade.php' ) ) {
+		// Click update
+		await this.page.click( '.button.button-large.button-primary' );
+		// Click continue
+		await this.page.click( '.button.button-large' );
+	}
+
+	if ( this.pageUtils.isCurrentURL( 'wp-login.php' ) ) {
+		throw new Error( 'Not logged in' );
+	}
+
+	const error = await this.getPageError();
+	if ( error ) {
+		throw new Error( 'Unexpected error in page content: ' + error );
+	}
+}

package/src/admin/visit-site-editor.ts

@@ -0,0 +1,62 @@
+/**
+ * Internal dependencies
+ */
+import type { Admin } from './';
+
+interface SiteEditorOptions {
+	postId?: string | number;
+	postType?: string;
+	path?: string;
+	canvas?: string;
+	activeView?: string;
+	showWelcomeGuide?: boolean;
+}
+
+/**
+ * Visits the Site Editor main page.
+ *
+ * @param this
+ * @param options Options to visit the site editor.
+ */
+export async function visitSiteEditor(
+	this: Admin,
+	options: SiteEditorOptions = {}
+) {
+	const { postId, postType, path, canvas, activeView } = options;
+	const query = new URLSearchParams();
+
+	if ( postId ) {
+		query.set( 'postId', String( postId ) );
+	}
+	if ( postType ) {
+		query.set( 'postType', postType );
+	}
+	if ( path ) {
+		query.set( 'path', path );
+	}
+	if ( canvas ) {
+		query.set( 'canvas', canvas );
+	}
+	if ( activeView ) {
+		query.set( 'activeView', activeView );
+	}
+
+	await this.visitAdminPage( 'site-editor.php', query.toString() );
+
+	if ( ! options.showWelcomeGuide ) {
+		await this.editor.setPreferences( 'core/edit-site', {
+			welcomeGuide: false,
+			welcomeGuideStyles: false,
+			welcomeGuidePage: false,
+			welcomeGuideTemplate: false,
+		} );
+	}
+
+	/**
+	 * Wait until the editor is loaded. The logic is a copy of the
+	 * `waitWhileSiteEditorLoading` function in the `edit-site` package.
+	 */
+	if ( ! query.size || postId || canvas === 'edit' ) {
+		await this.waitForSiteEditor();
+	}
+}

package/src/admin/wait-for-site-editor.ts

@@ -0,0 +1,52 @@
+/**
+ * Internal dependencies
+ */
+import type { Admin } from './';
+
+/**
+ * Waits for the Site Editor to finish loading, i.e., for all resolvers
+ * in the `core` store to finish and then pause for a short period.
+ *
+ * @param this
+ */
+export async function waitForSiteEditor( this: Admin ) {
+	await this.page.evaluate( () => {
+		const MAX_LOADING_TIME = 10000;
+		const MAX_PAUSE_TIME = 100;
+
+		return new Promise< void >( ( resolve ) => {
+			let pauseTimeout: ReturnType< typeof setTimeout > | undefined;
+
+			function finish() {
+				unsubscribe();
+				clearTimeout( pauseTimeout );
+				clearTimeout( maxTimeout );
+				resolve();
+			}
+
+			const maxTimeout = setTimeout( finish, MAX_LOADING_TIME );
+
+			function checkResolving() {
+				const isResolving = window.wp.data
+					.select( 'core' )
+					.hasResolvingSelectors();
+
+				if ( isResolving ) {
+					clearTimeout( pauseTimeout );
+					pauseTimeout = undefined;
+					return;
+				}
+
+				if ( ! pauseTimeout ) {
+					pauseTimeout = setTimeout( finish, MAX_PAUSE_TIME );
+				}
+			}
+
+			const unsubscribe = window.wp.data.subscribe(
+				checkResolving,
+				'core'
+			);
+			checkResolving();
+		} );
+	} );
+}

package/src/config.ts

@@ -0,0 +1,12 @@
+const {
+	WP_USERNAME = 'admin',
+	WP_PASSWORD = 'password',
+	WP_BASE_URL = 'http://localhost:8889',
+} = process.env;
+
+const WP_ADMIN_USER = {
+	username: WP_USERNAME,
+	password: WP_PASSWORD,
+} as const;
+
+export { WP_ADMIN_USER, WP_USERNAME, WP_PASSWORD, WP_BASE_URL };

package/src/editor/click-block-options-menu-item.ts

@@ -0,0 +1,18 @@
+/**
+ * Internal dependencies
+ */
+import type { Editor } from './index';
+
+/**
+ * Clicks a block toolbar button.
+ *
+ * @param this
+ * @param label The text string of the button label.
+ */
+export async function clickBlockOptionsMenuItem( this: Editor, label: string ) {
+	await this.clickBlockToolbarButton( 'Options' );
+	await this.page
+		.getByRole( 'menu', { name: 'Options' } )
+		.getByRole( 'menuitem', { name: label } )
+		.click();
+}

package/src/editor/click-block-toolbar-button.ts

@@ -0,0 +1,21 @@
+/**
+ * Internal dependencies
+ */
+import type { Editor } from './index';
+
+/**
+ * Clicks a block toolbar button.
+ *
+ * @param this
+ * @param label The text string of the button label.
+ */
+export async function clickBlockToolbarButton( this: Editor, label: string ) {
+	await this.showBlockToolbar();
+
+	const blockToolbar = this.page.locator(
+		'role=toolbar[name="Block tools"i]'
+	);
+	const button = blockToolbar.locator( `role=button[name="${ label }"]` );
+
+	await button.click();
+}

package/src/editor/get-blocks.ts

@@ -0,0 +1,75 @@
+/**
+ * Internal dependencies
+ */
+import type { Editor } from './index';
+
+type Block = {
+	name: string;
+	attributes: Record< string, unknown >;
+	innerBlocks: Block[];
+};
+
+/**
+ * Returns the edited blocks.
+ *
+ * @param options
+ * @param options.clientId Limit the results to be only under a partial tree of the specified clientId.
+ * @param options.full     Whether to return the full block data or just the name and attributes.
+ *
+ * @return  The blocks.
+ */
+export async function getBlocks(
+	this: Editor,
+	{ clientId, full = false }: { clientId?: string; full?: boolean } = {}
+) {
+	await this.page.waitForFunction(
+		() => window?.wp?.blocks && window?.wp?.data
+	);
+
+	return await this.page.evaluate(
+		( [ _full, _clientId ] ) => {
+			// Serialize serializable attributes of blocks.
+			function serializeAttributes(
+				attributes: Record< string, unknown >
+			) {
+				return Object.fromEntries(
+					Object.entries( attributes ).map( ( [ key, value ] ) => {
+						// Serialize RichTextData to string.
+						if (
+							value instanceof window.wp.richText.RichTextData
+						) {
+							return [ key, ( value as string ).toString() ];
+						}
+						return [ key, value ];
+					} )
+				);
+			}
+
+			// Remove other unpredictable properties like clientId from blocks for testing purposes.
+			function recursivelyTransformBlocks( blocks: Block[] ): Block[] {
+				return blocks.map( ( block ) => ( {
+					name: block.name,
+					attributes: serializeAttributes( block.attributes ),
+					innerBlocks: recursivelyTransformBlocks(
+						block.innerBlocks
+					),
+				} ) );
+			}
+
+			const blocks = window.wp.data
+				.select( 'core/block-editor' )
+				.getBlocks( _clientId ) as Block[];
+
+			// The editor might still contain an unmodified empty block even when it's technically "empty".
+			if (
+				blocks.length === 1 &&
+				window.wp.blocks.isUnmodifiedDefaultBlock( blocks[ 0 ] )
+			) {
+				return [];
+			}
+
+			return _full ? blocks : recursivelyTransformBlocks( blocks );
+		},
+		[ full, clientId ]
+	);
+}

package/src/editor/get-edited-post-content.ts

@@ -0,0 +1,19 @@
+/**
+ * Internal dependencies
+ */
+import type { Editor } from './index';
+
+/**
+ * Returns a promise which resolves with the edited post content (HTML string).
+ *
+ * @param this
+ *
+ * @return Promise resolving with post content markup.
+ */
+export async function getEditedPostContent( this: Editor ) {
+	await this.page.waitForFunction( () => window?.wp?.data );
+
+	return await this.page.evaluate( () =>
+		window.wp.data.select( 'core/editor' ).getEditedPostContent()
+	);
+}

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();
+	}
+}