Novices Performing Miracles

    @wordpress/e2e-test-utils

    7.5.0 • Public • Published

    E2E Test Utils

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

    It works properly with the minimum version of Gutenberg 9.2.0 or the minimum version of WordPress 5.6.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 12.0.0 or later. 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.

    clickSiteEditorMenuItem

    Searches for an item in the navigation panel with the label provided and clicks it.

    Parameters

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

    closeGlobalBlockInserter

    Undocumented declaration.

    closeListView

    Closes list view

    closeSiteEditorNavigationPanel

    Closes the site editor navigation panel if open

    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.

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

    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.

    getSiteEditorMenuItem

    Searches for an item in the site editor navigation menu with the provided label.

    Parameters

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

    Returns

    • Promise<?ElementHandle>: The menu item handle or null

    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. It then waits briefly for the block list to update.

    Parameters

    • searchTerm string: The text to search the inserter for.

    insertBlockDirectoryBlock

    Opens the inserter, searches for the given block, then selects the first result that appears from the block directory. It then waits briefly for the block list to update.

    Parameters

    • searchTerm string: The text to search the inserter for.

    insertPattern

    Opens the inserter, searches for the given pattern, then selects the first result that appears. It then waits briefly for the block list to update.

    Parameters

    • searchTerm string: The text to search the inserter for.

    insertReusableBlock

    Opens the inserter, searches for the given reusable block, then selects the first result that appears. It then waits briefly for the block list to update.

    Parameters

    • searchTerm string: The text to search the inserter for.

    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.

    isOfflineMode

    Undocumented declaration.

    isSiteEditorRoot

    Returns true if in the site editor navigation root

    Checks whether the “Back to dashboard” button is visible. If not in the root, a “Back” button would be visible instead.

    Returns

    • Promise<boolean>: Whether it currently is the navigation root or not

    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.

    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.

    navigateSiteEditorBack

    Navigates the site editor back

    navigateSiteEditorBackToRoot

    Goes back until it gets to the root

    openDocumentSettingsSidebar

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

    openGlobalBlockInserter

    Opens the global block 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.

    openSiteEditorNavigationPanel

    Opens the site editor navigation panel if closed

    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

    Search for block in the global inserter

    Parameters

    • searchTerm string: The text to search the inserter for.

    searchForPattern

    Search for pattern in the global inserter

    Parameters

    • searchTerm string: The text to search the inserter for.

    searchForReusableBlock

    Search for reusable 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.

    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.

    siteEditorNavigateSequence

    Navigates through a sequence of links in the site editor navigation panel

    Parameters

    • labels string[] | string: Labels to navigate through

    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.



    Code is Poetry.

    Install

    npm i @wordpress/e2e-test-utils

    DownloadsWeekly Downloads

    16,607

    Version

    7.5.0

    License

    GPL-2.0-or-later

    Unpacked Size

    675 kB

    Total Files

    364

    Last publish

    Collaborators

    • gutenbergplugin
    • mamaduka
    • ryanwelcher
    • adamziel
    • garypendergast
    • aduth
    • riad
    • adamsilverstein
    • gziolo
    • ntwb
    • noisysocks
    • kadamwhite
    • jorgefilipecosta
    • ellatrix
    • iandunn206
    • whyisjake
    • ockham
    • sirreal
    • nosolosw
    • wpisabel
    • ntsekouras
    • nerrad
    • desrosj
    • talldanwp
    • peterwilsoncc