ta11y

Modern web accessibility audits. 💪

Features

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

Usage

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.

CLI

The easiest way to get started is via the CLI.

npm install -g @ta11y/ta11y

Usage: 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 information

Notes

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

API Key

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.

Output

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

Examples

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

Single 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.csv

Basic 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 8

This 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 http://localhost:3000 --crawl

This 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 http://localhost:3000 --crawl --suites wcag2aa

This 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

---

Help us with our goal of building a more accessible and inclusive web. ☺️

License

MIT © Saasify

Support my OSS work by following me on twitter