Hidden Gem of Chromium Accessibility

Alexander Surkov
5 min readApr 22, 2021


Low-level accessibility tools

There’s a hidden gem in Chromium accessibility. It is the command line accessibility tools. Similar to accessibility inspection tools available on all popular platforms such as Windows or OSX, these tools are designed for the very same purpose: they provide a low level access to accessibility features of a web site. They also have a superpower though that makes them mighty and unique, but let’s talk about it later. Let’s do some backgrounds for the start.

An accessible website means that the assistive technologies like a screen reader can see, perceive and operate on the website. Not every website is accessible. If website content can’t be expressed in a way the assistive technologies understand, then the website is inaccessible. It’s like translating the website to the assistive technologies language: if it cannot be done, then you are out of luck.

Each platform has its own accessibility API, the assistive technologies rely on those to work with websites. In particular it means the website content should be designed in such a way that it can be mapped to those APIs. So if you have an accessibility issue on a website, then quite likely it indicates the content is not properly mapped to the accessibility APIs.

If a website has an accessibility bug, then it’s often a good idea to inspect how the website is mapped to the APIs. Each platform has its own set of accessibility tools: Linux has Accerciser, OSX has Accessibility Inspect, Windows has Inspect. Each browser is also packed by developer tools which incorporate functions for website accessibility inspection. They all are designed to help web authors to better understand how screen readers see a web site. They represent website content in a quite techy way in terms of APIs, objects and their properties, but it may give you a clue why accessibility doesn’t work as expected. It’s definitely worth a shot.

Let’s stop from burrowing further into tech details of how accessibility works. It should be good enough for the context to move back to the original topic. In case if you want to dive deeper, then you can check out this podcast where igalians discuss tech accessibility.

So what makes Chromium accessibility tools special?

  • First, they are cross platform. You have a single tool for all major platforms: Windows, OSX and Linux. It is handy and makes a learning curve shallow.
  • Second, these tools are open source, you know what happens under-the-hood and you can always add a new feature if missing.
  • And finally, these are CLI tools and can be used as a building block to create other accessibility inspection applications. This is my favourite part. I think this latter argument captures the spirit of the Unix world quite nicely, but let’s talk on this later.

The Chromium accessibility is packed by two tools:

  • ax_dump_tree which is used to dump an accessible tree of an application. It makes it quite similar to well known inspection tools (see above) and
  • ax_dump_events tool which is designed to log all accessibility events coming from an application.

Being able to inspect an accessible tree which shows a hierarchy of accessible elements and includes all accessibility properties like name, description is a quite handy feature when you dig into accessibility bugs.

Accessibility events logging can be also super helpful. It’s not something typically supported out of box by existing accessibility tools, but this is a super important bit of information. Indeed, events are the primary notification mechanism used by the assistive technologies to pick up changes from a website. If events are broken, then the assistive technologies get broken too. It makes the ax_dump_events tool special, and also makes another good reason why you’d want to try it next time :)

These tools support a bunch of pre-defined selectors to grab a tree or record events in browsers in no time. For example:

  • — chrome and — chromium for Chrome and Chromium
  • — firefox for Firefox
  • — edge for Edge
  • — safari for Safari

For example, you do:

ax_dump_tree — edge

to dump the accessible tree of Microsoft Edge browser on Windows.

Same with events. To start recording events for Safari browser you do:

ax_dump_events — safari

If you need to scope the tool to a web site (as opposed to the whole browser), then you have — active-tab selector to do so. In case of multiple windows of the same application, you can tune your search by — pattern option. For non browser applications you can specify process ID via — pid option. See docs for full documentation.

Let’s recapture some of the above. You’d want to use these tools when:

  • You need to inspect an accessible tree for a website/test case, or when you need to check which accessibility events are fired: sometimes it’s important to understand how the assistive technologies see your website (Say “hi” to web authors);
  • You need to compare accessible trees/events between browsers. It’s helpful when you need to figure out why a screen reader works in one browser and doesn’t work in another (say “hi” to browser developers);
  • It’s useful to find implementation gaps and inconsistencies (say “hi” to spec authors).

There is no official place for the tools yet. You can build those yourself from Chromium sources. I also prepared nightly builds and uploaded them at my google drive at your convenience.

The tools are awesome: fast, reliable and easy to use. They are perfect except … they have no GUI :) All console tools have such flaws, just by design. Indeed, CLI lacks certain useful options inherent to GUI tools, for example, click-to-inspect feature, which allows you to select a DOM element and inspect its accessible tree. This is very handy. You can find the feature literally in any accessibility tool, and not having it is a real bummer.

But no-GUI disadvantage can become a benefit: the tools can be easily incorporated into other accessibility tools as an accessibility inspect engine. You can create a cross platform GUI tool backed, for example, by Electron, and powered by Chromium’s ax_dump tools. Indeed, you don’t have to c++ or python into web applications accessibility, you can rely on ax_dump tools output instead. Chromium developer tools, which is not surprising, are based on these very same CLI tools.

And last but not least. It opens a new world for cross browser testing. Now you should be able to automate the platform accessibility mapping, for example, HTML-AAM, and it might be an easier solution than Accessible Testing Protocol. Needless to say Chromium already uses it in their automated test suite.

This is the beauty of the Unix word: you have a basic but powerful command line tool, which can serve as an engine to build anything you want upon it: GUI accessibility tools, automated testing, or you can use them as is because they are just cool.



Alexander Surkov

Software engineer and author passionate about web, open source, accessibility and user-facing technologies.