Oobee (CLI)

Oobee (formerly known as 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 Oobee. The official application can only be downloaded at https://go.gov.sg/oobee-cli. 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.

For the user-friendly desktop application, check out Oobee.

Technology Stack

1. Crawlee
2. Axe-core
3. Node.js
4. Playwright
5. Pixelmatch
6. Corretto
7. VeraPDF

Using Oobee as a NodeJS module

If you wish to use Oobee 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.

Prerequisites and Installations

Portable Oobee

Portable Oobee is the recommended way to run Oobee as it reduces the difficulty for installation. Refer to Installation Guide for step-by-step instructions for portable Oobee.

Manual Installation

Please ensure the following requirements are met:

Node.js

• A Node distribution of 20 (LTS) or above.
• To check your version of Node, go into terminal and paste the command bellow

node -v

• If you do not have node, or if there is a need to manage your node versions, you can consider using Node Version Manager (NVM). After NVM is installed, you can then install an LTS version of Node:

# Install NodeJS version with NVM
nvm install --lts

# For subsequent use, you will need to run the command below each time you open a new terminal
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

java --version

• If you do not have java, you can consider installing Corretto distribution of OpenJDK.

VeraPDF

• VeraPDF is used for scanning PDF files. Install VeraPDF by following the install guide. You may wish to use the Automated installation script provided on that page, and changing the XML installation script section <installpath>/tmp/verapdf-test</installpath> to a location of your choice.
• Ensure you have VeraPDF set in PATH then verify verapdf is installed correctly:

# Invoke the VeraPDF installer
# Windows users should use vera-install.bat instead of vera-install
./verapdf-install ./auto-install.xml

# Add VeraPDF to PATH. For subsequent use, you will need to run the command below each time you open a new terminal
export PATH="<location of verapdf>:$PATH"

# Verify verapdf is installed
verapdf --version

Environment variables (Optional)

| Variable Name | Description | Default | | ------------- | ----------- | ------- | | OOBEE_VERBOSE | When set to true, log output goes to console | false | | OOBEE_FAST_CRAWLER| When set to true, increases scan concurrency at a rapid rate. Experimental, may cause system stability issues on low-powered devices. | false| | OOBEE_VALIDATE_URL| When set to true, validates if URLs are valid and exits. | false | | OOBEE_LOGS_PATH | When set, logs are written to this path. | | | WARN_LEVEL | Only used in tests. | | | OOBEE_DISABLE_BROWSER_DOWNLOAD | Experimental flag to disable file downloads on Chrome/Chromium/Edge. Does not affect Local File scan | | | OOBEE_SLOWMO | Experimental flag to slow down web browser behaviour by specified duration (in miliseconds) | | | HTTP_PROXY | URL of the proxy server to be used for HTTP requests (e.g. http://proxy.example.com:8080). | | | HTTPS_PROXY | URL of the proxy server to be used for HTTPS requests (e.g. https://proxy.example.com:8080). | | | ALL_PROXY | URL of the proxy server to be used for all requests, typically used for SOCKS5 proxies (e.g. socks5://proxy.example.com:1080. Note: IPv6 direct connections may still continue even though socks5 proxy is specified due to a known issue with Chrome/Chromium. (Recommended workaround is to turn off IPv6 at host-level). | | | NO_PROXY | Comma-separated list of domains that should bypass the proxy (e.g. localhost,127.0.0.1,.example.com). | | | INCLUDE_PROXY | Comma-separated list of domains that should specifically be routed through the proxy. | |

Environment variables used internally (Do not set)

Do not set these environment variables or behaviour might change unexpectedly. | Variable Name | Description | | ------------- | ----------- | | CRAWLEE_LOG_LEVEL | https://crawlee.dev/docs/guides/configuration#crawlee_log_level | | CRAWLEE_STORAGE_DIR | https://crawlee.dev/docs/guides/configuration#crawlee_storage_dir | | CRAWLEE_HEADLESS | https://crawlee.dev/docs/guides/configuration#crawlee_headless |

Facing issues?

Please refer to Troubleshooting section for more information.

---

Features

Oobee can perform the following to scan the target URL.

• To run Oobee 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. Oobee 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.

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\Oobee\userData.txt"
• MacOS (Terminal): rm "$HOME/Library/Application Support/Oobee/userData.txt"

If userData.txt does not exists just run npm start.

Scan Selection

You can interact via your arrow keys.

% npm start
┌────────────────────────────────────────────────────────────┐
│  Oobee (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

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
┌────────────────────────────────────────────────────────────┐
│ Oobee (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 oobee to run in the background? (Y/n) No

Sitemap Scan

% npm start
┌────────────────────────────────────────────────────────────┐
│ Oobee (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 oobee 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...

#oobee 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.

Website Scan

% npm start
┌────────────────────────────────────────────────────────────┐
│ Oobee (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 oobee 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.

Customised Mobile Device Scan

% npm start
┌────────────────────────────────────────────────────────────┐
│ Oobee (ver      )