@wordpress/e2e-test-utils Edit

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 Installation

Install the module

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

Top ↑

API 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.

# 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

  • name string: Block name.

# 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.

Code is Poetry.