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 {Environment} from "./AxeReporter.js";
import {Router} from "vue-router";

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 base URL of the app being scanned (optional).
   */
  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
}

// 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.