Skip to main content
Version: v5

Writing Custom Accessibility Tests

The AudioEye Accessibility Testing SDK allows you to write custom tests using the @audioeye/testing-sdk-core package. This package provides the core functionality used for all of our testing frameworks. If specific framework coverage is not provided, you can use this package to write your own tests.

Prerequisites​

Before you install the core package, complete the package-manager setup in getting started. Depending on your project, that means configuring either:

  • .npmrc for npm or pnpm
  • .yarnrc.yml for Yarn

Installation​

Install the core package as a development dependency:

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

If you need to set up a virtual browser environment, also install:

npm install -D @audioeye/testing-sdk-virtual-dom

If you need to convert test results to different formats:

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

Usage​

Use the findIssues function to run your custom tests. This function can be imported from @audioeye/testing-sdk-core. The return type of this function is a TestingSdkAllResultType.

Importing the function​

import { findIssues } from '@audioeye/testing-sdk-core';

findIssues type signature​

import type { RenderResult } from '@testing-library/react';

type EvaluateRulesInputType = string | RenderResult | HTMLElement | DocumentFragment | JQuery<HTMLElement>;

type RunOptions = {
  browserMode: 'virtual' | 'real';
  runMode: 'external' | 'embedded';
  resultsToFilter?: Set<string>;
  component?: boolean;
  printTestList?: boolean;
  debug?: boolean;
  format?: 'html' | 'json' | 'csv';
  viewportDimensions?: {
    width: number;
    height: number;
  };
  mobile?: boolean;
  output?: string;
  stdout?: boolean;
  timeout?: number;
  cssSelectors?: boolean;
  localWindow?: Window;
  metadataToExclude?: (keyof RuleMetaOutput)[];
};

type TestingSdkAllResultType = {
  ruleResults: TestingSdkRuleResultType[];
  exitCode: number;
  summaryResults: string;
  formattedResults: string;
};

type TestingSdkRuleResultType = {
  ruleCode: string;
  ruleMetadata: RuleMetaOutput | undefined;
  result: string;
  source: string;
  cssSelector?: string;
};

type RuleMetaOutput = {
  code: string;
  description: string;
  fixAtSource: boolean;
  fullName: string;
  sourceFixGuidance?: string;
  wcagSuccessCriteriaLevelCode: string;
  wcagSuccessCriteriaName: string;
  wcagSuccessCriteriaNumber: string;
};

declare const findIssues: (partialRunOptions?: Partial<RunOptions>) => TestingSdkAllResultType;

declare const setupDocument: (
  input: EvaluateRulesInputType,
  {
    isRealBrowser,
    localWindow,
  }?: {
    isRealBrowser?: boolean | null | undefined;
    localWindow?: Window | null | undefined;
  },
) => () => void;

declare function isHTMLHtmlElement(input: EvaluateRulesInputType): boolean;

declare const addFormattedResults: (
  results: TestingSdkAllResultType,
  { runMode, format }: RunOptions,
  url?: URL,
) => TestingSdkAllResultType;

Example​

import { addFormattedResults, findIssues, isHTMLHtmlElement } from '@audioeye/testing-sdk-core';
import { setupDocument } from '@audioeye/testing-sdk-virtual-dom';

// If you do not have a real browser environment, you can use setupDocument function to create a virtual DOM.
const cleanup = setupDocument(document.body);
let a11yIssues = findIssues({ component: !isHTMLHtmlElement(document.body) });

// Clean up the virtual DOM
cleanup();

// Add CSV to the results
a11yIssues = addFormattedResults(a11yIssues, {
  browserMode: 'virtual',
  runMode: 'embedded',
  format: 'csv',
});

// Handle the results
const { ruleResults, exitCode, summaryResults, formattedResults } = a11yIssues;