Test an Oracle JET App for Accessibility: Visual Inspection

Introduction

The Web Content Accessibility Guidelines (WCAG) 2.1 contains a set of more than sixty success criteria for creating an accessible web app. In this learning path, we will focus on a subset of these criteria that focuses primarily on:

This tutorial focuses on where testing an app starts: the visual inspection. This tutorial and the two that follow it, Test an Oracle JET App for Keyboard-Only Accessibility and Perform Screen-Reader Validation on an Oracle JET App, will walk you through the necessary testing steps. You must complete these three testing tutorials in order before continuing the learning path.

The first step in evaluating a web app for accessibility is to perform a visual review of the app. During the review, look for the following items:

Objectives

In this tutorial, you will learn how to perform a manual accessibility test of a web app, as well as learn how the Oracle JavaScript Audit framework can aid in finding accessibility issues.

Prerequisites

Task 1: Prepare the Starter App

We are using an Oracle JET 13.0 Nav Drawer starter app in this learning path.

  1. In the location in your file system where you want the app to reside, extract the downloaded ACCLearningPath.zip into an ACCLearningPath folder.

  2. Open a terminal window and verify that the latest version of the Oracle JET command-line interface (CLI) is installed (release 13.0 or later is required).

    $ ojet --version

    If the latest version of the Oracle JET CLI displays, then the installation is correct. If not, please reinstall by using the npm install command for your platform.

    • For Windows:

      $ npm install -g @oracle/ojet-cli

    • For Mac and Linux systems:

      $ sudo npm install -g @oracle/ojet-cli

      After the installation is completed, the Oracle JET CLI shows a summary of all changes.

  3. Navigate to the ACCLearningPath directory and restore the Oracle JET app tooling.

    $ ojet restore

  4. Run the app.

    $ ojet serve

    The Oracle JET tooling runs your app in a local web browser. The browser opens to the app’s Introduction page, with the Overview tab loaded. The app is ready to use.

    Leave the terminal window and the browser open so that your app automatically updates with any changes you make.

Task 2: Audit the App

The Oracle JET Audit Framework (JAF) is a command-line utility and supporting API that is designed to audit the files of an Oracle JET app, based on runtime options it finds in a configuration file. The diagnostic messages returned by an app’s audit derive from built-in rule sets that are specific to the JET release version of the app. However, the audit framework is extensible, and users may extend its capabilities by writing custom rules.

Oracle JAF audits can help identify accessibity and other issues in your apps, though they will not find all the accessibility issues that we will address in the ACCLearningPath app. That is why, in addition to auditing the app, you should follow the procedure and steps outlined in this Identify Accessibility Issues learning path for finding and addressing accessibility issues. A JAF audit should be run at the outset of making the sample app accessible, in order to identify potential issues in your app before beginning your work. For more information on Oracle JAF, see Using and Extending the Oracle JET Audit Framework.

