Accessibility Conformance Testing Rules Format

1. Introduction

There are currently many tools available which aid their users in testing web content for conformance to accessibility standards such as the Web Content Accessibility Guidelines (WCAG) [WCAG]. As the web develops in both size and complexity, these tools are essential for managing the resources available on the web.

This format is intended to enable a consistent interpretation of how to test for accessibility requirements to avoid conflicting results of accessibility tests. It is intended to be used to describe both manual accessibility tests as well as automated tests performed by accessibility testing tools (ATTs).

Describing how to test certain accessibility requirements will result in accessibility tests that are transparent with test results that are reproducible. The Accessibility Conformance Testing (ACT) Rules Format defines the requirements for these test descriptions, known as Accessibility Conformance Testing Rules (ACT Rules).

2. Scope

The ACT Rules Format defined in this specification is focused on the description of rules applicable to content created using web technologies, such as Hypertext Markup Language [HTML], Cascading Style Sheets [CSS2], Accessible Rich Internet Applications [WAI-ARIA], Scaleable Vector Graphics [SVG2] and more, including digital publishing. The ACT Rules Format, however, is designed to be technology agnostic, meaning that it can conceivably be used to describe test rules for other technologies.

For instance, the ACT Rules Format can be used to describe ACT Rules dedicated to testing the accessibility requirements defined in WCAG, which are specifically designed for web content.

Other accessibility requirements applicable to web technologies can also be testable with ACT Rules. For example, ACT Rules could be developed to test the conformance of web-based user agents to the User Agent Accessibility Guidelines [UAAG20]. However, the ACT Rules Format would not necessarily be suitable to describe tests for the conformance of a non-web-based user agent.

3. ACT Rule Structure

3.1. Rule Outline

An ACT Rule MUST be written in plain language. It MUST consist of the following items:

• Descriptive title

• Unique identifier

• Rule Description

• Accessibility Requirements

• Limitations, Assumptions or Exceptions, if any

• Accessibility Support (optional)

• Aspects Under Test

• Test Definition

3.2. Unique Identifier

An ACT Rule MUST have a unique identifier that can be any unique text value, such as plain text, URL or a database identifier.

3.3. Rule Description

An ACT Rule MUST have a description that is in plain language and provides a brief explanation of what the rule does.

3.4. Accessibility Requirements

An ACT Rule MUST identify the accessibility requirements to which the rule maps. For example, WCAG 2.0 Success Criterion 1.1.1 [WCAG]. An ACT Rule is a complete or partial test for one or more accessibility requirements.

Outcomes from an ACT Rule MUST be consistent with the accessibility requirement, e.g. a rule only returns the outcome Fail when the content fails the accessibility requirement. This means that the rule maps to the accessibility requirement, as opposed to it merely being related to the requirement, thematically or otherwise.

The actual definition of specific accessibility requirements is beyond the scope of ACT Rules and of this document. For WCAG, Success Criteria are considered to be accessibility requirements. Some organizations have additional accessibility requirements, such as specific implementation techniques to meet WCAG Success Criteria.

3.5. Limitations, Assumptions or Exceptions

An ACT Rule MUST list any limitations, assumptions or any exceptions for the test, the test environment, technologies being used or the subject being tested. For example, a rule that would partially test WCAG 2.0 Success Criterion 1.4.3 Contrast (Minimum) based on the inspection of CSS properties could state that it is only applicable to HTML text content stylable with CSS and does not support images of text.

Sometimes there are multiple plausible ways that an accessibility requirement can be interpreted. For instance, it is not immediately obvious if emoji characters should be considered "text" or "non-text content" under WCAG 2.0. Whatever the interpretation is, this MUST be documented in the rule.

4. Accessibility Support

ACT Rules are designed to test the conformance of content using web technologies to accessibility requirements. However, not every feature of a web technology is implemented in all assistive technologies or user agents that a website may need to support. The concept of accessibility supported use of a Web technology is defined in WCAG [WCAG]. Because of this, ACT Rules are not necessarily applicable in all test scenarios. For instance, a web page that has to work in assistive technologies that have no WAI-ARIA [WAI-ARIA] support, wouldn’t be tested with an ACT Rule that relies on WAI-ARIA support, since this could lead to false positive results.

