From 9f5a0803b3129ba4b4e4b647eb181d65db6f89eb Mon Sep 17 00:00:00 2001 From: Alexander Surkov Date: Wed, 10 Mar 2021 21:49:16 +0000 Subject: [PATCH] ax_dump tools: update inspect tools docs Bug: 1177438 Change-Id: I06701639c748688ac491ddafa2b41a1416d8fbd1 Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/2736075 Commit-Queue: Alexander Surkov Reviewed-by: Aaron Leventhal Cr-Commit-Position: refs/heads/master@{#861714} --- tools/accessibility/inspect/README.md | 94 +++++++++++++++++---------- 1 file changed, 59 insertions(+), 35 deletions(-) diff --git a/tools/accessibility/inspect/README.md b/tools/accessibility/inspect/README.md index 759ae3649667c8..eff9acb97ed320 100644 --- a/tools/accessibility/inspect/README.md +++ b/tools/accessibility/inspect/README.md @@ -2,47 +2,71 @@ These cli tools are designed to help to debug accessibility problems in applications, primarily in web browsers. -`ax_dump_tree` to inspect accessibility tree of application -`ax_dump_events` to watch accessibility events fired by application +* `ax_dump_tree` to inspect accessibility tree of application +* `ax_dump_events` to watch accessibility events fired by application -Note: if you are on Windows, see convenience scripts section, it makes the tools easier to use on Windows. +## Prerequisites -## Build +You may be required to enable accessibility on your system. 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 or flip +a preference on in order to activate accessibility application-wide. -`autoninja -C out/Default ax_dump_tree ax_dump_events` +### Mac -The command generates `ax_dump_tree` and `ax_dump_events` executables in `out/Default` directory. +1) Turn on Accessibility for Terminal in Security & Privacy System Preferences. -## Prerequesties +2) Either +* Start VoiceOver (`CMD+F5`) or +* Use application specific flag/preference + * Chrome/Chromium: use `--force-renderer-accessibility` runtime flag -### Mac +For example, to enable accessibility in Chromium run: +```Chromium.app/Contents/MacOS/Chromium --force-renderer-accessibility``` -1) Turn on Accessibility for Terminal in Security & Privacy System Preferences. +### Linux + +Either +* Start Orca or +* Use application specific flag/preference + * Chrome/Chromium: use `--force-renderer-accessibility` runtime flag -2) Some applications keep accessibility inactive, which prevents them to generate accessible trees or emit events. Thus either: -* start VoiceOver (`CMD+F5`) or -* use application specific runtime flags -** Chromium: `Chromium.app/Contents/MacOS/Chromium --force-renderer-accessibility` +### Windows + +Either +* Start Narrator/NVDA/JAWS or +* Use application specific flag/preference + * Chrome/Chromium: use `--force-renderer-accessibility` runtime flag ## ax_dump_tree Helps to inspect accessibility trees of applications. Trees are dumped into console. -### Run - To dump an accessible tree, run: `ax_dump_tree ` +## ax_dump_events + +The tool logs into console accessibility events fired by application. + +To watch accessibility events, run: +`ax_dump_events ` + +## Options + At your convenience the number of pre-defined application selectors are available: -`--chrome` for Chrome browser -`--chromium` for Chromium browser -`--firefox` for Firefox browser -`--safari` for Safari 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) -`--active-tab` to dump a tree of active tab of selected browser. +`--active-tab` to dump a tree of active tab of a selected browser. You can also specify an application by its title: `ax_dump_tree --pattern=title` +The pattern string can contain wildcards like * and ?. Note, you can use +``--pattern`` selector in conjunction with pre-defined selectors. Alternatively you can dump a tree by HWND on Windows: `--pid=HWND` @@ -52,26 +76,26 @@ Or by application PID on Mac and Linux: `--pid=process_id` Other options: -`--filters=absolute_path_to_filters.txt` to filter properties, use where the filters text file has a series of `@ALLOW` and/or `@DENY` lines. See example-tree-filters.txt in tools/accessibility/inspect. +`--filters=absolute_path_to_filters.txt` to filter properties, use where +the filters text file has a series of `@ALLOW` and/or `@DENY` lines. See +example-tree-filters.txt in tools/accessibility/inspect. + `--help` for help -## ax_dump_events +## Examples -The tool logs into console accessibility events fired by application. +To dump Edge accessible tree on Windows: +``out\Default\ax_dump_tree --edge`` -To watch accessibility events, run: -`ax_dump_events ` +To dump an accessible tree on Mac for a Firefox window having title containing ``mozilla``: +``out/Default/ax_dump_tree --firefox --pattern=*mozilla*`` -Use these pre-defined application selectors to indicate application: -`--chrome` for Chrome browser -`--chromium` for Chromium browser -`--firefox` for Firefox browser -`--safari` for Safari browser +To watch Chromium accessibility events on Linux: +``out/Default/ax_dump_events --chromium`` -`--active-tab` to scope events to an active tab of selected browser. +## Build -You can also specify application by its title: -`--pattern=title` +`autoninja -C out/Default ax_dump_tree ax_dump_events` -Or by application PID: -`--pid=process_id` +The command generates `ax_dump_tree` and `ax_dump_events` executables in +`out/Default` directory.