Skip to content

Accessibility Interop Project Overview and Contribution Guidelines

Jump to bottom
Rahim Abdi edited this page Sep 20, 2024 · 36 revisions

Accessibility Interop Overview and Contribution Guidelines

Web Platform Tests (WPT) Overview

The Web Platform Tests (WPT) project is a “cross-browser test suite for the Web-platform stack”. Its main goals are described on the Web Platform Tests website:

“Writing tests in a way that allows them to be run in all browsers gives browser projects confidence that they are shipping software which is compatible with other implementations, and that later implementations will be compatible with their implementations. This in turn gives Web authors/developers confidence that they can actually rely on the Web platform to deliver on the promise of working across browsers and devices without needing extra layers of abstraction to paper over the gaps left by specification editors and implementors.”

Additional resources to learn more about WPT:

Accessibility Interop Group

The Interop Project is an integral component of WPT:

“The goal of the Interop Project is to improve the web by making it easier to make websites and web apps that work in every browser or browser engine at the same time.”

The Interop Project investigates specific focus areas (2024 Interop focus areas dashboard) and specifically, the Accessibility Interop group focuses on web platform accessibility testing.

From the accessibility-interop GitHub repo README:

“Contributors from Apple, Mozilla, Igalia, Bocoup, Adobe, Hilton, Microsoft, Google, and many more individual web developers collaborated to kickstart a continuous integration, interoperable, accessibility testing project in all major browsers. To date, this is the only known project that stands to improve the state of accessibility across the entire Web, regardless of which platform, browser, or assistive technology you may be using or testing.”

The group usually meets on the first Tuesday of the month to discuss current accessibility investigation and focus area topics, accessibility tests, yearly investigation progress and open issues.

To participate in the monthly Zoom meetings, please reach out to Simon Pieters (@zcorpan).

Related groups:

Accessibility Testing Overview

Why Are We Doing This?

Prior to WPT, browser vendors primarily wrote engine-specific, internal tests to check accessibility. This sometimes resulted in inconsistent behavior between browsers, whether due to testing of different edge cases or differing interpretations of the specifications. In addition, for web developers that may be frustrated by code that should “just work”, writing engine-specific tests is an opaque, non-trivial task. For example, if an ARIA attribute is supported in all but one browser, what can a developer do to get this fixed at the browser level?

Using the WPT framework, the Interop Accessibility project enables developers to write a single automated test that runs in all major browser engines; once submitted to WPT, browser bugs can then be raised, systematically tracked and ultimately resolved in a transparent manner.

By empowering web developers to make the web more interoperable, we achieve numerous accessibility benefits:

  • Helping to build a web that accessible by default
  • Surfacing browser implementation gaps and unexpected accessibility behaviors per specifications
  • Preventing regression of accessibility bugs
  • Freeing up time spent on debugging/addressing accessibility during development

Web Automation Stack

At a high level, platform accessibility APIs expose browser-generated accessibility information about user interfaces (UI). This metadata (e.g., role, name, state) is then relayed to users of assistive technologies to understand the purpose and structure of UI:

web automation stack Source: https://github.com/w3c/aria/blob/main/documentation/tests.md

Browser engines have internal, engine-specific tests however, WPT facilitates cross-browser testing via WebDriver.

WebDriver & Accessibility Introspection

We’re able to write JavaScript-based tests to test accessibility-focused web platform features using the WPT infrastructure which includes:

At present, WebDriver supports the following accessors for querying accessibility object properties:

Note: See also web-platform-tests.org for additional function documentation on get_computed_label() and get_computed_role().

As part of the 2024 accessibility interop investigation, additional accessibility accessors are being explored to query more than label/role for an accessible node.

WPT Accessibility Directories

WPT contains tests for many web features/technologies and there is no single “accessibility” directory. Below are common locations for accessibility-focused tests:

WPT directory (/wpt) Tested Specifications
/accessibility Primarily accessibility crash tests (and not for testing accessibility specs)
/accname Accessible Name and Description Computation
/core-aam Core Accessibility API Mappings
/css For accessibility testing of CSS browser behavior. Currently, we only have CSS tests in wpt/css/css-display/accessibility.
/dpub-aam Digital Publishing Accessibility API Mappings
/html-aam HTML Accessibility API Mappings
/svg-aam SVG Accessibility API Mappings
/wai-aria ARIA, includes ARIA roles/states/properties. Here, you’ll also find useful ARIA utilities when writing tests (see wpt/wai-aria/scripts).