Even within a rules group, certain individual rules are not always applicable. This leaves one fewer solution for passing that particular rule group. Because of this, ACT Rules have to be atomic, meaning an ACT Rule MUST NOT rely on other rules to be part of the same test scenario.

To support users of ACT Rules in properly defining their test scenarios, an ACT Rule SHOULD include a warning if there are significant accessibility support concerns known about a rule.

5. Aspects Under Test

ACT Rules can operate on different aspects of the subject being tested. An aspect is a distinct part of the test subject itself or its underlying implementation. For example, rendering a web page to an end user involves multiple different technologies, some or all of which may be of interest to an ACT Rule. Some rules need to operate directly on the Hypertext Transfer Protocol [http11] messages exchanged between a server and a client, while others need to operate on the Document Object Model [DOM] tree exposed by a web browser. Some rules may even need to operate on several aspects simultaneously such as both the HTTP messages and the DOM tree.

An ACT Rule MUST include a description of all the aspects under test by the rule. Each aspect MUST be discrete with no overlap between the aspects. Some aspects are already well defined within the context of web content, such as HTTP messages, DOM tree, and CSS styling [CSS2], and do not warrant a detailed description. Other aspects may not be well defined or even specific to web content. In these cases, an ACT Rule SHOULD include either a detailed description of the aspect in question or a reference to that description.

5.1. Common Aspects

5.1.1. HTTP Messages

The HTTP messages [http11] exchanged between a client and a server as part of requesting a web page may be of interest to ACT Rules. For example, analyzing HTTP messages to perform validation of HTTP headers or unparsed HTML [HTML] and CSS [CSS2].

5.1.2. DOM Tree

The DOM [DOM] tree constructed from parsing HTML [HTML], and optionally executing DOM manipulating JavaScript, may be of interest to ACT Rules to test the structure of web pages. In the DOM tree, information about individual elements of a web page, and their relations, becomes available.

The means by which the DOM tree is constructed, be it by a web browser or not, is not of importance as long as the construction follows the Document Object Model [DOM].

5.1.3. CSS Styling

The computed CSS [CSS2] styling resulting from parsing CSS and applying it to the DOM [DOM] may be of interest to ACT Rules that wish to test the web page as presented to the user. Through CSS styling, information about the position, the foreground and background colors, the visibility, and more, of elements becomes available.

The means by which the CSS styling is computed, be it by a web browser or not, is not of importance as long as the computation follows any applicable specifications that might exist, such as the CSS Object Model [CSSOM].

5.1.4. Accessibility Tree

The accessibility tree constructed from extracting information from both the DOM [DOM] tree and the CSS [CSS2] styling may be of interest to ACT Rules. This can be used to test the web page as presented to assistive technologies such as screen readers. Through the accessibility tree, information about the semantic roles, accessible names and descriptions, and more, of elements becomes available.

The means by which the accessibility tree is constructed, be it by a web browser or not, is not of importance as long as the construction follows any applicable specifications that might exist, such as the Core Accessibility API Mappings 1.1 [CORE-AAM-1.1].

5.1.5. Language

Language, either written or spoken, contained in nodes of the DOM [DOM] or accessibility trees may be of interest to ACT Rules that intend to test things like complexity or intention of the language. For example, an ACT Rule might test that paragraphs of text within the DOM tree do not exceed a certain readability score or that the text alternative of an image provides a sufficient description.

The means by which the language is assessed, whether by a person or a machine, is not of importance as long as the assessment meets the criteria defined in Requirements for WCAG 2.0 Checklists and Techniques §humantestable [WCAG].

6. ACT Test Definition

6.1. Applicability

The applicability section is a required part of an ACT rule. It MUST contain a precise description of the parts of the test subject to which the rule applies. For example, specific nodes in the DOM [DOM] tree, or tags that are incorrectly closed in an HTML [HTML] document. These are known as the test targets. The applicability MUST only use information provided through test aspects of the same rule. No other information should be used in the applicability.

Applicability MUST be described objectively, unambiguously and in plain language. When a formal syntax, such as a CSS selector [css3-selectors] or XML Path Language [XPATH], can be used, that (part of the) applicability MAY use that syntax in addition to the plain language description. While testing, if nothing within the test subject matches the applicability of the rule, the result is inapplicable.

