/alfa-integrations

Integrations of Alfa with various external tools

Primary LanguageTypeScriptMIT LicenseMIT

Alfa Integrations

This repository contains integrations of Siteimprove's Alfa accessibility checker with various external tools, notably:

  • a Command Line Interface;
  • a minimal scraper/crawler to grab snapshot of web pages;
  • integrations with component libraries such as React or Vue;
  • integrations with testing frameworks such as Cypress or Jest;
  • integrations with browser automations such as Playwright or Puppeteer.

Issues, Discussions, and project board are handled in the main Alfa repository.

Command Line Interface

This repository contains a Command Line Interface for Alfa.

Setup

To build the project, a recent version of Node.js is required in addition to the Yarn package manager. Once installed, login to the @siteimprove scope, if you aren't already, to ensure that all dependencies can be fetched:

yarn npm login --scope siteimprove

⚠️ This command must be run from the root of the repository as the registry address of the @siteimprove scope is defined in the local Yarn configuration.

You will be prompted for your GitHub username and a personal access token. If you don't already have an access token, generate a new one with the read:packages permission and paste it into the prompt.

  • If that does not work run
yarn config set --home "npmRegistries['https://npm.pkg.github.com'].npmAuthToken" <your-token>

It will create a file .yarnrc.yml on your machine. This is a private file for your user, only. It will most likely be saved in a path like C:\Users\<username>\.yarnrc.yml

  • If that fails and the file content is different than the below code then you can manually update the file. MAKE SURE to edit your own .yarnrc.yml file, not the one in this repository. The reason is because your npmAuthTokens should never be committed to a shared repository - keep it secret on your local machine.

    npmRegistries:
  "https://npm.pkg.github.com":
    npmAuthToken: <your-token>

npmScopes:
  siteimprove:
    npmAuthToken: <your-token>

Once authenticated, do:

yarn install

Next, you can build the project by doing:

yarn build

Usage

You can now run the Alfa CLI with:

# Display help
$ yarn alfa --help
# Audit a single page, storing results in JSON:
$ yarn alfa audit -f json -o audit.json https://example.com
# Scrape a page, to a JSON object that is usable as Alfa's input:
$ yarn alfa scrape -o page.json https://example.com

# Show detailed help for the commands:
$ yarn alfa scrape --help
$ yarn alfa audit --help

Scraper and Crawler

The @siteimprove/alfa-scraper package uses browser automation to navigate to a given page, and scrape its content in a format that is usable by the rest of Alfa.

The @siteimprove/alfa-crawler package contains a minimal crawler that can scrape all pages belonging to a (sub-)domain or a website.

Integrations

This repository contains several ready-made integrations of Alfa to various tools, making it easy and simple to integrate accessibility conformance testing as part of your development workflow. If you have suggestions for additional integerations, feel free to open an issue! We are always looking for new places where Alfa can be put to good use.

⚠️ The integrations are still experimental and subject to change.

Package Integrates with
@siteimprove/alfa-angular Angular
@siteimprove/alfa-chai Chai
@siteimprove/alfa-cheerio Cheerio
@siteimprove/alfa-cypress Cypress
@siteimprove/alfa-enzyme Enzyme
@siteimprove/alfa-jasmine Jasmine
@siteimprove/alfa-jest Jest
@siteimprove/alfa-jquery jQuery
@siteimprove/alfa-playwright Playwright
@siteimprove/alfa-puppeteer Puppeteer
@siteimprove/alfa-react React
@siteimprove/alfa-unexpected Unexpected
@siteimprove/alfa-vue Vue
@siteimprove/alfa-webdriver WebdriverIO

Funding

European emblem

Alfa is part of a project that has received funding from the European Union's Horizon 2020 research and innovation programme under grant agreement Nº780057. We would like to give thanks to the European Commission for their grant, as well as all European citizens, who have indirectly contributed to making Alfa possible. You rock! 🙌

License

Copyright © Siteimprove A/S. Released under the terms of the MIT license.