WordPress · tjnicolaides · Jan 23, 2019 · Feb 24, 2019 · Feb 24, 2019 · Mar 7, 2019
@@ -181,6 +181,18 @@ _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
+
+_Returns_
+
+-   `Promise`: A promise that's resolved when the active element is evaluated and asserted against the expected result.
+
 <a name="findSidebarPanelToggleButtonWithTitle" href="#findSidebarPanelToggleButtonWithTitle">#</a> **findSidebarPanelToggleButtonWithTitle**
 
 Finds a sidebar panel with the provided title.
@@ -259,6 +271,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
@@ -327,6 +352,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`
@@ -477,6 +510,91 @@ 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="tabThroughBlockControls" href="#tabThroughBlockControls">#</a> **tabThroughBlockControls**
+
+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
+
+_Returns_
+
+-   `Promise`: A promise that's resolved when the browser has finished tabbing through the major components of a common block.
+
+<a name="tabThroughBlockMovers" href="#tabThroughBlockMovers">#</a> **tabThroughBlockMovers**
+
+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="tabThroughTextContentAreas" href="#tabThroughTextContentAreas">#</a> **tabThroughTextContentAreas**
+
+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="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="toggleMoreMenu" href="#toggleMoreMenu">#</a> **toggleMoreMenu**
 
 Toggles the More Menu.

@@ -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
+ * @return {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 );
+}
@@ -15,28 +15,39 @@ 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 { findSidebarPanelToggleButtonWithTitle } from './find-sidebar-panel-toggle-button-with-title';
+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 {
+	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 { hasBlockSwitcher } from './has-block-switcher';
+export { insertAndPopulateBlock } from './insert-and-populate-block';
 export { insertBlock } from './insert-block';
 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 {
+	openAllBlockInserterCategories,
+} from './open-all-block-inserter-categories';
 export { openDocumentSettingsSidebar } from './open-document-settings-sidebar';
 export { openGlobalBlockInserter } from './open-global-block-inserter';
 export { openPublishPanel } from './open-publish-panel';
 export { pressKeyTimes } from './press-key-times';
 export { pressKeyWithModifier } from './press-key-with-modifier';
 export { publishPost } from './publish-post';
-export { publishPostWithPrePublishChecksDisabled } from './publish-post-with-pre-publish-checks-disabled';
+export {
+	publishPostWithPrePublishChecksDisabled,
+} from './publish-post-with-pre-publish-checks-disabled';
 export { saveDraft } from './save-draft';
 export { searchForBlock } from './search-for-block';
 export { selectBlockByClientId } from './select-block-by-client-id';
@@ -46,6 +57,16 @@ 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 { tabThroughBlockControls } from './tab-through-block-controls';
+export { tabThroughBlockMovers } from './tab-through-block-movers';
+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 { tabThroughTextContentAreas } from './tab-through-text-content-areas';
+export { textContentAreas } from './text-content-areas';
 export { toggleMoreMenu } from './toggle-more-menu';
 export { toggleOfflineMode, isOfflineMode } from './offline-mode';
 export { toggleScreenOption } from './toggle-screen-option';

@@ -0,0 +1,27 @@
+/**
+ * Internal dependencies
+ */
+import { insertBlock } from './insert-block';
+import { textContentAreas } from './text-content-areas';
+
+/**
+ * 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 blockContentAreas = await textContentAreas( { empty: true } );
+
+	for ( let i = 0; i < blockContentAreas.length; i++ ) {
+		await page.keyboard.press( 'Tab' );
+		await page.keyboard.type( content );
+	}
+	await page.keyboard.press( 'Enter' );
+}
@@ -0,0 +1,18 @@
+/**
+ * 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' );
+}
@@ -0,0 +1,37 @@
+/**
+ * Internal dependencies
+ */
+import { externalWrapperHasFocus } from './external-wrapper-has-focus';
+import { tabThroughBlockMovers } from './tab-through-block-movers';
+import { tabThroughBlockToolbar } from './tab-through-block-toolbar';
+
+/**
+ * Asserts that a content block's inserter toggle has keyboard focus
+ *
+ * @return {Promise} A promise that's resolved when the active element is evaluated and asserted to have the inserter toggle's classname.
+ */
+
+const inserterToggleHasFocus = async function() {
+	const isFocusedInserterToggle = await page.evaluate( () => document.activeElement.classList.contains( 'block-editor-inserter__toggle' ) );
+	expect( isFocusedInserterToggle ).toBe( true );
+};
+
+/**
+ * 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
+ * @return {Promise} A promise that's resolved when the browser has finished tabbing through the major components of a common block.
+ */
+
+export async function tabThroughBlockControls( 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 tabThroughBlockMovers();
+	await tabThroughBlockToolbar();
+}
@@ -0,0 +1,21 @@
+/**
+ * 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 tabThroughBlockMovers() {
+	// 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 );
+}
@@ -0,0 +1,18 @@
+/**
+ * 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 );
+	}
+}
@@ -0,0 +1,18 @@
+
+/**
+ * Internal dependencies
+ */
+
+import { tabThroughBlockControls } from './tab-through-block-controls';
+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 tabThroughBlockControls( blockType );
+	await tabThroughPlaceholderButtons();
+}
@@ -0,0 +1,17 @@
+/**
+ * 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 );
+	}
+};