Skip to content

Get Accessibility Properties #1960

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
spectranaut wants to merge 11 commits into
base: master
Choose a base branch
from
Open

Get Accessibility Properties #1960

Changes from 9 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
82d7844
Get Accessibility Properties
spectranaut May 12, 2026
71d6ead
Accessible object to accessibility node and other fixes
spectranaut May 13, 2026
1c104df
Apply suggestions from code review
spectranaut Jun 3, 2026
f02fdbd
Update based on convos
spectranaut Jun 3, 2026
174fccf
Apply suggestion from @jcsteh
spectranaut Jun 4, 2026
55e15b3
Update route name
spectranaut Jun 4, 2026
24d7021
Use accessibility node id
spectranaut Jun 10, 2026
4472187
Fix typos reported by Mike
spectranaut Jun 18, 2026
eef1ef4
Remove relevant
spectranaut Jun 18, 2026
1a04a3c
rm accessibility properties definitions, add core-aam links to defini…
lolaodelola Aug 18, 2026
97a068d
add acknowledgments
lolaodelola Aug 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
123 changes: 123 additions & 0 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1040,6 +1040,19 @@ <h3>Endpoints</h3>
<td>/session/{<var>session id</var>}/print</td>
<td><a>Print Page</a></td>
</tr>

<tr>
Comment thread
OrKoN marked this conversation as resolved.
<td>GET</td>
<td>/session/{<var>session id</var>}/element/{<var>element id</var>}/accessibilityproperties</td>

@OrKoN OrKoN Jun 18, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

would these endpoints allow getting the entire a11y tree? what is the expected workflow? getting accessibilityproperties for the root element and then using accessibility/properties/<accessibility id> to traverse?

@OrKoN OrKoN Jun 18, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it also seems like it would require many roundtrips to get properties for all elements.

@spectranaut spectranaut Jun 22, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes we will have some "subtree" tests which walk the accessibility tree by accessibility ID, for example: https://github.com/web-platform-tests/wpt/blob/master/wai-aria/subtree/tablist.tentative.html