An objective description is one that can be resolved without uncertainty in a given technology. Examples of objective properties in HTML are element names, their computed role, the spacing between two elements, etc. Subjective properties on the other hand, are concepts like decorative, navigation mechanism and pre-recorded. Even concepts like headings and images can be misunderstood. Is this talking about the tag name, the accessibility role, it’s purpose in the web page? The latter of which is almost impossible to define with objectivity. When used in applicability, these concepts MUST have an objective definition. This definition can be part of a larger glossary shared between rules.

6.2. Expectations

An ACT Rule MUST contain one or more expectations. An expectation is an assertion that must be true about each test target (see Applicability). Each expectation MUST be distinct, unambiguous, and be written in plain language. Unlike in applicability, a certain level of subjectivity is allowed in expectations. Meaning that the expectation has only one possible meaning, but that meaning isn’t fully quantifiable.

Editor note - The task force is looking for feedback about whether expectations should be allowed to reference each other, or if each must be testable independently of the others. For details, see Github issue #173.

When all expectations are true for a test target, the test target passed the rule. If one or more expectations is false, the test target failed the rule. If the rule is part of a rule group, a test target that failed a rule may still meet the requirement (see Rule Grouping for details).

An expectation MUST only use information available in the test aspects, and from the applicability and other expectations of the same rule. No other information should be used in the expectation. So for instance, an expectation could be "Expectation 1 is true and ...", but it can’t be "Rule XYZ passed and ...". This ensures the rule is encapsulated.

7. Rule Grouping

In accessibility testing, there are often multiple ways to solve the same problem. For instance, header cells in HTML [HTML] tables can be indicated through the scope attribute, by using the headers attribute, or by using ARIA [WAI-ARIA] labels. All of these separate techniques could be described in one big rule. But this creates a large, and often difficult to maintain rule. To ensure rules are kept small and atomic, they SHOULD be put into a rule group instead.

To meet the accessibility requirement, only one rule in a rule group has to pass. For our table example, one could write three separate rules, one for scope, one for headers + id and one for ARIA labels. If a table meets any of these rules, it automatically passes the group. The failed results of the other rules can be ignored.

Editor note - The ACT Task Force is looking for feedback about the use of Rule groups. We are considering whether a group should be allowed to have a single rule. Though it adds some complexity, it minimizes change if rules are added in the future. Additionally, we are considering allowing a group to require more than one pass, before the group passes. As an example, this may be particularly useful for WCAG 2.0 Success Criterion 2.4.5 Multiple ways. For details, see Github issue #161.

A test target will pass a rule group if it passes at least one of the applicable rules within that group. Likewise, a test target will fail the rule group, if it does not pass any of the applicable rules in the group. In the example of HTML Tables, passing the table scope rule, and failing the ARIA label and headers + id rule, would mean the test target passed this group of rules.

Note that rules in a group MAY have different applicability. Because of this, not every element applicable within the group is tested by every rule. Rules MAY also be disabled during a test run due to accessibility support concerns. See Accessibility Support for details.

8. ACT Data Format (Output Data)

With ACT Rules, it is important that data coming from different sources can be compared. By having a shared vocabulary, accessibility data that is produced by different auditors can be compared and, where necessary, aggregated. Therefore, every ACT Rule MUST express the output in a format that has all of the features described in the ACT Data Format.

Rules are tested in two steps. Firstly, the applicability is used to find a list of Test Targets (elements, tags or other "components") within the web page or other test subject. Then each test target is tested to see if all of the expectations are true. This will give the outcome for each test target. For contextual information, the output data must also include test subject and the rule identifier.

Editor note - The ACT Task Force is investigating to what extent a shared data format may or may not be necessary for the rules output format. If it is necessary, how in depth it should be? For details, see Github issue #162.

This will mean that every time a rule is executed on a page, it will return a set with zero or more results, each of which MUST have at least the following properties:

• Rule Identifier (test)

• Test Subject (Web page)

• Test Target (pointer)

• Outcome (Passed, Failed, or Inapplicable)