Writing WPT Accessibility Tests

Getting Started

See machine setup steps for Running WPT Tests for ARIA and Related Specs.

Example Test File Structure

Accessibility tests are simply HTML files with some data attributes that provide hooks for WPT test execution and reporting.

As an example, here’s an excerpt from the button roles test (wpt/wai-aria/role/button-role.html):

<!doctype html>
<html>
<head>
  <title>Button-related Role Verification Tests</title>
  <script src="/resources/testharness.js"></script>
  <script src="/resources/testharnessreport.js"></script>
  <script src="/resources/testdriver.js"></script>
  <script src="/resources/testdriver-vendor.js"></script>
  <script src="/resources/testdriver-actions.js"></script>
  <script src="/wai-aria/scripts/aria-utils.js"></script>
</head>
<body>

<p>Tests <a href="https://w3c.github.io/aria/#button">button</a> and related roles.</p>

<div role="button" aria-haspopup="false" data-testname="button aria-haspopup false" data-expectedrole="button" class="ex"></div>
…

<script>
AriaUtils.verifyRolesBySelector(".ex");
</script>

</body>
</html>

Notable callouts:

  • The <title> tag serves as the page title. Usually, this is the name of the test, e.g., “Button-related Role Verification Tests”.
  • The <script> tags in the import external WPT scripts required for test execution.
  • The actual test declaration, e.g., in the example above, we have a <div role=”button”> that we’re asserting has a “button” role. Specifically, note the data-expectedrole attribute used to assert what we’re looking for, and the data-testname attribute that serves as a test descriptor.
  • The <script> block at the bottom of the <body> tag references a helpful function. Here, we’re using the ARIA utility verifyRolesBySelector() function on all elements matching the .ex selector to verify their role.

Promise Tests, Assertions & Accessibility WPT Utilities

Returning to our button example above, let’s look at this test:

<div role="button" aria-haspopup="false" data-testname="button aria-haspopup false" data-expectedrole="button" class="ex"></div>

It would be cumbersome to write WebDriver accessibility accessor functions for every HTML test file. To simplify testing efforts, what we want to do is write HTML markup, provide a test name (via data-testname) and assert some accessibility information about the DOM element (e.g., WebDriver get_computed_role() returns "button" for this example test).

Fortunately, we have ARIA helper functions available in wpt/wai-aria/scripts/aria-utils.js. Our button test uses verifyRolesBySelector() from ARIA utils:

 /*
  Tests computed ROLE of all elements matching selector
  against the string value of their data-expectedrole attribute.

  …

  verifyRolesBySelector: function(selector, roleTestNamePrefix) {
    const els = document.querySelectorAll(selector);
    if (!els.length) {
      throw `Selector passed in verifyRolesBySelector("${selector}") should match at least one element.`;
    }
    for (const el of els) {
      let role = el.getAttribute("data-expectedrole");
      let testName = el.getAttribute("data-testname") || role; // data-testname optional if role is unique per test file
      if (typeof roleTestNamePrefix !== "undefined") {
        testName = roleTestNamePrefix + testName;
      }
      promise_test(async t => {
        const expectedRole = el.getAttribute("data-expectedrole");
        const computedRole = await test_driver.get_computed_role(el);
        assert_equals(computedRole, expectedRole, el.outerHTML);
      }, `${testName}`);
    }
  }

Notable callouts:

  • We don’t need to call the Webdriver accessibility accessors (i.e., get_computed_role(), get_computed_label()) in this test because it happens within verifyRolesBySelector() here:
const computedRole = await test_driver.get_computed_role(el);
  • For each of our tests, the ARIA utility functions use a Promise test which is a method of reliably executing code in an asynchronous manner. The important thing to note here is the assertion:
assert_equals(computedRole, expectedRole, el.outerHTML);

Note: This section is mostly informative. Besides including aria-utils.js in your test file’s <script> block, you won’t be interacting much with ARIA utils unless new global functionality is needed to support test authoring.

Clone this wiki locally