• This repository has been archived on 07/Dec/2022
  • Stars
    star
    2,280
  • Rank 20,199 (Top 0.4 %)
  • Language
    JavaScript
  • License
    Apache License 2.0
  • Created over 11 years ago
  • Updated about 2 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

This is a library of accessibility-related testing and utility code.

Build Status npm version npm downloads

Accessibility Developer Tools

This is a library of accessibility-related testing and utility code.

Its main component is the accessibility audit: a collection of audit rules checking for common accessibility problems, and an API for running these rules in an HTML page.

There is also a collection of accessibility-related utility code, including but not limited to:

Getting the code

To include just the javascript rules, require the following file:

https://raw.github.com/GoogleChrome/accessibility-developer-tools/stable/dist/js/axs_testing.js

git 1.6.5 or later:

% git clone --recursive https://github.com/GoogleChrome/accessibility-developer-tools.git

Before git 1.6.5:

% git clone https://github.com/GoogleChrome/accessibility-developer-tools.git
% cd accessibility-developer-tools
% git submodule init; git submodule update

Building

You will need node and grunt-cli to build.

  1. (Once only) Install Node.js and npm - useful instructions here: https://gist.github.com/isaacs/579814

    Make sure you have Node.js v 0.8 or higher.

  2. (Once only) Use npm to install grunt-cli

     % npm install -g grunt-cli  # May need to be run as root
    
  3. (Every time you make a fresh checkout) Install dependencies (including grunt) for this project (run from project root)

     % npm install
    
  4. (Rebuild if you make changes) Build using grunt (run from project root)

     % grunt
    

Troubleshooting

This project uses Closure Compiler to build our releases. You may need to install a recent version of JDK in order for builds to successfully complete.

Using the Audit API

Including the library

The simplest option is to include the generated axs_testing.js library on your page. After you build, you will have two versions of axs_testings.js:

  • Distribution Build: project-root/dist/js/axs_testing.js
  • Local Build (use if you make changes): project-root/tmp/build/axs_testing.js

Work is underway to include the library in WebDriver and other automated testing frameworks.

The axs.Audit.run() method

Once you have included axs_testing.js, you can call axs.Audit.run(). This returns an object in the following form:

{
  /** @type {axs.constants.AuditResult} */
  result,  // one of PASS, FAIL or NA

  /** @type {Array.<Element>} */
  elements,  // The elements which the rule fails on, if result == axs.constants.AuditResult.FAIL

  /** @type {axs.AuditRule} */
  rule  // The rule which this result is for.
}

Command Line Runner

The Accessibility Developer Tools project includes a command line runner for the audit. To use the runner, install phantomjs then run the following command from the project root directory.

$ phantomjs tools/runner/audit.js <url-or-filepath>

The runner will load the specified file or URL in a headless browser, inject axs_testing.js, run the audit and output the report text.

Run audit from Selenium WebDriver (Scala):

 val driver = org.openqa.selenium.firefox.FirefoxDriver //use driver of your choice
 val jse = driver.asInstanceOf[JavascriptExecutor]
 jse.executeScript(scala.io.Source.fromURL("https://raw.githubusercontent.com/GoogleChrome/" +
   "accessibility-developer-tools/stable/dist/js/axs_testing.js").mkString)
 val report = jse.executeScript("var results = axs.Audit.run();return axs.Audit.createReport(results);")
 println(report)

Run audit from Selenium WebDriver (Scala)(with caching):

 val cache = collection.mutable.Map[String, String]()
 val driver = org.openqa.selenium.firefox.FirefoxDriver //use driver of your choice
 val jse = driver.asInstanceOf[JavascriptExecutor]
 def getUrlSource(arg: String): String = cache get arg match {
    case Some(result) => result
    case None =>
      val result: String = scala.io.Source.fromURL(arg).mkString
      cache(arg) = result
      result
  }
 jse.executeScript(getUrlSource("https://raw.githubusercontent.com/GoogleChrome/" +
   "accessibility-developer-tools/stable/dist/js/axs_testing.js"))
 val report = js.executeScript("var results = axs.Audit.run();return axs.Audit.createReport(results);")
 println(report)

