E2E Test Utils

End-To-End (E2E) test utils for WordPress.

It works properly with the minimum version of Gutenberg 13.8.0 or the minimum version of WordPress 6.0.0.

Note that there's currently an ongoing project to migrate E2E tests to Playwright instead. This package is deprecated and will only accept bug fixes until fully migrated.

Installation

Install the module

npm install @wordpress/e2e-test-utils --save-dev

Note: This package requires Node.js version with long-term support status (check Active LTS or Maintenance LTS releases). It is not compatible with older versions.

API

activatePlugin

Activates an installed plugin.

Parameters

slug string: Plugin slug.

activateTheme

Activates an installed theme.

Parameters

slug string: Theme slug.

arePrePublishChecksEnabled

Verifies if publish checks are enabled.

Returns

Promise<boolean>: Boolean which represents the state of prepublish checks.

canvas

Gets the editor canvas frame.

changeSiteTimezone

Visits general settings page and changes the timezone to the given value.

Parameters

timezone string: Value of the timezone to set.

Returns

string: Value of the previous timezone.

clearLocalStorage

Clears the local storage.

clickBlockAppender

Clicks the default block appender.

clickBlockToolbarButton

Clicks a block toolbar button.

Parameters

label string: The text string of the button label.
type [string]: The type of button label: 'ariaLabel' or 'content'.

clickButton

Clicks a button based on the text on the button.

Parameters

buttonText string: The text that appears on the button to click.

clickMenuItem

Searches for an item in the menu with the text provided and clicks it.

Parameters

label string: The label to search the menu item for.

clickOnCloseModalButton

Click on the close button of an open modal.

Parameters

modalClassName ?string: Class name for the modal to close

clickOnMoreMenuItem

Clicks on More Menu item, searches for the button with the text provided and clicks it.

Parameters

buttonLabel string: The label to search the button for.

closeGlobalBlockInserter

Closes the global inserter.

closeListView

Closes list view

createEmbeddingMatcher

Creates a function to determine if a request is embedding a certain URL.

Parameters

url string: The URL to check against a request.

Returns

Function: Function that determines if a request is for the embed API, embedding a specific URL.

createJSONResponse

Respond to a request with a JSON response.

Parameters

mockResponse string: The mock object to wrap in a JSON response.

Returns

Promise: Promise that responds to a request with the mock JSON response.

createMenu

Create menus and all linked resources for the menu using the REST API.

Parameters

menu Object: Rest payload for the menu
menuItems ?Array: Data for any menu items to be created.

createNewPost

Creates new post.

Parameters

object Object: Object to create new post, along with tips enabling option.
object.postType [string]: Post type of the new post.
object.title [string]: Title of the new post.
object.content [string]: Content of the new post.
object.excerpt [string]: Excerpt of the new post.
object.showWelcomeGuide [boolean]: Whether to show the welcome guide.

createNewTemplate

Opens the template editor with a newly created template.

Parameters

name string: Name of the template.

createReusableBlock

Creates a simple reusable block with a paragraph block.

Parameters

content string: Paragraph block's content
title title: Reusable block's name.

createURL

Creates new URL by parsing base URL, WPPath and query string.

Parameters

WPPath string: String to be serialized as pathname.
query ?string: String to be serialized as query portion of URL.

Returns

string: String which represents full URL.

createURLMatcher

Creates a function to determine if a request is calling a URL with the substring present.

Parameters

substring string: The substring to check for.

Returns

Function: Function that determines if a request's URL contains substring.

createUser

Create a new user account.

Parameters

username string: User name.
object Object?: Optional Settings for the new user account.
object.firstName [string]: First name.
object.lastName [string]: Last name.
object.role [string]: Role. Defaults to Administrator.

Returns

string: Password for the newly created user account.

deactivatePlugin

Deactivates an active plugin.

Parameters

slug string: Plugin slug.

deleteAllMenus

Delete all menus using the REST API

deleteAllTemplates

Delete all the templates of given type.

Parameters

type ('wp_template'|'wp_template_part'): - Template type to delete.

deleteAllWidgets

Delete all the widgets in the widgets screen.

deleteTheme

Deletes a theme from the site, activating another theme if necessary.

Parameters

slug string: Theme slug.
settings Object?: Optional settings object.
settings.newThemeSlug string?: A theme to switch to if the theme to delete is active. Required if the theme to delete is active.
settings.newThemeSearchTerm string?: A search term to use if the new theme is not findable by its slug.