(this test runs on firefox because of the marionette endpoint: https://wpt.fyi/results/wai-aria/subtree?label=experimental&label=master&aligned)

In general, though, the subtrees are not testable, because they are pretty different between browsers, and we don't think we will ever have full alignment. The main issue is how much "generic" nodes there are (things that represent something meaningless in the a11y tree, like a div for styling purposes). We expect only to test specific scenarios. We discussed having an endpoint for the whole subtree, but we think it's more comment to just test a node or a few children/parents, thus the current design.

@OrKoN OrKoN Jun 22, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, that makes sense but I wonder once this is published if other WebDriver clients might start building out features based on the subtree iteration mechanisms available (thus starting to rely on the non-specified behavior) and require many roundtrips to implement the subtree retrieval.

@cookiecrook cookiecrook Jun 30, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I expect that will be the case, and don't see harm in testing the subtree of smaller features, like a known list or table with a known style sheet... However, it won't be a reliable cross-UA WPT test yet to include something like dumpAccessiblityTree() at the root node for a complex web site. Perhaps someday if and when we are able to standardize the rest.

@OrKoN OrKoN Jul 1, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

would it make sense to add a note about this to the spec text here?

<td><a>Get Accessibility Properties For Element</a></td>
</tr>

<tr>
<td>GET</td>
<td>/session/{<var>session id</var>}/accessibility/properties/{<var>accessibility id</var>}</td>
<td><a>Get Accessibility Properties For Accessibility Node</a></td>
</tr>

</table>
</section> <!-- /Endpoints -->

Expand Down Expand Up @@ -1193,6 +1206,14 @@ <h3>Errors</h3>
and cannot be brought into that viewport.
</tr>

<tr>
<td><dfn>no such accessibility node</dfn>
<td>404
<td><code>no such accessibility node</code>
<td>An <a>accessibility node</a> could not be located on the page
using the given search parameters.
</tr>

<tr>
<td><dfn>no such alert</dfn>
<td>404
Expand Down Expand Up @@ -6028,6 +6049,42 @@ <h4><dfn>Get Computed Label</dfn></h4>
<li><p>Return <a>success</a> with data <var>label</var>.
</ol>
</section> <!-- /Get Element Computed Label -->

<section>
<h4><dfn>Get Accessibility Properties For Element</dfn></h4>

<table class="simple jsoncommand">
<tr>
<th>HTTP Method</th>
<th>URI Template</th>
</tr>
<tr>
<td>GET</td>
<td>/session/{<var>session id</var>}/element/{<var>element id</var>}/accessibilityproperties</td>
</tr>
</table>

<p>The <a>remote end steps</a>, given <var>session</var>, <var>URL
variables</var> and <var>parameters</var> are:

<ol>
<li><p>If <var>session</var>&apos;s <a>current browsing context</a> is <a>no longer open</a>,
return <a>error</a> with <a>error code</a> <a>no such window</a>.

<li><p><a>Try</a> to <a>handle any user prompts</a>
with <var>session</var>.

<li><p>Let <var>element</var> be the result
of <a>trying</a> to <a>get a known element</a>
with <var>URL variables</var>["<code>element id</code>"].

<li><p>Let <var>accessible</var> be the <a>accessibility node</a> that corresponds to this element. If no <a>accessibility node</a> exists, return <a>error</a> with <a>error code</a> <a>no such accessibility node</a>.

<li><p>Let <var>properties</var> be the result of computing the <a>accessibility properties</a> of <var>accessible</var>.

<li><p>Return <a>success</a> with data <var>properties</var>.
</ol>
</section> <!-- /Get Element Accessibility Properties -->
</section> <!-- /State -->

<section>
Expand Down Expand Up @@ -11116,6 +11173,60 @@ <h3><dfn>Take Element Screenshot</dfn></h3>
</section> <!-- /Take Element Screenshot -->
</section> <!-- /Screen capture -->

<section>
<h2>Accessibility</h2>

<p> An <dfn>accessibility node ID</dfn> is a string value representing a handle to an <a>accessibility node</a> in a specific WebDriver session.

<p> An <dfn>accessibility node</dfn> is a platform-independent, implementation-defined node in the platform-independent, implementation-defined accessibility tree. The platform-independent, implementation defined accessibility tree is built from the DOM tree for the purposes of interacting with the web page via an <a>accessibility API</a>. Accessibility nodes might exist in this tree for which there are no DOM element backing them (for example, one might be created to represent a CSS pseudo element). Additionally, an accessibility node might not be created for every DOM node (for example, if something is intentionally hidden from accessibility APIs using <a>aria-hidden</a>). See the ARIA definition of the <a>accessibility tree</a> for more information.

<p> <dfn>Accessibility properties</dfn> is a JSON <a>Object</a> that contains the <a>computed accessibility properties</a> of an <a>accessibility node</a>, as well as the following properties:
Comment thread
spectranaut marked this conversation as resolved.
Outdated

<dl>
<dt>"<code>accessibilityId</code>"

@OrKoN OrKoN Jun 18, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

as far as I see the a11y properties do not link back to DOM element IDs? it seems like it might limit usefulness of the a11y properties?

@spectranaut spectranaut Jun 22, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

They don't link back, it's true. Can you explain why it might limit the usefulness? Oh maybe you mean, if you have an accessibility node, and you want to click it, you don't know where to send that click?

That is a problem, I'm not sure right now how to get around, I'll bring it up.

@OrKoN OrKoN Jun 22, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yes, this would be a use case we have in Puppeteer or in Chrome DevTools (a11y tree view), for example, but also if the a11y tree is traversed using the methods in PR, there seems to be no mechanism to do something with the backing DOM node or even know what DOM contributed this a11y node (if any). I understand that the proposed extension is probably useful for the WPT use cases but I also wonder how it would work for other WebDriver clients.

@cookiecrook cookiecrook Jun 30, 2026 •
edited
Loading

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There should be an optional DOM Node ID reference from the Accessibility Node, if relevant... The reason it's optional is that not all Accessibility Nodes have a relevant DOM Node, and vice versa, not all DOM Elements have a backing Accessibility Node...

An example of the latter is any hidden DOM node; not mapped in the AX Tree. An example of the former (AX Nodes without a DOM Element) is any CSS generated content, or sometimes (depending on implementation details, dynamic nodes like table columns or other in-betweener AX nodes)

@OrKoN OrKoN Jul 1, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I do not see an optional DOM Node ID reference in the spec. Could you please point me to the definition?

@cookiecrook cookiecrook Jul 1, 2026 •
edited
Loading

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That could be defined here, but would more likely come from the TBD property bag definition in Core-AAM. @spectranaut?

@spectranaut spectranaut Jul 1, 2026 •
edited
Loading

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the case of webdriver, it would be the webdriver element ID. Maybe we will make some kind of abstraction in order to define this in Core-AAM -- because other testing frameworks (like marionette driver) will have a different kind of ID references to get back to the original DOM element.

<dd>The <a>accessibility node ID</a> of this <a>accessibility node</a>.

<dt>"<code>parent</code>"
<dd>The <a>accessibility node ID</a> of the parent of this <a>accessibility node</a> in the <a>accessibility tree</a>.

<dt>"<code>children</code>"
<dd>An <a>Array</a> of <a>accessibility node IDs</a> representing the child nodes of this <a>accessibility node</a> in the <a>accessibility tree</a>.

@OrKoN OrKoN Jun 18, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there something to link to that defines what child nodes are? should this extend into iframes or is it expected to work with https://www.w3.org/TR/webdriver2/#switch-to-frame?

@cookiecrook cookiecrook Jul 1, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's a good question. The cross-frame and cross-process hop makes it tricky, and I'd defer to a security analysis of whether its wise to allow that here. @gsnedders, @twilco, @minorninth, @jcsteh, do you have any thoughts?

@minorninth minorninth Jul 8, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think it's a security concern, because my understanding is that a WebDriver client has full access to the whole browser - all tabs, all frames. So exposing the whole composed accessibility tree makes sense.

It might be trickier for browsers to implement globally-unique node IDs across all frames. But we definitely need to pick a direction to go here.

Ideas:
(1) browsers could handle all of the details transparently, either coordinating between frames to make globally unique ids, or making ids that are the composition of a frame id and node id
(2) we could expose both a frame id and node id for each node, mirroring the internal structure that (some) browsers actually use
(3) we could scope this API to a single frame and ensure there's a way to identify an iframe element and continue the search from there
...

</dl>

<section>
<h3><dfn>Get Accessibility Properties for Accessibility Node</dfn></h3>

<table class="simple jsoncommand">
<tr>
<th>HTTP Method</th>
<th>URI Template</th>
</tr>
<tr>
<td>GET</td>
<td>/session/{<var>session id</var>}/accessibility/properties/{<var>accessibility id</var>}</td>
</tr>
</table>

<p>The <a>remote end steps</a>, given <var>session</var>, <var>URL
variables</var> and <var>parameters</var> are:

<ol>
<li><p>If <var>session</var>&apos;s <a>current browsing context</a> is <a>no longer open</a>,
return <a>error</a> with <a>error code</a> <a>no such window</a>.

<li><p><a>Try</a> to <a>handle any user prompts</a>
with <var>session</var>.

<li><p>Let <var>node</var> be the <a>accessibility node</a> with <a>accessibility node ID</a> matching the <var>URL variables</var>["<code>accessibility id</code>"]. If no such <a>accessibility node</a> exists, return <a>error</a> with <a>error code</a> <a>no such accessibility node</a>.

<li><p>Let <var>properties</var> be the result of computing the <a>accessibility properties</a> of <var>node</var>.

@OrKoN OrKoN Jun 18, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you know how well does this corresponds to https://chromedevtools.github.io/devtools-protocol/tot/Accessibility/#type-AXNode?

@spectranaut spectranaut Jun 18, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, actually, this will be backed by the devtools node -- the webdriver command goes through the devtools protocol to get this information. The difference is that to start it will be a subset of the properties -- just the ones all three browsers agree to expose, and the agreement is being worked out in the other PR (w3c/aria#2800).

@OrKoN OrKoN Jun 18, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

are you also working on the implementation in Chromium?

@spectranaut spectranaut Jun 22, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, I sent it to you, but just in case here is is again: https://chromium-review.googlesource.com/c/chromium/src/+/7922212


<li><p>Return <a>success</a> with data <var>properties</var>.
</ol>

</section> <!-- /Get Accessibility Properties for Accessibility Node -->
</section> <!-- /Accessibility -->

<section>
<h2>Print</h2>

Expand Down Expand Up @@ -11603,6 +11714,10 @@ <h2>Index</h2>
in the Accessible Rich Internet Applications (WAI-ARIA) 1.2 specification: [[wai-aria-1.2]]
<ul>
<li><dfn><a href="https://w3c.github.io/aria/#introroles">WAI-ARIA role</a></dfn>
<li><dfn><a href="https://w3c.github.io/aria/#accessibility_tree">Accessibility tree</a></dfn>
Comment thread
spectranaut marked this conversation as resolved.
<li><dfn><a href="https://w3c.github.io/aria/#dfn-accessibility-api">Accessibility API</a></dfn>
<li><dfn><a href="https://w3c.github.io/aria/#aria-hidden">aria-hidden</a></dfn>

</ul>

<dd>
Expand All @@ -11614,6 +11729,14 @@ <h2>Index</h2>
Name and Description Computation</a></dfn>
</ul>

<dd>
<p>The following terms are defined
in the Core Accessibility API Mappings (Core-AAM) 1.2 specification: [[core-aam-1.2]]
<ul>
<li><dfn><a href="https://w3c.github.io/core-aam/#computed_accessibility_properties">Computed accessibility properties</a></dfn>

@OrKoN OrKoN Jun 18, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this link does not seem to work for me? is the content for this in a PR?

@spectranaut spectranaut Jun 18, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So sorry -- I should have made that more clear. This is also currently being specified and there is a PR: w3c/aria#2800

To see the spec text: https://deploy-preview-2800--wai-aria.netlify.app/core-aam/#computed_accessibility_properties

We need to get agreement between all the browsers on this, and we are working on that actively, it seems like it's close to landing.

</ul>


<dt>Web App Security
<dd><p>The following terms are defined
in the Content Security Policy Level 3 specification: [[CSP3]]
Expand Down
Loading