This is a test suite for tools that scan for semantic structural information on web pages, such as landmarks [with headings and articles in the works]. Such information is often used to afford or improve the accessibility of pages, allowing people using screen-readers and alternative browsers to navigate and understand the content.
The following topics are covered below:
The test suite provides a set of:
- Fixtures: HTML scenes (one for each test). Example fixture
- Expectations: JSON objects that describe the correct set of landmarks (one for each fixture). Example expectation
The fixtures and expectations are provided in two formats:
-
A set of full-HTML-page fixtures and separate matching expectation files can be found in the "fixtures/" and "expectations/" directories. It's recommended that you use these, as they cover all of the tests.
-
A single fixture file, containing all but two of the tests, can be found alongside a matching single expectation file, in the "combined/" directory. The HTML file contains only the fixtures, in a series of
<div>elements; it is not a fully-formed HTML document.These may be useful if your test runner runs inside a browser but they have a limitation: two of the tests ("application-alone-on-body-is-ignored" and "landmark-role-on-body") require an ARIA
roleattribute to be set on the<body>element, so cannot be included.
'use strict'
const pssst = require('page-structural-semantics-scanner-tests')
console.log(JSON.stringify(pssst.getFullPageTests(), null, 2))
// console.log(JSON.stringify(pssst.getFullPageTestsInline(), null, 2))...will give you a result of the form...
{
. . .
"main-alone-is-recognised": {
"meta": {
"name": "Main element is recognised"
},
"fixture": ".../page-structural-semantics-scanner-tests/fixtures/main-alone-is-recognised.html",
"expected": [
{
"type": "landmark",
"role": "main",
"roleDescription": null,
"label": null,
"selector": "body > main"
}
]
},
. . .
}
Two functions are provided, allowing you to control whether you want the file paths for the HTML, or to have their contents inline:
getFullPageTests()getFullPageTestsInline()
There are no convenience functions for iterating over the combined tests mentioned above—it makes most sense to just load them directly.
Finally, there are two more convenience functions that mirror those above and allow you to specify custom fixture and expectation directories. These are useful if you have extra custom test cases in the same format that you wish to use.
getFullPageTestsFrom(fixturesDir, expectationsDir)getFullPageTestsInlineFrom(fixturesDir, expectationsDir)
All of the core WAI-ARIA landmark roles, both as supplied via the role attribute and as implicit landmarks via HTML 5 elements are supported, with some caveats, as described below.
- banner1
- complementary
- contentinfo1
- form2, 3, 4
- main
- navigation
- region2, 3, 5
- search
-
Both
<header>(banner) and<footer>(contentinfo) elements are not considered landmarks unless they are the page-wide header/footer elements, as per the HTML Accessibility API Mappings. -
Elements with a
formrole or aregionrole are intended to be labelled. Ideally, this should be done with a visual label and anaria-labelledbyattribute, so that all users can perceive the label. However, if a label is only provided by the non-visualaria-labelattribute, it should be recognised by assistive technologies. -
The HTML Accessibility API Mappings document is clear that both unlabelled
<form>and unlabelled<section>(region) elements are not to be counted as landmark regions. -
A
formrole that is explicitly specified via<div role="form">(lacking a label of any kind) is counted as a valid landmark. This is because the request for a label with theformrole is a "should" (optional). -
A
regionrole explicitly specified via<div role="region">(lacking a label of any kind) is not counted as a landmark. This is because the request for a label with theregionrole is a "must" (required).
As per the accessible name calculation algorithm used by browsers, the aria-labelledby attribute takes precedence over aria-label.
If an aria-labelledby attribute references multiple elements, all of those elements' text content will be joined to form the label for the landmark. However, it's not recommended that you label landmark regions with more than one element (usually referring to a single HTML heading element is sufficient). Using more than one labelling element could be a sign that your landmark structure is too complicated. Referencing multiple labelling elements is more suited for labelling <input> elements with information from multiple sources.
It is possible to use the aria-roledescription attribute to provide a custom label to be used for the type of landmark. This allows you to, for example, provide more application-specific and thus user-friendly names for the roles.
This can be very helpful in some cases, but don't be tempted to over-use this technique: swapping conventional role names for custom ones can decrease usability. The examples and guidelines given in the ARIA specification, linked above, are most helpful.
You do not need to use this attribute in an attempt to localise your site if you're using standard landmark roles: user agents (browsers, browser extensions and assistive technologies) should already support this.
The following additional landmark roles defined in the Digital Publishing WAI-ARIA Module 1.0 are also supported.
doc-acknowledgmentsdoc-afterworddoc-appendixdoc-bibliographydoc-chapterdoc-conclusiondoc-creditsdoc-endnotesdoc-epiloguedoc-erratadoc-foreworddoc-glossarydoc-index(is a landmark vianavigation)doc-introductiondoc-pagelist(is a landmark vianavigation)doc-partdoc-prefacedoc-prologuedoc-toc(is a landmark vianavigation)
Hidden landmarks
If any of the following apply to an element, then the element and its descendants will be excluded from the accessibility tree. Thus any landmark regions the element may have contained would not be exposed.
- Having the
aria-hiddenattribute set to "true" - Having the proposed
inertattribute, or having it explicitly set to "true" - CSS
display: none - CSS
visibility: hidden
Development is test-driven; use npm test to run the tests on the suite itself.