Download and use Oracle JAF in CLI mode to check for accessibility issues.

  1. Use npm to install the Oracle JAF CLI.

    Open a terminal window and check for installed versions of Oracle JAF.

    $ ojaf -v

    If not installed or if your version of JAF is not the current release, uninstall older versions and install the most current version.

    $ npm uninstall -g @oracle/oraclejet-audit

    $ npm install -g @oracle/oraclejet-audit

  2. Navigate to the ACCLearningPath directory of your app and use the --init command-line flag to initialize a default JAF configuration.

    $ ojaf --init

    The tooling scaffolds the default JAF configuration file oraclejafconfig.json in the ACCLearningPath directory and defines the default configuration settings based on the JET app configuration file oraclejetconfig.json, also located in the app’s root directory.

  3. Open oraclejafconfig.json in your editor and ensure that the value of the jetVer property is correct for the version of JET you want to audit against (for example, 13.0, 13.1, and so on).

    "builtinJetRules": true,
   "jetVer": "13.0",

    You may customize your app audit by adding or amending JAF properties in the oraclejafconfig.json file. A full description of the configuration options is found in About the Oracle JAF Configuration File Properties.

  4. Before you audit the app for the first time, you can confirm the default configuration for the files that JAF will audit by using the --dryrun command-line flag.

    $ ojaf --dryrun

    A dry run does not audit the app but confirms the files to be audited based on current JAF configuration settings.

    Note: You can obtain a complete list of command-line flags by entering the ojaf --help command.

  5. Perform an audit of your app by entering the command to invoke the JAF audit utility.

    $ ojaf

  6. When you run the audit, Oracle JAF searches the directory for oraclejafconfig.json and creates an audit report.

    The report will list the rule-breaking issues found in the app, as well as their locations in the app files. Additionally, the report includes a summary of the issues found and their severities, the rules audited, and the files audited.

    JAF Audit Report

    Description of the illustration jaf-report.png

    In the audit report’s list of issues, note the severity-level blocker issue found in the departments.html file: 'aria-label' or 'aria-labelledby' missing on <oj-film-strip>.

    An aria-label property is missing from the film-strip component in the app, which can prevent a screen reader from accessing the identity of the component. This is one of the accessibility issues that we will address in later tutorials.

This is the end of the discussion of Oracle JAF in this learning path. When you are finished auditing your app, remember to delete the folder jaftmp@ and the file oraclejafconfig.json from the ACCLearningPath directory.

Task 3: Review the Page Structure

Page structure is the logical starting point for the visual inspection of an app. HTML headings provide an outline of the page content without focusing on specifics. Screen readers provide shortcuts to allow users to quickly move between properly marked-up headings.

Use the ACCLearningPath app to review the page structure.

  1. In the running app, determine whether the sections of the pages are identified by headings.

    The text of headings is larger or styled differently than regular text on the page. Create true HTML headings by using <h1> through <h6> tags.

  2. Determine whether the text of each heading adequately describes the content associated with it.

    Examine the Overview tab of the Introduction page. The third, rightmost panel has the heading Text Spacing. The content of this panel concerns adjusting text spacing. Therefore this heading is an example of an adequately descriptive heading.

  3. Use the Chrome DevTools Elements tab to determine whether the headings are true HTML headings or text designed to resemble them.

    • Right-click on the heading The Introduction Page and select Inspect from the context menu to view the Document Object Model (DOM) structure of the page.

      The highlighted element in the DOM tree, displayed in the DevTools Elements pane, employs the correct method of creating an HTML heading.

      <h4>The Introduction Page</h4>

    • Close the DevTools, and then right-click on the heading The Resources Page and select Inspect from the context menu.

      The highlighted element in this DOM tree is text styled to look like an HTML heading.

      <span class="h4Style">The Resources Page</span>

      A screen reader will not detect this code as a heading. Screen-reader users often navigate a page by headings, and text styled to resemble headings is ignored. In the following steps, you will fix the incorrectly coded heading. Leave your app running and browser open to observe how the following changes affect the app.

  4. Navigate to the ACCLearningPath/src/js/views folder and open overview.html in your code editor.

  5. Locate the <span class="h4Style"> tag.

  6. Replace the <span class="h4Style"> tag with an <h4> tag.

  7. Replace the </span> tag with an </h4> tag.

  8. Save the file and view the changes to your app in the browser.

Task 4: Review the Page Title

A visual inspection of the app includes an assessment of the effectiveness of the page title.

Navigate through the running starter app and look at each page title.

  1. Determine whether the page title clearly identifies the page, the tab, and the app name.

  2. Determine whether the page title changes as you navigate between pages or among the tabs on the Introduction page.

    The page title should change for each new page or tab that is displayed. For example, when Introduction is selected in the main menu at the top right of the page, the title needs to read “Introduction”, and when Resources is selected, the title should read “Resources”.

    The title of the Introduction page should include both the word “Introduction” and the name of the currently selected tab. When you select a different tab from the tab bar, the title should change to reflect the newly selected tab.

    • Introduction - Overview
    • Introduction - Organization
    • Introduction - Employees
    • Introduction - Departments

    Likewise the Resources page title should include the word “Resources”.

    You will notice that the page title does not change when you navigate between pages or tabs. This problem will be remedied in a later tutorial.

