OLD | NEW |
1 DumpAccessibilityTreeTest Notes | 1 DumpAccessibilityTreeTest and DumpAccessibilityEventsTest Notes: |
2 | 2 |
| 3 Both sets of tests use a similar format for files. |
| 4 |
| 5 DumpAccessibilityTree tests load an HTML file, wait for it to load, then |
| 6 dump the accessibility tree in the "blink" format (the internal data), |
| 7 and again in a platform-specific format. |
| 8 |
| 9 The test output is a compact text representation of the accessibility tree |
| 10 for that format, and it should be familiar if you're familiar with the |
| 11 accessibility protocol on that platform, but it's not in a standardized |
| 12 format - it's just a text dump, meant to be compared to expected output. |
| 13 |
| 14 The exact output can be filtered so it only dumps the specific attributes |
| 15 you care about for a specific test. |
| 16 |
| 17 One the output has been generated, it compares the output to an expectation |
| 18 file in the same directory. If an expectation file for that test for that |
| 19 platform is present, it must match exactly or the test fails. If no |
| 20 expectation file is present, the test passes. Most tests don't have |
| 21 expectations on all platforms. |
| 22 |
| 23 DumpAccessibilityEvent tests use a similar format but dump events fired after |
| 24 the document finishes loading. See more on this below. |
| 25 |
| 26 Compiling and running the tests: |
| 27 ninja -C out/Debug content_browsertests |
| 28 out/Debug/content_browsertests --gtest_filter="DumpAccessibility*" |
| 29 |
3 Files used: | 30 Files used: |
4 * foo.html -- a file to be tested | 31 * foo.html -- a file to be tested |
5 * foo-expected-win.txt -- expected MSAA output | 32 * foo-expected-android.txt -- expected Android AccessibilityNodeInfo output |
6 * foo-expected-mac.txt -- expected Mac accessibility output | 33 * foo-expected-auralinux.txt -- expected Linux ATK output |
| 34 * foo-expected-blink.txt -- representation of internal accessibility tree |
| 35 * foo-expected-mac.txt -- expected Mac NSAccessibility output |
| 36 * foo-expected-win.txt -- expected Win IAccessible/IAccessible2 output |
7 | 37 |
8 Format for expected files: | 38 Format for expected files: |
9 * Blank lines and lines beginning with # are ignored | 39 * Blank lines and lines beginning with # are ignored |
10 * Skipped files: if first line of file begins with #<skip then the entire file i
s ignored, | 40 * Skipped files: if first line of file begins with #<skip then the |
11 but listed in the output as skipped | 41 test passes. This can be used to indicate desired output with a link |
12 * Use 4 spaces for indent to show hierarchy | 42 to a bug, or as a way to temporarily disable a test during refactoring. |
13 * MSAA states do not have a prefix, e.g. FOCUSED, not STATE_SYSTEM_FOCUSED | 43 * Use 2 plus signs for indent to show hierarchy |
14 * All other constants are used exactly as normally named | |
15 * See specific examples (e.g. ul-expected-win.txt) for more details | |
16 | 44 |
17 Compiling and running the tests: | 45 Filters: |
18 ninja -C out/Debug content_browsertests | 46 * By default only some attributes of nodes in the accessibility tree, or |
19 out/Debug/content_browsertests --gtest_filter="DumpAccessibilityTreeTest*" | 47 events fired (when running DumpAccessibilityEvents) are output. |
| 48 This is to keep the tests robust and not prone to failure when unrelated |
| 49 changes affect the accessibility tree in unimportant ways. |
| 50 * Filters contained in the HTML file can be used to control what is output. |
| 51 They can appear anywhere but typically they're in an HTML comment block, |
| 52 and must be one per line. |
| 53 * Filters are platform-specific: |
| 54 @WIN- |
| 55 @MAC- |
| 56 @BLINK- |
| 57 @ANDROID- |
| 58 @AURALINUX- |
| 59 * To dump all attributes while writing or debugging a test, add this filter: |
| 60 @WIN-ALLOW:* |
| 61 (and similarly for other platforms). |
| 62 * Once you know what you want to output, you can use filters to match the |
| 63 attributes and attribute values you want included in the output. An |
| 64 ALLOW filter means to include the attribute, and a DENY filter means to |
| 65 exclude it. Filters can contain simple wildcards ('*') only, they're not |
| 66 regular expressions. Examples: |
| 67 - @WIN-ALLOW:name* - this will output the name attribute on Windows |
| 68 - @WIN-ALLOW:name='Foo' - this will only output the name attribute if it |
| 69 exactly matches 'Foo'. |
| 70 - @WIN-DENY:name='X* - this will skip outputting any name that begins with |
| 71 the letter X. |
| 72 * By default empty attributes are skipped. To output the value an attribute |
| 73 even if it's empty, use @WIN-ALLOW-EMPTY:name, for example, and similarly |
| 74 for other platforms. |
| 75 |
| 76 Advanced: |
| 77 |
| 78 Normally the system waits for the document to finish loading before dumping |
| 79 the accessibility tree. |
| 80 |
| 81 Occasionally you may need to write a test that makes some changes to the |
| 82 document before it runs the test. In that case you can use a special |
| 83 @WAIT-FOR: directive. It should be in an HTML comment, just like |
| 84 @ALLOW-WIN: directives. The WAIT-FOR directive just specifies a text substring |
| 85 that should be present in the dump when the document is ready. The system |
| 86 will keep blocking until that text appears. |
| 87 |
| 88 To skip dumping a particular element, make its accessible name equal to |
| 89 @NO_DUMP, for example <div aria-label="@NO_DUMP"></div>. |
| 90 |
| 91 To skip dumping all children of a particular element, make its accessible |
| 92 name equal to @NO_CHILDREN_DUMP. |
| 93 |
| 94 Generating expectations and rebaselining: |
| 95 |
| 96 If you want to populate the expectation file directly rather than typing it |
| 97 or copying-and-pasting it, first make sure the file exists (it can be empty), |
| 98 then run the test with the --generate-accessibility-test-expectations |
| 99 argument, for example: |
| 100 |
| 101 out/Debug/content_browsertests \ |
| 102 --generate-accessibility-test-expectations |
| 103 --gtest_filter="DumpAccessibilityTreeTest.AccessibilityA" |
| 104 |
| 105 This will replace the -expected-*.txt file with the current output. It's |
| 106 a great way to rebaseline a bunch of tests after making a change. Please |
| 107 manually check the diff, of course! |
| 108 |
| 109 Adding a new test: |
20 | 110 |
21 If you are adding a new test file remember to add a corresponding test case in | 111 If you are adding a new test file remember to add a corresponding test case in |
22 content/browser/accessibility/dump_accessibility_events_browsertest.cc | 112 content/browser/accessibility/dump_accessibility_events_browsertest.cc |
23 or | 113 or |
24 content/browser/accessibility/dump_accessibility_tree_browsertest.cc | 114 content/browser/accessibility/dump_accessibility_tree_browsertest.cc |
| 115 |
| 116 More details on DumpAccessibilityEvents tests: |
| 117 |
| 118 These tests are similar to DumpAccessibilityTree tests in that they first |
| 119 load an HTML document, then dump something, then compare the output to |
| 120 an expectation file. The difference is that what's dumped is accessibility |
| 121 events that are fired. |
| 122 |
| 123 To write a test for accessibility events, your document must contain a |
| 124 JavaScript function called go(). This function will be called when the document |
| 125 is loaded (or when the @WAIT_FOR directive passes), and any subsequent |
| 126 events will be dumped. Filters apply to events just like in tree dumps. |
| 127 |
| 128 After calling go(), the system asks the page to generate a sentinel |
| 129 accessibility event - one you're unlikely to generate in your test. It uses |
| 130 that event to know when to "stop" dumping events. There isn't currently a |
| 131 way to test events that occur after some delay, just ones that happen as |
| 132 a direct result of calling go(). |
OLD | NEW |