mirror of https://github.com/pa11y/pa11y-dashboard.git synced 2025-09-24 14:21:13 +00:00

Go to file

Danyal Aytekin e76dccef77 Fix tests, test more, support Node 16-20 (#318 )

* Add `.nvmrc` → 14

* Fix package.json's URLs

* Update to Pa11y CI's version (`https` etc)

* Add Node 16 to matrix, and make linter run each time

* Standardise `.editorconfig`

* Upgrade to `actions/checkout@4` and `actions/setup-node@3`

* Replace `npm install` with `npm ci`

* Replace `wait-action` with `sleep 10s`

* Rewrite to detach config, use promises, and replace `request` with `fetch` (adding `node-fetch` until Node 18)

* Delete small single-use helper

* Bump to `pa11y-webservice@4.1` and use caret from here (we control the dep)

* Return to `this.last`, fix syntax errors

* Update copyright to 2023 and remove unused ref

* Fix troubleshooting link

* Remove symbols, since they could become outdated

* Remove missing link

* Replace emoji note with GitHub Markdown note

* Fix setup link

* Replace br with double space

* Replace `sh` with `console` for terminal output

* Rename Mongo DB used in integration tests to avoid clash locally

* Remove JSCS and references to other unused tools

* Remove tooling tasks update

* Compress definitions and layout where it makes sense or brings clarity

* Rename db used in tests to `pa11y-dashboard-integration-test`, to avoid clash with `pa11y-webservice`'s own test DB

* Use briefer syntax

* Fix integration test setup & config

* Reverse function order to return early

* Update to `pa11y-lint-config@3`, update `ecmaVersion` to 2020, remove some rule overrides

* Fix linting errors, remove cruft

* Move linting and broken integration test command into npm scripts (it remains broken)

* Revert `node-fetch` to `^2.7.0` (can't do ESM right now)

* Upgrade to `pa11y-webservice@^4.2` from `^4.1`

* Upgrade to `mocha@^9.2` from `^8.4` (can't do `10` yet because it drops Node 12)

* Use backticks for property names

* Fix anchor link for 'installing MongoDB'

* Reorganise test workflow and add Node `18` and `20` to test matrix

* Fix `lockfile-version` to `2`

* Apply support policy

* Replace Travis badge with one for Actions

* Define some more links, separate code blocks

* Reflect greater confidence in support for recent versions of MongoDB

* Test against MongoDB versions 3-7

* Remove Make tasks `all`, `ci`, `clean`, `install`, `node_modules`, `lint`

* Fix integration test command in workflow

* Restore shallow Mocha command for now

* Move linting into own step `lint` to avoid duplicated warnings

* Give the `test` workflow a better name now that it uses a bigger matrix

* Drop back to ES2019 from ES2020 for Node 12, remove use of `?.`

* Reduce `--slow` to `4000`

* Remove a `describe.only` 👀

* Fix broken test for add new item → standard

* Rename availability check function

* Fix task count check when testing task creation

* Return fully to the original `new` logic

* Use `127.0.0.1` consistently to fix (possible) IPV6 issue

* Fix Cheerio call in failing test

* Add MongoDB 2, and tweak other final versions

* Lower case and shorten test name, to sit well alongside lint job

* Replace `underscore(.groupBy)` with `lodash/groupby`

* Capitalise Puppeteer

* Say we test against MongoDB 2 as well

* Document two replacements of Make with npm scripts

* Revise requirements, permitting Node 16+ and describing Ubuntu issue

* Support Node 16, 18, 20

* Install `lodash.keys` and fix Lodash mistakes

* Fix rebase autoresolution error affecting `index.js` 👀

* This is Pa11y Dashboard not Webservice

* Fix MongoDB link

* Remove unused link def for Puppeteer

* Shush markdown linter

* Actually use `pa11y-webservice@4.3`

* Improve support table

* Don't `fail-fast`

* Remove dependency `underscore`

* Fix dashboard's port definition for integration test

* Set `NODE_ENV=test` for integration tests

* Use `mocha@10`

* Extend the sleep to rule out the service not starting in time

* Wait on port `4000` instead of sleeping

* Fix `wait-on-action` to `v1.1.0`

* Fix includes of `lodash.groupby` and `lodash.keys`

* Label the port waiting action

* Fix to `pa11y-webservice@4.2.0` until dep issue resolved

* Set waiter action to start after 1s, time out after 30s, and log

* Upgrade to `pa11y-webservice@^4.3.1` from `~4.2.0`

* Remove comment about recent versions of MongoDB, since we test with them now

2024-03-13 05:48:58 +00:00

.github

Fix tests, test more, support Node 16-20 (#318 )

2024-03-13 05:48:58 +00:00

config

Fix tests, test more, support Node 16-20 (#318 )

2024-03-13 05:48:58 +00:00

data

Fix tests, test more, support Node 16-20 (#318 )

2024-03-13 05:48:58 +00:00

public

A11y fixes for pa11y dashboard pages. (#306 )

2022-10-11 14:17:43 +02:00

route

Fix tests, test more, support Node 16-20 (#318 )

2024-03-13 05:48:58 +00:00

test

Fix tests, test more, support Node 16-20 (#318 )

2024-03-13 05:48:58 +00:00

view

Fix tests, test more, support Node 16-20 (#318 )

2024-03-13 05:48:58 +00:00

.bowerrc

Add bower package management

2013-10-04 11:37:40 +01:00

.editorconfig

Fix tests, test more, support Node 16-20 (#318 )

2024-03-13 05:48:58 +00:00

.eslintignore

Tooling update (#184 )

2017-03-21 13:41:46 +00:00

.eslintrc.js

Fix tests, test more, support Node 16-20 (#318 )

2024-03-13 05:48:58 +00:00

.gitignore

Fix tests, test more, support Node 16-20 (#318 )

2024-03-13 05:48:58 +00:00

.npmrc

Fix tests, test more, support Node 16-20 (#318 )

2024-03-13 05:48:58 +00:00

.nvmrc

Fix tests, test more, support Node 16-20 (#318 )

2024-03-13 05:48:58 +00:00

app.js

Fix tests, test more, support Node 16-20 (#318 )

2024-03-13 05:48:58 +00:00

bower.json

Fix tests, test more, support Node 16-20 (#318 )

2024-03-13 05:48:58 +00:00

CHANGELOG.md

Version 4.2.0

2022-03-30 17:19:08 +01:00

config.js

Fix tests, test more, support Node 16-20 (#318 )

2024-03-13 05:48:58 +00:00

CONTRIBUTING.md

Fix tests, test more, support Node 16-20 (#318 )

2024-03-13 05:48:58 +00:00

index.js

Improve the console messaging on starting the app to avoid confusion. (#292 )

2023-11-15 09:26:25 +00:00

LICENSE

Bring the README into line with newer projects

2016-05-22 11:45:57 +01:00

Makefile

Fix tests, test more, support Node 16-20 (#318 )

2024-03-13 05:48:58 +00:00

MIGRATION.md

Version 4.0.0

2021-11-26 15:34:37 +00:00

package-lock.json

Fix tests, test more, support Node 16-20 (#318 )

2024-03-13 05:48:58 +00:00

package.json

Fix tests, test more, support Node 16-20 (#318 )

2024-03-13 05:48:58 +00:00

README.md

Fix tests, test more, support Node 16-20 (#318 )

2024-03-13 05:48:58 +00:00

README.md

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 mongodb-community@4.4

Start the MongoDB server:

brew services start mongodb/brew/mongodb-community@4.4

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

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

README.md

Pa11y Dashboard

Requirements

Pally Dashboard 4 and Linux/Ubuntu

Setting up Pa11y Dashboard

Installing MongoDB

Example MongoDB installation for macOS

Configuring Pa11y Dashboard

Option 1: Using environment variables

Option 2: Using config files

Configurations

port

noindex

readonly

siteMessage

webservice

Contributing

Useful resources

Troubleshooting

Common issues

Create a new issue

Support and migration

License

`port`

`noindex`

`readonly`

`siteMessage`

`webservice`