Refactored e2e keyboard navigation util functions / tests

packages/e2e-test-utils/README.md

@@ -181,6 +181,14 @@ _Returns_
 
 -   `Promise`: Promise resolving once the edit post sidebar is opened.
 
+<a name="externalWrapperHasFocus" href="#externalWrapperHasFocus">#</a> **externalWrapperHasFocus**
+
+Asserts that the element with keyboard focus is a block's external wrapper
+
+_Parameters_
+
+-   _blockType_ `string`: The expected value of the data-type attribute of the block's external wrapper
+
 <a name="findSidebarPanelToggleButtonWithTitle" href="#findSidebarPanelToggleButtonWithTitle">#</a> **findSidebarPanelToggleButtonWithTitle**
 
 Finds a sidebar panel with the provided title.
@@ -259,6 +267,19 @@ _Returns_
 
 -   `Promise`: Promise resolving with a boolean.
 
+<a name="insertAndPopulateBlock" href="#insertAndPopulateBlock">#</a> **insertAndPopulateBlock**
+
+Inserts a content block and then, if it has text content areas, fills them with text
+
+_Parameters_
+
+-   _blockName_ `string`: The type of block to insert
+-   _content_ `string`: The text to enter into each contenteditable area
+
+_Returns_
+
+-   `Promise`: A promise that resolves when all the blocks are inserted and filled with content.
+
 <a name="insertBlock" href="#insertBlock">#</a> **insertBlock**
 
 Opens the inserter, searches for the given term, then selects the first
