A site for Joomla! documentation

Joomla Magazine

Manual Index

Part 4: Accessibility

Test your Extension, Part 4: Accessibility

Author: Herman Peeren | Date: Thursday, 19 February 2026

Review

This article describes the WCAG 2.2 Accessibility Requirements and various methods to test for compliance.

Original Article

The Joomla project has invested considerable effort in making the CMS accessible to everyone. With every release we continue to improve this even more. Joomla’s core does well.

The Joomla Community Magazine has published extensively on accessibility over the past years. I listed a selection under this article. The articles on accessible resources and testing approaches  provide a good introduction. A real goldmine is the "Blind Spots of Accessibility Testing Tools" series  by Christiane Maier-Stadtherr. These articles systematically cover what automated tools miss with regard to colour contrast, alt text quality, bypass blocks, focus management, buttons, and labels and input fields.

Accessible Joomla extensions

A chain is only as strong as its weakest link. Your beautifully accessible Joomla site would become inaccessible the moment you install an extension that ignores accessibility standards. Complying with those standards isn't just a moral issue anymore, but also a legal requirement. Extension developers should test their products against accessibility standards. Before installing an extension you want to know if it is compliant with Web Content Accessibility Guidelines (WCAG) 2.2, and on which level (level AAA meets all success criteria, level A is only a minimal subset, and level AA is somewhere in between). Joomla is WCAG 2.1 AA compliant, which prescribes 50 criteria. It is the current basis for many laws about accessible websites worldwide. WCAG 2.2 AA has extended its predecessor with six more criteria. Joomla is working on some to become fully compliant with the updated standard, and so should your extension, to be usable in every Joomla installation. Of course, you don’t want to exclude anyone from using your extension!

WCAG 2.2 AA Compliance

When we talk about accessibility standards, we're primarily referring to the Web Content Accessibility Guidelines (WCAG) 2.2 at Level AA. This is an international standard. Most of its criteria were already in its predecessor, WCAG 2.1 AA, which is the basis for legal requirements in many countries. But the most important part of all those rules and criteria is its purpose: let’s take away the barriers that exclude people from using websites.

The most critical WCAG 2.2 AA requirements for extensions include:

Perceivable

Information and user interface components must be presented to users in ways they can perceive them with the senses that are available to them.

Operable

User interface components and navigation must be operable, also when a mouse or touchscreen cannot be used.

Understandable

Content and the operation of the user interface must be understandable for everybody, not only for people with a disability.

Robust

Your extension must be interpreted reliably by a wide variety of user agents (including assistive technologies).

These aren't theoretical requirements, but practical necessities. A modal dialog that traps keyboard focus incorrectly fails WCAG. A color picker that requires mouse interaction fails WCAG. A data table without proper <th> elements and scope attributes fails WCAG. Dynamic content that doesn't announce changes to screen readers fails WCAG.

Following WCAG 2.2 AA makes your extension better for everyone, not just users with disabilities. Good heading structure helps everyone scan content. Keyboard navigation benefits power users. Clear error messages reduce support requests. Accessibility and usability go hand in hand.

Fortunately, testing for accessibility doesn't have to be difficult or time-consuming, especially when you build it into your development workflow from the start.

Some accessibility testing tools

Here are some browser-based tools that can help you to analyse the accessibility of your site.

  • Axe DevTools: Browser extension for Chrome, Firefox, Edge. Integrates into DevTools, scans for WCAG violations, provides clear explanations and fixes. Most popular choice among developers.
  • WAVE (Web Accessibility Evaluation Tool): Overlays icons directly on your page showing exact issue locations. Visual feedback makes it excellent for learning and quick identification.
  • Lighthouse: Built into Chrome DevTools. Includes accessibility audit with performance and SEO checks. Less comprehensive than Axe or WAVE but convenient for quick scans.
  • IBM Equal Access Accessibility Checker: Outstanding tool for developers. Provides detailed error/warning/recommendation summaries with granular, technical information. Available in browser DevTools, can scan single pages or entire sites. Particularly strong at explaining complex issues.
  • Jooa11y: Joomla's own accessibility checker plugin. Activates in frontend for sites under development, provides Joomla-specific checks.

These tools detect static accessibility issues—about 30-40% of all problems. They excel at finding missing alt attributes, basic color contrast violations, and missing form labels in rendered HTML/CSS.

Manual testing

As detailed in the Magazine's colour contrast article, tools detect basic violations (white text on light gray) but miss:

  • Color contrast changes on hover/focus.
  • Text over background images/gradients.
  • JavaScript-applied color changes.
  • Opacity/transparency effects.
  • Contrast in images containing text.

They also can't evaluate alt text quality, heading hierarchy logic, or focus trap behavior in modal dialogs.

Other manual testing requirements from the "Blind Spots" series:

  • Keyboard navigation through your entire extension
  • Screen reader compatibility (NVDA is free for Windows, JAWS for testing, VoiceOver built into macOS/iOS)
  • Focus management in dynamic components
  • Semantic HTML structure
  • Content should make sense when read linearly 

