WIP - add e2e keyboard navigation util functions

packages/e2e-test-utils/README.md

@@ -173,6 +173,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.
@@ -243,6 +251,14 @@ _Returns_
 
 -   `Promise`: Promise resolving with post content markup.
 
+<a name="getElementSelectorList" href="#getElementSelectorList">#</a> **getElementSelectorList**
+
+Returns an array of classnames that match a given selector on the current page
+
+_Parameters_
+
+-   _selector_ `string`: The selector to query on the page
+
 <a name="hasBlockSwitcher" href="#hasBlockSwitcher">#</a> **hasBlockSwitcher**
 
 Returns a boolean indicating if the current selected block has a block switcher or not.
@@ -251,6 +267,15 @@ _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
+
 <a name="insertBlock" href="#insertBlock">#</a> **insertBlock**
 
 Opens the inserter, searches for the given term, then selects the first
@@ -261,6 +286,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.
@@ -315,6 +344,10 @@ _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**
+
+Undocumented declaration.
+
 <a name="observeFocusLoss" href="#observeFocusLoss">#</a> **observeFocusLoss**
 
 Binds to the document on page load which throws an error if a `focusout`
@@ -469,6 +502,59 @@ 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.
+
+<a name="tabThroughBlockToolbar" href="#tabThroughBlockToolbar">#</a> **tabThroughBlockToolbar**
+
+Navigate through a block's toolbar using the keyboard. Asserts that each button receives 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
+
+<a name="tabThroughPlaceholderButtons" href="#tabThroughPlaceholderButtons">#</a> **tabThroughPlaceholderButtons**
+
+Tabs through the file upload buttons that appear in a file content block's placeholder area
+
+<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
+
+<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
+
+<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
+
 <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,10 @@
+/**
+ * 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
+ */
+
+export async function externalWrapperHasFocus( blockType ) {
+	const activeElementDataType = await page.evaluate( () => document.activeElement.dataset.type );
+	await expect( activeElementDataType ).toEqual( blockType );
+}

packages/e2e-test-utils/src/get-element-list.js

@@ -0,0 +1,16 @@
+/*eslint no-shadow: ["error", { "allow": ["selector"] }]*/
+
+/**
+ * Returns an array of classnames that match a given selector on the current page
+ *
+ * @param {string} selector The selector to query on the page
+ */
+export const getElementSelectorList = async ( selector ) => {
+	return await page.evaluate( ( selector ) => {
+		return Array.from(
+			document.querySelectorAll(
+				selector
+			)
+		).map( ( elem ) => elem.className );
+	}, selector );
+};

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

@@ -14,19 +14,24 @@ export { dragAndResize } from './drag-and-resize';
 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';
 export { getAllBlocks } from './get-all-blocks';
 export { getAvailableBlockTransforms } from './get-available-block-transforms';
 export { getBlockSetting } from './get-block-setting';
 export { getEditedPostContent } from './get-edited-post-content';
+export { getElementSelectorList } from './get-element-list';
 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';
@@ -44,6 +49,14 @@ export { setPostContent } from './set-post-content';
 export { switchEditorModeTo } from './switch-editor-mode-to';
 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,28 @@
+/**
+ * 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
+ */
+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,8 @@
+/**
+ * Asserts that a content block's inserter toggle has keyboard focus
+ */
+
+export async function inserterToggleHasFocus() {
+	const isFocusedInserterToggle = await page.evaluate( () => document.activeElement.classList.contains( 'block-editor-inserter__toggle' ) );
+	await expect( isFocusedInserterToggle ).toBe( true );
+}

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

@@ -0,0 +1,17 @@
+/**
+ * Navigates to the top of the content editor using the keyboard.
+ */
+
+/**
+ * Internal dependencies
+ */
+import { pressKeyWithModifier } from './press-key-with-modifier';
+
+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,18 @@
+/**
+ * Navigates through the block mover control using the keyboard. Asserts that the 'move up' and 'move down' controls receive focus.
+ */
+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' )
+	);
+	await 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' )
+	);
+	await expect( isFocusedMoveDownControl ).toBe( true );
+}

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

@@ -0,0 +1,20 @@
+/**
+ * Navigate through a block's toolbar using the keyboard. Asserts that each button receives focus.
+ */
+
+export async function tabThroughBlockToolbar() {
+	const blockToolbarButtons = await page.evaluate( () => {
+		// return an array with the classNames of the block toolbar's buttons
+		return [].slice.call(
+			document.querySelectorAll( '.block-editor-block-contextual-toolbar button:not([disabled])' )
+		).map( ( elem ) => elem.className );
+	} );
+
+	for ( const buttonClassName of blockToolbarButtons ) {
+		await page.keyboard.press( 'Tab' );
+		const focusedBlockToolBarButton = await page.evaluate( () =>
+			document.activeElement.className
+		);
+		await expect( focusedBlockToolBarButton ).toEqual( buttonClassName );
+	}
+}

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

@@ -0,0 +1,28 @@
+/**
+ * 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
+ */
+
+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,17 @@
+
+/**
+ * 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
+ */
+export async function tabThroughFileBlock( blockType ) {
+	await tabThroughBlock( blockType );
+	await tabThroughPlaceholderButtons();
+}

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

@@ -0,0 +1,21 @@
+/**
+ * WordPress dependencies
+ */
+import {
+	getElementSelectorList,
+} from '@wordpress/e2e-test-utils';
+
+/**
+ * Tabs through the file upload buttons that appear in a file content block's placeholder area
+ */
+export const tabThroughPlaceholderButtons = async () => {
+	const placeholderButtons = await getElementSelectorList( '.wp-block.is-selected .block-editor-media-placeholder button:not([disabled])' );
+
+	for ( const buttonClassName of placeholderButtons ) {
+		await page.keyboard.press( 'Tab' );
+		const focusePlaceholderButton = await page.evaluate( () =>
+			document.activeElement.className
+		);
+		await expect( focusePlaceholderButton ).toEqual( buttonClassName );
+	}
+};

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

@@ -0,0 +1,20 @@
+/**
+ * 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
+ */
+
+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 );
+}