@@ -269,6 +290,10 @@ _Parameters_
 -   _searchTerm_ `string`: The text to search the inserter for.
 -   _panelName_ `string`: The inserter panel to open (if it's closed by default).
 
+<a name="inserterToggleHasFocus" href="#inserterToggleHasFocus">#</a> **inserterToggleHasFocus**
+
+Asserts that a content block's inserter toggle has keyboard focus
+
 <a name="installPlugin" href="#installPlugin">#</a> **installPlugin**
 
 Installs a plugin from the WP.org repository.
@@ -323,6 +348,14 @@ _Returns_
 
 -   `Promise`: Promise that uses `mockCheck` to see if a request should be mocked with `mock`, and optionally transforms the response with `responseObjectTransform`.
 
+<a name="navigateToContentEditorTop" href="#navigateToContentEditorTop">#</a> **navigateToContentEditorTop**
+
+Navigates to the top of the content editor using the keyboard.
+
+_Returns_
+
+-   `Promise`: A promise that's resolved when the browser has finished emulating the keyboard shortcut for focusing the top of the editor, and tabbed to the next focusable element.
+
 <a name="observeFocusLoss" href="#observeFocusLoss">#</a> **observeFocusLoss**
 
 Binds to the document on page load which throws an error if a `focusout`
@@ -473,6 +506,87 @@ running the test is not already the admin user).
 Switches the current user to whichever user we should be
 running the tests as (if we're not already that user).
 
+<a name="tabThroughBlock" href="#tabThroughBlock">#</a> **tabThroughBlock**
+
+Tabs through a content block and asserts that the external wrapper, inserter toggle, mover controls, and toolbar buttons all receive keyboard focus.
+
+_Parameters_
+
+-   _blockType_ `string`: The expected value of the data-type attribute of the block's external wrapper
+
+<a name="tabThroughBlockMoverControl" href="#tabThroughBlockMoverControl">#</a> **tabThroughBlockMoverControl**
+
+Navigates through the block mover control using the keyboard. Asserts that the 'move up' and 'move down' controls receive focus.
+
+_Returns_
+
+-   `Promise`: A promise that's resolved when the browser has finished tabbing throught the block mover controls.
+
+<a name="tabThroughBlockToolbar" href="#tabThroughBlockToolbar">#</a> **tabThroughBlockToolbar**
+
+Navigate through a block's toolbar using the keyboard. Asserts that each button receives focus.
+
+_Returns_
+
+-   `Promise`: A promise that resolves when it's finished tabbing through the buttons in a block's toolbar, asserting that each one received focus.
+
+<a name="tabThroughFileBlock" href="#tabThroughFileBlock">#</a> **tabThroughFileBlock**
+
+Tabs through a content block with file upload buttons, such as an Image, Gallery, Audio, or Cover block
+
+_Parameters_
+
+-   _blockType_ `string`: The expected value of the data-type attribute of the block's external wrapper
+
+_Returns_
+
+-   `Promise`: A promise that resolves when the browser has completed tabbing through the common block components, and the placeholder buttons that are unique to blocks with file-upload features.
+
+<a name="tabThroughPlaceholderButtons" href="#tabThroughPlaceholderButtons">#</a> **tabThroughPlaceholderButtons**
+
+Tabs through the file upload buttons that appear in a file content block's placeholder area
+
+_Returns_
+
+-   `Promise`: A promise that resolves when the browser has completed tabbing through the placeholder buttons that are unique to blocks with file-upload features.
+
+<a name="tabThroughTextBlock" href="#tabThroughTextBlock">#</a> **tabThroughTextBlock**
+
+Tabs through a content block with text content areas, such as a Heading, Quote, or Paragraph block. Asserts that the text content areas all receive focus.
+
+_Parameters_
+
+-   _blockType_ `string`: The expected value of the data-type attribute of the block's external wrapper
+-   _content_ `string`: The expected title of the block
+
+_Returns_
+
+-   `Promise`: A promise that resolves when the browser has completed tabbing through the focusable elements of a common block, and through the contenteditbable areas unique to text blocks.
+
+<a name="textContentAreas" href="#textContentAreas">#</a> **textContentAreas**
+
+Returns a list of a block's contenteditable elements.
+
+_Parameters_
+
+-   _empty_ `boolean`: When true, restricts the list to contenteditable elements with no value
+
+_Returns_
+
+-   `Promise`: A promise that resolves when it's returned an array of classes representing the contenteditable areas of a block with keyboard focus.
+
+<a name="textContentAreasHaveFocus" href="#textContentAreasHaveFocus">#</a> **textContentAreasHaveFocus**
+
+Tabs through the text content areas of a block and asserts the expected values
+
+_Parameters_
+
+-   _content_ `string`: The expected value of the block's contenteditable elements
+
+_Returns_
+
+-   `Promise`: A promise that's resolved when the browser has finished tabbing throught the contenteditable areas of a block, and asserting they have keyboard focus and the expected content.
+
 <a name="toggleScreenOption" href="#toggleScreenOption">#</a> **toggleScreenOption**
 
 Toggles the screen option with the given label.

packages/e2e-test-utils/src/external-wrapper-has-focus.js

@@ -0,0 +1,11 @@
+/**
+ * Asserts that the element with keyboard focus is a block's external wrapper
+ *
+ * @param {string} blockType  The expected value of the data-type attribute of the block's external wrapper
+ * @returns {Promise} A promise that's resolved when the active element is evaluated and asserted against the expected result.
+ */
+
+export async function externalWrapperHasFocus( blockType ) {
+	const activeElementDataType = await page.evaluate( () => document.activeElement.dataset.type );
+	expect( activeElementDataType ).toEqual( blockType );
+}

packages/e2e-test-utils/src/index.js

@@ -15,6 +15,7 @@ export { enableExperimentalFeatures } from './enable-experimental-features';
 export { enablePageDialogAccept } from './enable-page-dialog-accept';
 export { enablePrePublishChecks } from './enable-pre-publish-checks';
 export { ensureSidebarOpened } from './ensure-sidebar-opened';
+export { externalWrapperHasFocus } from './external-wrapper-has-focus';
 export { findSidebarPanelToggleButtonWithTitle } from './find-sidebar-panel-toggle-button-with-title';
 export { findSidebarPanelWithTitle } from './find-sidebar-panel-with-title';
 export { getAllBlockInserterItemTitles } from './get-all-block-inserter-item-titles';
@@ -23,11 +24,14 @@ export { getAvailableBlockTransforms } from './get-available-block-transforms';
 export { getBlockSetting } from './get-block-setting';
 export { getEditedPostContent } from './get-edited-post-content';
 export { hasBlockSwitcher } from './has-block-switcher';
+export { insertAndPopulateBlock } from './insert-and-populate-block';
 export { insertBlock } from './insert-block';
+export { inserterToggleHasFocus } from './inserter-toggle-has-focus';
 export { installPlugin } from './install-plugin';
 export { isCurrentURL } from './is-current-url';
 export { isInDefaultBlock } from './is-in-default-block';
 export { loginUser } from './login-user';
+export { navigateToContentEditorTop } from './navigate-to-content-editor-top';
 export { observeFocusLoss } from './observe-focus-loss';
 export { openAllBlockInserterCategories } from './open-all-block-inserter-categories';
 export { openDocumentSettingsSidebar } from './open-document-settings-sidebar';
@@ -46,6 +50,14 @@ export { switchEditorModeTo } from './switch-editor-mode-to';
 export { disableNavigationMode } from './keyboard-mode';
 export { switchUserToAdmin } from './switch-user-to-admin';
 export { switchUserToTest } from './switch-user-to-test';
+export { tabThroughBlock } from './tab-through-block';
+export { tabThroughBlockMoverControl } from './tab-through-block-mover-control';
+export { tabThroughBlockToolbar } from './tab-through-block-toolbar';
+export { tabThroughFileBlock } from './tab-through-file-block';
+export { tabThroughPlaceholderButtons } from './tab-through-placeholder-buttons';
+export { tabThroughTextBlock } from './tab-through-text-block';
+export { textContentAreas } from './text-content-areas';
+export { textContentAreasHaveFocus } from './text-content-areas-have-focus';
 export { toggleScreenOption } from './toggle-screen-option';
 export { transformBlockTo } from './transform-block-to';
 export { uninstallPlugin } from './uninstall-plugin';

packages/e2e-test-utils/src/insert-and-populate-block.js

@@ -0,0 +1,29 @@
+/**
+ * WordPress dependencies
+ */
+import {
+	insertBlock,
+	textContentAreas,
+} from '@wordpress/e2e-test-utils';
+
+/**
+ * Inserts a content block and then, if it has text content areas, fills them with text
+ *
+ * @param {string} blockName The type of block to insert
+ * @param {string} content  The text to enter into each contenteditable area
+ * @return {Promise} A promise that resolves when all the blocks are inserted and filled with content.
+ */
+export async function insertAndPopulateBlock( blockName, content ) {
+	await insertBlock( blockName );
+	// typing populates the first content area
+	await page.keyboard.type( content );
+
+	// if there are more contenteditable elements, select and populate them too:
+	const blocks = await textContentAreas( { empty: true } );
+
+	for ( let i = 0; i < blocks.length; i++ ) {
+		await page.keyboard.press( 'Tab' );
+		await page.keyboard.type( content );
+	}
+	await page.keyboard.press( 'Enter' );
+}

packages/e2e-test-utils/src/inserter-toggle-has-focus.js

@@ -0,0 +1,9 @@
+/**
+ * Asserts that a content block's inserter toggle has keyboard focus
+ * @returns {Promise} A promise that's resolved when the active element is evaluated and asserted to have the inserter toggle's classname.
+ */
+
+export async function inserterToggleHasFocus() {
+	const isFocusedInserterToggle = await page.evaluate( () => document.activeElement.classList.contains( 'block-editor-inserter__toggle' ) );
+	expect( isFocusedInserterToggle ).toBe( true );
+}

packages/e2e-test-utils/src/navigate-to-content-editor-top.js

@@ -0,0 +1,17 @@
+/**
+ * Internal dependencies
+ */
+import { pressKeyWithModifier } from './press-key-with-modifier';
+
+/**
+ * Navigates to the top of the content editor using the keyboard.
+ * @return {Promise} A promise that's resolved when the browser has finished emulating the keyboard shortcut for focusing the top of the editor, and tabbed to the next focusable element.
+ */
+export async function navigateToContentEditorTop() {
+	// Use 'Ctrl+`' to return to the top of the editor
+	await pressKeyWithModifier( 'ctrl', '`' );
+	await pressKeyWithModifier( 'ctrl', '`' );
+
+	// Tab into the Title block
+	await page.keyboard.press( 'Tab' );
+}

packages/e2e-test-utils/src/tab-through-block-mover-control.js

@@ -0,0 +1,19 @@
+/**
+ * Navigates through the block mover control using the keyboard. Asserts that the 'move up' and 'move down' controls receive focus.
+ * @return {Promise} A promise that's resolved when the browser has finished tabbing throught the block mover controls.
+ */
+export async function tabThroughBlockMoverControl() {
+	// Tab to focus on the 'move up' control
+	await page.keyboard.press( 'Tab' );
+	const isFocusedMoveUpControl = await page.evaluate( () =>
+		document.activeElement.classList.contains( 'block-editor-block-mover__control' )
+	);
+	expect( isFocusedMoveUpControl ).toBe( true );
+
+	// Tab to focus on the 'move down' control
+	await page.keyboard.press( 'Tab' );
+	const isFocusedMoveDownControl = await page.evaluate( () =>
+		document.activeElement.classList.contains( 'block-editor-block-mover__control' )
+	);
+	expect( isFocusedMoveDownControl ).toBe( true );
+}

packages/e2e-test-utils/src/tab-through-block-toolbar.js

@@ -0,0 +1,17 @@
+/**
+ * Navigate through a block's toolbar using the keyboard. Asserts that each button receives focus.
+ * @return {Promise} A promise that resolves when it's finished tabbing through the buttons in a block's toolbar, asserting that each one received focus.
+ */
+
+export async function tabThroughBlockToolbar() {
+	const blockToolbarButtons = await page.$$eval( '.block-editor-block-contextual-toolbar button:not([disabled])',
+		( elements ) => elements.map( ( elem ) => elem.className ) );
+
+	for ( const buttonClassName of blockToolbarButtons ) {
+		await page.keyboard.press( 'Tab' );
+		const focusedBlockToolBarButton = await page.evaluate( () =>
+			document.activeElement.className
+		);
+		expect( focusedBlockToolBarButton ).toEqual( buttonClassName );
+	}
+}

packages/e2e-test-utils/src/tab-through-block.js

@@ -0,0 +1,29 @@
+/**
+ * WordPress dependencies
+ */
+import {
+	externalWrapperHasFocus,
+	inserterToggleHasFocus,
+	tabThroughBlockMoverControl,
+	tabThroughBlockToolbar,
+} from '@wordpress/e2e-test-utils';
+
+/**
+ * Tabs through a content block and asserts that the external wrapper, inserter toggle, mover controls, and toolbar buttons all receive keyboard focus.
+ *
+ * @param {string} blockType  The expected value of the data-type attribute of the block's external wrapper
+ * @returns {Promise} A promise that's resolved when the browser has finished tabbing through the major components of a common block.
+ */
+
+export async function tabThroughBlock( blockType ) {
+	// Tab to the next block
+	await page.keyboard.press( 'Tab' );
+	await externalWrapperHasFocus( blockType );
+
+	// Tab causes 'add block' button to receive focus
+	await page.keyboard.press( 'Tab' );
+	await inserterToggleHasFocus();
+
+	await tabThroughBlockMoverControl();
+	await tabThroughBlockToolbar();
+}

packages/e2e-test-utils/src/tab-through-file-block.js

@@ -0,0 +1,18 @@
+
+/**
+ * Internal dependencies
+ */
+
+import { tabThroughBlock } from './tab-through-block';
+import { tabThroughPlaceholderButtons } from './tab-through-placeholder-buttons';
+
+/**
+ * Tabs through a content block with file upload buttons, such as an Image, Gallery, Audio, or Cover block
+ *
+ * @param {string} blockType  The expected value of the data-type attribute of the block's external wrapper
+ * @return {Promise} A promise that resolves when the browser has completed tabbing through the common block components, and the placeholder buttons that are unique to blocks with file-upload features.
+ */
+export async function tabThroughFileBlock( blockType ) {
+	await tabThroughBlock( blockType );
+	await tabThroughPlaceholderButtons();
+}

packages/e2e-test-utils/src/tab-through-placeholder-buttons.js

@@ -0,0 +1,16 @@
+/**
+ * Tabs through the file upload buttons that appear in a file content block's placeholder area
+ * @return {Promise} A promise that resolves when the browser has completed tabbing through the placeholder buttons that are unique to blocks with file-upload features.
+ */
+export const tabThroughPlaceholderButtons = async () => {
+	const placeholderButtons = await page.$$eval( '.wp-block.is-selected .block-editor-media-placeholder button:not([disabled])',
+		( elements ) => elements.map( ( elem ) => elem.className ) );
+
+	for ( const buttonClassName of placeholderButtons ) {
+		await page.keyboard.press( 'Tab' );
+		const focusedPlaceholderButton = await page.evaluate( () =>
+			document.activeElement.className
+		);
+		expect( focusedPlaceholderButton ).toEqual( buttonClassName );
+	}
+};

packages/e2e-test-utils/src/tab-through-text-block.js

@@ -0,0 +1,21 @@
+/**
+ * Internal dependencies
+ */
+import { tabThroughBlock } from './tab-through-block';
+import { textContentAreasHaveFocus } from './text-content-areas-have-focus';
+
+/**
+ * Tabs through a content block with text content areas, such as a Heading, Quote, or Paragraph block. Asserts that the text content areas all receive focus.
+ *
+ * @param {string} blockType  The expected value of the data-type attribute of the block's external wrapper
+ * @param {string} content The expected title of the block
+ * @return {Promise} A promise that resolves when the browser has completed tabbing through the focusable elements of a common block, and through the contenteditbable areas unique to text blocks.
+ */
+
+export async function tabThroughTextBlock( blockType, content ) {
+	await tabThroughBlock( blockType );
+
+	// Tab causes the block text content to receive focus
+	await page.keyboard.press( 'Tab' );
+	await textContentAreasHaveFocus( content );
+}