Understanding Axe-Core: The Engine Behind Axe

Introduction

Axe-core stands as an open-source accessibility testing library designed to meticulously scan websites and web applications for accessibility shortcomings. Its versatility extends across multiple programming languages, including JavaScript, Python, and in our context, Java for automation purposes. Renowned for its lightweight nature and rapid performance, axe seamlessly integrates into existing testing frameworks, enhancing their accessibility testing capabilities.

Built upon the principles of the Web Content Accessibility Guidelines (WCAG) 2.1, axe-core incorporates a plethora of rules aimed at identifying prevalent accessibility issues, such as:

1. Absence of descriptive alt text for images.
2. Discrepancies between labels and their corresponding controls.
3. Non-navigable links for keyboard-only users.
4. Inaccessible forms for screen reader users, among others.

This robust set of rules ensures thorough accessibility evaluations, facilitating the creation of digital experiences that are inclusive and user-friendly for all individuals.

Architecture Overview

Axe-core revolutionizes accessibility testing through its structured approach, employing objects known as Rules to assess various aspects of web accessibility. Let’s delve into its architecture to better understand its inner workings:

Rules and Checks

• Rules: Represent high-level accessibility aspects such as color contrast, button labels, and image alt text. Each Rule comprises a series of Checks, and depending on the Rule, these Checks may collectively determine its pass or fail status.
• Checks: These entities validate specific conditions against relevant nodes on the webpage. Upon execution, a Check returns true, false, or undefined based on the satisfaction of the tested condition.

Execution Workflow

1. Rule Execution: Each Rule iterates through its Checks, applying them to relevant nodes determined by the Rule’s selector property and matches function. If a Rule’s Checks don’t apply to a node, it’s considered inapplicable.
2. Check Result Handling: After execution, Checks store results in passes, violations, or incomplete arrays, providing insights into the compliance status and reasons for passing or failing.

Rule Definition

• JSON Representation: Rules are defined in JSON files within the lib/rules directory. A valid Rule JSON comprises specific attributes:
  • id: Unique identifier for the Rule.
  • impact: Defines the severity of the Rule’s results (e.g., minor, moderate, serious, critical).
  • selector: CSS selector specifying elements for Rule application. If omitted, the Rule applies to every node.
  • excludeHidden: Determines whether hidden elements are excluded from Rule evaluation.
  • enabled: Indicates whether the Rule is enabled by default.
  • pageLevel: Specifies if the Rule applies at the page level.
  • matches: ID of the filtering function excluding elements based on selector.
  • tags: Accessibility guidelines to which the Rule adheres.
  • metadata: Object containing descriptive information about the Rule.
• Check Specification: Rules consist of three arrays: any, all, and none, each containing Checks that influence Rule validation. Checks are defined by:
  • id: Unique identifier for the Check.
  • options: Specific options required by the Check, tailored to the Rule’s context.

Main Features of Axe

• Automated Testing: Axe boasts a crucial feature: it automates accessibility testing within automated test suites. By combining Axe with testing frameworks such as Selenium, developers can seamlessly integrate accessibility checks into their automated testing workflows. This integration ensures that developers prioritize accessibility right from the start of development.
• Extensive Rule Set: Axe provides an extensive set of accessibility rules aligned with WCAG standards. These rules address various accessibility concerns, including structure, semantics, interactions, and more. With this comprehensive rule set, developers can conduct thorough testing and effectively address a variety of accessibility barriers.
• Flexibility and Customization: While Axe offers a solid set of predefined rules, it also allows for customization, giving developers the flexibility to tailor the testing process to their specific requirements. This includes enabling or disabling rules, adjusting violation thresholds, and even creating custom rules to address unique accessibility needs.
• Integration with Testing Frameworks: Axe seamlessly integrates with popular testing frameworks like Selenium, making it simple to include accessibility testing in current test suites. This integration streamlines the testing process, enabling developers to conduct accessibility checks alongside functional and regression tests, ensuring thorough test coverage.
• Detailed Reporting: Axe generates detailed reports that outline identified issues, their severity levels, and suggestions for remediation. These reports offer valuable insights into accessibility concerns within web applications, empowering developers to prioritize and effectively address them.

