pa11y / pa11y-dashboard

Pa11y Dashboard is a web interface which helps you monitor the accessibility of your websites

Pa11y Dashboard

Pa11y Dashboard is a web interface to the Pa11y accessibility reporter; allowing you to focus on fixing issues rather than hunting them down.

---

Requirements

• Node.js: Pa11y Dashboard 4 requires a stable (even-numbered) version of Node.js of 12 or above.
• MongoDB: This project depends on Pa11y Webservice, which stores test results in a MongoDB database and expects one to be available and running.

Pally Dashboard 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 Dashboard 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 Dashboard, which will use Pa11y 7 along with a more recent version of Puppeteer, will resolve this issue.

Setting up Pa11y Dashboard

In order to run Pa11y Dashboard, we recommend cloning this repository locally:

git clone https://github.com/pa11y/pa11y-dashboard.git

Then installing the dependencies:

cd pa11y-dashboard
npm install

Installing MongoDB

Instructions for installing and running MongoDB are outside the scope of this document. When in doubt, please refer to the MongoDB installation instructions for details of how to install and run MongoDB on your specific operating system. An example of the installation and configuration process for macOS follows.

Pa11y Dashboard uses MongoDB Node.js Driver version 3, which may not support some features of MongoDB versions 6 and beyond. We do however test against MongoDB versions 2 to 6, plus the latest major version, which at the time of writing is 7.

Example MongoDB installation for macOS

On recent versions of macOS (10.13 or later), you can use Homebrew to install MongoDB Community Edition.

Tap the MongoDB Homebrew Tap:

brew tap mongodb/brew

Install a supported Community version of MongoDB:

brew install [email protected]

Start the MongoDB server:

brew services start mongodb/brew/[email protected]

Check that the service has started properly:

$ brew services list

Name              Status  User       Plist
mongodb-community started pa11y      /Users/pa11y/Library/LaunchAgents/homebrew.mxcl.mongodb-community.plist

Configuring Pa11y Dashboard

The last step before being able to run Pa11y Dashboard is to define a configuration for it. This can be done in two ways:

Option 1: Using environment variables

Each configuration can be set with an environment variable rather than a config file. For example to run the application on port 8080 you can use the following:

PORT=8080 node index.js

The available configurations are documented in the next section.

Option 2: Using config files

You can store the configuration for Pa11y Dashboard on a JSON file. You can use a different configuration file for each environment you're planning to run Pa11y Dashboard on. You can choose a specific environment to run the application from by setting the NODE_ENV environment variable:

NODE_ENV=development node index.js

Three example files are provided in this repository, you can copy and customise them to your liking:

cp config/development.sample.json config/development.json

cp config/production.sample.json config/production.json

cp config/test.sample.json config/test.json

The available configurations are documented in the next section.

If you run into problems, check the troubleshooting guide.

Configurations

The boot configurations for Pa11y Dashboard are as follows. Look at the sample JSON files in the repo for example usage.

port

(number) The port to run the application on. Set via a config file or the PORT environment variable.

noindex

(boolean) If set to true (default), the dashboard will not be indexed by search engines. Set to false to allow indexing. Set via a config file or the NOINDEX environment variable.

readonly

(boolean) If set to true, users will not be able to add, delete or run URLs (defaults to false). Set via a config file or the READONLY environment variable.

siteMessage

(string) A message to display prominently on the site home page. Defaults to null.

webservice

This can either be an object containing Pa11y Webservice configurations, or a string which is the base URL of a Pa11y Webservice instance you are running separately. If using environment variables, prefix the webservice vars with WEBSERVICE_.

Contributing

There are many ways to contribute to Pa11y Dashboard, we cover these in the contributing guide for this repo.

If you're ready to contribute some code, you'll need to clone the repo and get set up as outlined in the setup guide. You'll then need to start the application in test mode with:

NODE_ENV=test node index.js

You'll now be able to run the following commands:

npm run lint   # Lint the code
npm test       # Run all tests

To compile the client-side JavaScript and CSS, you'll need the following commands. Compiled code is committed to the repository.