When there is repeated content such as navigation links and logos in the page header of a web app, include a skip nav link. Industry standards suggest that the skip nav link should be hidden from view until it is accessed by tabbing.

Test for the existence of the skip nav link in the app running in the browser.

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

  2. Press <Tab> to make the skip nav link to appear and receive focus.

    Because no skip nav link appears, focus goes to the first focusable element on the page: john.hancock@oracle.com in the user menu at the top-right of the page. Focusable elements are defined in more detail in the Keyboard-Only Accessibility tutorial.

    You have determined during the test that the starter app has no skip nav link implemented.

    There are three steps to adding the skip nav link:

    1. Add the link to the index.html file.
    2. Add a style class to the app.css file to hide the skip nav link until tabbing to it.
    3. Add the target anchors to the intro.html and resources.html files.

Update the index.html File

The index.html file defines the overarching structure of the Oracle JET web app. The skip nav link needs to be placed in this page.

  1. Navigate to the ACCLearningPath/src directory and open index.html in a code editor.

  2. Locate the <body> tag.

    <body class="oj-web-applayout-body">
   <!-- Template for rendering navigation items shared between nav bar and nav list -->

  3. Insert a link with its target as #main between the <body> tag and the comment that follows it.

    <body class="oj-web-applayout-body">
   <a class="hideSkipNav" href="#main">Skip to main content</a>
   <!-- Template for rendering navigation items shared between nav bar and nav list -->

    The hideSkipNav class will cause the link to be invisible until the user starts at the top of the page and presses <Tab>.

  4. Save and close index.html. Your file should look similar to index-html.txt.

Update the app.css File

We have referenced the hideSkipNav style class in the index.html file. Now we need to define it in app.css. All custom style definitions are located in this file.

  1. Navigate to the ACCLearningPath/src/css folder and edit app.css.

  2. Add the .hideSkipNav style class and properties to the end of the file.

    .hideSkipNav { 
   position: absolute;
   left: -1000px; }

.hideSkipNav:focus {
   position: unset;
   left: 0px; }

  3. Save and close app.css. Your file should look similar to app-css.txt.

Update the Pages’ HTML Files

Since the target of the skip nav link should be at the top of the main content of each page, add the target anchor tags to both the Introduction and the Resource pages.

  1. Navigate to the ACCLearningPath/src/js/views folder and edit the intro.html file.

  2. Locate the <div> with the oj-hybrid-padding class.

    <div class="oj-hybrid-padding">
   <div id="mainContainer">

  3. Insert the anchor tag and h2 heading between the two <div> tags.

    <div class="oj-hybrid-padding">
<a id="main">
   <h2>Introduction</h2>
</a>
   <div id="mainContainer">

    The added code provides not only the skip nav link’s target but also an h2 heading to improve page structure.

  4. Save and close intro.html. Your file should look similar to intro-html.txt.

  5. Open resources.html in your code editor and locate the <div> with the oj-hybrid-padding class.

    <div class="oj-hybrid-padding">
   <ul>

  6. Insert the anchor tag and h2 heading between the <div> and <ul> tags.

    <div class="oj-hybrid-padding">
<a id="main">
   <h2>Resources</h2>
</a>
   <ul>

  7. Save and close resources.html. Your file should look similar to resources-html.txt.

  8. In the running app, press <Ctrl+L> to move focus to the address bar.

  9. Press <Tab> to cause the skip nav link to appear and receive focus.

  10. Press <Enter> to activate the skip nav link.

    The focus then moves to the main content of the page.

    Once you have tested the functionality of the skip nav link, move to the next element of the visual inspection.

