Skip to main content
Version: v5

Testing with Jest

The AudioEye Accessibility Testing SDK Jest library lets you test rendered components for accessibility issues as part of your existing unit and integration test suite.

If you are new to the SDK, complete the entitlement-token and package-manager setup in getting started before installing the Jest package.

When to use Jest​

Jest is a good fit when you want to:

  • catch accessibility issues while developing components
  • validate rendered output in unit or integration tests
  • test isolated UI states without launching a full browser
  • add accessibility assertions to an existing React Testing Library workflow

If you need to test full browser behavior such as routing, authentication, or multi-step flows, use Playwright or Cypress instead.

Prerequisites​

Before you begin, make sure you have:

  • configured your entitlement token as described in getting started
  • installed Jest in your project
  • set up a DOM-based test environment when your tests render UI
  • installed any rendering utilities your app already uses, such as @testing-library/react
Browser-context limitations

The Jest SDK evaluates component markup in a test environment. Because Jest does not run in a real browser page, some rules that depend on full browser context, computed styles, layout, or runtime page behavior are not available here.

For more details, see About Our Rules.

Installation​

Install the Jest SDK as a development dependency:

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

Test environment setup​

Most component tests should run in a DOM-capable environment such as jsdom.

A minimal Jest configuration looks like this:

jest.config.js
module.exports = {
  testEnvironment: 'jsdom',
};

If you are using Jest 28 or later, make sure your project has configured the test environment correctly for that version of Jest. See the Jest documentation for details:

Your first accessibility test​

The basic workflow is:

  1. render a component
  2. pass the rendered output to accessibility.evaluate(...)
  3. assert on the returned results

Here is a simple React example using React Testing Library:

import { accessibility } from '@audioeye/testing-sdk-jest';
import { render } from '@testing-library/react';
import React from 'react';

function Image({ altText }: { altText: string }) {
  return <img src="/logo.png" alt={altText} />;
}

describe('Image', () => {
  it('finds weak alt text', () => {
    const results = accessibility.evaluate(render(<Image altText="image" />));

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

  it('passes when alt text is descriptive', () => {
    const results = accessibility.evaluate(render(<Image altText="The AudioEye company logo" />));

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

Supported input types​

For convenience, the Jest SDK accepts several common input types. This makes it easier to use with the testing tools you already have.

You can pass any of the following to accessibility.evaluate(...):

  • string
  • RenderResult
  • HTMLElement
  • DocumentFragment
  • JQuery<HTMLElement>

Common usage patterns​

Using a RenderResult​

If you already use React Testing Library, passing the full render result is often the shortest option.

import { accessibility } from '@audioeye/testing-sdk-jest';
import { render } from '@testing-library/react';
import React from 'react';

import { Image } from './image';

describe('Image', () => {
  it('tests accessibility from the render result', () => {
    const results = accessibility.evaluate(render(<Image altText="image" />));

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

Using an HTMLElement​

Use the rendered container when you want to evaluate the component's root DOM node directly.

import { accessibility } from '@audioeye/testing-sdk-jest';
import { render } from '@testing-library/react';
import React from 'react';

import { Image } from './image';

describe('Image', () => {
  it('tests accessibility from an HTMLElement', () => {
    const { container } = render(<Image altText="image" />);

    const results = accessibility.evaluate(container);

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

Using a DocumentFragment​

Use a fragment when you want to evaluate the output returned by asFragment().

import { accessibility } from '@audioeye/testing-sdk-jest';
import { render } from '@testing-library/react';
import React from 'react';

import { Image } from './image';

describe('Image', () => {
  it('tests accessibility from a DocumentFragment', () => {
    const { asFragment } = render(<Image altText="image" />);

    const results = accessibility.evaluate(asFragment());

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

Using an HTML string​

If your tests produce raw markup instead of rendered components, you can evaluate a string directly.

import { accessibility } from '@audioeye/testing-sdk-jest';

describe('raw HTML', () => {
  it('tests accessibility from a string', () => {
    const results = accessibility.evaluate('<img src="/logo.png" alt="image" />');

    expect(results.resultCodes).toEqual(['Img_Name_WeakName']);
  });
});
Helper names

The SDK provides helper names accessibility and a11y. You can use either one based on your team's preferred style.

SDK API​

evaluate​

Use evaluate to analyze a component or HTML fragment with AudioEye's rule set.

const results = accessibility.evaluate(render(<Image altText="image" />));

Parameters​

› expectSource (string | RenderResult | HTMLElement | DocumentFragment | JQuery<HTMLElement> )

The rendered output or markup to evaluate.

Returns​

evaluate returns an instance of A11yResults.

A11yResults API​

conformanceLevel​

Filter results by WCAG conformance level. Valid levels are A, AA, and AAA. Higher levels include lower levels.

const aaResults = results.conformanceLevel('AA');

Parameters​

› level (String)

Either A, AA, or AAA.

Returns​

A new instance of A11yResults.

resultCodes​

Get the matching accessibility rule codes as a string array.

const resultCodes = results.resultCodes;
// ['Img_Name_WeakName']

Returns​

An array of strings representing the matching result codes.

resultsGroupedByWcagSuccessCriteriaLevel​

Group results by WCAG success-criteria level.

results.resultsGroupedByWcagSuccessCriteriaLevel;
// { A: [ ... ], AA: [ ... ], AAA: [ ... ] }

Returns​

An object containing results grouped by WCAG success-criteria level.

Example assertions​

Assert on specific rule codes​

Use resultCodes when you want a compact assertion on which issues were found.

const results = accessibility.evaluate(render(<Image altText="image" />));

expect(results.resultCodes).toEqual(['Img_Name_WeakName']);

Assert on a WCAG level​

Use conformanceLevel(...) when your test should focus on a specific compliance target.

const results = accessibility.evaluate(render(<Image altText="image" />));

expect(results.conformanceLevel('A').resultCodes).toContain('Img_Name_WeakName');

Troubleshooting​

No package found during install​

If installation fails, verify that your entitlement token and package-manager configuration are set up correctly in getting started.

Tests fail because document or DOM APIs are missing​

Confirm that Jest is using a DOM test environment such as jsdom.

Expected browser-dependent rules are not running​

Jest does not provide the same browser context as Playwright, Cypress, or the CLI. If you need browser-context rules, use a browser-based integration instead. See About Our Rules.

Next steps​

After your first Jest test is working, you can:

  • add accessibility assertions to your existing component tests
  • compare resultCodes in CI to prevent regressions
  • move browser-dependent scenarios to Playwright or Cypress
  • review Troubleshooting if installation or execution fails