Automated Testing

It is best practice to automate testing of your extension as much as possible in your Continuous Integration (CI) pipeline. As we use Cypress for Joomla core CMS it is a good practice to do the same for your extension. See the recent  article in this Magazine about using Cypress to test your extension. The Axe-core tool has a plugin that you can use directly in your Cypress tests.

Add cypress-axe as dependency:

npm install --save-dev cypress-axe axe-core

It will be added to the devDependencies in your package.json:

"cypress-axe": "^1.7.0",

In tests/cypress/support/index.mjs (or whatever file you use to import commands):

import 'cypress-axe';

Basic test:

describe('My Extension Accessibility Tests', () => {
  beforeEach(() => {
    cy.visit('/index.php?option=com_myextension')
    cy.injectAxe()
  })

  it('should have no detectable accessibility violations', () => {
    cy.checkA11y()
  })

  it('should have accessible form elements', () => {
    cy.checkA11y('.my-form-container')
  })
})

Configure rules and impact levels:

cy.checkA11y(null, {
  includedImpacts: ['critical', 'serious'],
  rules: {
    'color-contrast': { enabled: true },
    'duplicate-id': { enabled: true }
  }
})

Besides the free Axe-core plugin, Cypress also has an Accessibility package, which is a paid premium solution.

There are other free tools, not using Cypress, that can be integrated in your CI workflow, for instance Pa11y-CI or using Axe-core in Playwright.

Example custom table accessibility test with Cypress

In the Accessible Tables article I mentioned some properties of column headers and row headers to make them usable for screen readers. Not all advice from that article is  tested in Axe-core. For instance, to check if a table with multiple rows and columns has row headers. But we can write some custom tests ourselves.

describe('Data Table Accessibility', () => {
  beforeEach(() => {
    cy.visit('/index.php?option=com_myextension&view=items')
    cy.injectAxe()
  })

  it('should pass Axe-core accessibility checks', () => {
    cy.checkA11y('table')
  })

  it('should have a table caption, () => {
    // Check that table has a caption
    cy.get('table').should('have.descendants', 'caption')

    // Verify caption is descriptive
    cy.get('table caption').invoke('text').should('not.be.empty')
  })

  it('should have properly scoped header cells', () => {
    // Column headers should have scope="col"
    cy.get('table thead th').each(($th) => {
      cy.wrap($th).should('have.attr', 'scope', 'col')
    })

    // If there are row headers, they should have scope="row"
    cy.get('table tbody th').each(($th) => {
      cy.wrap($th).should('have.attr', 'scope', 'row')
    })
  })

   // Check if table has 2+ tbody rows and 3+ columns (then expect row headers)
   cy.get('table tbody tr').then(($rows) => {
     if ($rows.length >= 2) {
        cy.get('table thead th').then(($headers) => {
          if ($headers.length >= 3) {
            // Each row should have exactly one th with scope="row"
            cy.get('table tbody tr').each(($row) => {
              cy.wrap($row).find('th[scope="row"]').should('have.length', 1)
            })
          }
        })
      }
    })
  })

Conclusion

Your Joomla extension should be accessible. That’s a baseline requirement. One of the priorities of the Joomla project is to be WCAG 2.2 AA compliant, and for an extension to be useful on a Joomla website, it should at least comply with that standard too.

Start with browser tools (Axe, WAVE, Lighthouse, IBM Equal Access, Jooa11y) to understand issues. Integrate automated testing into CI with cypress-axe. Write custom tests for extension-specific patterns. Remember: automated testing catches about 40% of issues, so manual testing with assistive technologies remains essential.

Convey that your extension is accessible. That makes it easier for integrators to choose your extension above that of a competitor. And it raises awareness of how important accessibility is. Maybe we can add some information about accessibility standards compliance to the Joomla Extension Directory (JED) entries. At the moment, when searching for accessibility on the JED, you mostly get add-ons to fix a non-accessible site. Only a few extensions advertise with being accessible.

Accessibility isn't a feature added later. It's fundamental to good software development. Build it in from the start, test continuously, make it self-evident in everything you create.

Next month

The next episode in this series will be about how to test the security of your Joomla extension. Prevent SQL-injection, Cross-Site Scripting, Remote Code Execution, and much more. We’ll look at security standards and testing tools.

Resources

Some Joomla Community Magazine articles about accessibility

(chronologically)

The “Blind Spots of Accessibility Testing Tools” series, by Christiane Maier-Stadtherr:

Some articles about accessibility on Brian Teeman's blog

Some presentations about accessibility

Joomla documentation about accessibility

Documentation of browser accessibility testing tools

Using Axe-core with Cypress

Some none Joomla specific articles:

General WCAG Resources

This “Test your Extension” series

  1. PHPUnit, test an isolated piece of PHP (a “unit”) in a controlled environment.
  2. Cypress, end-to-end tests, running the extension in a Joomla site.
  3. PHPStan, static code analysis to check source code on errors.
  4. Accessibility (this article)
  5. Security