Purple A11y is a customisable, automated accessibility testing tool that allows software development teams to assess whether their products are user-friendly to persons with disabilities (PWDs).
This is the engine and command-line interface (CLI) for Purple A11y. For a desktop graphical user interface (GUI), check out Purple A11y Desktop. The official application can only be downloaded at https://go.gov.sg/purple-a11y-cicd. We recommend that you download the software only from the official link, as other sources and/or third party links may pose risks and/or compromise your system.
If you wish to use Purple A11y as a NodeJS module that can be integrated with end-to-end testing frameworks, refer to the integration guide on how you can do so.
Portable Purple A11y is the recommended way to run Purple A11y as it reduces the difficulty for installation. Refer to Installation Guide for step-by-step instructions for portable Purple A11y.
Please ensure the following requirements are met:
node -v
# Install NodeJS version with NVM
nvm install --lts
nvm use --lts
- Install the required NPM packages with `npm install`.
- Build the project with `npm run build` before you try to run it with `npm start`.
#### Java JRE/JDK
- A JRE/JDK distribution of version 11 or above.
- To check your version of Java, go into terminal and paste the command bellow
```shell
java --version
<installpath>/tmp/verapdf-test</installpath>
to a location of your choice.
# Invoke the VeraPDF installer
# Windows users should use vera-install.bat instead of vera-install
./verapdf-install ./auto-install.xml
export PATH="
verapdf --version
#### Facing issues?
Please refer to [Troubleshooting section](#troubleshooting) for more information.
---
## Features
Purple A11y can perform the following to scan the target URL.
- To **run** Purple A11y in **terminal**, run `npm start`. Questions will be prompted to assist you in providing the right inputs.
- Results will be compiled in JSON format, followed by generating a HTML report.
> NOTE: For your initial scan, there may be some loading time required before use. Purple-A11y will also ask for your name and email address and collect your app usage data to personalise your experience. Your information fully complies with [GovTech’s Privacy Policy](https://www.tech.gov.sg/privacy/).
#### Delete/Edit Details
> You may delete and edit your cached name and e-mail address by running the following command to delete `userData.txt`:
> - Windows (PowerShell): `rm "$env:APPDATA\Purple A11y\userData.txt"`
> - MacOS (Terminal): `rm "$HOME/Library/Application Support/Purple A11y/userData.txt"`
If `userData.txt` does not exists just run `npm start`.
### Scan Selection
You can interact via your arrow keys.
```shell
% npm start
┌────────────────────────────────────────────────────────────┐
│ Purple A11y (ver ) │
│ We recommend using Chrome browser for the best experience.│
│ │
│ Welcome back User! │
│ (Refer to readme.txt on how to change your profile) │
└────────────────────────────────────────────────────────────┘
? What would you like to scan? (Use arrow keys)
❯ Sitemap
Website
Custom
Headless mode would allow you to run the scan in the background. If you would like to observe the scraping process, please enter n
% npm start
┌────────────────────────────────────────────────────────────┐
│ Purple A11y (ver ) │
│ We recommend using Chrome browser for the best experience. │
│ │
│ Welcome back User! │
│ (Refer to readme.txt on how to change your profile) │
└────────────────────────────────────────────────────────────┘
? What would you like to scan? Sitemap
? Do you want purple-a11y to run in the background? (Y/n) No
% npm start
┌────────────────────────────────────────────────────────────┐
│ Purple A11y (ver ) │
│ We recommend using Chrome browser for the best experience. │
│ │
│ Welcome back User! │
│ (Refer to readme.txt on how to change your profile) │
└────────────────────────────────────────────────────────────┘
? What would you like to scan? Sitemap
? Do you want purple-a11y to run in the background? No
? Which screen size would you like to scan? (Use arrow keys) Desktop
? Please enter URL or file path to sitemap, or drag and drop a sitemap file here: https://www.sitemaps.org/sitemap.xml
Scanning website...
Fetching URLs. This might take some time...
Scanning website...
#purple-a11y will then start scraping from the file link provided above.
#Console results
If the sitemap URL provided is invalid, an error message will be prompted for you to provide a valid input.
>> Invalid sitemap format. Please provide a URL with a valid sitemap.
% npm start
┌────────────────────────────────────────────────────────────┐
│ Purple A11y (ver ) │
│ We recommend using Chrome browser for the best experience. │
│ │
│ Welcome back User! │
│ (Refer to readme.txt on how to change your profile) │
└────────────────────────────────────────────────────────────┘
? What would you like to scan? Website
? Do you want purple-a11y to run in the background? Yes
? Which screen size would you like to scan? (Use arrow keys) Desktop
? Please enter URL of website: https://www.domain.org
If the website URL provided is invalid, an error message will be prompted for you to provide a valid input.
>> Cannot resolve URL. Please provide a valid URL.
% npm start
┌────────────────────────────────────────────────────────────┐
│ Purple A11y (ver ) │
│ We recommend using Chrome browser for the best experience. │
│ │
│ Welcome back User! │
│ (Refer to readme.txt on how to change your profile) │
└────────────────────────────────────────────────────────────┘
? What would you like to scan? Website
? Do you want purple-a11y to run in the background? No
? Which screen size would you like to scan? (Use arrow keys) (Use arrow keys)
❯ Desktop
Mobile
Custom
Choose Mobile
for a default mobile screen size scan and Custom
to choose a device or specify viewport width options.
Custom flow allows you to specify a user journey by enabling you to click the scan button on each desired webpage on a browser to initiate scan. This is useful to scan websites that require user and form input.
Custom flow
in the menu selection.% npm start
┌────────────────────────────────────────────────────────────┐
│ Purple A11y (ver ) │
│ We recommend using Chrome browser for the best experience. │
│ │
│ Welcome back User! │
│ (Refer to readme.txt on how to change your profile) │
└────────────────────────────────────────────────────────────┘
? What would you like to scan?
Sitemap
Website
❯ Custom
Other options:
exclusions.txt
. An example of exclusions.txt
:\.*login.singpass.gov.sg\.*
If the custom flow fails to start, you might be running multiple versions of Playwright. Re-install Playwright:
%USERPROFILE%\AppData\Local\ms-playwright
where %USERPROFILE%
is typically located at C:\Users\<username>
.~/Library/Caches/ms-playwright
where ~
refers to /Users/<username>
.npx playwright@1.27.1 install
CLI mode is designed to be run in continuous integration (CI) environment.
Run npm run cli
for a set of command-line parameters available.
Usage: npm run cli -- -c <crawler> -d <device> -w <view
port> -u <url> OPTIONS
Options:
--help Show help [boolean]
-c, --scanner Type of scan, 1) sitemap, 2) website crawl,
3) custom flow, 4) intelligent
elligent
[required] [choices: "sitemap", "website", "custom", "intelligent"]
-u, --url Website URL you want to scan
[string] [required]
-d, --customDevice Device you want to scan [string]
-w, --viewportWidth Viewport width (in pixels) you want to scan
[number]
-o, --zip Zip filename to save results [string]
-p, --maxpages Maximum number of pages to scan (default: 1
00). Only available in website and sitemap
scans [number]
-f, --safeMode Disable dynamically clicking of page button
s and links to find links, which resolve is
sues on some websites. [yes / no]
[string] [default: "no"]
-h, --headless Run the scan in headless mode. [yes / no]
[string] [default: "yes"]
-b, --browserToRun Browser to run the scan on: 1) Chromium, 2)
Chrome, 3) Edge. Defaults to Chromium.
[choices: "chromium", "chrome", "edge"] [default: "chrome"]
-s, --strategy Crawls up to general (same parent) domains,
or only specific hostname. Defaults to "sa
me-domain".
[choices: "same-domain", "same-hostname"]
-e, --exportDirectory Preferred directory to store scan results.
Path is relative to your home directory.
[string]
-j, --customFlowLabel Give Custom Flow Scan a label for easier re
ference in the report [string]
-k, --nameEmail To personalise your experience, we will be
collecting your name, email address and app
usage data. Your information fully complie
s with GovTech’s Privacy Policy. Please pro
vide your name and email address in this fo
rmat "John Doe:john@domain.com".
[string] [required]
-t, --specifiedMaxConcurrency Maximum number of pages to scan concurrentl
y. Use for sites with throttling. Defaults
to 25. [number]
-i, --fileTypes File types to include in the scan. Defaults
to html-only.
[string] [choices: "all", "pdf-only", "html-only"] [default: "html-only"]
-x, --blacklistedPatternsFilename Txt file that has a list of pattern of doma
ins to exclude from accessibility scan sepa
rated by new line
[string] [default: "exclusions.txt"]
-a, --additional Additional features to include in the repor
t:
screenshots - Include element screensho
ts in the generated report
none - Exclude
all additional features in the generated re
port
[string] [choices: "screenshots", "none"] [default: "screenshots"]
-q, --metadata Json string that contains additional scan m
etadata for telemetry purposes. Defaults to
"{}" [string] [default: "{}"]
-r, --followRobots Crawler adheres to robots.txt rules if it e
xists. [yes / no] [string] [default: "no"]
-m, --header The HTTP authentication header keys and the
ir respective values to enable crawler acce
ss to restricted resources. [string]
Examples:
To scan sitemap of website:', 'npm run cli -- -c [ 1 | sitemap ] -u <url_lin
k> [ -d <device> | -w <viewport_width> ]
To scan a website', 'npm run cli -- -c [ 2 | website ] -u <url_link> [ -d <d
evice> | -w <viewport_width> ]
To start a custom flow scan', 'npm run cli -- -c [ 3 | custom ] -u <url_link
> [ -d <device> | -w <viewport_width> ]
If the device name contains (
and )
, wrap the device name in single quotes when entered into the CLI.
Please note that -d
and -w
are mutually exclusive. If none are specified, the default device used for the CLI scan is Desktop.
For example, to conduct a website scan to the URL "http://localhost:8000" and write to "a11y-scan-results.zip" with an 'iPad (gen 7) landscape' screen, run
npm run cli -- -c 2 -o a11y-scan-results.zip -u http://localhost:8000 -d 'iPad (gen 7) landscape'
If the site you want to scan has a query string wrap the link in single quotes when entered into the CLI.
For example, to conduct a website scan to the URL "http://localhost:8000" and write to "a11y-scan-results.zip" with a custom screen width '360', run
npm run cli -- -c 2 -o a11y-scan-results.zip -u "http://localhost:8000" -w 360
Once a scan of the site is completed.
A report will be downloaded into the current working directory.
Each Issue has its own severity "Must Fix" / "Good to Fix" based on the WCAG 2.2 Conformance.
For details on which accessibility scan results triggers a "Must Fix" / "Good to Fix" findings, you may refer to Scan Issue Details.
Please refer to the information below to assist in debugging. Most errors below are due to the switching between Node.js versions.
Issue: When your Node.js version is incompatible, you may face the following syntax error.
const URL_NO_COMMAS_REGEX = RegExp('https?://(www\\.)?[\\p{L}0-9][-\\p{L}0-9@:%._\\+~#=]{0,254}[\\p{L}0-9]\\.[a-z]{2,63}(:\\d{1,5})?(/[-\\p{L}0-9@:%_\\+.~#?&//=\\(\\)]*)?', 'giu'); // eslint-disable-line
^
SyntaxError: Invalid regular expression: /https?://(www\.)?[\p{L}0-9][-\p{L}0-9@:%\._\+~#=]{0,254}[\p{L}0-9]\.[a-z]{2,63}(:\d{1,5})?(/[-\p{L}0-9@:%_\+.~#?&//=\(\)]*)?/: Invalid escape
Solution: Install Node.js versions >= 20, i.e. Node.js v20 and above.
Issue: When you switch between different versions of Node.js in your environment, you may face the following error.
<user_path>/purple-a11y/node_modules/bindings/bindings.js:91
throw e
^
Error: The module '<module_file_path>'
was compiled against a different Node.js version using
NODE_MODULE_VERSION 57. This version of Node.js requires
NODE_MODULE_VERSION 88. Please try re-compiling or re-installing
the module (for instance, using `npm rebuild` or `npm install`).
Solution: As recommended in the error message, run npm rebuild
or npm install
Issue: Not able to run Purple A11y due to the following error shown below
dyld: lazy symbol binding failed: Symbol not found: __ZN2v87Isolate37AdjustAmountOfExternalAllocatedMemoryEx
Referenced from: <user_path>/purple-a11y/node_modules/libxmljs/build/Release/xmljs.node
Expected in: flat namespace
dyld: Symbol not found: __ZN2v87Isolate37AdjustAmountOfExternalAllocatedMemoryEx
Referenced from: <user_path>/PURPLE_A11y/purple-a11y/node_modules/libxmljs/build/Release/xmljs.node
Expected in: flat namespace
zsh: abort node index.js
Solutions:
node_modules
folder and re-install the NPM packages with npm install
.Limitation: Due to animations causing elements to shift out of the viewport after an Axe scan, there's a risk of element screenshots timing out within 5 seconds if the element is not found. This known issue is particularly prevalent in scenarios like carousels with interval-based transitions.
If you find a scan takes too long to complete due to large website, or there are too many pages in a sitemap to scan, you may choose to limit number of pages scanned.
To do this, run CLI mode npm run cli --
with the needed settings and specify -p 10
where 10
is the number of pages you wish to scan.
We recommend looking at our Technology Stack to understand the usage of each component. Take your time to understand.
Purple A11y uses third-party open-source tools that may be downloaded over the Internet during the installation process of Purple A11y. Users should be aware of the libraries used by examining package.json
.
Purple A11y may send information to the website, URL and HTML code snippets where the user chooses to initiate a Purple A11y scan for telemetry purposes.