Test an Oracle JET App for Keyboard-Only Accessibility

Introduction

This is the second tutorial in the Identify Accessibility Issues learning path.

The Web Content Accessibility Guidelines (WCAG) 2.1 outlines many of the success criteria for creating an accessible web app. This tutorial focuses on those criteria that address keyboard-only usage.

An app that is keyboard-only accessible can be used with alternate input devices for people with limited mobility or an inability to manipulate a mouse. When people can use a keyboard, the internet is at their fingertips.

Objectives

In this tutorial, you will learn how to perform a keyboard-only test of a web app.

Prerequisites

Task 1: Prepare for Keyboard-Only Accessibility Testing

The visual inspection provides an overview of the structure and basic functionality of an accessible page. Keyboard-only testing is at the center of manual accessibility testing; it gives the developer an opportunity to interact with the app from a disabled user’s perspective. The subset of WCAG 2.1 Success Criteria around which this tutorial focuses involves several specific concepts.

The success criteria mentioned at the beginning of this section indirectly address the concept of focusable elements, so a couple terms need to be defined.

With these applicable concepts defined and explained, you are prepared to test the starter app.

Notice the text “No Exception” included in the parentheses of Success Criterion 2.1.3. This signifies that keyboard accessibility is mandatory.

WCAG Guideline 2.1 and the Success Criterion that follows it underscore the absolute need for keyboard accessibility. The keyboard plays a pivotal role in bringing technology to everyone.

Task 2: Verify the Existence of a Visual Focus

Keyboard-only accessibility testing relies solely on the focus indicator. Adherence to the following “Focus Visible” Success Criterion is not negotiable. Disabled users cannot navigate an app without an active focus or when focus placement is unclear.

As you tab through the web app, there should always be a visible indicator identifying the focus location. The indicator is typically a rectangle. Disabling the focus rectangle causes a failure of this criterion.

App developers take pride in the apps and programs they write. Their goal is to integrate function with a visually engaging experience. A focus rectangle often detracts from the design; developers therefore often hide or disable it and violate Success Criterion 2.4.7.

Focus Rectangle 1

Focus Rectangle 1

Description of the illustration focus_rec1.png

Focus Rectangle 2

Focus Rectangle 2

Description of the illustration focus_rec2.png

Locate the point of focus in the two screenshots above.

The first screenshot, Focus Rectangle 1, represents a page with a correct indication of focus. The focus indicator is very evident as it surrounds the Overview tab at the top left of the page. The second screenshot, Focus Rectangle 2, lacks any indication of focus around the Overview tab.

Watch for the focus rectangle as you navigate through the first few focusable components on the Introduction page.

  1. If your app is not already running, navigate to the ACCLearningPath folder and start it.

    $ ojet serve

  2. When the app opens in your browser, press <Ctrl+L> to set focus on the address bar, and then press <Tab> to move focus to the skip navigation link.

  3. Press <Tab> to move focus to john.hancock@oracle.com in the user menu, at the top-right of the page.

  4. Press <Tab> to move focus to Introduction in the main navigation menu immediately below the user menu.

  5. Press <down arrow> to move focus to Resources in the navigation menu, and press <Enter> to load the Resources page.

    The Resources Page

    Description of the illustration resources_page.png

  6. Press <Tab> to move focus to the Oracle JET Main Site link.

    Notice that there is no clear indication of focus location. The Resources page fails Success Criterion 2.4.7.

    In the following steps, you will fix the absent focus rectangle issue in order to comply with WCAG standards.

  7. Navigate to the ACCLearningPath/src/js/views folder and open the resources.html file in a code editor.

  8. Locate the link for Oracle JET Main Site.

    <li><a style="outline-width:0"
   href="https://www.oracle.com/webfolder/technetwork/jet/index.html"
   target="_blank">Oracle JET Main Site</a>
</li>

    Change "outline-width:0" to "outline-width:3" in the style attribute.

    <li><a style="outline-width:3"
   href="https://www.oracle.com/webfolder/technetwork/jet/index.html"
   target="_blank">Oracle JET Main Site</a>
</li>

  9. Save and close resources.html.

    Your file should look similar to resources-html.txt.

  10. Repeat steps 2 through 6 above to verify that the focus rectangle is now visible.

Task 3: Verify a Meaningful Tab Sequence

The next piece to keyboard-only testing involves the organization of a page as the user tabs through it.

