Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/dequelabs/axe-cli

[Deprecated] A command-line interface for the aXe accessibility testing engine
https://github.com/dequelabs/axe-cli

axe-cli

Last synced: about 2 months ago
JSON representation

[Deprecated] A command-line interface for the aXe accessibility testing engine

Awesome Lists containing this project

README 

        
# [DEPRECATED] axe-cli



[![No Maintenance Intended](http://unmaintained.tech/badge.svg)](http://unmaintained.tech/)



> This repository has been deprecated. The package has been moved to [axe-core-npm](https://github.com/dequelabs/axe-core-npm/tree/develop/packages/cli). The package will be available via NPM as [`@axe-core/cli`](https://www.npmjs.com/package/@axe-core/cli).



---



[![Greenkeeper badge](https://badges.greenkeeper.io/dequelabs/axe-cli.svg)](https://greenkeeper.io/)



[![Join the chat at https://gitter.im/dequelabs/axe-core](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/dequelabs/axe-core?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)

[![Version](https://img.shields.io/npm/v/axe-cli.svg)](https://www.npmjs.com/package/axe-cli)

[![License](https://img.shields.io/npm/l/axe-cli.svg)](LICENSE)



Provides a command line interface for [aXe](https://github.com/dequelabs/axe-core) to run quick accessibility tests.



## Getting Started



Install [Node.js](https://docs.npmjs.com/getting-started/installing-node) if you haven't already. This project requires Node 6+. By default, axe-cli runs Chrome in headless mode, which requires Chrome 59 or up.



Install axe-cli globally: `npm install axe-cli -g`



Lastly, install the webdrivers of the browsers you wish to use. A webdriver is a driver for your web browsers. It allows other programs on your machine to open a browser and operate it. Current information about available webdrivers can be found at [selenium-webdriver project](https://www.npmjs.com/package/selenium-webdriver). Alternatively, you could use [Webdriver manager](https://www.npmjs.com/package/webdriver-manager)



## Usage



After installing, you can now run the `axe` command in your CLI, followed by the URL of the page you wish to test:



```

axe https://www.deque.com

```



You can run multiple pages at once, simply add more URLs to the command. Keep in mind that axe-cli is not a crawler, so if you find yourself testing dozens of pages at once, you may want to consider switching over to something like [axe-webdriverjs](https://www.npmjs.com/package/axe-webdriverjs). If you do not specify the protocol, http will be used by default:



```

axe www.deque.com, dequeuniversity.com

```



**Note:** If you are having difficulty with the color scheme, use `--no-color` to disable text styles.



## Running specific rules



You can use the `--rules` flag to set which rules you wish to run, or you can use `--tags` to tell axe to run all rules that have that specific tag. For example:



```

axe www.deque.com --rules color-contrast,html-has-lang

```



Or, to run all wcag2a rules:



```

axe www.deque.com --tags wcag2a

```



In case you want to disable some rules, you can use `--disable` followed by a list of rules. These will be skipped when analyzing the site:



```

axe www.deque.com --disable color-contrast

```



This option can be combined with either `--tags` or `--rules`.



A list of rules and what tags they have is available at: https://dequeuniversity.com/rules/worldspace/3.0/.



## Saving the results



Results can be saved as JSON data, using the `--save` and `--dir` flags. By passing a filename to `--save` you indicate how the file should be called. If no filename is passed, a default will be used. For example:



```

axe www.deque.com --save deque-site.json

```



Or:



```

axe www.deque.com --dir ./axe-results/

```



## Sending results to STDOUT



To output the test results to STDOUT, provide the `--stdout` flag. This flag has the side-effect of silencing all other logs/output (other than errors, which are written to STDERR).



To print the entire result object to your terminal, do:



```

axe --stdout www.deque.com

```



To pipe the results to a file, do:



```

axe --stdout www.deque.com > your_file.json

```



To pipe the results to a JSON-parsing program for further processing, do:



```

axe --stdout www.deque.com | jq ".[0].violations"

```



## Defining the scope of a test



If you want to only test a specific area of a page, or wish to exclude some part of a page you can do so using the `--include` and `--exclude` flags and pass it a CSS selector:



```

axe www.deque.com --include "#main" --exclude "#aside"

```



You may pass multiple selectors with a comma-delimited string. For example:



```

axe www.deque.com --include "#div1,#div2,#div3"

```



## Custom axe-core versions



Axe-cli will look for locally available versions of axe-core. If the directory from where you start axe-cli has an `axe.js` file, or has a `node_modules` directory with axe-core installed in it. Axe-cli will use this version of axe-core instead of the default version installed globally.



To specify the exact file axe-core file axe-cli should use, you can use the `--axe-source` flag (`-a` for short), with a relative or absolute path to the file.



```

axe www.deque.com --axe-source ./axe.nl.js

```



## Different browsers



Axe-cli can run in a variety of web browsers. By default axe-cli uses Chrome in headless mode. But axe-cli is equally capable of testing pages using other web browsers. **Running in another browser requires that browser's webdriver to be available on your PATH**. You can find a list of available webdrivers and how to install them at: https://seleniumhq.github.io/docs/wd.html



To run axe-cli using another browser, pass it in as the `--browser` option:



```

axe www.deque.com --browser chrome

```



Or for short:



```

axe www.deque.com -b c

```



## Custom Chrome Flags



When using the Headless Chrome browser, you may provide any number of [flags to configure how the browser functions](https://peter.sh/experiments/chromium-command-line-switches/).



Options are passed by name, without their leading `--` prefix. For example, to provide the `--no-sandbox --disable-setuid-sandbox --disable-dev-shm-usage` flags to the Chrome binary, you'd do:



```

axe --chrome-options="no-sandbox,disable-setuid-sandbox,disable-dev-shm-usage" www.deque.com

```



## CI integration



Axe-cli can be ran within the CI tooling for your project. Many tools are automatically configured to halt/fail builds when a process exits with a code of `1`.



Use the `--exit` flag, `-q` for short, to have the axe-cli process exit with a failure code `1` when any rule fails to pass.



```

axe www.deque.com --exit

```



## Timing and timeout



For debugging and managing timeouts, there are two options available. With `--timer` set, axe-cli will log how long it takes to load the page, and how long it takes to run axe-core. If you find the execution of axe-core takes too long, which can happen on very large pages, use `--timeout` to increase the time axe has to test that page:



```

axe www.cnn.com --timeout=120

```



## Delay audit to ensure page is loaded



If you find your page is not ready after axe has determined it has loaded, you can use `--load-delay` followed by a number in milliseconds. This will make axe wait that time before running the audit after the page has loaded.



```

axe www.deque.com --load-delay=2000

```



## Verbose output



To see additional information like test tool name, version and environment details, use the `--verbose` flag, `-v` for short.



```

axe www.deque.com --verbose

```



## ChromeDriver Path



If you need to test your page using an older version of Chrome, you can use `--chromedriver-path` followed by the absolute path to the desired version of the ChromeDriver executable.



```

axe www.deque.com --chromedriver-path="absolute/path/to/chromedriver"

```