{
  "@context": "https://raw.githubusercontent.com/w3c/wcag-act/master/earl-act.json",
  "@type": "Assertion",
  "subject": "https://example.org/",
  "test": "auto-wcag:rules/SC1-1-1-css-image.html",
  "result": {
    "outcome": "Failed",
    "pointer": "html > body > h1:first-child"
  }
}

8.1. Test Subject

When a single URL can be used to reference the web page, or other test subject, this URL MUST be used. In scenarios where more complex actions are required to obtain the test subject (in the state that it is to be tested), it is left to ATT developers to determine which method is best used to express the test subject.

8.2. Test Target

When representing the test target in the output data, it is often impractical or impossible to serialize the test target as a whole. Instead of this, a pointer can be used to indicate where the test target exists within the web page or other test subject. There are a variety of pointer methods available, such as those defined in Pointer Methods in RDF 1.0 [Pointers-in-RDF].

The pointer method used in the output data of an ACT Rule MUST include the pointer method used in Implementation Validation.

8.3. Outcome

The procedure of a rule MUST always return one of the following outcomes:

• Passed: All expectations for the Test Target were true

• Failed: One or more expectations for the Test Target was false

• Inapplicable: There were no Test Targets in the Test Subject

8.4. Ensure Comparable Results

In addition to the Test Target and the Outcome, ACT Rule output data MUST include the following contextual information:

• the Web page, file or other test subject the rule was applied to and

• an identifier of the rule itself.

9. Rule Quality Assurance

9.1. Implementation Validation

Implementation tests are tests for accessibility test tools. These tests enable the developers and users of ATTs to validate the implementation of an ACT Rule. An ACT rule MUST have implementation tests for the applicability, as well as for each expectation in the rule.

An implementation test consists of two parts: a piece of input data and an expected result. When applying the test, the piece of input data, for instance an HTML code snippet, is evaluated by following the rule’s test procedure. The result is then compared to the expected result of the test. The expected result consists of a list of test targets and the expected outcome (Passed, Failed, Inapplicable) of the evaluation.

9.2. Accuracy Benchmarking

The web is ever changing, and technologies are used in such diverse and creative ways that it is impossible to predict in advance, all the ways that accessibility issues can occur and all the ways they can be solved for. When writing ACT Rules, it is almost inevitable that exceptions will be overlooked during the design of a rule, or that new technologies will emerge that introduce new exceptions.

This makes it important to be able to regularly test if the rule has the accuracy that is expected of it. This can be done by benchmark testing. In benchmark testing, the accuracy of a rule is measured by comparing its results to those obtained through accessibility expert testing.

The accuracy of a rule is the average between the false positives and false negatives, which are in turn calculated as follows:

• False positives: This is the percentage of test targets, that were failed by the rule, but were not failed by an accessibility expert.

• False negatives: This is the percentage of test targets, that were passed by the rule, but were failed by an accessibility expert.

There are several ways this can be done. For instance, accessibility test tools can implement a feature which lets users indicate that a result is in error, or pages that for which accessibility results are known, can be tested using ATT, and the results are compared. To compare results from ACT Rules to those of expert evaluations, data aggregation may be necessary.

9.3. Rule Aggregation

As described in section §8 ACT Data Format (Output Data) a rule will return a list of results, each of which contain 1) the Rule ID, 2) the test subject, 3) the test target, and 4) an outcome (Passed, Failed, Inapplicable). Data expressed this way has a great deal of detail, as it gives multiple pass / fail results for each rule.

Most expert evaluations do not report results at this level of detail. Often reports are limited to giving a single outcome (Passed, Failed, Inapplicable) per page, for each success criteria (or other accessibility requirement). To compare the data, results from rules should be combined, so that they are at the same level.

When all rules pass, that does not mean that all accessibility requirements are met. Only if the rules can test 100% of what should be tested, can this claim be made. Otherwise the outcome for a criterion is inconclusive.

Example: An expert evaluates a success criterion to fail on a specific page. When testing that page using ACT Rules, there are two rules that map to this criterion. The first rule returns no results. The second rule finds 2 test targets that pass, and a 3rd test target that fails.

In this example, the first rule is inapplicable (0 results), and the second rule has failed (1 fail, 2 pass). Combining this inapplicable and fail, means the success criterion has failed.

