1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
|
# Inspect tools
These cli tools are designed to help to debug accessibility problems in
applications, primarily in web browsers.
* `ax_dump_tree` to show the accessibility tree of an application
* `ax_dump_events` to watch accessibility events fired by application
## Build
To build the tools, run:
```
autoninja -C out/Default ax_dump_tree ax_dump_events
```
The command generates `ax_dump_tree` and `ax_dump_events` executables in
`out/Default` directory.
To use the tools:
1. Enable accessibility on your system and/or target application. Refer to the
"Enabling Accessibility" section below for guidance.
2. Launch the application and go to the specific screen, webpage, or content you
want to inspect.
3. To view the accessibility trees of the application, run `ax_dump_tree
<options>`.
To view accessibility events fired by application, run `ax_dump_events
<options>`. Both tools will output information into the console.
## Options
### Selectors
A selector is needed to specify the application you wish to inspect.
#### Web Browsers:
The following flags can be used to specify a web browser:
* `--chrome` for Chrome browser
* `--chromium` for Chromium browser
* `--firefox` for Firefox browser
* `--edge` for Edge browser (Windows only)
* `--safari` for Safari browser (Mac only)
You may pass in `--active-tab` when using any of the browser selectors above to
dump the tree of active (current) tab. Otherwise, trees from all tabs will be
dumped.
#### Other Applications:
You can specify an application by its title:
`ax_dump_tree --pattern=title`.
The pattern string can contain wildcards like `*` and `?`. Note, you can use the
`--pattern` selector in conjunction with pre-defined browser selectors.
Alternatively, you can dump a tree by HWND on Windows:
`--pid=HWND`
Note, to use a hex window handle prefix it with `0x`.
Or by application PID on Mac and Linux:
`--pid=process_id`
### Filters
By default, the accessibility tree output is filtered to show a specific set of
properties. To control which properties are included or excluded, use the
`--filters` option.
#### How to Use Filters:
1. **Create a Filter File:** Write a plain text file (e.g., filters.txt) where
each line contains one filtering rule.
2. **Apply Filters:** Run the tool with the `--filters` option, specifying the
full path to your filter file:
```
--filters=absolute_path_to_filters.txt
```
#### Filtering Rules:
- `@ALLOW:property_name`: Include the property only if it has a non-empty value.
- `@ALLOW-EMPTY:property_name`: Include the property even if it has an empty
value.
- `@DENY:property_name`: Exclude the property.
#### Examples:
- `@ALLOW:AXARIALive`: Include the `AXARIALive` attribute in the tree.
- `@ALLOW:*`: Include all properties in the tree.
See [example-tree-filters.txt](https://source.chromium.org/chromium/chromium/src/+/main:tools/accessibility/inspect/example-tree-filters.txt)
in `tools/accessibility/inspect` for more examples.
### API option for Windows
On windows, we support two accessibility APIs, IAccessible2 and UI Automation.
By default, IA2 is selected.
To dump a tree with IAccessible2:
`--api=ia2`
To dump a tree with UI Automation:
`--api=uia`
### Other options
`--help` for help
## Examples
To dump an Edge accessible tree on Windows:
``out\Default\ax_dump_tree --edge``
To dump an accessible tree on Mac for a Firefox window with title containing
``mozilla``:
``out/Default/ax_dump_tree --firefox --pattern=*mozilla*``
To watch Chromium accessibility events on Linux:
``out/Default/ax_dump_events --chromium``
## Enabling Accessibility
You may be required to enable accessibility on your system so that accessibility
tree/events are generated. Depending on the application, you may also be
required to run an assistive technology, like a screen reader, or use an
application-specific runtime flag in order to activate accessibility
application-wide.
### Operating System-Specific Instructions
#### Mac
1) Turn on Accessibility for Terminal in Security & Privacy System Preferences.
2) Start VoiceOver (`CMD+F5`) or if your application has a specific
flag/preference to turn on accessibility, use that instead.
#### Linux
Use Orca or use the application specific flag/preference to turn on
accessibility.
#### Windows
Use Narrator/NVDA/JAWS or use the application specific flag/preference to turn
on accessibility.
### Chrome/Chromium
To enable accessibility for Chrome/Chromium, launch chrome with the run time
flag `--force-renderer-accessibility`. For example, on Mac, the full command
would be ``Chromium.app/Contents/MacOS/Chromium --force-renderer-accessibility``.
|
