Modern web accessibility audits. 💪
- Accessibility as a service
- Audit your websites with a range of test suites including WCAG 2.0/2.1 A, AA, AAA, Section 508, HTML validation, as well as our own best practices.
- Flexible and automated
- Run manual tests during development and then integrate into any CI pipeline. Supports generating reports in XLS, XLSX, CSV, JSON, HTML, and more.
- Runs in any environment
- Easy integration that supports localhost, firewalls, custom auth, as well as any public production environment.
- Modern dynamic websites
- Ta11y treats all websites as dynamic with full JavaScript support, so you'll test pages as your users actually experience them.
- Free to try
- Simple to get started for free, then sign up once you're ready to remove rate limits. Have a non-profit use case? Get in touch.
- Private & secure
- Ta11y is built using serverless functions and never stores any of your data or audit results.
This project is broken down into the following packages:
- @ta11y/ta11y - Main CLI for running web accessibility audits with ta11y.
- @ta11y/core - Core library for programatically running web accessibility audits with ta11y.
- @ta11y/extract - Library to crawl and extract content from websites.
- @ta11y/reporter - Library to convert audit results to different formats.
The easiest way to get started is via the CLI.
npm install -g @ta11y/ta11yUsage: ta11y [options] <url>
Options:
-V, --version output the version number
-o, --output <file> Output the results to the given file (format determined by file
type). Supports xls, xlsx, csv, json, html, txt, etc.
-r, --remote Run all content extraction remotely (website must be publicly
accessible). Default is to run content extraction locally.
(default: false)
-e, --extract-only Only run content extraction and disable auditing. (default: false)
-s, --suites <strings> Optional comma-separated array of test suites to run. (section508,
wcag2a, wcag2aa, wcag2aaa, best-practice, html). Defaults to
running all audit suites.
-c, --crawl Enable crawling additional pages. (default: false)
-d, --max-depth <int> Maximum crawl depth. (default: 16)
-v, --max-visit <int> Maximum number of pages to visit while crawling.
-S, --no-same-origin By default, we only crawling links with the same origin as the
root. Disables this behavior so we crawl links with any origin.
-b, --blacklist <strings> Optional comma-separated array of URL glob patterns to ignore.
-w, --whitelist <strings> Optional comma-separated array of URL glob patterns to include.
-u, --user-agent <string> Optional user-agent override.
-e, --emulate-device <string> Optionally emulate a specific device type.
-H, --no-headless Disables headless mode for puppeteer. Useful for debugging.
-P, --no-progress Disables progress logging.
--api-key <string> Optional API key.
--api-base-url <string> Optional API base URL.
-h, --help output usage informationThe CLI defaults to running all crawling and content extraction locally via a headless Puppeteer instance.
You can disable this and run everything remotely by passing the --remote option, though it's not recommended.
See @ta11y/core for more detailed descriptions of how the different configuration options affect auditing behavior.
The free tier is subject to rate limits as well as a 60 second timeout, so if you're crawling a larger site, you're better off running content extraction locally.
If you're processing a non-publicly accessible website (like localhost), then you must perform content extraction locally.
You can bypass rate limiting by signing up for an API key and passing it either via the --api-key flag or via the TA11Y_API_KEY environment variable.
Visit ta11y once you're ready to sign up for an API key.
The output format is determined by the file type if given a filename via -o or --output. If no file is given, the CLI defaults to logging the results in JSON format to stdout.
Ta11y supports a large number of output formats including:
- xls
- xlsx
- csv
- json
- html
- txt
Here are some example audit results so you can get a feel for the data:
- example.com single page audit: csv, json, xls, xlsx
- Wikipedia small crawl (
--max-visit 16): csv, json, xls, xlsx
Basic single page audit
This example runs all available audit test suites on the given URL.
It uses the default output behavior which logs the results in JSON format to stdout.
ta11y https://example.com{
"summary": {
"errors": 4,
"warnings": 0,
"infos": 2,
"numPages": 1,
"numPagesPass": 0,
"numPagesFail": 1
},
"results": {
"https://example.com": {
"url": "https://example.com",
"depth": 0,
"rules": [
{
"id": "html",
"description": "A document must not include both a “meta” element with an “http-equiv” attribute whose value is “content-type”, and a “meta” element with a “charset” attribute.",
"context": "f-8\">\n <meta http-equiv=\"Content-type\" content=\"text/html; charset=utf-8\">\n <",
"type": "error",
"tags": [
"html"
],
"firstColumn": 5,
"lastLine": 5,
"lastColumn": 71
},
...
],
"summary": {
"errors": 4,
"warnings": 0,
"infos": 2,
"pass": false
}
}
}
}If you only want specific audit results, use the --suite option.
Basic single page audit writing results to an Excel file
This example runs the wcag2a and wcag2aa audit test suites on the given URL and outputs the results to an Excel spreadsheet (supports any xls, xlsx, or csv file).
ta11y https://example.com -o audit.xlsSingle page audit testing WCAG2A and WCAG2AA writing results to a CSV file
This example runs wcag2a and wcag2aa audit test suites on the given URL and outputs the results to a comma-separated-value file (csv).
ta11y https://example.com --suites wcag2a,wcag2aa -o audit.csvBasic single page content extraction
ta11y https://example.com --extract-only{
"results": {
"https://example.com": {
"url": "https://example.com",
"depth": 0,
"content": "<!DOCTYPE html><html><head>\n <title>Example Domain</title>\n\n <meta charset=\"utf-8\">\n <meta http-equiv=\"Content-type\" content=\"text/html; charset=utf-8\">\n <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n <style type=\"text/css\">\n body {\n background-color: #f0f0f2;\n margin: 0;\n padding: 0;\n font-family: -apple-system, system-ui, BlinkMacSystemFont, \"Segoe UI\", \"Open Sans\", \"Helvetica Neue\", Helvetica, Arial, sans-serif;\n \n }\n div {\n width: 600px;\n margin: 5em auto;\n padding: 2em;\n background-color: #fdfdff;\n border-radius: 0.5em;\n box-shadow: 2px 3px 7px 2px rgba(0,0,0,0.02);\n }\n a:link, a:visited {\n color: #38488f;\n text-decoration: none;\n }\n @media (max-width: 700px) {\n div {\n margin: 0 auto;\n width: auto;\n }\n }\n </style> \n</head>\n\n<body>\n<div>\n <h1>Example Domain</h1>\n <p>This domain is for use in illustrative examples in documents. You may use this\n domain in literature without prior coordination or asking for permission.</p>\n <p><a href=\"https://www.iana.org/domains/example\">More information...</a></p>\n</div>\n\n\n</body></html>"
}
},
"summary": {
"root": "https://example.com",
"visited": 1,
"success": 1,
"error": 0
}
}Crawl part of a site and audit each page
ta11y https://en.wikipedia.org --crawl --max-depth 1 --max-visit 8This example will crawl and extract the target site locally and then perform a full remote audit of the results. You can use the --remote flag to force the whole process to operate remotely.
Crawl a localhost site and audit each page
ta11y https://localhost:3000 --crawlThis example will crawl all pages of a local site and then perform an audit of the results.
Note that the local site does not have to be publicly accessible as content extraction happens locally.
Run a WCAG2AA audit on a localhost site
ta11y https://localhost:3000 --crawl --suites wcag2aaThis example will crawl all pages of a local site and then perform an audit of the results, only considering the WCAG2AA test suite.
Note that the local site does not have to be publicly accessible as content extraction happens locally.
Single page audit using WCAG2A and HTML validation test suites
ta11y https://example.com --suites wcag2a,html{
"summary": {
"suites": [
"wcag2a",
"html"
],
"errors": 2,
"warnings": 0,
"infos": 2,
"numPages": 1,
"numPagesPass": 0,
"numPagesFail": 1
},
"results": {
"https://example.com": {
"url": "https://example.com",
"depth": 0,
"rules": [
{
"id": "html",
"description": "A document must not include both a “meta” element with an “http-equiv” attribute whose value is “content-type”, and a “meta” element with a “charset” attribute.",
"context": "f-8\">\n <meta http-equiv=\"Content-type\" content=\"text/html; charset=utf-8\">\n <",
"type": "error",
"tags": [
"html"
],
"firstColumn": 5,
"lastLine": 5,
"lastColumn": 71
},
{
"id": "html",
"description": " The “type” attribute for the “style” element is not needed and should be omitted.",
"context": "e=1\">\n <style type=\"text/css\">\n b",
"type": "info",
"tags": [
"html"
],
"firstColumn": 5,
"lastLine": 7,
"lastColumn": 27
},
{
"id": "html",
"description": "Consider adding a “lang” attribute to the “html” start tag to declare the language of this document.",
"context": "TYPE html><html><head>",
"type": "info",
"tags": [
"html"
],
"firstColumn": 16,
"lastLine": 1,
"lastColumn": 21
},
{
"id": "html-has-lang",
"type": "error",
"description": "Ensures every HTML document has a lang attribute",
"impact": "serious",
"tags": [
"cat.language",
"wcag2a",
"wcag311"
],
"help": "<html> element must have a lang attribute",
"helpUrl": "https://dequeuniversity.com/rules/ta11y/3.4/html-has-lang?application=Ta11y%20API"
}
],
"summary": {
"errors": 2,
"warnings": 0,
"infos": 2,
"pass": false
}
}
}
}More advanced crawling with debug output
This example crawls the English Wikipedia site, visiting up to 200 pages and uses a whitelist to ensure that we only consider links on the English Wikipedia domain.
It then runs an audit against the wcag2a and wcag2aa test suites.
This example also shows how you can get additional debug output during crawling and auditing that can be really helpful to understand what's going on under the hood.
DEBUG=ta11y:* ta11y "https://en.wikipedia.org" --crawl --max-visit 200 --whitelist "https://en.wikipedia.org/**/*" --suites wcag2a,wcag2aa -o wikipedia.xlsx
MIT © Saasify
Support my OSS work by following me on twitter
