Skip to main content
Version: v5

Testing with Cypress

Use the AudioEye Accessibility Testing SDK for Cypress to add accessibility assertions to browser-based tests and full user flows.

Cypress is a good fit when you want to:

  • test accessibility after real navigation and rendering
  • validate authenticated or multi-step flows
  • scan a full page or a specific element
  • keep accessibility checks alongside existing Cypress tests

Before you begin​

Complete the entitlement-token and package-manager setup in getting started before installing the Cypress package.

Compatibility with other Cypress plugins

The AudioEye Testing SDK Cypress library is compatible with most Cypress plugins. Plugins that fundamentally change how tests are authored may require additional integration work. For example, @badeball/cypress-cucumber-preprocessor, which uses .feature files, is not directly documented by this guide.

Installation​

Install the SDK as a development dependency:

npm install -D @audioeye/testing-sdk-cypress
Minimum version requirement

This package requires cypress version 13.0.0 or greater.

Setup​

The Cypress SDK registers custom commands that you can call from a Cypress chain.

1. Import the SDK in your Cypress commands file​

If your project uses TypeScript:

cypress/support/commands.ts
import '@audioeye/testing-sdk-cypress';

If your project uses JavaScript:

cypress/support/commands.js
import '@audioeye/testing-sdk-cypress';

2. Ensure your support file loads the commands file​

If you already import ./commands from your support file, you do not need to change anything else.

TypeScript example:

cypress/support/e2e.ts
import './commands';

JavaScript example:

cypress/support/e2e.js
import './commands';

3. Confirm Cypress can run your existing tests​

Before adding accessibility assertions, make sure your normal Cypress setup is already working and your application can be visited in tests.

Your first accessibility test​

Start with a full-page scan to confirm the SDK is installed and working.

cypress/e2e/accessibility.cy.js
describe('accessibility checks', () => {
  it('checks the full page for accessibility issues', () => {
    cy.visit('http://localhost:3000');

    cy.get('html').accessibility('resultCodes').should('be.an', 'array');
  });
});

Once that works, you can make assertions against the returned result codes.

Common usage patterns​

Scan the full page​

describe('full-page accessibility', () => {
  it('returns result codes for the document', () => {
    cy.visit('http://localhost:3000');

    cy.get('html')
      .accessibility('resultCodes')
      .should('deep.equal', [
        'BadTag_Emphasis_Detect',
        'Heading_Sequence_Wrong',
        'Img_AttributeRequirement_Missing',
        'Link_ExternalWarning_Missing',
      ]);
  });
});

Scan a specific element​

describe('element-level accessibility', () => {
  it('checks a specific region of the page', () => {
    cy.visit('http://localhost:3000');

    cy.get('[data-cy="login"]').accessibility('resultCodes').should('deep.equal', ['Link_ExternalWarning_Missing']);
  });
});

Filter results by WCAG conformance level​

describe('conformance-level filtering', () => {
  it('filters results to level AA and lower', () => {
    cy.visit('http://localhost:3000');

    cy.get('html').accessibility('resultsGroupedByWcagSuccessCriteriaLevel', 'AA').should('deep.equal', {
      A: [
        /* ... */
      ],
      AA: [
        /* ... */
      ],
    });
  });
});
Command names

The SDK provides both accessibility and a11y commands. They are interchangeable.

SDK API​

accessibility / a11y​

Use the accessibility custom command to evaluate the current subject in the Cypress chain.

cy.get('html').accessibility();
cy.get('[data-cy="checkout-form"]').a11y();

Parameters​

› output (string)

Determines the output type. Supported values are:

  • resultCodes - returns an array of rule names
  • resultsGroupedByWcagSuccessCriteriaLevel - returns an object grouped by WCAG level

Defaults to resultCodes.

cy.get('html')
  .accessibility('resultCodes')
  .should('deep.equal', [
    'BadTag_Emphasis_Detect',
    'Heading_Sequence_Wrong',
    'Img_AttributeRequirement_Missing',
    'Link_ExternalWarning_Missing',
  ]);

› conformanceLevel (string)

Filters the returned results by WCAG conformance level. Supported values are A, AA, and AAA.

Higher conformance levels include lower levels. For example, AA includes both A and AA results.

cy.get('html').accessibility('resultsGroupedByWcagSuccessCriteriaLevel', 'AA').should('deep.equal', {
  A: [
    /* ... */
  ],
  AA: [
    /* ... */
  ],
});

Returns​

The command returns a Cypress chainable wrapping either:

  • a string[] of result codes, or
  • an object grouped by WCAG success criteria level

If you're adopting the Cypress SDK for the first time, this sequence usually works well:

  1. Install @audioeye/testing-sdk-cypress.
  2. Import the SDK in cypress/support/commands.ts or cypress/support/commands.js.
  3. Add one smoke test that scans cy.get('html').
  4. Confirm the command runs successfully in local development.
  5. Add focused checks for key flows such as login, signup, checkout, navigation, or modal dialogs.
  6. Move the checks into CI once the baseline is stable.

Troubleshooting​

TypeScript errors in a JavaScript-only Cypress setup​

If you use JavaScript only and see a compilation error related to TypeScript declaration files, configure Cypress to ignore .d.ts files during preprocessing.

Error example​

Oops...we found an error preparing this test file:

  > cypress/support/e2e.js

The error was:

Error: Webpack Compilation Error
Module parse failed: Unexpected token (3:8)
You may need an appropriate loader to handle this file type, currently no loaders are configured to process this file. See https://webpack.js.org/concepts#loaders
| import { EvaluateRulesOutput } from './rules';
|
> declare const A11Y_RULES_VERSION = "__A11Y_RULES_VERSION__";
| declare const SDK_VERSION = "__SDK_VERSION__";
|

Resolution​

Add @cypress/webpack-preprocessor as a development dependency, then configure Cypress to ignore TypeScript declaration files.

cypress.config.js
import { defineConfig } from 'cypress';
import webpackPreprocessor from '@cypress/webpack-preprocessor';

export default defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      const options = {
        webpackOptions: {
          module: {
            rules: [
              {
                test: /\.d\.ts$/,
                use: 'ignore-loader',
              },
            ],
          },
        },
      };

      on('file:preprocessor', webpackPreprocessor(options));

      return config;
    },
    baseUrl: 'http://localhost:3000',
    specPattern: 'cypress/e2e/**/*.cy.{js,jsx}',
  },
});

Need to test authenticated pages or multi-step workflows?​

That is a strong use case for Cypress. Log in through your normal test setup, navigate to the page state you care about, and then run accessibility() on either the full page or a targeted element.

Want to understand which rules run in different environments?​

See About Our Rules for details on rule behavior across component, browser, and test-runner contexts.