If println() outputs nothing, check if you need to set DesiredCapabilities for your WebDriver (such as loggingPrefs): https://code.google.com/p/selenium/wiki/DesiredCapabilities

Using the results

Interpreting the result

The result may be one of three constants:

  • axs.constants.AuditResult.PASS - This implies that there were elements on the page that may potentially have failed this audit rule, but they passed. Congratulations!
  • axs.constants.AuditResult.NA - This implies that there were no elements on the page that may potentially have failed this audit rule. For example, an audit rule that checks video elements for subtitles would return this result if there were no video elements on the page.
  • axs.constants.AuditResult.FAIL - This implies that there were elements on the page that did not pass this audit rule. This is the only result you will probably be interested in.

Creating a useful error message

The static, global axs.Audit.createReport(results, opt_url) may be used to create an error message using the return value of axs.Audit.run(). This will look like the following:

*** Begin accessibility audit results ***
An accessibility audit found 4 errors and 4 warnings on this page.
For more information, please see https://github.com/GoogleChrome/accessibility-developer-tools/wiki/Audit-Rules

Error: badAriaAttributeValue (AX_ARIA_04) failed on the following elements (1 - 3 of 3):
DIV:nth-of-type(3) > INPUT
DIV:nth-of-type(5) > INPUT
#aria-invalid

Error: badAriaRole (AX_ARIA_01) failed on the following element:
DIV:nth-of-type(11) > SPAN

Error: controlsWithoutLabel (AX_TEXT_01) failed on the following elements (1 - 3 of 3):
DIV > INPUT
DIV:nth-of-type(12) > DIV:nth-of-type(3) > INPUT
LABEL > INPUT

Error: requiredAriaAttributeMissing (AX_ARIA_03) failed on the following element:
DIV:nth-of-type(13) > DIV:nth-of-type(11) > DIV

Warning: focusableElementNotVisibleAndNotAriaHidden (AX_FOCUS_01) failed on the following element:
#notariahidden

Warning: imagesWithoutAltText (AX_TEXT_02) failed on the following elements (1 - 2 of 2):
#deceptive-img
DIV:nth-of-type(13) > IMG

Warning: lowContrastElements (AX_COLOR_01) failed on the following elements (1 - 2 of 2):
DIV:nth-of-type(13) > DIV
DIV:nth-of-type(13) > DIV:nth-of-type(3)

Warning: nonExistentAriaLabelledbyElement (AX_ARIA_02) failed on the following elements (1 - 2 of 2):
DIV:nth-of-type(3) > INPUT
DIV:nth-of-type(5) > INPUT
*** End accessibility audit results ***

Each rule will have at most five elements listed as failures, in the form of a unique query selector for each element.

Configuring the Audit

If you wish to fine-tune the audit, you can create an axs.AuditConfiguration object, with the following options:

Ignore parts of the page for a particular audit rule

For example, say you have a separate high-contrast version of your page, and there is a CSS rule which causes certain elements (with class pretty) on the page to be low-contrast for stylistic reasons. Running the audit unmodified produces results something like

Warning: lowContrastElements (AX_COLOR_01) failed on the following elements (1 - 5 of 15):
...

You can modify the audit to ignore the elements which are known and intended to have low contrast like this:

var configuration = new axs.AuditConfiguration();
configuration.ignoreSelectors('lowContrastElements', '.pretty');
axs.Audit.run(configuration);

The AuditConfiguration.ignoreSelectors() method takes a rule name, which you can find in the audit report, and a query selector string representing the parts of the page to be ignored for that audit rule. Multiple calls to ignoreSelectors() can be made for each audit rule, if multiple selectors need to be ignored.

Restrict the scope of the entire audit to a subsection of the page

You may have a part of the page which varies while other parts of the page stay constant, like a content area vs. a toolbar. In this case, running the audit on the entire page may give you spurious results in the part of the page which doesn't vary, which may drown out regressions in the main part of the page.

You can set a scope on the AuditConfiguration object like this:

var configuration = new axs.AuditConfiguration();
configuration.scope = document.querySelector('main');  // or however you wish to choose your scope element
axs.Audit.run(configuration);

You may also specify a configuration payload while instantiating the axs.AuditConfiguration, which allows you to provide multiple configuration options at once.

