diff --git a/.github/workflows/image.yml b/.github/workflows/image.yml index 41b1e9a0..5c2d73bd 100644 --- a/.github/workflows/image.yml +++ b/.github/workflows/image.yml @@ -13,13 +13,13 @@ jobs: - name: Check out repository code uses: actions/checkout@v3 with: - path: purple-hats + path: purple-a11y - name: Copy scripts to parent directory run: | - cp ${{github.workspace}}/purple-hats/scripts/*.ps1 ${{github.workspace}} - cp ${{github.workspace}}/purple-hats/scripts/*.cmd ${{github.workspace}} - cp ${{github.workspace}}/purple-hats/scripts/*.xml ${{github.workspace}} + cp ${{github.workspace}}/purple-a11y/scripts/*.ps1 ${{github.workspace}} + cp ${{github.workspace}}/purple-a11y/scripts/*.cmd ${{github.workspace}} + cp ${{github.workspace}}/purple-a11y/scripts/*.xml ${{github.workspace}} - name: Install Purple dependencies for Windows shell: pwsh @@ -28,20 +28,20 @@ jobs: - name: Zip entire Purple folder (Windows) shell: pwsh - run: Compress-Archive -Path ${{github.workspace}}/* -DestinationPath purple-hats-portable-windows.zip + run: Compress-Archive -Path ${{github.workspace}}/* -DestinationPath purple-a11y-portable-windows.zip - name: Upload Windows artifact uses: actions/upload-artifact@v3 with: - name: purple-hats-portable-windows - path: ./purple-hats-portable-windows.zip + name: purple-a11y-portable-windows + path: ./purple-a11y-portable-windows.zip - name: Release Windows artifact uses: softprops/action-gh-release@v1 if: startsWith(github.ref, 'refs/tags/') with: files: | - purple-hats-portable-windows.zip + purple-a11y-portable-windows.zip mac-install-purple: runs-on: self-hosted @@ -56,15 +56,15 @@ jobs: - name: Check out repository code uses: actions/checkout@v3 with: - path: purple-hats + path: purple-a11y - name: Grant execute permissions for user run: chmod ugo+rwx ./scripts/*.command ./scripts/*.sh - working-directory: purple-hats + working-directory: purple-a11y - name: Copy scripts to parent directory run: | - cp ./purple-hats/scripts/{*.command,*.sh,*.xml} ${{ github.workspace }} + cp ./purple-a11y/scripts/{*.command,*.sh,*.xml} ${{ github.workspace }} - name: Install Purple dependencies for MacOS run: | @@ -77,8 +77,8 @@ jobs: # Paths to the binaries you want to sign BINARIES=( - "./purple-hats/node_modules/playwright/node_modules/fsevents/fsevents.node" - "./purple-hats/node_modules/fsevents/fsevents.node" + "./purple-a11y/node_modules/playwright/node_modules/fsevents/fsevents.node" + "./purple-a11y/node_modules/fsevents/fsevents.node" ) # Loop through the binary paths and sign each one with a secure timestamp @@ -93,17 +93,17 @@ jobs: - name: Zip entire Purple folder (Mac) run: | - zip purple-hats-portable-mac.zip -y -r ./ + zip purple-a11y-portable-mac.zip -y -r ./ - name: Upload Mac artifact uses: actions/upload-artifact@v3 with: - name: purple-hats-portable-mac - path: ./purple-hats-portable-mac.zip + name: purple-a11y-portable-mac + path: ./purple-a11y-portable-mac.zip - name: Release Mac artifact uses: softprops/action-gh-release@v1 if: startsWith(github.ref, 'refs/tags/') with: files: | - purple-hats-portable-mac.zip + purple-a11y-portable-mac.zip diff --git a/Dockerfile b/Dockerfile index 95866f42..7d6220c1 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,7 +1,7 @@ # Use Node LTS alpine distribution FROM node:lts-alpine -# Installation of packages for purple-hats and chromium +# Installation of packages for purple-a11y and chromium RUN apk add build-base gcompat g++ make python3 zip bash git chromium openjdk11-jre # Installation of VeraPDF @@ -28,7 +28,7 @@ RUN latest_version=$(ls -d /opt/verapdf-greenfield-* | sort -V | tail -n 1) && [ "$latest_version/verapdf-install" "/opt/verapdf-auto-install-docker.xml" RUN rm -rf /opt/verapdf-installer.zip /opt/verapdf-greenfield-* -# Set purple-hats directory +# Set purple-a11y directory WORKDIR /app # Copy package.json to working directory, perform npm install before copying the remaining files diff --git a/INSTALLATION.md b/INSTALLATION.md index afebbcc5..42aa3567 100644 --- a/INSTALLATION.md +++ b/INSTALLATION.md @@ -1,61 +1,61 @@ ## Installation Guide -Purple hats is provided as a portable distribution which minimises installation steps required for Windows and Mac. +Purple A11y is provided as a portable distribution which minimises installation steps required for Windows and Mac. -### About Purple hats -Purple hats is a customisable, automated accessibility testing tool that allows software development teams to find and fix accessibility problems to improve persons with disabilities (PWDs) access to digital services. +### About Purple A11y +Purple A11y is a customisable, automated accessibility testing tool that allows software development teams to find and fix accessibility problems to improve persons with disabilities (PWDs) access to digital services. ### System Requirements -* Purple HATS can run on MacOS Big Sur or above, and a [supported](https://learn.microsoft.com/en-us/windows/release-health/supported-versions-windows-client) version of Windows 10 (64-bit) or Windows 11. +* Purple A11y can run on MacOS Big Sur or above, and a [supported](https://learn.microsoft.com/en-us/windows/release-health/supported-versions-windows-client) version of Windows 10 (64-bit) or Windows 11. * Google Chrome browser is [installed](https://www.google.com/chrome). -* One-time Internet access is needed to download and install Purple HATS Desktop. -* You are recommended to be logged on to an admin user to run Purple HATS Desktop. +* One-time Internet access is needed to download and install Purple A11y Desktop. +* You are recommended to be logged on to an admin user to run Purple A11y Desktop. ### Windows
Click here for Windows setup instructions #### Download Portable Copy -* Download and extract latest [purple-hats-portable-windows.zip](https://github.com/GovTechSG/purple-hats/releases/latest/download/purple-hats-portable-windows.zip). +* Download and extract latest [purple-a11y-portable-windows.zip](https://github.com/GovTechSG/purple-a11y/releases/latest/download/purple-a11y-portable-windows.zip). * Tip: To extract files, right-click the Compressed zip file and click "Extract All…" in the context menu. -#### Run Purple hats - * Navigate to the folder containing purple-hats-portable. - * Double-click `hats_shell.cmd` (Windows Command Script file). - Screenshot of Windows Explorer with hats_shell.cmd selected +#### Run Purple A11y + * Navigate to the folder containing purple-a11y-portable-windows. + * Double-click `a11y_shell.cmd` (Windows Command Script file). + Screenshot of Windows Explorer with a11y_shell.cmd selected - * A Windows Command Prompt window should open with contents as illustrated below. `hats_shell` will automatically prepare your system to run Purple hats. + * A Windows Command Prompt window should open with contents as illustrated below. `a11y_shell` will automatically prepare your system to run Purple a11y. ``` -hats Shell - Created By younglim - NO WARRANTY PROVIDED +a11y Shell - Created By younglim - NO WARRANTY PROVIDED ================================================================ -INFO: Stored current working directory at C:\Users\a11y\Downloads\purple-hats-portable-windows +INFO: Stored current working directory at C:\Users\a11y\Downloads\purple-a11y-portable-windows INFO: Set path to node for this session INFO: Set path to node_modules for this session INFO: Set path to npm-global for this session INFO: Set path to Playwright cache for this session INFO: Set path to ImageMagick for this session -INFO: Set path to purple-hats for this session +INFO: Set path to purple-a11y for this session -PS C:\Users\username\Downloads\purple-hats-portable-windows> +PS C:\Users\username\Downloads\purple-a11y-portable-windows> ``` - * Type in the following commands into the window. The following commands will navigate your Command Prompt window to the `purple-hats` sub-directory and initiate a scan + * Type in the following commands into the window. The following commands will navigate your Command Prompt window to the `purple-a11y` sub-directory and initiate a scan ``` -cd purple-hats +cd purple-a11y node index ``` * If a Windows Firewall prompt appears, click "Allow access" -Windows Firewall prompt for Allow access +Windows Firewall prompt for Allow access * You should then see your Windows Command Prompt window updated with the following contents ``` -PS C:\Users\username\Downloads\purple-hats-portable-windows> cd purple-hats -PS C:\Users\username\Downloads\purple-hats-portable-windows\purple-hats> node index +PS C:\Users\username\Downloads\purple-a11y-portable-windows> cd purple-a11y +PS C:\Users\username\Downloads\purple-a11y-portable-windows\purple-a11y> node index ┌────────────────────────────────────────────────────────────┐ -│ Welcome to HATS Accessibility Testing Tool! │ +│ Welcome to A11y Accessibility Testing Tool! │ │ We recommend using Chrome browser for the best experience. │ │ │ │ Version: ░░░░░░ │ @@ -66,7 +66,7 @@ PS C:\Users\username\Downloads\purple-hats-portable-windows\purple-hats> node in custom flow ``` - * Follow the steps at [Features](https://github.com/GovTechSG/purple-hats#features) for more information on how to run a scan. + * Follow the steps at [Features](https://github.com/GovTechSG/purple-a11y#features) for more information on how to run a scan.
@@ -75,23 +75,23 @@ PS C:\Users\username\Downloads\purple-hats-portable-windows\purple-hats> node in Click here for MacOS setup instructions #### Download Portable Copy - * Download and extract [purple-hats-portable-mac.zip](https://github.com/GovTechSG/purple-hats/releases/latest/download/purple-hats-portable-mac.zip) version. - * Tip: To extract files in Mac, double-click on `purple-hats-portable-mac.zip` file, usually located at your Downloads folder. A new folder with the name `purple-hats-mac` will appear in Finder. + * Download and extract [purple-a11y-portable-mac.zip](https://github.com/GovTechSG/purple-a11y/releases/latest/download/purple-a11y-portable-mac.zip) version. + * Tip: To extract files in Mac, double-click on `purple-a11y-portable-mac.zip` file, usually located at your Downloads folder. A new folder with the name `purple-a11y-portable-mac` will appear in Finder. -#### Run Purple hats - * Navigate to the folder `purple-hats-mac`, usually located at your Downloads folder. - * Right-click `hats_shell.command`. Then click `Open` in the context menu. - Screenshot of right-click hats_shell.command and Open +#### Run Purple A11y + * Navigate to the folder `purple-a11y-portable-mac`, usually located at your Downloads folder. + * Right-click `a11y_shell.command`. Then click `Open` in the context menu. + Screenshot of right-click a11y_shell.command and Open * A prompt as follows will appear like below. Click `Open`. - MacOS prompt for unidentified developer + MacOS prompt for unidentified developer - * A Terminal window should open with contents as illustrated below. `hats_shell` will automatically prepare your system to run Purple hats. + * A Terminal window should open with contents as illustrated below. `a11y_shell` will automatically prepare your system to run Purple A11y. ``` Last login: Thu Mar 16 10:48:05 on ttys002 -/Users/username/Downloads/purple-hats-portable-mac/hats_shell.command ; exit; -username@hostname ~ % /Users/username/Downloads/purple-hats-portable-mac/hats_shell.command ; exit; -hats Shell - Created By younglim - NO WARRANTY PROVIDED +/Users/username/Downloads/purple-a11y-portable-mac/a11y_shell.command ; exit; +username@hostname ~ % /Users/username/Downloads/purple-a11y-portable-mac/a11y_shell.command ; exit; +a11y Shell - Created By younglim - NO WARRANTY PROVIDED ================================================================ INFO: Setting path to node for this session @@ -100,21 +100,21 @@ INFO: Set path to Playwright cache for this session INFO: Set symbolic link to ImageMagick INFO: Set path to ImageMagick binaries INFO: Removing com.apple.quarantine attributes for required binaries to run -username@hostname purple-hats-portable-mac % +username@hostname purple-a11y-portable-mac % ``` - * Type in the following commands into the window. The following commands will navigate your Terminal window to the `purple-hats` sub-directory and initiate a scan + * Type in the following commands into the window. The following commands will navigate your Terminal window to the `purple-a11y` sub-directory and initiate a scan ``` -cd purple-hats +cd purple-a11y node index ``` * You should then see your Terminal window updated with the following contents ``` -username@hostname purple-hats-portable-mac % cd purple-hats -username@hostname purple-hats % node index +username@hostname purple-a11y-portable-mac % cd purple-a11y +username@hostname purple-a11y % node index ┌────────────────────────────────────────────────────────────┐ -│ Welcome to HATS Accessibility Testing Tool! │ +│ Welcome to A11y Accessibility Testing Tool! │ │ We recommend using Chrome browser for the best experience. │ │ │ │ Version: ░░░░░░ │ @@ -125,5 +125,5 @@ username@hostname purple-hats % node index custom flow ``` - * Follow the steps at [Features](https://github.com/GovTechSG/purple-hats#features) for more information on how to run a scan. + * Follow the steps at [Features](https://github.com/GovTechSG/purple-a11y#features) for more information on how to run a scan. diff --git a/INTEGRATION.md b/INTEGRATION.md index 0e3b3577..bb2200d9 100644 --- a/INTEGRATION.md +++ b/INTEGRATION.md @@ -1,6 +1,6 @@ -## Integrating Purple HATS with end-to-end testing frameworks +## Integrating Purple A11y with end-to-end testing frameworks -Purple HATS provides functionalities that makes it possible to be integrated with end-to-end testing frameworks such as [Cypress](https://www.cypress.io/) and [Playwright](https://playwright.dev/). +Purple A11y provides functionalities that makes it possible to be integrated with end-to-end testing frameworks such as [Cypress](https://www.cypress.io/) and [Playwright](https://playwright.dev/). ### Prerequisites @@ -10,40 +10,40 @@ In order to use this functionality, the testing framework must support: - Injection of JavaScript into the document that is being tested. - Execution of JavaScript in the context of the document and retrieval of results back into the NodeJS environment after execution. -### How to include Purple HATS in your project +### How to include Purple A11y in your project -1. Add Purple HATS to your project by running the following command: +1. Add Purple A11y to your project by running the following command: `npm install --save-dev @govtechsg/purple-hats` -2. In the file of choice, import Purple HATS using: +2. In the file of choice, import Purple A11y using: - `import purpleHatsInit from '@govtechsg/purple-hats'` + `import purpleA11yInit from '@govtechsg/purple-hats'` - Note that Purple HATS should be imported in a script that runs in a NodeJS environment. + Note that Purple A11y should be imported in a script that runs in a NodeJS environment. -3. Create an instance of Purple HATS with: +3. Create an instance of Purple A11y with: - `const ph = await purpleHatsInit(entryUrl)` + `const purpleA11y = await purpleA11yInit(entryUrl)` - `entryUrl` should be a valid URL referring to the domain of the website to be scanned with Purple HATS. + `entryUrl` should be a valid URL referring to the domain of the website to be scanned with Purple A11y. ### API Reference -#### `async purpleHatsInit(entryUrl, testLabel, name, email, needsReview, includeScreenshots, viewportSettings, thresholds, scanAboutMetadata)` +#### `async purpleA11yInit(entryUrl, testLabel, name, email, needsReview, includeScreenshots, viewportSettings, thresholds, scanAboutMetadata)` -Returns an instance of Purple HATS +Returns an instance of Purple A11y ##### Parameters - `entryUrl` - - Initial URL to start the purple hats scan + - Initial URL to start the purple a11y scan - `testLabel` - Label for test in report - `name` - - For PH data collection purposes + - For Purple A11y data collection purposes - `email` - - For PH data collection purposes + - For Purple A11y data collection purposes - `needsReview` (optional) - Show potential false positive issues in the report. Defaults to false. - `includeScreenshots` (optional) @@ -54,7 +54,7 @@ Returns an instance of Purple HATS - Object containing the max number of mustFix or goodToFix issue occurrences before an error is thrown for test failure. Does not fail tests by default. Example: `{ mustFix: 1, goodToFix: 3 }` - `scanAboutMetadata` (optional) - Include additional information in the Scan About section of the report by passing in a JSON object. -#### Purple HATS Instance +#### Purple A11y Instance ##### Properties @@ -108,24 +108,24 @@ Checks the accumulated issue occurrences count against the specified threshold a `async terminate()` -Stops the Purple HATS instance and generates the scan report and other scan result artifacts +Stops the Purple A11y instance and generates the scan report and other scan result artifacts ### How to use Example usages for Cypress and Playwright can be found in [this section](#example-usages). -With reference to an instance of Purple HATS as `ph`: +With reference to an instance of Purple A11y as `purpleA11y`: -1. Fetch the necessary scripts needed to be injected to document to be scanned by executing `ph.getScripts()`. The scripts will be returned as a string. +1. Fetch the necessary scripts needed to be injected to document to be scanned by executing `purpleA11y.getScripts()`. The scripts will be returned as a string. 2. Inject the scripts into the document to be scanned. The easiest way that this can be done is by using `eval()` in the document's environment. - Note that this step needs to be done for every page visited. 3. Run a scan by executing `runA11yScan()` in the document's environment. - By default, the scan will be run for the entire page. - It is possible to run the scan for specific sections or elements in the page. One way to do this is to pass an array of CSS selectors of the elements to be scanned into `runA11yScan`. For example, `runA11yScan(['#my-component', 'button'])`. Other acceptable forms of argument can be found [here](https://github.com/dequelabs/axe-core/blob/develop/doc/API.md#context-parameter). -4. Pass the scan results back into the NodeJS environment where `ph` is in. -5. Push the results using `await ph.pushScanResults(scanResults)`. +4. Pass the scan results back into the NodeJS environment where `purpleA11y` is in. +5. Push the results using `await purpleA11y.pushScanResults(scanResults)`. 6. Repeat steps 2-5 as many times as desired. -7. Terminate Purple HATS by using `await ph.terminate()`. A folder containing the details and report of your scan will be created, under the directory `results` which can be found in your project's root directory. +7. Terminate Purple A11y by using `await purpleA11y.terminate()`. A folder containing the details and report of your scan will be created, under the directory `results` which can be found in your project's root directory. ### Example usages @@ -150,7 +150,7 @@ Change the type of npm package to module by running npm pkg set type="modu Install the following node dependencies by running npm install cypress @govtechsg/purple-hats --save-dev -Navigate to node_modules/@govtechsg/purple-hats and run npm install within the folder to install remaining Purple HATS dependencies: +Navigate to node_modules/@govtechsg/purple-hats and run npm install within the folder to install remaining Purple A11y dependencies: cd node_modules/@govtechsg/purple-hats npm install @@ -159,7 +159,7 @@ Navigate to node_modules/@govtechsg/purple-hats and run npm i Create cypress.config.js with the following contents, and change your Name, E-mail address, and boolean value for whether rule items requiring manual review in the report should be displayed below: import { defineConfig } from "cypress"; - import purpleHatsInit from "@govtechsg/purple-hats"; + import purpleA11yInit from "@govtechsg/purple-hats"; // viewport used in tests to optimise screenshots const viewportSettings = { width: 1920, height: 1040 }; @@ -168,7 +168,7 @@ Create cypress.config.js with the following contents, and change yo // additional information to include in the "Scan About" section of the report const scanAboutMetadata = { browser: 'Chrome (Desktop)' }; - const ph = await purpleHatsInit( + const purpleA11y = await purpleA11yInit( "https://govtechsg.github.io", // initial url to start scan "Demo Cypress Scan", // label for test "Your Name", @@ -187,21 +187,21 @@ Create cypress.config.js with the following contents, and change yo e2e: { setupNodeEvents(on, _config) { on("task", { - getPhScripts() { - return ph.getScripts(); + getPurpleA11yScipts() { + return purpleA11y.getScripts(); }, - async pushPhScanResults({res, metadata, elementsToClick}) { - return await ph.pushScanResults(res, metadata, elementsToClick); + async pushPurpleA11yScanResults({res, metadata, elementsToClick}) { + return await purpleA11y.pushScanResults(res, metadata, elementsToClick); }, returnResultsDir() { - return `results/${ph.randomToken}_${ph.scanDetails.urlsCrawled.scanned.length}pages/reports/report.html`; + return `results/${purpleA11y.randomToken}_${purpleA11y.scanDetails.urlsCrawled.scanned.length}pages/reports/report.html`; }, - finishPhTestCase() { - ph.testThresholdsAndReset(); + finishPurpleA11yTestCase() { + purpleA11y.testThresholdsAndReset(); return null; }, - async terminatePh() { - return await ph.terminate(); + async terminatePurpleA11y() { + return await purpleA11y.terminate(); }, }); }, @@ -210,56 +210,56 @@ Create cypress.config.js with the following contents, and change yo Create a sub-folder and file cypress/support/e2e.js with the following contents:: - Cypress.Commands.add("injectPhScripts", () => { - cy.task("getPhScripts").then((s) => { + Cypress.Commands.add("injectPurpleA11yScripts", () => { + cy.task("getPurpleA11yScipts").then((s) => { cy.window().then((win) => { win.eval(s); }); }); }); - Cypress.Commands.add("runPhScan", (items={}) => { + Cypress.Commands.add("runPurpleA11yScan", (items={}) => { cy.window().then(async (win) => { const { elementsToScan, elementsToClick, metadata } = items; const res = await win.runA11yScan(elementsToScan); - cy.task("pushPhScanResults", {res, metadata, elementsToClick}).then((count) => { return count }); + cy.task("pushPurpleA11yScanResults", {res, metadata, elementsToClick}).then((count) => { return count }); }); }); - Cypress.Commands.add("finishPhTestCase", () => { - cy.task("finishPhTestCase"); + Cypress.Commands.add("finishPurpleA11yTestCase", () => { + cy.task("finishPurpleA11yTestCase"); }); - Cypress.Commands.add("terminatePh", () => { - cy.task("terminatePh"); + Cypress.Commands.add("terminatePurpleA11y", () => { + cy.task("terminatePurpleA11y"); }); Create cypress/e2e/spec.cy.js with the following contents: describe("template spec", () => { - it("should run purple HATS", () => { + it("should run purple A11y", () => { cy.visit( "https://govtechsg.github.io/purple-banner-embeds/purple-integrated-scan-example.htm" ); - cy.injectPhScripts(); - cy.runPhScan(); + cy.injectPurpleA11yScripts(); + cy.runPurpleA11yScan(); cy.get("button[onclick=\"toggleSecondSection()\"]").click(); // Run a scan on and