Getting Started

Available Packages

AudioEye's Accessibility Testing SDK is available as NPM packages (Node Package Manager)

• Core - @audioeye/testing-sdk-core
• CLI - @audioeye/testing-sdk-cli
• Jest - @audioeye/testing-sdk-jest
• Cypress - @audioeye/testing-sdk-cypress
• Playwright - @audioeye/testing-sdk-playwright

Software Requirements

Node versions 18, 20, and 22 are supported by the AudioEye's Accessibility Testing SDK.

Pre-Requisites

AudioEye is hosting the NPM packages for this SDK in Cloudsmith for secure distribution. In order to download packages, you will need a copy of your AudioEye Entitlement Token. This token is available in the AudioEye Customer Portal.

Getting your entitlement token

1. Log in to the AudioEye Customer Platform.
2. Click on the Account menu in the bottom left and select the Account settings menu item.
3. Scroll down to the Testing SDK Entitlement Token section.
4. If not created yet, click the Generate Entitlement Token button to create a token for your account.
5. Once complete click on the Copy Entitlement Token button to copy the key to your clipboard.

This key can now be used to download the AudioEye Accessibility Testing SDK packages. We will refer to this key as AUDIOEYE_ENTITLEMENT_TOKEN in the rest of this document.

Refreshing your entitlement token

If you want to replace your entitlement token key with a new one, follow these steps:

1. Log in to the AudioEye Customer Portal.
2. Click on the account menu in the top right and select the My Account menu item.
3. Scroll down to the Testing SDK Entitlement Token section.
4. Click the Refresh Entitlement Token button. The new token will appear.
5. Click on the Copy Entitlement Token button to copy the new token key to your clipboard.

Your existing projects and workflows will need to be manually updated to use the new token. Proceed with the steps described in the Setting up your `.npmrc section below.

Setting up your .npmrc

In your node package root directory (where package.json lives), add or modify the .npmrc file with the following contents:

.npmrc

@audioeye:registry=https://npm.cloudsmith.io/audioeye-K01/audioeye/
//npm.cloudsmith.io/audioeye-K01/audioeye/:_authToken=AUDIOEYE_ENTITLEMENT_TOKEN

Note: For security reasons you should not commit the AUDIOEYE_ENTITLEMENT_TOKEN to your repository. Instead, you should set it up as a secret in GitHub and reference it in your workflow. Beta users will have this pre-generated with the AUDIOEYE_ENTITLEMENT_TOKEN filled out for them.

Core Package

NPM Installation or Update

You can install or update the core package locally (as a developer only dependency) in your project.

npm install -D @audioeye/testing-sdk-core

CLI

NPM Installation or Update

You can install or update the CLI (as a developer only dependency) using the following command:

npm install -D @audioeye/testing-sdk-cli

Installation in a Docker Container

In order to run our CLI in Docker, you must set up your project to support Puppeteer. This Dockerfile works for ubuntu containers.

FROM ubuntu-22.04
RUN apt-get update \
    && apt-get install -y wget gnupg \
    && wget -q -O - https://dl-ssl.google.com/linux/linux_signing_key.pub | apt-key add - \
    && sh -c 'echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" >> /etc/apt/sources.list.d/google.list' \
    && apt-get update \
    && apt-get install -y google-chrome-stable fonts-ipafont-gothic fonts-wqy-zenhei fonts-thai-tlwg fonts-kacst fonts-freefont-ttf libxss1 \
      --no-install-recommends \
    && rm -rf /var/lib/apt/lists/*

You must also run docker run with the flag --cap-add=SYS_ADMIN.

You can find full details on how to set up Puppeteer in Docker here.

Using the CLI

npx aetest [command] [options]

Available Commands

  scan [options] [url]  Perform an accessibility scan on a URL or on the provided raw html on stdin
  describe [rule]       Output available information about the rules in the testing framework and their usage in the testing sdk cli
  help [command]        display help for command

Available Options

  -V, --version         output the version number
  -h, --help            display help for command

Jest

NPM Installation or Update

You can install or update the Jest package locally (as a developer only dependency) in your project.

npm install -D @audioeye/testing-sdk-jest

Cypress

NPM Installation or Update

npm install -D @audioeye/testing-sdk-cypress

Minimum version requirement

We require cypress to be version 13.0.0 or greater.

We use Cypress custom commands to evaluate accessibility issues. Set up the custom commands in your Cypress support file or custom commands file.

Typescript commands file

cypress/support/commands.ts

import '@audioeye/testing-sdk-cypress';

Javascript commands file

cypress/support/commands.js

import '@audioeye/testing-sdk-cypress';

Support file

cypress/support/e2e.ts

import './commands';

Playwright

NPM Installation or Update

npm install -D @audioeye/testing-sdk-playwright

Minimum version requirement

We require @playwright/test to be version 1.39.0 or greater.

We use Playwright fixtures to evaluate accessibility issues. Fixtures work by extending the built in test runner. To use the AudioEye Playwright SDK, you will need to add our fixtures to your existing Playwright tests (see Playwright's documentation on using a fixture). This can be done by either:

1. Importing the extended test runner exported from @audioeye/testing-sdk-playwright directly into your tests.
2. Adding our fixtures to the test runner in your Playwright test code and importing that exported test runner into your tests.

Adding fixtures to the test runner

// tests/fixtures.ts
import { type AudioEyeFixtures, AudioEyeA11y } from '@audioeye/testing-sdk-playwright';
import { test as base } from '@playwright/test';

export const test = base.extend<AudioEyeFixtures>({
  accessibility: async ({ page }, use) => {
    await use(new AudioEyeA11y(page));
  },
  a11y: async ({ accessibility }, use) => {
    await use(accessibility);
  },
});


// tests/example.spec.ts
import { expect } from '@playwright/test';

import { test } from './fixtures';

test('Example Playwright test using AudioEye\'s Testing SDK', async ({
  page,
  accessibility,
}) => {
  await page.goto('http://localhost:3000/');

  const results = await accessibility.evaluate();

  expect(results.resultCodes).toEqual([
    ...
  ]);
});

Using the extended test runner directly

import { test } from '@audioeye/testing-sdk-playwright';
import { expect } from '@playwright/test';

test('Example Playwright test using AudioEye\'s Testing SDK', async ({
  page,
  accessibility,
}) => {
  await page.goto('http://localhost:3000/');

  const results = await accessibility.evaluate();

  expect(results.resultCodes).toEqual([
    ...
  ]);
});

Fixture names

We provide fixtures named accessibility and a11y which can be used interchangeably.

Software Development Lifecycle (SDLC)

GitHub Actions (example)

1. To download any of our packages in a GitHub Action, make sure you've set up permissions in your .npmrc with the contents shown in the Pre-Requisites section.

2. Setup a repository secret in GitHub named AUDIOEYE_ENTITLEMENT_TOKEN with the value of your entitlement token.

3. Use the environment variable in your workflow:

name: Pull Request CI

on:
  pull_request:

permissions:
  contents: read

jobs:
  build:
    name: Build & Test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          registry-url: 'https://npm.cloudsmith.io/audioeye-K01/audioeye/'
          cache: 'npm'

      - name: Install Dependencies
        env:
          AUDIOEYE_ENTITLEMENT_TOKEN: ${{ secrets.AUDIOEYE_ENTITLEMENT_TOKEN }}
        run: |
          npm ci

      - name: Build
        run: |
          npm run build

      - name: Test
        run: |
          npm test