Thank you for your interest in contributing to our data.
There are a few ways that you can contribute:
- Tell us that something is wrong
- Add or modify a support point
- Suggest a missing test case
- Improve a test case
- Suggest a new technology
- Suggest a new feature
We can't get everything right. And let's be honest, this project represents a huge amount of work by a lot of people. We are human and we make mistakes. But in order for us to fix those mistakes, we must first know about them. Please create an issue to bring something to our attention.
When creating an issue, please be as detailed as you can.
The best thing you can do to help us out is to run tests against specific AT/Browser combinations and contribute your findings back to us.
A support point is the support value for a given AT/Browser/Test.
- Find a test that you want to run.
- Read the provided instructions so that you understand the expected results.
- Use the chosen AT/Browser combination to run the test.
- Use the provided form to open an issue that details the results. You can also create a pull request with your findings. Be sure to provide specific versions of the AT, Browser, and OS that were used.
- If creating a pull request, add an entry to the history array for the test that describes any changes and set the support point's date to today's date.
- Your findings should be verified by at least one other person before they are accepted. Verification must either be done manually or by citing a trustworthy 3rd party resource.
An issue to add or modify a support point should include:
- The name of the test
- The AT name
- The AT version
- The Browser Name
- The Browser version
- The OS version
- The specific command(s) used to access the target element with the AT (keys used, touch gestures, or voice command)
- The output announced by the screen reader for each specific command (if using a screen reader). #7 and #8 help to make the test easier to replicate.
- Whether or not you think the test passes or fails and why
Please create an issue or create a pull request to suggest a new test case.
A test case provides instructions to test the functionality of a feature when used with AT. For example, a test case might include a specific attribute or value that is used to modify a feature. If aria-hidden is a feature, separate test cases should exist to test aria-hidden="true" and aria-hidden="false".
Details for the test case should include:
- A name for the test case.
- Sample code for the test case (preferably committed to this project so that it doesn't change without our knowledge).
- List the feature(s) should reference the test case. If you are making a pull request, update the features to reference the test.
- Describe the Expected output and instructions. This must be objective and empirical in nature and must correlate to the output that is described by associated standards. The following should be listed
- The CSS selector for the target element
- The expected role, accessible name, accessible description, states, and properties of the element
- Any current support if you know it (follow the instructions for adding a new support point).
We support three kinds of test cases:
- Assertion test - usually used to verify proper mapping of the accessible name, description, states, and properties. Can include custom instructions for tests that depend on specific interactions.
- External test - (experimental) Used to include the rests of an external test. These tests should include details on methodology, as well as detailed information about AT, Browser, and OS versions.
- Custom test - (experimental) these tests check for functionality not covered by an AAM test. This might include dynamic functionality such as aria-live and always requires custom instructions to be developed.
All new test cases must be approved by at least one other person.
Use the Accessibility API Mapping standards wherever possible to determine the expected values.
- Accessible Name and Description Computation - general expectations
- HTML AAM - specific HTML rules
- SVG AAM - specific SVG rules
- ARIA in HTML - guidelines for using ARIA in the host language: HTML.
If you find a problem with a test case, please create an issue or create a pull request to detail the problem. Any changes to a test case must be approved by one other person.
Please create an issue or create a pull request to suggest a new feature.
What is and is not a feature can be hard to define and might depend on the technology or unique circumstances. In general, a feature is a high-level object that is provided by a technology.
In HTML, a feature might be an element. Note that an HTML tag does not necessarily map 1:1 with an element. For example, an input tag with the attribute type="text" represents a different element than input[type="email"].
In ARIA, a feature might be a role or an attribute. For example, the aria-hidden attribute should be considered a feature in the same way that the heading role is a feature.
For both ARIA and HTML, attributes that can be used across many different features should also be considered features. However, attributes that are restricted to specific features are not. Separate test cases should be created for these feature-specific modifiers.
A new feature will only be accepted if it includes:
- A name for the feature.
- A description of the feature.
- Links to relevant standards to support the feature and describe how AT interaction is supposed to work.
- At least one test case with at least one support point.
- Any support details that you are aware of.
All new features must be approved by at least one other person.
Please create an issue or create a pull request to suggest a new technology. A new technology should include:
- A link to the standard that supports the technology
- Any relevant links to aid in determining the correct AT behavior when interacting with the technology. There must be at least one.
- At least one feature with at least one test with at least one support point (follow relevant instructions).
All new technologies must be approved by at least one other person.