See Appendix 1: Aggregation examples, using JSON-LD and EARL on how this could be expressed using JSON-LD and EARL.

9.4. Update Management

9.4.1. Change Log

It is important to keep track of changes to the ACT rules so that users of the rules can understand if changes in test results are due to changes in the rules used when performing the tests, rather than changes in the content itself. All changes to an ACT Rule that can change the outcome of a test MUST be recorded in a change log. The change log can either be part of the rule document itself or be referenced from it.

Each new release of an ACT Rule MUST be identifiable with either a date or a version number. Additionally, a reference to the previous version of that rule MUST be available. For extensive changes, a new rule SHOULD be created and the old rule SHOULD be deprecated.

Example: An example of when a new rule should be created is when a rule that tests for the use of a blink element changes to instead look for any animated style changes. This potentially adds several new failures that were previously out of scope. Using that same rule as an example, adding an exception to allow blink elements positioned off screen should be done by updating the existing rule.

9.4.2. Issues List

An ACT Rule MAY include an issues list. When included, the issues list MUST be used to record cases in which the ACT Rule might return a failure where it should have returned a pass or vice versa. There are several reasons why this might occur, including:

• Certain scenarios or the use of technologies that are very rare and were not included in the rule for that reason.

• Certain accessibility features are impossible to test within the test environment. For instance, they might only be testable by accessing the accessibility API, require screen capturing, etc.

• The scenario did not exist (due to changing technologies) or was overlooked during the initial design of the rule.

The issues list serves two purposes. For users of ACT Rules, the issues list may give insight into why an inaccurate result occurred, as well as provide confidence in the result of that rule. For the designer of the rule, the issues list is also useful to plan future updates to the rule. In a new version of the rule, resolved issues would be moved to the change log.

Appendix 1: Aggregation examples, using JSON-LD and EARL

Example:

{
  "@context": "https://raw.githubusercontent.com/w3c/wcag-act/master/earl-act.json",
  "@type": "Assertion",
  "subject": "https://example.org/",
  "test": "auto-wcag:SC1-1-1-css-image.html",
  "result": {
    "outcome": "Failed",
    "source": [{
      "test": "auto-wcag:SC1-1-1-css-image.html",
      "result": {
        "outcome": "Failed",
        "pointer": "html > body > h1:first-child"
      }
    }, {
      "test": "auto-wcag:SC1-1-1-css-image.html",
      "result": {
        "outcome": "Passed",
        "pointer": "html > body > h1:nth-child(2)"
      }
    }]
  }
}

Example: Aggregate rules to a WCAG success criterion

{
  "@context": "https://raw.githubusercontent.com/w3c/wcag-act/master/earl-act.json",
  "@type": "Assertion",
  "subject": "https://example.org/",
  "test": {
    "@id": "wcag20:#text-equiv-all",
    "title": "1.1.1 Non-text Content"
  },
  "result": {
    "outcome": "Failed",
    "source": [{
      "test": "auto-wcag:SC1-1-1-css-image.html",
      "result": {
        "outcome": "Failed",
        "pointer": "html > body > h1:first-child"
      }
    }, {
      "test": "auto-wcag:SC1-1-1-longdesc.html",
      "result": {
        "outcome": "Passed",
        "pointer": "html > body > img:nth-child(2)"
      }
    }]
  }
}

Example: Aggregate a list of results to a result for the website

{
  "@context": "https://raw.githubusercontent.com/w3c/wcag-act/master/earl-act.json",
  "@type": "Assertion",
  "subject": {
    "@type": ["WebSite", "TestSubject"],
    "@value": "https://example.org/"
  }
  "test": "http://www.w3.org/WAI/WCAG2A-Conformance",
  "result": {
    "outcome": "Failed",
    "source": [{
      "test": "wcag20:text-equiv-all",
      "result": {
        "outcome": "Failed",
        "source": [ … ]
      }
    }, {
      "test": "wcag20:media-equiv-av-only-alt",
      "result": {
        "outcome": "Passed",
        "source": [ … ]
      }
    }, {
      "test": "wcag20:media-equiv-captions",
      "result" : {
        "outcome": "Inapplicable",
        "source": [ … ]
      }
    }, … ]
  }
}