Focus order can be best understood with an illustration. As the user tabs through the page, focus location is not random. It does not move from one side of the page to the other and back again. It moves in an expected and logical fashion.

In the previous Verify the Existence of a Visual Focus task, you saw how the focus moved in an expected order through the banner of the page; however, the Resources page itself has been coded to illustrate a more random tab order.

  1. In the running app, press <Ctrl+L> to set focus on the address bar.

  2. Press <Tab> to move focus to the skip nav link.

  3. Press <Tab> to move focus to john.hancock@oracle.com in the user menu, at the top-right of the page.

  4. Press <Tab> to move focus to Introduction in the main navigation menu.

  5. Press <Tab> to move focus to the Oracle JET Main Site link in the body of the page.

  6. Press <Tab>. Focus should move to the Oracle JET Developer’s Guide but instead moves to the Oracle JET Cookbook link.

    The Oracle JET Developer’s Guide link is not in the tab sequence, which violates Success Criteria 2.4.3.

    Steps 7 through 11 describe the necessary method to return the Oracle JET Developer’s Guide link to its correct position in the tab sequence. Steps 12 through 16 illustrate how to confirm that the fix worked.

  7. In your code editor, locate the Oracle JET Developer’s Guide link in the resources.html file.

    <li><a tabindex="-1"
   href="https://docs.oracle.com/en/middleware/developer-tools/jet/13/books.html"
   target="_blank">Oracle JET Developer's Guide</a>
</li>

    The tabindex="-1" attribute takes this link completely out of the tab order of the page.

  8. Modify the value of the tabindex attribute to 0 to return the link to its proper place in the tab sequence of the page.

    <li><a tabindex="0"
   href="https://www.oracle.com/pls/topic/lookup?ctx=jetlatest&id=OJACC"
   target="_blank">Oracle JET Developer's Guide</a>
</li>

  9. Save and close the file. The Resources page in the browser is automatically refreshed with its new content.

  10. Press <Ctrl+L> to set focus on the address bar.

  11. Press <Tab> three times to move focus to Introduction in the navigation menu.

  12. Press <Tab> to move focus to the Oracle JET Main Site link.

  13. Press <Tab> to move focus to the Oracle JET Developer’s Guide link.

  14. Continue pressing <Tab> until focus lands on the About Oracle link in the page footer.

    Once you have navigated all the focusable elements on a page, reverse the process. Sometimes when shift-tabbing backwards through a page, the path changes unexpectedly, new elements appear, or some elements disappear.

  15. Use <Shift+Tab> to move in a bottom-to-top order to ensure that the meaningful sequence holds true while navigating in reverse through the page.

Task 4: Interact with Controls

Many of the controls that are used in this tutorial are Oracle JET-specific controls. A feature of Oracle JET is that its components are designed with keyboard-only accessibility already built in. Developers using Oracle JET can copy components directly from the Oracle JET Cookbook and drop them into place, and the resulting code is accessible.

For example, here is a brief list of common keystrokes for interacting with standard HTML components:

Note: For certain controls like navigation menus, tab bars, radio groups, and similar group controls, you may need to tab into the control and then use the arrow keys to navigate within it.

Use the running starter app to interact with several Oracle JET components.

  1. Press <Ctrl+L> to set focus on the address bar.

  2. Press <Tab> to move focus to the skip nav link.

  3. Press <Tab> to move focus to john.hancock@oracle.com in the user menu, at the top-right of the page.

    According to the <oj-menu-button> element’s keyboard documentation, pressing <Space>, <Enter>, or <down arrow> opens the menu, and pressing <Escape> closes the menu.

  4. Press <Space> to expand the user menu. Focus moves to Preferences.

  5. Press <down arrow> to move down the list of menu items.

  6. Press <Escape> to close the user menu.

  7. Press <Tab>. Focus moves to Introduction in the main nav menu immediately below the user menu.

    For additional information about the specific keystrokes for each Oracle JET component, see the Oracle JET Keyboard and Gesture Guide.

Task 5: Identify a Keyboard Trap

The final topic introduced at the outset of this tutorial involves a concept known as a keyboard trap. A keyboard trap occurs when a user cannot move focus away from an element on the page using <Tab>, <Shift+Tab>, or any of the arrow keys.

A keyboard trap renders the entire page unusable for a keyboard-only user. The common solution for a keyboard trap is to restart the app.

Let’s get practical!

This section of the tutorial gives a detailed example of a keyboard-only testing methodology.