make less    # Compile the site CSS from LESS files
make uglify  # Compile and uglify the client-side JavaScript

Useful resources

• Setting up An Accessibility Dashboard from Scratch with Pa11y on DigitalOcean
• Monitoring Web Accessibility Compliance With Pa11y Dashboard

Troubleshooting

Common issues

• 500 errors or Could not connect to pa11y-webservice messages are often related to MongoDB. Ensure that you have the appropriate version of MongoDB installed, and that it's running - it doesn't always start automatically.
• Error messages saying that pa11y-webservice isn't running may be due to dependency installation problems. Try deleting your pa11y-dashboard/node_modules directory and running npm install again.

Create a new issue

Check the issue tracker for similar issues before creating a new one. If the problem that you're experiencing is not covered by one of the existing issues, you can create a new issue. Please include your node.js and MongoDB version numbers, and your operating system, as well as any information that may be useful in debugging the issue.

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	Last minor release	Node.js support	Support end date
4	Imminent	>= 12	✅ Current major version
3	3.3.0	8, 10	2022-05-26
2	2.4.2	4, 6	2020-01-16
1	1.12.0	0.10, 0.12, 4, 6	2016-12-05

License

Pa11y Dashboard is licensed under the GNU General Public License 3.0.
Copyright © 2023, Team Pa11y and contributors

pa11y-dashboard's Issues

Functionality to download results as CSV or JSON

As a user
When on the tasks page
Then I should be able to download the results for the selected date as a CSV or JSON file.

Add some dev fixtures

We need to make it a lot easier to see lots of different URLs with results, so that it's easier to see all the styles etc. Also for demo purposes and to get new developers up-and-running quicker.

If only one result for a task do not show graph

As a user
When I view the task page
Then if there is only one result I should not see the graph

Fix bug with reset zoom button toggling appearance on Zooming on graph

Name

What should this be called? "pa11y-web" isn't particularly descriptive in my opinion. Something with "dashboard" in the name might make sense. It doesn't technically have to be pa11y-associated – pa11y is almost just an implementation detail.

Suggestions welcome.

Refactor layout of task results page

Move the date selector to the main section above the graph.
Add the current date being shown to the main section above the graph
Add a Results from dd/mm/yyy to the bottom section below the graph as a title.

This will then make the results page clearer that the results being shown (apart from the graph are just from this particular date)

Add list of other urls to the task / result pages in aside

Run pa11y against site

Run pa11y against site and aim for 0 errors / warnings and notifications

Add list of ignore rules to task page

As a user
When on the task page
Then I want to be able to see the list of ignored rules for this url

Fix layout grid in IE7 and IE8

Bootstrap 3 does not support less than IE9 unless you use response.js to enable media-queries in IE8. In IE7 you get bugger all.
Rather than rely on a js script I have adopted a fixed width for IE8 and IE7 and made specific styles for these browsers. No js needed :-)

Link to the WCAG and Section508 specs

Suggested by @GlynnPhillips.

Add aria-roles to markup

Add graph to home page showing average of all tasks errors, warnings and notifications.

As a user
When on the home page
Then I want to see a graph which shows the average of all tasks at the run times.
Then if no javascript a table with the averages needs to be shown

If there are no Ignored Rules amend header to say so on tasks and results pages

Ability to select run date from dropdown on the task page and see results for that date

As a user
When I am on the task page
Then I need to be able to select a run date from the dropdown in the left column and be taken to the results for that date. The results should be reflected in the graph, the table for the graph, the main content of the right column and the task stats below the date selector.

Investigate using Dust for templates

Handlebars is being used at the moment, because it works well with Express and we can easily get layout/partial/block support. Investigate replacing with Dust, as we're using Dust on some internal projects.

Add context to numbers in index view

The numbers in the index view could do with something to contextualise them. I went to hover over them, maybe a title attribute would make sense explaining what the numbers mean?

Add run functionality to webapp

As a user
When I am on the task page
Then I should be able run pa11y against this task/url via the Run button

Add ability to remove tasks / urls

