pa11y-webservice
v4.3.1
Published
Pa11y Webservice provides scheduled accessibility reports for multiple URLs
Downloads
10,606
Readme
Pa11y Webservice
Pa11y Webservice is a Node.js service that can schedule accessibility testing for multiple URLs, using Pa11y.
Use this service if you'd like to coordinate your testing by interacting with a restful API. For other scenarios, another Pa11y tool may be more appropriate:
- Pa11y Dashboard provides a visual interface
- Pa11y CI, and Pa11y itself, can be executed from the command line, which is likely to be more useful for accessibility testing as part of a CI/CD workflow
Requirements
- Node.js: Each major version of Pa11y Webservice is designed to support a set of stable/LTS versions of Node.js. Pa11y Webservice 4 requires a stable (even-numbered) version of Node.js of 12 or above.
- MongoDB: The service stores test results in a MongoDB database, and expects one to be available and running.
Pally Webservice 4 and Linux/Ubuntu
Pa11y (and therefore this service) uses Headless Chrome to perform accessibility testing. On Linux and other Unix-like systems, Pa11y's attempt to install it as a dependency sometimes fails since additional operating system packages will be required. Your distribution's documentation should describe how to install these.
In addition, to use Pa11y Webservice 4 with a version of Ubuntu above 20.04, a path to the Chrome executable must be defined in chromeLaunchConfig, as chromeLaunchConfig.executablePath
. Version 5 of Pa11y Webservice, which will use Pa11y 7 along with a more recent version of Puppeteer, will resolve this issue.
Setup
Clone this repository:
git clone https://github.com/pa11y/pa11y-webservice.git
Now install its dependencies:
cd pa11y-webservice
npm install
We're nearly ready to run the service, but first we must provide some configuration.
Configuration
The service can be configured in one of two ways: using environment variables, or using a configuration file. When both are present, the file's contents will override the environment variables. We provide some sample configuration files for reference.
Each configurable option is documented here, listed by its JSON-file property name. The environment variable equivalent for each option is identical, but upper-snake-cased.
Configuration using environment variables
Supply each option to the service's environment. For example, to supply a port inline at the time of execution, the relevant environment variable would be PORT
:
PORT=8080 npm start
Configuration using a JSON file
Configuration can also be provided by a JSON file, allowing separate configurations to be maintained for multiple contexts. This method is also the only way to configure the instance of Headless Chrome that Pa11y will use.
We label each of these contexts a 'mode'. The mode is set by the NODE_ENV
environment variable, and defaults to development
. Pa11y Webservice will look for the mode's configuration file at config/{mode}.json
. Providing NODE_ENV=production
would lead to the service looking for config/production.json
:
NODE_ENV=production npm start
The config
directory here contains three examples. You could use one as a base to create your own configuration.
cp config/development.sample.json config/development.json
cp config/production.sample.json config/production.json
cp config/test.sample.json config/test.json
List of configuration options
database
(string) The MongoDB connection string for your database.
Env equivalent: DATABASE
.
host
(string) The host to run the application on. This is normally best left as "0.0.0.0"
, which means the application will run on any incoming connections.
Env equivalent: HOST
.
port
(number) The port to run the application on.
Env equivalent: PORT
.
cron
(string) A crontab which describes when to generate reports for each task.
Env equivalent: CRON
.
numWorkers
(number) The number of workers that will be running concurrently on each cron execution.
Env equivalent: NUM_WORKERS
.
chromeLaunchConfig
(config file only)
(object) Options to be supplied to the instance of Headless Chrome that Pa11y will create. See chromeLaunchConfig
's documentation for more information.
Env equivalent: none. This option can only be defined by a file.
API documentation
Our wiki documents the interface presented by this webservice:
Client libraries
Contributing
There are many ways to contribute to Pa11y Webservice, we cover these in the contributing guide for this repo.
If you're ready to contribute some code, follow the setup guide. The project can be linted and unit tested immediately:
make lint # Lint the code
make test-unit # Run the unit tests
The integration tests require the service to be running in the background, since they'll be checking its behaviour.
Create a configuration file for the
test
mode; one can be created quickly withcp config/test.sample.json config/test.json
Start the service in test mode with:
NODE_ENV=test npm start &
The
&
places the service into the background. An alternative approach is to runNODE_ENV=test npm start
, suspend the process withCTRL+z
, and finally runbg
to place it into the background.make test-integration # Run the integration tests make test # Run both the integration tests and the unit tests mentioned above
Fixtures
If you'd like to preview Pa11y Webservice or present it to someone else, we've provided some sample tasks and results, which can be embedded by running one of the following commands:
NODE_ENV=development make fixtures
NODE_ENV=test make fixtures
Support and migration
[!NOTE] We maintain a migration guide to help you migrate between major versions.
When we release a new major version we will continue to support the previous major version for 6 months. This support will be limited to fixes for critical bugs and security issues. If you're opening an issue related to this project, please mention the specific version that the issue affects.
The following table lists the major versions available and, for each previous major version, its end-of-support date, and its final minor version released.
| Major version | Final minor version | Node.js support | Support end date |
| :------------ | :----------------- | :----------------------- | :--------------- |
| 4
| | >= 12
| ✅ Current major version |
| 3
| 3.2.1
| 8
, 10
| 2022-05-26 |
| 2
| 2.3.1
| 4
, 6
| 2020-01-04 |
| 1
| 1.11.1
| 0.10
, 0.12
, 4
, 6
| 2016-12-05 |
License
Pa11y Webservice is licensed under the GNU General Public License 3.0.
Copyright © 2013-2023, Team Pa11y and contributors