How Axe-Core Works

Under the hood, Axe employs a combination of JavaScript code and browser APIs to analyze the accessibility of web pages. When integrated with testing frameworks like Selenium, Axe injects its script into the web page being tested and executes accessibility checks against the DOM (Document Object Model) structure.

The process can be summarized as follows:

• Injection: Axe-Core injects its JavaScript code into the web page under test using Selenium or similar automation tools.
• DOM Analysis: Once injected, Axe-Core analyzes the DOM structure of the web page, traversing through elements and evaluating their accessibility properties and attributes.
• Rule Evaluation: With its predefined rule set, Axe-Core applies accessibility checks to the elements within the DOM, identifying violations based on WCAG guidelines.
• Violation Detection: Axe-Core categorizes accessibility violations it detects based on severity levels (e.g., minor, moderate, serious) and generates a detailed report outlining the issues.
• Reporting: Finally, Axe-Core generates a comprehensive report containing information about identified accessibility issues, including their descriptions, locations within the DOM, and recommendations for remediation.

By following this process, Axe-Core provides developers with actionable insights into accessibility issues within their web applications, empowering them to make informed decisions and improve the overall accessibility of their products.

Example Axe-Core tests

The following code demonstrates how to use Playwright Test along with Axe Core for accessibility testing. It defines a test suite for the homepage and a test case to ensure that there are no accessibility violations on the page.

const { test, expect } = require('@playwright/test');
const AxeBuilder = require('@axe-core/playwright').default; // Importing the @axe-core/playwright package

test.describe('homepage', () => { // Defining a test suite for the homepage
  test('should not have any automatically detectable accessibility issues', async ({ page }) => { // Defining a test case
    await page.goto('https://your-site.com/'); // Navigating to the page under test

    // Running an accessibility scan against the page
    const accessibilityScanResults = await new AxeBuilder({ page }).analyze();

    // Verifying that there are no violations in the returned scan results
    expect(accessibilityScanResults.violations).toEqual([]);
  });
});

This code snippet demonstrates how to use AxeBuilder to specify configuration options for Axe Core when conducting accessibility scans with Playwright. It focuses the accessibility scan specifically on the navigation menu flyout after interacting with it on the page.

test('navigation menu should not have automatically detectable accessibility violations', async ({ page }) => {
  await page.goto('https://your-site.com/'); // Navigating to the page under test

  await page.getByRole('button', { name: 'Navigation Menu' }).click(); // Clicking on the navigation menu button to reveal the menu

  // Waiting for the navigation menu flyout to be visible before running the accessibility scan
  await page.locator('#navigation-menu-flyout').waitFor();

  // Creating an AxeBuilder instance with configuration to include only the navigation menu flyout for the accessibility scan
  const accessibilityScanResults = await new AxeBuilder({ page })
    .include('#navigation-menu-flyout')
    .analyze();

  // Verifying that there are no violations in the accessibility scan results
  expect(accessibilityScanResults.violations).toEqual([]);
});

Conclusion

Developers and QA engineers rely on Axe-Core as a potent tool for building accessible web applications. By automating accessibility testing and offering detailed insights into accessibility issues, Axe-Core helps teams spot and tackle barriers to accessibility early in development.
Integrating Axe-Core into automated testing workflows not only ensures compliance with accessibility standards but also nurtures a culture of inclusivity and usability, leading to improved experiences for all users. As we persist in prioritizing accessibility in web development, tools like Axe-Core will increasingly shape a more inclusive digital environment.

Reference

Please refer the following for more information:
Accessibility Testing in Agile Development with Axe: https://blog.nashtechglobal.com/accessibility-testing-in-agile-development-with-axe/
Accessibility testing with TS/JS : https://playwright.dev/docs/accessibility-testing