Task 6: Check for the Use of Color and Position

Buttons are an integral part of directions that move a user from one page or action to the next. Developers enhance the look and functionality of a page with the use of colored buttons. “Press the green button to continue” is a common instruction. Yet without proper labeling, visually impaired users cannot follow these and similar instructions.

The center panel of the Overview page contains a toolbar with three colored buttons, as well as a couple of instructions to press buttons based on their color and position. A blind or color-blind user is unable to distinguish between the buttons because they have no labels or other distinguishing features. This set of buttons fails Success Criteria 1.3.3 and 1.4.1.

Use of Color Instructions

Description of the illustration color_buttons.png

Each of the colored buttons in the center panel must have a text label associated with it. The following changes will add color names as labels to the buttons.

  1. Navigate to the ACCLearningPath/src/js/views folder and edit the overview.html file.

  2. Locate the set of three oj-button elements.

    <oj-button id="chat"
   class="demo-button-green button-set-width"
   chroming="solid"
   on-oj-action="[[greenActivated]]">
</oj-button>
<oj-button id="paint"
   class="demo-button-red button-set-width"
   chroming="solid"
   on-oj-action="[[redActivated]]">
</oj-button>
<oj-button id="bookmark"
   class="demo-button-purple button-set-width"
   chroming="solid"
   on-oj-action="[[purpleActivated]]">
</oj-button>

  3. Modify the buttons in the code to create the color identifiers.

    <oj-button id="chat"
   class="demo-button-green button-set-width"
   chroming="solid"
   on-oj-action="[[greenActivated]]">Green
</oj-button>
<oj-button id="paint"
   class="demo-button-red button-set-width"
   chroming="solid"
   on-oj-action="[[redActivated]]">Red
</oj-button>
<oj-button id="bookmark"
   class="demo-button-purple button-set-width"
   chroming="solid"
   on-oj-action="[[purpleActivated]]">Purple
</oj-button>

  4. Save overview.html and verify that the buttons now have appropriate text labels.

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

Task 7: Verify Readability

The final phase of the visual inspection is specific to low-vision users. Determine whether adjusting the line, word, and character spacing or changing the zoom level of the page increases or decreases readability.

We will use the Overview page to illustrate these criteria and verify text spacing and zoom in the app.

Verify text spacing and zoom

Description of the illustration text_spacing.png

  1. In the running app, examine the rightmost panel of the page, titled Text Spacing. The panel contains two sections. Compare the text in both sections to ensure that all text is present.

    The top portion of the panel has text with normal spacing. The bottom portion contains the same text with increased character, word, and line spacing.

    If none of the characters in the lower section are distorted, clipped, or overlap, then the page meets Success Criterion 1.4.12.

  2. Increase the zoom level of the browser to 200%. Click the magnifying-glass zoom icon in the toolbar, then click the + sign to increase the zoom.

    If all text is readable and the text wraps correctly inside of each panel, then the page meets Success Criterion 1.4.4 at 200% magnification.

    • Success Criterion 1.4.10 Reflow states: “Content can be presented without loss of information or functionality, and without requiring scrolling in two dimensions for:
      • Vertical scrolling content at a width equivalent to 320 CSS pixels;
      • Horizontal scrolling content at a height equivalent to 256 CSS pixels. Except for parts of the content which require two-dimensional layout for usage or meaning.”

    The page should reformat to require scrolling in only one direction. A page is scrolled either horizontally or vertically but not in both directions. Success Criterion 1.4.10 makes pages easier to use.

  3. Increase the zoom to 400%.

  4. Examine the page for the appearance of scroll bars. If both horizontal and vertical scroll bars appear, the page fails this criterion.

The initial testing phase is complete. The next tutorial within this learning path is Test an Oracle JET App for Keyboard-Only Accessibility.

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.