deleteUser

Delete a user account.

Parameters

username string: User name.

disableFocusLossObservation

Removes the focus loss listener that enableFocusLossObservation() adds.

disablePageDialogAccept

Disable auto-accepting any dialogs.

disablePrePublishChecks

Disables Pre-publish checks.

disableSiteEditorWelcomeGuide

Skips the welcome guide popping up to first time users of the site editor

dragAndResize

Clicks an element, drags a particular distance and releases the mouse button.

Parameters

element Object: The puppeteer element handle.
delta Object: Object containing movement distances.
delta.x number: Horizontal distance to drag.
delta.y number: Vertical distance to drag.

Returns

Promise: Promise resolving when drag completes.

enableFocusLossObservation

Adds an event listener to the document which throws an error if there is a loss of focus.

enablePageDialogAccept

Enables event listener which auto-accepts all dialogs on the page.

enablePrePublishChecks

Enables Pre-publish checks.

ensureSidebarOpened

Verifies that the edit post/site/widgets sidebar is opened, and if it is not, opens it.

Returns

Promise: Promise resolving once the sidebar is opened.

enterEditMode

Enters edit mode.

findSidebarPanelToggleButtonWithTitle

Finds a sidebar panel with the provided title.

Parameters

panelTitle string: The name of sidebar panel.

Returns

?ElementHandle: Object that represents an in-page DOM element.

findSidebarPanelWithTitle

Finds the button responsible for toggling the sidebar panel with the provided title.

Parameters

panelTitle string: The name of sidebar panel.

Returns

Promise<ElementHandle|undefined>: Object that represents an in-page DOM element.

getAllBlockInserterItemTitles

Returns an array of strings with all inserter item titles.

Returns

Promise: Promise resolving with an array containing all inserter item titles.

getAllBlocks

Returns an array with all blocks; Equivalent to calling wp.data.select( 'core/block-editor' ).getBlocks();

Returns

Promise: Promise resolving with an array containing all blocks in the document.

getAvailableBlockTransforms

Returns an array of strings with all block titles, that the current selected block can be transformed into.

Returns

Promise: Promise resolving with an array containing all possible block transforms

getBlockSetting

Returns a string containing the block title associated with the provided block name.

Parameters

blockName string: Block name.
setting string: Block setting e.g: title, attributes....

Returns

Promise: Promise resolving with a string containing the block title.

getCurrentPostContent

Returns a promise which resolves with the current post content (HTML string).

Returns

Promise: Promise resolving with current post content markup.

getCurrentSiteEditorContent

Returns a promise which resolves with the edited post content (HTML string).

Returns

Promise<string>: Promise resolving with post content markup.

getEditedPostContent

Returns a promise which resolves with the edited post content (HTML string).

Returns

Promise: Promise resolving with post content markup.

getListViewBlocks

Gets all block anchor nodes in the list view that match a given block name label.

Parameters

blockLabel string: the label of the block as displayed in the ListView.

Returns

Promise: all the blocks anchor nodes matching the lable in the ListView.

getOption

Returns a site option, from the options admin page.

Parameters

setting string: The option, used to get the option by id.

Returns

string: The value of the option.

getPageError

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 error is present, a null value will be resolved instead. This requires the environment be configured to display errors.

Related

http://php.net/manual/en/function.error-reporting.php

Returns

Promise<?string>: Promise resolving to a string or null, depending whether a page error is present.

hasBlockSwitcher

Returns a boolean indicating if the current selected block has a block switcher or not.

Returns

Promise: Promise resolving with a boolean.

insertBlock

Inserts a block matching a given search term via the global inserter.

Parameters

searchTerm string: The term by which to find the block to insert.

insertBlockDirectoryBlock

Inserts a Block Directory block matching a given search term via the global inserter.

Parameters

searchTerm string: The term by which to find the Block Directory block to insert.

insertPattern

Inserts a pattern matching a given search term via the global inserter.

Parameters

searchTerm string: The term by which to find the pattern to insert.

installPlugin

Installs a plugin from the WP.org repository.

Parameters

slug string: Plugin slug.
searchTerm string?: If the plugin is not findable by its slug use an alternative term to search.

installTheme

Installs a theme from the WP.org repository.

Parameters

slug string: Theme slug.
settings Object?: Optional settings object.
settings.searchTerm string?: Search term to use if the theme is not findable by its slug.

isCurrentURL