As a user
When I am on the pa11y site
And I have added a task / url
If I no longer need it I should be able to delete it

I think this is pretty important until we workout how to give edit access. If I add a task / url and the url is wrong or I no longer need it I should be able to remove it as it will be throwing my stats out

Refactor date selector navigation to be non-js friendly

As a user
When on the tasks page
Then I should be able to navigate to results for another date from the list of date links in the left hand column when js is disabled as well as when it is enabled.

Currently the standard implementation of the bootstrap dropdown menu does not degrade gracefully.

Only show latest result for any day

Warn user if they try to run pa11y for a url on a date where a result already exists

Fix js for jumping to an already opened task list

As a user
When in the task view and I click on one of the stats boxes
Then I should jump to the correct type of list (error, warning or notice) and if this box is already showing the contents it should stay open and not toggle closed.

Responsiveness

Check responsiveness of site and correct

Make WCAG2AA the default selected option in standards dropdown on add new task form

Make this the default on the form so that the correct ignore rules are shown when the page loads

Cross browser testing

H1s should describe the page

Small thing I noticed: the page h1 is always the same. Ideally it should describe the current page, not be used for the banner.

I've got around this before by making the banner a h1 on the home page, but just an anchor on all other pages.

404 + 500 pages

Introduce Bower to manage js files

Look at reducing number of js files

There are a number of separate js files being called in.
1 ) Reduce number of files being called. Reduce bootstrap to one minified bootstrap. Same with flot?
2) For @rowanmanning : Could do with these being compiled into a single minified js file for production.

Try to get a *full* list of standard/rule descriptions

Refactor the dropdown for the date selector

This needs to be far more non js friendly.
Refactor to enable hover support to show the dropdown and use js to re-jig the markup to produce the bootstrap markup. Nice.

Add filter to home page to allow easy search of tasks / url

As a user when I am on the home page and I have a long list of tasks I want to be able to find a particular task easily by using a filter option.

Split latest task results section into errors, warnings and notifications

As a user
When on the task page
Then I expect to see the Errors grouped together, and the Warnings grouped together and the Notifications grouped together.

Add graph and date selector to the result page

Allow editing of tasks

This isn't as simple as it seems; there are a couple of questions to discuss:

1. Will it be confusing/misleading to see sudden drops in number of errors (for example, if somebody adds some ignore rules to an existing task)
2. Do we want to log changes to a task, to allow people to easily see when something changed? If so, how should this look?
3. Is this required, or would it be better to just create a new task? If we do this, would it make sense to be able to "archive" old tasks, in order to give them less prominence in the interface?

View diffs between results

Add the ability to view diffs between results, so you can easily see which errors are new or which errors have been fixed.

Get a live demo site up-and-running

Rename Home in Breadcrumb to Dashboard

Check for other instances

Change "Notifications" to "Notices"

Notices is the term used by HTML CodeSniffer etc, notifications kind of makes me think of alerts you get when something changes.

Redesign the tasks lists on the task view

The tasks view headers and lists need redesigning as they look a bit busy and cumbersome at the moment.

Convert current css to less files

Currently we use 2 separate css files. One for the bootstrap template and one for the pa11y specific styles.
We should ideally be using the less files for the bootstrap theme and extra pa11y specific less files which get compiled into a single css file for production.

Reverse the order that the graph results are being shown

The graph is plotting results from most recent to least recent.
This needs to be reversed in the js using reverse.array

Convert existing pa11y poc to the pa11y web-app

Create auto compile routine for LESS files

Once the less files are added to the project add the ability for auto compile once a less file is changed within the project without need to use local compiler.

Add more info to the footer

Not sure what...just more info.
e.g. if you want to contribute link
license info
version info

Add descriptions to ignore rules

This can be accessed using {{description}}. I don't know what's best for this, maybe as a title attribute or something? Your call

Fix issue with flot being broken in IE8 and IE7

Add breadcrumb

Add delete button to tasks on home page

Add delete buttons with the href of /{{id}}/delete to the tasks on the home page
@rowanmanning to complete functionality