var configuration = new axs.AuditConfiguration({
  auditRulesToRun: ['badAriaRole'],
  scope: document.querySelector('main'),
  maxResults: 5
});

axs.Audit.run(configuration);

License

Copyright 2013 Google Inc. All Rights Reserved.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

More Repositories

1

lighthouse

Automated auditing, performance metrics, and best practices for the web.
JavaScript
28,269
star
2

chrome-extensions-samples

Chrome Extensions Samples
JavaScript
14,888
star
3

workbox

📦 Workbox: JavaScript libraries for Progressive Web Apps
JavaScript
12,346
star
4

web-vitals

Essential metrics for a healthy site.
JavaScript
7,571
star
5

lighthouse-ci

Automate running Lighthouse for every commit, viewing the changes, and preventing regressions
JavaScript
6,377
star
6

rendertron

A Headless Chrome rendering solution
TypeScript
5,936
star
7

samples

A repo containing samples tied to new functionality in each release of Google Chrome.
HTML
5,769
star
8

web.dev

The frontend, backend, and content source code for web.dev
Nunjucks
3,563
star
9

dialog-polyfill

Polyfill for the HTML dialog element
JavaScript
2,443
star
10

web-vitals-extension

A Chrome extension to measure essential metrics for a healthy site
CSS
2,360
star
11

developer.chrome.com

The frontend, backend, and content source code for developer.chrome.com
HTML
1,665
star
12

custom-tabs-client

Chrome custom tabs examples
Java
1,399
star
13

chrome-launcher

Launch Google Chrome with ease from node.
TypeScript
1,232
star
14

proxy-polyfill

Proxy object polyfill
JavaScript
1,134
star
15

omnitone

Spatial Audio Rendering on the web.
JavaScript
851
star
16

android-browser-helper

The Android Browser Helper library helps developers use Custom Tabs and Trusted Web Activities on top of the AndroidX browser support library.
Java
693
star
17

devtools-docs

The legacy documentation for Chrome DevTools.
HTML
691
star
18

chromium-dashboard

Chrome Status Dashboard
Python
637
star
19

OriginTrials

Enabling safe experimentation with web APIs
Bikeshed
519
star
20

related-website-sets

Python
395
star
21

audion

Audion is a Chrome extension that adds a Web Audio panel to Developer Tools. This panel visualizes the web audio graph in real-time.
TypeScript
368
star
22

chrome-app-codelab

The goal of this tutorial is to get you building Chrome apps fast. Once you've completed the tutorial, you will have a simple Todo app. We've done our best to capture some of the trickier parts to the development process keeping the sample simple and straightforward.
JavaScript
213
star
23

CrUX

The place to share queries, ideas, or issues related to the Chrome UX Report
Jupyter Notebook
206
star
24

lighthouse-stack-packs

Lighthouse Stack Packs
JavaScript
204
star
25

inert-polyfill

Polyfill for the HTML inert attribute
JavaScript
188
star
26

chrome-types

Code to parse Chrome's internal extension type definitions—published on NPM as chrome-types
JavaScript
184
star
27

ip-protection

171
star
28

devtools-samples

Samples for demonstrating DevTools features.
HTML
152
star
29

CertificateTransparency

HTML
148
star
30

browser-bug-search

Search across all major browser vendor issue trackers
JavaScript
114
star
31

multi-device

Chrome multi-device (mobile) docs
HTML
103
star
32

kino

A sample offline streaming video PWA built for web.dev/media
JavaScript
102
star
33

webstatus.dev

A tool to monitor and track the status of all Web Platform features across dimensions that are related to availability and implementation quality across browsers, and adoption by web developers.
Go
97
star
34

webstore-docs

Developer docs for Chrome Web Store:
HTML
65
star
35

jank-busters

Resources for jank busting on the web.
JavaScript
64
star
36

webdev-infra

JavaScript
40
star
37

private-tokens

39
star
38

budget.json

38
star
39

.github

11
star
40

.allstar

7
star
41

CertificateTransparency-todelete

HTML
7
star
42

baseline-status

JavaScript
4
star
43

lighthouse-plugin-example

JavaScript
1
star