Checks if current URL is a WordPress path.

Parameters

WPPath string: String to be serialized as pathname.
query ?string: String to be serialized as query portion of URL.

Returns

boolean: Boolean represents whether current URL is or not a WordPress path.

isInDefaultBlock

Checks if the block that is focused is the default block.

Returns

Promise: Promise resolving with a boolean indicating if the focused block is the default block.

isListViewOpen

Undocumented declaration.

isOfflineMode

Undocumented declaration.

isThemeInstalled

Checks whether a theme exists on the site.

Parameters

slug string: Theme slug to check.

Returns

boolean: Whether the theme exists.

loginUser

Performs log in with specified username and password.

Parameters

username ?string: String to be used as user credential.
password ?string: String to be used as user credential.

logout

Performs log out.

mockOrTransform

Mocks a request with the supplied mock object, or allows it to run with an optional transform, based on the deserialised JSON response for the request.

Parameters

mockCheck Function: function that returns true if the request should be mocked.
mock Object: A mock object to wrap in a JSON response, if the request should be mocked.
responseObjectTransform Function|undefined: An optional function that transforms the response's object before the response is used.

Returns

Promise: Promise that uses mockCheck to see if a request should be mocked with mock, and optionally transforms the response with responseObjectTransform.

openDocumentSettingsSidebar

Clicks on the button in the header which opens Document Settings sidebar when it is closed.

openGlobalBlockInserter

Opens the global inserter.

openGlobalStylesPanel

Opens a global styles panel.

Parameters

panelName string: Name of the panel that is going to be opened.

openListView

Opens list view

openPreviewPage

Opens the preview page of an edited post.

Parameters

editorPage Page: puppeteer editor page.

Returns

Page: preview page.

openPreviousGlobalStylesPanel

Opens the previous global styles panel.

openPublishPanel

Opens the publish panel.

openTypographyToolsPanelMenu

Opens the Typography tools panel menu provided via block supports.

pressKeyTimes

Presses the given keyboard key a number of times in sequence.

Parameters

key string: Key to press.
count number: Number of times to press.

pressKeyWithModifier

Performs a key press with modifier (Shift, Control, Meta, Alt), where each modifier is normalized to platform-specific modifier.

Parameters

modifier string: Modifier key.
key string: Key to press while modifier held.

publishPost

Publishes the post, resolving once the request is complete (once a notice is displayed).

Returns

Promise: Promise resolving when publish is complete.

publishPostWithPrePublishChecksDisabled

Publishes the post without the pre-publish checks, resolving once the request is complete (once a notice is displayed).

Returns

Promise: Promise resolving when publish is complete.

resetPreferences

Clears all user meta preferences.

saveDraft

Saves the post as a draft, resolving once the request is complete (once the "Saved" indicator is displayed).

Returns

Promise: Promise resolving when draft save is complete.

searchForBlock

Searches for a block via the global inserter.

Parameters

searchTerm string: The term to search the inserter for.

Returns

Promise<ElementHandle|null>: The handle of block to be inserted or null if nothing was found.

searchForBlockDirectoryBlock

Searches for a Block Directory block via the global inserter.

Parameters

searchTerm string: The term to search the inserter for.

Returns

Promise<ElementHandle|null>: The handle of the Block Directory block to be inserted or null if nothing was found.

searchForPattern

Searches for a pattern via the global inserter.

Parameters

searchTerm string: The term to search the inserter for.

Returns

Promise<ElementHandle|null>: The handle of the pattern to be inserted or null if nothing was found.

searchForReusableBlock

Searches for a reusable block via the global inserter.

Parameters

searchTerm string: The term to search the inserter for.

Returns

Promise<ElementHandle|null>: The handle of the reusable block to be inserted or null if nothing was found.

selectBlockByClientId

Given the clientId of a block, selects the block on the editor.

Parameters

clientId string: Identified of the block.

setBrowserViewport

Sets browser viewport to specified type.

Parameters

viewport WPViewport: Viewport name or dimensions object to assign.

setClipboardData

Sets the clipboard data that can be pasted with pressKeyWithModifier( 'primary', 'v' ).

Parameters

$1 Object: Options.
$1.plainText string: Plain text to set.
$1.html string: HTML to set.

setOption

Sets a site option, from the options-general admin page.

Parameters

setting string: The option, used to get the option by id.
value string: The value to set the option to.

Returns

string: The previous value of the option.

setPostContent

