npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

pa11y-webservice

v4.3.1

Published

Pa11y Webservice provides scheduled accessibility reports for multiple URLs

Downloads

10,606

Readme

Pa11y Webservice

NPM version Node.js version support Build status GPL-3.0 licensed


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.

  1. Create a configuration file for the test mode; one can be created quickly with cp config/test.sample.json config/test.json

  2. Start the service in test mode with:

    NODE_ENV=test npm start &

    The & places the service into the background. An alternative approach is to run NODE_ENV=test npm start, suspend the process with CTRL+z, and finally run bg to place it into the background.

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