Accessibility Testing – Creating Custom Axe Rules and Assertions

In web development, Accessibility testing is not just a checkbox, but it is a fundamental aspect of user experience. Automated accessibility testing tools like Axe allow developers to identify accessibility issues within their web applications. As projects become more complicated and varied, it becomes clear that the customized solutions are required. This is where the creating custom Axe rules and assertions comes into picture. In this blog we will explore how to extend Axe’s capabilities by creating custom accessibility rules and assertions tailored to specific project requirements or compliance standards.

Understanding Axe and its Importance:

One of the most often used tools for accessibility testing is Axe. It is an effective open-source accessibility testing tool made to assist testers and developers in locating and fixing accessibility problems in online applications. It also identifies accessibility issues based on the Web Content Accessibility Guidelines (WCAG). Developers and testers can easily identify the accessibility violations and make a inclusive user experience web application with the help of Axe tool regularly.

Why custom axe rules and assertions?

Axe provides a comprehensive set of accessibility rules which are based on WCAG (Web Content Accessibility Guidelines) standards. These guidelines cover a lot of typical problems, other projects can have specific requirements to different accessibility standards. In such scenarios, creating custom Axe rules and assertions can help the project team customize accessibility testing to meet their specific requirements.

This not only ensures that your product is accessible according to your specific requirements but also helps in maintaining consistency across your development projects.

Criteria for Creating Custom Axe Rules and Assertions:

Identify Requirements: For creating the custom Axe Rules, you will Determine the specific accessibility requirements that need to be addressed.

Implement Rule Configuration: while integrating your custom rule into Axe’s configuration settings, you have specified during the testing process when and how to invoke these assertions.

Test and Refine: When you create your custom rule against sample pages or components, you have to ensure that it accurately identifies accessibility issues without generating false positives.

Define Assertion Criteria: Before creating the custom assertion, you need to Determine the criteria that Axe should use to evaluate accessibility issues.

Integration into Axe Configuration: Seamlessly integrate your custom assertions into Axe’s configuration settings. You have specified when and how these assertions should be invoked during the testing process.

Getting Started:

To integrate custom rules and assertions into your testing workflow, you can use the axe-playwright package. This package provides a set of pre-defined rules for accessibility testing, along with the ability to create custom rules.

First, you need to install the axe-playwright package:

npm install axe-playwright --save-dev

Creating Custom Axe Rules:

Axe provides a set of pre-defined rules that cover a wide range of accessibility issues. However, there may be cases where you need to create custom rules to meet specific project requirements or compliance standards. To create a custom Axe Rule, you will typically need to define a function that takes an element and returns an object with the following properties:

1. id:  A unique identifier for the rule.
2. description:  A brief description of the rule.
3. help:  Additional information about the rule, such as how to fix the issue.
4. impact:  The impact of the issue on accessibility, such as “serious” or “minor”.
5. tags:  A list of tags that categorize the rule, such as “wcag2a” or “wcag2aa”.
6. any:  A function that takes an element and returns true if the element violates the rule.

Let’s taken an example of a custom rule that checks if an image has a descriptive alt attribute:

const customRule = {
  id: 'custom-rule',
  description: 'Check if an image has a descriptive alt attribute',
  help: 'Add a descriptive alt attribute to the image to provide context for screen reader users',
  impact: 'serious',
  tags: ['wcag2a'],
  any: (element) => {
    if (element.tagName === 'IMG') {
      const alt = element.getAttribute('alt');
      return !alt || alt.trim() === '';
    }
    return false;
  },
};

Creating Custom Axe Assertions

Once you have created a custom rule, you can create a custom assertion that checks if an element violates the rule. To create a custom assertion, you need to define a function that takes an element and an assertion options object. The function should use the assert module to check if the element violates the rule. To create a custom Axe Rule, you will typically need to:

Sure, here are some different types of assertions that can be used in relation to custom Axe rules and assertions in Accessibility Testing:

checks that the element does not violate the custom rule.

assert.isFalse(customRule.any(element)) 

checks that the width of the element is greater than 500 pixels.

assert.isAbove(element.offsetWidth, 500)

If you want to check that the height of the element is less than 100 pixels.

assert.isBelow(element.offsetHeight, 100)

checks if the element has the aria-hidden attribute.

assert.isTrue(element.hasAttribute('aria-hidden'))

checks if the tabindex attribute of the element is null.

assert.isNull(element.getAttribute('tabindex'))

If you want to check that the role attribute of the element is equal to button.

assert.isTrue(element.getAttribute('role') === 'button')

Let’s taken an example of custom assertion that checks if an image has a descriptive alt attribute:

const { assert } = require('chai');
const customAltAssertion = (element, options) => {
  assert.isTrue(
    !customRule.any(element),
    `Expected element to have a descriptive alt attribute, but it was missing or empty`,
  );
};

Benefits:

1. Enhanced User Experience: Custom Axe rules and assertions contribute to a more inclusive user experience by identifying and addressing accessibility issues early in the development process.
2. Efficiency and Cost Savings: Developers can save time and resources that would spend on manual testing and retroactive fixes by automating the identification of common accessibility issues.
3. Consistency: Creating Custom Axe Rules and Assertions promotes consistency in accessibility testing practices across projects and overall development standards.

Conclusion

Custom Axe rules and assertions offer a powerful way to extend Axe’s capabilities and ensure that your digital products are accessible to all users. you can address a wider range of accessibility issues and maintain compliance by tailoring the testing process to meet your project’s specific requirements. By creating custom rules and assertions, you can ensure that your website or application meets the highest standards of accessibility.

References:

https://playwright.dev/docs/accessibility-testing

https://blog.nashtechglobal.com/introduction-to-accessibility-testing-with-axe/