Sets code editor content

Parameters

content string: New code editor content.

Returns

Promise: Promise resolving with an array containing all blocks in the document.

setUpResponseMocking

Sets up mock checks and responses. Accepts a list of mock settings with the following properties:

match: function to check if a request should be mocked.
onRequestMatch: async function to respond to the request.

Usage

const MOCK_RESPONSES = [
	{
		match: isEmbedding( 'https://wordpress.org/gutenberg/handbook/' ),
		onRequestMatch: JSONResponse( MOCK_BAD_WORDPRESS_RESPONSE ),
	},
	{
		match: isEmbedding(
			'https://wordpress.org/gutenberg/handbook/block-api/attributes/'
		),
		onRequestMatch: JSONResponse( MOCK_EMBED_WORDPRESS_SUCCESS_RESPONSE ),
	},
];
setUpResponseMocking( MOCK_RESPONSES );

If none of the mock settings match the request, the request is allowed to continue.

Parameters

mocks Array: Array of mock settings.

showBlockToolbar

The block toolbar is not always visible while typing. Call this function to reveal it.

switchBlockInspectorTab

Clicks on the block inspector tab button with the supplied label and waits for the tab switch.

Parameters

label string: Aria label to find tab button by.

switchEditorModeTo

Switches editor mode.

Parameters

mode string: String editor mode.

switchUserToAdmin

Switches the current user to the admin user (if the user running the test is not already the admin user).

switchUserToTest

Switches the current user to whichever user we should be running the tests as (if we're not already that user).

toggleGlobalBlockInserter

Toggles the global inserter.

toggleGlobalStyles

Toggles the global styles sidebar (opens it if closed and closes it if open).

toggleMoreMenu

Toggles the More Menu.

Parameters

waitFor ['open' | 'close']: Whether it should wait for the menu to open or close. If undefined it won't wait for anything.

toggleOfflineMode

Undocumented declaration.

togglePreferencesOption

Toggles a preference option with the given tab label and the option label.

Parameters

tabLabel string: The preferences tab label to click.
optionLabel string: The option label to search the button for.
shouldBeChecked [boolean]: If true, turns the option on. If false, off. If not provided, the option will be toggled.

transformBlockTo

Converts editor's block type.

Parameters

name string: Block name.

trashAllComments

Navigates to the comments listing screen and bulk-trashes any comments which exist.

Returns

Promise: Promise resolving once comments have been trashed.

trashAllPosts

Navigates to the post listing screen and bulk-trashes any posts which exist.

Parameters

postType string: - String slug for type of post to trash.
postStatus string: - String status of posts to trash.

Returns

Promise: Promise resolving once posts have been trashed.

uninstallPlugin

Uninstalls a plugin.

Parameters

slug string: Plugin slug.

visitAdminPage

Visits admin page; if user is not logged in then it logging in it first, then visits admin page.

Parameters

adminPath string: String to be serialized as pathname.
query string: String to be serialized as query portion of URL.

visitSiteEditor

Visits the Site Editor main page

By default, it also skips the welcome guide. The option can be disabled if need be.

Related

disableSiteEditorWelcomeGuide

Parameters

query string: String to be serialized as query portion of URL.
skipWelcomeGuide [boolean]: Whether to skip the welcome guide as part of the navigation.

waitForWindowDimensions

Function that waits until the page viewport has the required dimensions. It is being used to address a problem where after using setViewport the execution may continue, without the new dimensions being applied. https://github.com/GoogleChrome/puppeteer/issues/1751

Parameters

width number: Width of the window.
height number: Height of the window.

wpDataSelect

Queries the WordPress data module.

page.evaluate - used in the function - returns undefined when it encounters a non-serializable value. Since we store many different values in the data module, you can end up with an undefined result. Before using this function, make sure the data you are querying doesn't contain non-serializable values, for example, functions, DOM element handles, etc.

Related

Parameters

store string: Store to query e.g: core/editor, core/blocks...
selector string: Selector to exectute e.g: getBlocks.
parameters ...Object: Parameters to pass to the selector.

Returns

Promise<?Object>: Result of querying.

Contributing to this package

This is an individual package that's part of the Gutenberg project. The project is organized as a monorepo. It's made up of multiple self-contained software packages, each with a specific purpose. The packages in this monorepo are published to npm and used by WordPress as well as other software projects.

To find out more about contributing to this package or Gutenberg as a whole, please read the project's main contributor guide.