Introduction

Axe Tools is a TypeScript library that allows AIS applications to add user-driven accessibility testing. The accessibility scans are powered by Dequeue's Axe library. Results are collected in a central repository, and the results are aggregated in a shared Campus Data report.

User-driven testing allows us to "automate" scans on dynamic, data-driven pages behind a HawkID login. These pages are typically hard to expose to automated tools. Additionally, it is hard to ensure all application states are covered with manual testing. By collecting results during user sessions, we can ensure we are covering real-world usage.

axe-tools integrates with all types of web applications.

Install

Axe Tools can be consumed as a Universal module (UMD) or an ES module. Both options offer full functionality, so choose the method that works best with your application.

HTML

<script src="https://tools.ais.its.uiowa.edu/axe-tools/axe-tools.umd.js"></script>

NPM Module

$ yarn add @ais-public/axe-tools

AxeReporter

The AxeReporter class is the core of Axe Tools. It uses the axe-core library to run scans. For the most part clients do not need to understand the details of AxeReporter. However, developers should familiarize themselves with the AxeToolsOptions interface. These options provide an application's basic configuration to AxeReporter.

AxeToolsOptions

import { AxeReporter, Environment } from "./AxeReporter.js";
import {Router} from "vue-router";
import axe from "axe-core";

export interface AxeToolsOptions {
  /**
   * The name of the team responsible for the app.
   * Consider using the GitLab group if not 'java'.
   */
  teamName: string,

  /**
   * The name of the app being scanned.
   * Use the application's GitLab repo name.
   */
  appName: string,

  /**
   * Flag to enable logging results to the browser console.
   */
  logReport: boolean,

  /**
   * The fully-qualified base URL of the app being scanned (optional).
   * Required if the app is not hosted at the root of a domain.
   * Example value: https://apps.its.uiowa.edu/dispatch
   */
  baseUrl?: string,

  /**
   * Time, in milliseconds, to wait before scanning the page
   * for issues (optional).Default is 5000ms.
   */
  timeout?: number,

  /**
   * Environment that determines where results are sent (optional).
   * DEV | TEST | PROD
   */
  env?: Environment,

  /**
   * Vue router instance (optional). Used to set the scanner's
   * URL property to the parameterized route to make sure
   * results for a page are collected under a single path.
   */
  router?: Router

  /**
   * targetElement specifies a DOM element to serve as the root of the axe scan.
   * If not provided, axe will scan the entire document. At times it may be
   * necessary to limit the scan to the root of your application's markup to avoid
   * accessibility errors cause by external tools like browser plugins.
   *
   * Must be a valid CSS selector string (e.g., '#app' or '.main-content').
   */
  targetElement?: string

  /**
   * Maximum number of DOM nodes to scan. If the page contains more nodes
   * than this limit, the scan will be aborted. This can help prevent
   * performance issues on very large pages.
   *
   * Default is 6000 nodes.
   */
  domSizeLimit?: number,

  /**
   * Options to pass to axe.run()
   * @see [documentation from axe-core](https://github.com/dequelabs/axe-core/blob/develop/doc/API.md#options-parameter)
   */
  runOptions?: axe.RunOptions,

  /**
   * Callback function that is invoked after each scan is completed.
   * @param results - The results of the axe scan.
   * @param axeReporter - The AxeReporter instance used to perform the scan.
   */
  scanCallback?: (results: axe.AxeResults, axeReporter: AxeReporter) => void
}

// export default AxeToolsOptions;

Environment

The execution environment is a key piece of configuration. Axe Tools provides the Env type with the valid values of DEV | TEST | PROD, and the utility function resolveEnvironment(), which can be called with no parameters or with the string parameter productionURL.

The following heuristic is used to determine the environment:

• If the current host is localhost, then DEV
• If productionURL is not provided and the host contains test. then TEST else PROD
• If the productionURL is included in the current URL, then PROD else TEST

The test. inspection should match application URLs like https://test.its.uiowa.edu/dispatch and http://data-test.uiowa.edu.

Parameterized Routes

Results are collected by "page" or "route". However, most of our pages are data-driven and each parameterized route has many instantiations. For example, if we have an "Item page" with the route /items/{id}, the app will produce many URLs like /items/1, /items/2, etc. In our report, we want all errors to aggregate under the path /items/{id}.

Our example configurations reference handling "parameterized routes". This is the issue they are referencing. AxeToolsPlugin will automatically handle parameterized routes for Vue 3 applications. Other applications may need to pass route information into their Axe Tools configuration.