This project consumes a Chrome Lighthouse JSON report and outputs a human readable version with screenshots of failing elements and suggestions on how to fix issues. The Accessibility portion of Chrome Lighthouse is largely sourced from Deque's Axe-core engine.
The project is written in Python. But, no Python experience is needed to use this project in its Docker configuration. If you do know Python, we would love your help.
Below is a link to a quick video that explains what OpenAssessIt does for you:
This project can work on all audit categories, but current efforts are focused on the accessibility audits.
Option 1. Run in local Docker container (Docker version no longer works on Mac due to ARM vs X86 architecture differences)
OR
Option 2. Manually install prerequisites and run natively
This is the easiest way to get set up. No stress, no mess.
Download and Install Docker for your OS:
NOTE: Currently Docker container verions is still using the computers local headless version of Chrome instead of the version inside the Docker container. Until we get that ironed out, please verify that a webdriver is installed (Firefox gecko or Chrome) and verify that Chrome Lighthouse is installed lighthouse --version
Download OpenAssessIt:
git clone https://github.com/OpenAssessItToolkit/openassessit.git
Change directory:
cd openassessit
Docker builds a tiny 1GB Docker Image (sorta like a VM) and installs everything inside that Container for you. It does not install any packages on your local computer.
Build the latest OpenAssessIt image:
Note: It might take up to 5 minutes for it to download everything.
docker-compose build
Build the Container to run the assessment (You can run as many assessments as you want from this Image build).
docker-compose run openassessit [url] [foldername] [webdriver]
docker-compose run openassessit https://cats.com catshomepage chrome
When you are done, remove the Image and the Container.
docker-compose down --rmi all
The audit will automatically be copied into your openassessit/tmp/
directory.
brew install node@16
brew link node@16
npm --global install -y lighthouse@10.4.0
brew install geckodriver
brew install chromedriver
Note: Works with Lighthouse 10
- Start up a virtual environment
- Verify that Chrome Lighthouse is installed
lighthouse --version
- Verify that Python is installed, preferaby Python 3.6+,
python --version
orpython3 --version
- Verify that PIP is installed
pip --version
(Note Pip already comes with Python 2.7.9+ and 3.4+) - Verify that a webdriver is installed (Firefox geckodriver 0.30.0 or Chrome 2.44)
- Run
pip install -r requirements.txt
from the root of this repo to install Selenium, Jinja2, and Pillow. - Read the README.md files.
From your projects directory:
1) Install requirements:
pip install -r requirements.txt
2) Clone OpenAssessIt and OpenAssessIt Templates:
git clone https://github.com/OpenAssessItToolkit/openassessit.git
git clone https://github.com/OpenAssessItToolkit/openassessit_templates.git
Note: You could optionally use the run.sh file to run all these commands in serial.
1) Create a Lighthouse json accessibility audit file to import
lighthouse https://cats.com \
--only-categories=accessibility \
--preset=desktop \
--output=json \
--output-path=catsaudit.json \
--chrome-flags="--headless --window-size=1300,600"
Or use our custom Lighthouse accessibility audit recipe
2) Run Lighthouse to Markdown
Converts the json file to markdown.
python -m openassessit.markdown \
--input-file="catsaudit.json" \
--output-file="catsaudit.md" \
--user-template-path="/abs/path/to/openassessit_templates/templates/"
3) Run Capture Assets
Looks for failed audit items in the json file and create a screenshots of each offending element and saves them in an 'assets' folder.
mkdir assets
python -m openassessit.capture \
--input-file="/abs/path/to/catsaudit.json" \
--assets-dir="/abs/path/to/assets/" \
--sleep=1 \
--driver=chrome
python -m openassessit.capture \
--input-file="/abs/path/to/catsaudit.json" \
--assets-dir="/abs/path/to/assets/" \
--sleep=1
4) Review the issues
open catsaudit.md
OR run all the commands together with the run.sh
file
chmod +x run.sh
Example:
./run.sh lighthouse https:/cats.com/ catscom
You can use it as-is, or augment the content with additional custom help text. It takes a real human to validate and prioritize accessibility issues. We recommend that people perform the list of manual tests and the results.
The Markdown file works best with an editor compatible with "Markdown Extras" like MacDown then you can use it to export it to HTML from there.
Or...
4) Convert MD to HTML after you are done editing it
We have a built in Markdown to HTML converter. The header and footer of the HTML are also customizable in the openassessit_templates folder.
python3 -m openassessit.to_html \
--input-file="/abs/path/to/catsaudit.md" \
--output-file="/abs/path/to/catsaudit.html" \
--user-template-path="/abs/path/to/openassessit_templates/templates/"
open catsaudit.html
When we are done, we host these assessments on GitHub pages.
-
If you want to change the order of the audits in the Markdown file, create a custom Lighthouse config and change the weight
[categories][accessibility][auditRefs][id][weight]
-
The report creates images from elements listed in 'color-contrast', 'link-name', 'button-name', 'image-alt', 'input-image-alt', 'label', 'accesskeys', 'frame-title', 'duplicate-id', 'list', 'listitem', 'definition-list', 'dlitem'.
-
If there is a failing element in a visibly hidden element, it will take a screen shot of the coordinates of the failing element. It does not know if the element is visible or not. As a result the screenshot will not always be what you expect it to be. Sometimes the screenshot being incorrect can be a helpful clue to debug the underlying problem.
-
For websites that require an exceptionally large amount of resources, you may need go into Docker's 'Advanced' preferences and increase it's resources.
This project is only possible because of ihadgraft's generous donation of his expertise, time, and patience with joelhsmith and our other contributers: