accessible-a11y-cli
v1.7.0
Published
A robust, developer-friendly CLI for accessibility testing and autofix with axe-core. Features advanced autofix logic, clear output, safe file handling, and extensive tests.
Maintainers
joecodesalldayReadme
accessible-a11y-cli
⭐️ If you find this project useful, please consider starring it on GitHub!
A robust, developer-friendly CLI for automated accessibility testing and autofix of HTML and JSX files using axe-core.
📚 Table of Contents
🚀 What's New in 1.6.0
Major autofix engine upgrade!
Customizable Markdown/HTML templates!
- Use
--template <file>to provide your own Markdown or HTML template for output reports. - Templates support
{{results}}(inserts formatted results for each file) and{{json}}(inserts the full JSON output). - Example usage:
a11y-check check test.html --format markdown --template my-template.md --output report.md
- Use
Now supports 8 high-impact autofix rules:
- Add/fix
<html lang> - Add/fix
<title> - Add
<main>landmark - Add
<h1>heading - Add missing
altattributes to images - Add missing accessible name to buttons/links
- Add table headers if missing
- Fix duplicate IDs
- Add/fix
Expanded and improved unit and integration tests for all new autofix rules
Markdown output support for both results and autofix logs (
--format markdown)All output formats (table, JSON, HTML, Markdown) are now robust and fully tested
🚀 What's New in 1.3.1
- Robust CLI integration tests for output/logging (table, JSON, HTML)
- Fixed: CLI now outputs autofix logs in the requested format when --fix and --output are used
- Improved documentation and test coverage for output formatting
🚀 What's New in 1.1.4
- Expanded robust test file with more accessibility issues for better coverage
- Improved dry-run default for --fix (now requires --no-fix-dry-run to write changes)
🚀 What's New in 1.1.3
- Fail-safe file handling: always creates a backup before fixing, and --fix-dry-run is now the default for --fix
🚀 What's New in 1.1.1
- CLI output and UX improvements: clearer logs, more context in autofix logs, improved error/warning messages, and enhanced summary formatting
🚀 What's New in 1.0.0
- Advanced autofix logic for alt, lang, labels, headings, ARIA, color contrast, tabindex, skip links, semantic HTML, and link text
- Comprehensive, reliable unit tests for all autofix logic
- Cleaned up legacy and redundant test files for maintainability
- Ready for production and open source use
🗺️ Roadmap
- [x] Advanced autofix logic for accessibility issues
- [x] Robust CLI output and logging (table, JSON, HTML, Markdown)
- [x] Fail-safe file handling and dry-run
- [x] Configurable rules and output formats
- [x] Markdown output support for results and autofix logs
- [x] Customizable Markdown/HTML templates
- [ ] HTML output improvements (planned)
🚀 Vision
accessible-a11y-cli aims to make accessibility testing simple, fast, and part of every developer's workflow. By leveraging axe-core, this tool helps you catch and fix accessibility issues early, ensuring your web projects are usable by everyone.
📦 Installation
npm install -g accessible-a11y-cli🛠️ Usage
Run accessibility checks on one or more HTML/JSX files or remote URLs:
a11y-check check path/to/file.html path/to/other.jsx https://example.comOutput Formats & Rule Configuration
- Output and autofix logs can be saved in
table,json, orhtmlformats using--format. - Use
--output <file>to save results and logs to a file. - Enable or disable specific rules with
--rulesand--disable-rule(comma-separated list). - All output formats are supported for both results and autofix logs.
Options
--template <file>Use a custom Markdown or HTML template for output (supports{{results}}and{{json}})-f, --format <type>Output format:table(default),json, orhtml-o, --output <file>Save results to a file--fixAttempt to auto-fix common accessibility issues (now covers: lang, title, main, h1, image alt, button/link name, table headers, duplicate IDs)--fix-dry-runShow what would be fixed without changing files--verboseVerbose output
You can mix local file paths and URLs in a single command. URLs must start with http:// or https://.
🧪 Testing & Reliability
This CLI is backed by robust unit tests for all autofix logic. Run npm test to verify reliability and coverage. You can also use CLI-level tests to check real file output.
💡 Example
Example custom Markdown template (my-template.md):
# My Custom Accessibility Report
{{results}}
---
Full JSON output:
```json
{{json}}
```bash
# Check a local file, a JSX file, and a remote URL
a11y-check check test/test.html src/App.jsx https://example.com
# Autofix and save to a new file (with backup)
a11y-check check --fix -o fixed.html test/test.html
# Dry run (see what would be fixed, but don’t write)
a11y-check check --fix-dry-run test/test.html
# Output results as JSON and save to a file
a11y-check check https://example.com --format json --output results.json
# Output autofix log as HTML
a11y-check check --fix --format html --output autofix-log.html test/test.html
# Output autofix log as table (plain text)
a11y-check check --fix --format table --output autofix-log.txt test/test.html
# Disable specific rules and output as JSON
a11y-check check --fix --disable-rule=region,tabindex --format json --output autofix-log.json test/test.html🤝 Contributing
Contributions are welcome! Please open issues or pull requests for bugs, features, or improvements.
- Fork the repo and create your branch
- Run
npm installto set up dependencies - Add tests for new features
- Use Conventional Commits for commit messages
- Open a pull request and describe your changes
This project is not affiliated with Deque Systems. "axe-core" is a trademark of Deque Systems, Inc.