As you test the app’s Organization page, verify that there is always a visible indication of the focus location and that focus moves in a predictable pattern.

The page that you will test is accessed via the Organization tab on the Introduction page.

The Organization Page

Description of the illustration org_page.png

Use the starter app to perform a keyboard test of the Organization page.

  1. In the app’s Resources page, press <Ctrl+L> to set focus on the address bar.

  2. Press <Tab> to move focus to the skip nav link.

  3. Press <Tab> to move focus to john.hancock@oracle.com in the user menu, at the top-right of the page.

  4. Press <Tab> to move focus to Introduction in the main navigation menu below the user name.

    According to the <oj-navigation-list> element’s keyboard documentation, use the <up arrow> and <down arrow> keys to navigate items in the main navigation menu.

  5. Press <Enter> to select Introduction.

  6. Press <Tab> and then <right arrow> to move focus to the Organization tab in the tab bar. Press <Enter> to load the Organization page.

    According to the <oj-tab-bar> element’s keyboard documentation, use arrow keys to move within the tab bar.

  7. Press <Tab> to move focus to the tree view. Focus lands on the first focusable item, the Accounting node.

    According to the <oj-tree-view> element’s keyboard documentation, use the <up arrow> and <down arrow> keys to navigate between nodes in the tree view.

  8. Press <right arrow> to expand the Accounting group node in the tree, and then press <left arrow> to collapse the group node.

  9. Press the <down arrow> twice to move focus to the employee JONES in the RESEARCH group node. Then press <Enter> to select it.

    A form will appear on the right side of the page with employee details.

    Organization Tab with Employee Details Form

    Description of the illustration org_page_form.png

  10. Press <Tab> to move focus to the Employee ID field.

  11. Press <Tab> to move focus to the Employee Name field.

  12. Press <Tab> to move focus to the Job Title field.

  13. Press <Tab> to move focus to the Hire Date field and display an expanded calendar grid.

    According to the <oj-date-picker> element’s keyboard documentation, press the arrow keys to change the date focus within the calendar grid.

  14. Press <down arrow> and then use the arrow keys to move focus to a date in the expanded date picker. Then press <Enter> to select a date.

  15. Press <Tab> to move focus to the Salary field.

    According to the <oj-input-number> element’s keyboard documentation, use <up arrow> to increase the salary value and use <down arrow> to decrease the salary value.

  16. Press <Tab> and attempt to move focus to the Manager ID field.

    Did you notice that once focus moved into the Salary field, pressing <Tab> or <Shift+Tab> did not move focus out of the field? This field has a keyboard trap. Without a fix to the code, the only way to exit the trap is to refresh the page.

Task 6: Remove the Trap

  1. Navigate to the src/js/views folder and open the organization.html file in an editor.

  2. Locate the <oj-input-number> element where id="salary":

       
<oj-input-number id="salary"
   label-hint="Salary"
   value="{{empDetails().sal}}"
   min="0"
   step="1"
   on-blur="[[setKeyTrap]]">
</oj-input-number>

    Remove the on-blur attribute that causes the keyboard trap.

       
<oj-input-number id="salary"
   label-hint="Salary"
   value="{{empDetails().sal}}"
   min="0"
   step="1">
</oj-input-number>

  3. Save the file. Then repeat the steps in the previous Identify a Keyboard Trap task to ensure that the keyboard trap has been removed.

  4. When you reach the Manager Id field, press <Tab> to move focus to the Jobs radio buttons.

    According to the <oj-radioset> element’s keyboard documentation, use <up arrow> to select the previous button in the group. Use the <down arrow> to select the next button in the group.

  5. Press <Tab> to move focus to the About Oracle link in the footer section of the page.

  6. Reverse the process. Press <Shift+Tab> to move back to the Jobs radio buttons. Continue pressing <Shift+Tab> to move back through the page to john.hancock@oracle.com in the user menu.

Remember to consult the Oracle JET Keyboard and Gestures Guide if you have any questions concerning the keystrokes necessary to use or navigate within an Oracle JET component.

The keyboard-only testing phase is complete. Proceed to the final tutorial within this learning path, Perform Screen-Reader Validation on an Oracle JET App.

More Learning Resources

Explore other labs on docs.oracle.com/learn or access more free learning content on the Oracle Learning YouTube channel. Additionally, visit education.oracle.com/learning-explorer to become an Oracle Learning Explorer.

For product documentation, visit Oracle Help Center.