E2E Test Utils
End-To-End (E2E) test utils for WordPress.
It works properly with the minimum version of Gutenberg 5.6.0
or the minimum version of WordPress 5.2.0
.
Installation
Install the module
npm install @wordpress/e2e-test-utils --save-dev
API
# activatePlugin
Activates an installed plugin.
Parameters
- slug
string
: Plugin slug.
# arePrePublishChecksEnabled
Verifies if publish checks are enabled.
Returns
boolean
: Boolean which represents the state of prepublish checks.
# clearLocalStorage
Clears the local storage.
# clickBlockAppender
Clicks the default block appender.
# clickBlockToolbarButton
Clicks a block toolbar button.
Parameters
- buttonAriaLabel
string
: The aria label of the button to click.
# clickButton
Clicks a button based on the text on the button.
Parameters
- buttonText
string
: The text that appears on the button to click.
# 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.
# 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.
# createNewPost
Creates new post.
Parameters
- obj
Object
: Object to create new post, along with tips enabling option.
# 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.
# deactivatePlugin
Deactivates an active plugin.
Parameters
- slug
string
: Plugin slug.
# disableFocusLossObservation
Removes the focus loss listener that enableFocusLossObservation()
adds.
# disablePrePublishChecks
Disables Pre-publish checks.
# 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 even listener which accepts a page dialog which
may appear when navigating away from Gutenberg.
# enablePrePublishChecks
Enables Pre-publish checks.
# ensureSidebarOpened
Verifies that the edit post sidebar is opened, and if it is not, opens it.
Returns
Promise
: Promise resolving once the edit post sidebar is opened.
# 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.
# getEditedPostContent
Returns a promise which resolves with the edited post content (HTML string).
Returns
Promise
: Promise resolving with post content markup.
# 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
Opens the inserter, searches for the given term, then selects the first
result that appears.
Parameters
- searchTerm
string
: The text to search the inserter for. - panelName
string
: The inserter panel to open (if it's closed by default).
# 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.
# 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.
# isOfflineMode
Undocumented declaration.
# 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.
# 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
.
# openAllBlockInserterCategories
Opens all block inserter categories.
# openDocumentSettingsSidebar
Clicks on the button in the header which opens Document Settings sidebar when it is closed.
# openGlobalBlockInserter
Opens the global block inserter.
# openPublishPanel
Opens the publish panel.
# 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.
# 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
Search for block in the global inserter
Parameters
- searchTerm
string
: The text to search the inserter for.
# 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.
# 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.
# 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).
# toggleMoreMenu
Toggles the More Menu.
# toggleOfflineMode
Undocumented declaration.
# toggleScreenOption
Toggles the screen option with the given label.
Parameters
- label
string
: The label of the screen option, e.g. 'Show Tips'. - shouldBeChecked
?boolean
: If true, turns the option on. If false, off. If undefined, the option will be toggled.
# transformBlockTo
Converts editor's block type.
Parameters
# 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.
# 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.