Skip to main content
Version: v4

Testing With Cypress

The AudioEye Accessibility Testing SDK Cypress Library gives you the ability to write Cypress tests to test for accessibility issues in your web application.

Pre-requisites​

Visit the Getting Started page to configure your .npmrc with your AudioEye entitlement token.

Integration with other Cypress plugins

The AudioEye Testing SDK Cypress Library maintains compatibility with the majority of Cypress plugins. However, certain plugins that fundamentally alter the test authoring methodology are not directly supported by the SDK. For example, the @badeball/cypress-cucumber-preprocessor plugin, which utilizes .feature files for test definition, is not directly compatible with the SDK.

Installation​

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

We require cypress to be version 13.0.0 or greater.

Setup​

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

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

Usage​

Use the SDK to test for accessibility issues.

describe('accessibility tests', () => {
  it('accessibility for the entire page matches our expectation', () => {
    cy.visit('http://localhost:3000');

    cy.get('html').accessibility('resultCodes').should('not.be.empty');

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

  it('accessibility for the login button matches our expectation', () => {
    cy.visit('http://localhost:3000');

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

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

SDK API​

accessibility / a11y​

Use the accessibility custom command to test for accessibility issues.

Parameters​

› output (String)

Determines the output type. Either resultCodes or resultsGroupedByWcagSuccessCriteriaLevel. If resultCodes is provided, an array of the test names will be returned. If resultsGroupedByWcagSuccessCriteriaLevel is provided, an object with the test results grouped by WCAG success criteria level will be returned. Defaults to resultCodes.

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

› conformanceLevel (String)

The conformance level to filter the results by. Either A, AA, or AAA.

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

Returns​

The accessibility command returns a Cypress.Chainable wrapper around either a string array or an object with the test results grouped by WCAG success criteria level.

Troubleshooting​

Typescript errors in a JavaScript only installation​

If you are using vanilla JavaScript and notice an error like this when running your Cypress tests you will need to configure Cypress to ignore Typescript type definition files.

Error:​

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__";
|

Module parse failed: Unexpected token (4: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

Resolution:​

Configure Cypress to ignore Typescript type definition files. Please incorporate this into your own config file after adding @cypress/webpack-preprocessor as a development dependency.

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}',
  },
});