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
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 usesmockCheck
to see if a request should be mocked withmock
, and optionally transforms the response withresponseObjectTransform
.
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. Ifundefined
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
- https://pptr.dev/#?product=Puppeteer&version=v9.0.0&show=api-pageevaluatepagefunction-args
- https://github.com/WordPress/gutenberg/pull/31199
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.