| OLD | NEW |
| (Empty) | |
| 1 [](https://travis-ci.org/GoogleChrome/accessibility-developer
-tools) |
| 2 []
(https://www.npmjs.com/package/accessibility-developer-tools) |
| 3 [](https://www.npmjs.com/package/accessibility-developer-tools) |
| 4 |
| 5 # Accessibility Developer Tools |
| 6 |
| 7 This is a library of accessibility-related testing and utility code. |
| 8 |
| 9 Its main component is the accessibility audit: a collection of audit rules check
ing for common accessibility problems, and an API for running these rules in an
HTML page. |
| 10 |
| 11 There is also a collection of accessibility-related utility code, including but
not limited to: |
| 12 * contrast ratio calculation and color suggestions |
| 13 * retrieving and validating ARIA attributes and states |
| 14 * accessible name calculation using the algorithm at [http://www.w3.org/TR/wai-a
ria/roles#textalternativecomputation](http://www.w3.org/TR/wai-aria/roles#textal
ternativecomputation) |
| 15 |
| 16 # Getting the code |
| 17 |
| 18 To include just the javascript rules, require the following file: |
| 19 |
| 20 https://raw.github.com/GoogleChrome/accessibility-developer-tools/stable/dis
t/js/axs_testing.js |
| 21 |
| 22 `git 1.6.5` or later: |
| 23 |
| 24 % git clone --recursive https://github.com/GoogleChrome/accessibility-develo
per-tools.git |
| 25 |
| 26 Before `git 1.6.5`: |
| 27 |
| 28 % git clone https://github.com/GoogleChrome/accessibility-developer-tools.gi
t |
| 29 % cd accessibility-developer-tools |
| 30 % git submodule init; git submodule update |
| 31 |
| 32 # Building |
| 33 |
| 34 You will need `node` and `grunt-cli` to build. |
| 35 |
| 36 1. (Once only) Install [Node.js](http://nodejs.org/) and `npm` - useful instruct
ions here: [https://gist.github.com/isaacs/579814](https://gist.github.com/isaac
s/579814) |
| 37 |
| 38 Make sure you have Node.js v 0.8 or higher. |
| 39 |
| 40 2. (Once only) Use `npm` to install `grunt-cli` |
| 41 |
| 42 % npm install -g grunt-cli # May need to be run as root |
| 43 |
| 44 3. (Every time you make a fresh checkout) Install dependencies (including `grunt
`) for this project (run from project root) |
| 45 |
| 46 % npm install |
| 47 |
| 48 4. (Rebuild if you make changes) Build using `grunt` (run from project root) |
| 49 |
| 50 % grunt |
| 51 |
| 52 |
| 53 ## Troubleshooting |
| 54 |
| 55 This project uses [Closure Compiler](https://github.com/google/closure-compiler)
to build our releases. You may need to install a recent version of [JDK](http:/
/www.oracle.com/technetwork/java/javase/downloads/index.html) in order for build
s to successfully complete. |
| 56 |
| 57 # Using the Audit API |
| 58 |
| 59 ## Including the library |
| 60 |
| 61 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`: |
| 62 * Distribution Build: project-root/dist/js/axs_testing.js |
| 63 * Local Build (use if you make changes): project-root/tmp/build/axs_testing.js |
| 64 |
| 65 Work is underway to include the library in WebDriver and other automated testing
frameworks. |
| 66 |
| 67 ## The `axs.Audit.run()` method |
| 68 |
| 69 Once you have included `axs_testing.js`, you can call `axs.Audit.run()`. This re
turns an object in the following form: |
| 70 |
| 71 { |
| 72 /** @type {axs.constants.AuditResult} */ |
| 73 result, // one of PASS, FAIL or NA |
| 74 |
| 75 /** @type {Array.<Element>} */ |
| 76 elements, // The elements which the rule fails on, if result == axs.const
ants.AuditResult.FAIL |
| 77 |
| 78 /** @type {axs.AuditRule} */ |
| 79 rule // The rule which this result is for. |
| 80 } |
| 81 |
| 82 ### Command Line Runner |
| 83 |
| 84 The Accessibility Developer Tools project includes a command line runner for the
audit. To use the runner, [install phantomjs](http://phantomjs.org/download.htm
l) then run the following command from the project root directory. |
| 85 |
| 86 $ phantomjs tools/runner/audit.js <url-or-filepath> |
| 87 |
| 88 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. |
| 89 |
| 90 ### Run audit from Selenium WebDriver (Scala): |
| 91 val driver = org.openqa.selenium.firefox.FirefoxDriver //use driver of your
choice |
| 92 val jse = driver.asInstanceOf[JavascriptExecutor] |
| 93 jse.executeScript(scala.io.Source.fromURL("https://raw.githubusercontent.co
m/GoogleChrome/" + |
| 94 "accessibility-developer-tools/stable/dist/js/axs_testing.js").mkString) |
| 95 val report = jse.executeScript("var results = axs.Audit.run();return axs.Au
dit.createReport(results);") |
| 96 println(report) |
| 97 |
| 98 ### Run audit from Selenium WebDriver (Scala)(with caching): |
| 99 val cache = collection.mutable.Map[String, String]() |
| 100 val driver = org.openqa.selenium.firefox.FirefoxDriver //use driver of your
choice |
| 101 val jse = driver.asInstanceOf[JavascriptExecutor] |
| 102 def getUrlSource(arg: String): String = cache get arg match { |
| 103 case Some(result) => result |
| 104 case None => |
| 105 val result: String = scala.io.Source.fromURL(arg).mkString |
| 106 cache(arg) = result |
| 107 result |
| 108 } |
| 109 jse.executeScript(getUrlSource("https://raw.githubusercontent.com/GoogleChr
ome/" + |
| 110 "accessibility-developer-tools/stable/dist/js/axs_testing.js")) |
| 111 val report = js.executeScript("var results = axs.Audit.run();return axs.Aud
it.createReport(results);") |
| 112 println(report) |
| 113 |
| 114 If println() outputs nothing, check if you need to set DesiredCapabilities for y
our WebDriver (such as loggingPrefs): |
| 115 https://code.google.com/p/selenium/wiki/DesiredCapabilities |
| 116 |
| 117 ## Using the results |
| 118 |
| 119 ### Interpreting the result |
| 120 |
| 121 The result may be one of three constants: |
| 122 * `axs.constants.AuditResult.PASS` - This implies that there were elements on th
e page that may potentially have failed this audit rule, but they passed. Congra
tulations! |
| 123 * `axs.constants.AuditResult.NA` - This implies that there were no elements on t
he 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. |
| 124 * `axs.constants.AuditResult.FAIL` - This implies that there were elements on th
e page that did not pass this audit rule. This is the only result you will proba
bly be interested in. |
| 125 |
| 126 ### Creating a useful error message |
| 127 |
| 128 The static, global `axs.Audit.createReport(results, opt_url)` may be used to cre
ate an error message using the return value of axs.Audit.run(). This will look l
ike the following: |
| 129 |
| 130 *** Begin accessibility audit results *** |
| 131 An accessibility audit found 4 errors and 4 warnings on this page. |
| 132 For more information, please see https://github.com/GoogleChrome/accessibili
ty-developer-tools/wiki/Audit-Rules |
| 133 |
| 134 Error: badAriaAttributeValue (AX_ARIA_04) failed on the following elements (
1 - 3 of 3): |
| 135 DIV:nth-of-type(3) > INPUT |
| 136 DIV:nth-of-type(5) > INPUT |
| 137 #aria-invalid |
| 138 |
| 139 Error: badAriaRole (AX_ARIA_01) failed on the following element: |
| 140 DIV:nth-of-type(11) > SPAN |
| 141 |
| 142 Error: controlsWithoutLabel (AX_TEXT_01) failed on the following elements (1
- 3 of 3): |
| 143 DIV > INPUT |
| 144 DIV:nth-of-type(12) > DIV:nth-of-type(3) > INPUT |
| 145 LABEL > INPUT |
| 146 |
| 147 Error: requiredAriaAttributeMissing (AX_ARIA_03) failed on the following ele
ment: |
| 148 DIV:nth-of-type(13) > DIV:nth-of-type(11) > DIV |
| 149 |
| 150 Warning: focusableElementNotVisibleAndNotAriaHidden (AX_FOCUS_01) failed on
the following element: |
| 151 #notariahidden |
| 152 |
| 153 Warning: imagesWithoutAltText (AX_TEXT_02) failed on the following elements
(1 - 2 of 2): |
| 154 #deceptive-img |
| 155 DIV:nth-of-type(13) > IMG |
| 156 |
| 157 Warning: lowContrastElements (AX_COLOR_01) failed on the following elements
(1 - 2 of 2): |
| 158 DIV:nth-of-type(13) > DIV |
| 159 DIV:nth-of-type(13) > DIV:nth-of-type(3) |
| 160 |
| 161 Warning: nonExistentAriaLabelledbyElement (AX_ARIA_02) failed on the followi
ng elements (1 - 2 of 2): |
| 162 DIV:nth-of-type(3) > INPUT |
| 163 DIV:nth-of-type(5) > INPUT |
| 164 *** End accessibility audit results *** |
| 165 |
| 166 Each rule will have at most five elements listed as failures, in the form of a u
nique query selector for each element. |
| 167 |
| 168 ### Configuring the Audit |
| 169 |
| 170 If you wish to fine-tune the audit, you can create an `axs.AuditConfiguration` o
bject, with the following options: |
| 171 |
| 172 #### Ignore parts of the page for a particular audit rule |
| 173 |
| 174 For example, say you have a separate high-contrast version of your page, and the
re 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 |
| 175 |
| 176 Warning: lowContrastElements (AX_COLOR_01) failed on the following elements
(1 - 5 of 15): |
| 177 ... |
| 178 |
| 179 You can modify the audit to ignore the elements which are known and intended to
have low contrast like this: |
| 180 |
| 181 var configuration = new axs.AuditConfiguration(); |
| 182 configuration.ignoreSelectors('lowContrastElements', '.pretty'); |
| 183 axs.Audit.run(configuration); |
| 184 |
| 185 The `AuditConfiguration.ignoreSelectors()` method takes a rule name, which you c
an 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 `ignoreSelector
s()` can be made for each audit rule, if multiple selectors need to be ignored. |
| 186 |
| 187 #### Restrict the scope of the entire audit to a subsection of the page |
| 188 |
| 189 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 does
n't vary, which may drown out regressions in the main part of the page. |
| 190 |
| 191 You can set a `scope` on the `AuditConfiguration` object like this: |
| 192 |
| 193 var configuration = new axs.AuditConfiguration(); |
| 194 configuration.scope = document.querySelector('main'); // or however you wis
h to choose your scope element |
| 195 axs.Audit.run(configuration); |
| 196 |
| 197 You may also specify a configuration payload while instantiating the `axs.AuditC
onfiguration`, |
| 198 which allows you to provide multiple configuration options at once. |
| 199 |
| 200 var configuration = new axs.AuditConfiguration({ |
| 201 auditRulesToRun: ['badAriaRole'], |
| 202 scope: document.querySelector('main'), |
| 203 maxResults: 5 |
| 204 }); |
| 205 |
| 206 axs.Audit.run(configuration); |
| 207 |
| 208 ## License |
| 209 |
| 210 Copyright 2013 Google Inc. All Rights Reserved. |
| 211 |
| 212 Licensed under the Apache License, Version 2.0 (the "License"); |
| 213 you may not use this file except in compliance with the License. |
| 214 You may obtain a copy of the License at |
| 215 |
| 216 [http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICE
NSE-2.0) |
| 217 |
| 218 Unless required by applicable law or agreed to in writing, software |
| 219 distributed under the License is distributed on an "AS IS" BASIS, |
| 220 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 221 See the License for the specific language governing permissions and |
| 222 limitations under the License. |
| OLD | NEW |