ACT Tools

This repository contains a collection of tools for the Accessibility Conformance Testing Task Force. This project is chiefly written using TypeScript, and relies on ts-node to run.

To use this project, you will need the following. Any version released in the last 12 months should do.

• git
• NodeJS
• Yarn

Installation

To install this project from the command line run the following commands:

git clone git@github.com/act-rules/act-tools.git
cd act-tools
yarn

Usage

Rule Transformer

This tool takes rule markdown files and transforms it to a markdown file that the WAI website can consume using Jekyll. To run it, use a command like the following:

yarn transform-rule \
  --rulesDir "../act-rules.github.io/_rules/" \
  --glossaryDir "../act-rules.github.io/pages/glossary/" \
  --outDir "../wcag-act-rules/" \
  --testAssetsDir "../act-rules.github.io/test-assets/" \
  --ruleIds 5f99a7,6cfa84

Build Examples

This tool takes rule markdown files, extracts the examples from it, saves those into a directory, and creates a new testcases.json file.

yarn build-examples \
  --rulesDir "../act-rules.github.io/_rules/" \
  --outDir "../wcag-act-rules/" \
  --testAssetsDir "../act-rules.github.io/test-assets/" \
  --ruleIds 5f99a7,6cfa84

Map an implementation

The map-implementation tool takes the test results from an implementation and works out how that implementation maps to ACT.

yarn map-implementation \
  --name "Acme Test Tool" \
  --vendor "Acme Corp" \
  --jsonReport "./acme-earl-report.json" \
  --output "../implementations/{organization}-{tool}.json" \
  --testCaseJson "../wcag-act-rules/content/testcases.json"

This script outputs a file implementations/acme-test-tool-mapping.json, which looks something like this:

{
  "vendor": "Acme Corp",
  "name": "Acme Test Tool",
  "summary": {
    "consistent": 20,
    "partiallyConsistent": 1,
    "inconsistent": 69,
    "incomplete": 68
  },
  "actMapping": [{
    "ruleId": "b5c3f8",
    "ruleName": "HTML page has `lang` attribute",
    "complete": false,
    "consistency": "consistent",
    "implementations": [{ ...details }]
  }]
}

Implementation Batch Update

The implementations-update tool generates implementation tables for rule pages. It uses an implementations.yml file which describes all implementations that need to be included.

yarn implementations-update \
  --implementations "../wcag-act-rules/implementations.yml" \
  --testCaseJson "https://act-rules.github.io/testcases.json" \
  --outDir "../wcag-act-rules/implementations/"
  --tableFilePattern "../wcag-act-rules/content/implementations/{ruleId}.md"

Development

The following commands are available for use in development:

• yarn build: Compile the TypeScript, and will tell you if there are any type errors
• yarn test: Executes all the tests in __tests__ directories using Jest
• yarn develop: Run tests, and watch for changes
• yarn lint: Check code for lint errors using ESLint
• yarn format: Format the code using Prettier

Update act-board issues

First generate the classifier JSON, then upsert the generated rule issues and cross-repository blocker sub-issues. The second command requires a GITHUB_TOKEN with write access to act-rules/act-board and issue read access to act-rules/act-rules.github.io.

yarn approval-report
GITHUB_TOKEN=... yarn upsert-act-board --input approval-report.json

The upsert command owns act-board issue titles, bodies, state, and sub-issue relationships. It does not update GitHub Project fields.

GITHUB_TOKEN=... ACT_BOARD_PROJECT_NUMBER=1 yarn sync-act-board-project \
  --input approval-report.json
yarn write-act-board-snapshot --input approval-report.json \
  --outFile ../act-board/data/snapshot.json

sync-act-board-project writes Projects v2 Status and optional numeric/date/URL fields. It skips GitHub writes when values already match, warns and skips missing or mistyped optional fields, and exits if the Status field is missing. --projectOwner must name a GitHub organization; user-owned Projects are not supported. Row failures are reported after the remaining rows are attempted and cause a non-zero exit status. Both upsert-act-board and sync-act-board-project fail clearly when GITHUB_TOKEN is unset. The snapshot command rewrites data/snapshot.json only when the classifier JSON actually changed.