| OLD | NEW |
| (Empty) |
| 1 DumpAccessibilityTreeTest and DumpAccessibilityEventsTest Notes: | |
| 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 | |
| 30 Files used: | |
| 31 * foo.html -- a file to be tested | |
| 32 * foo-expected-android.txt -- expected Android AccessibilityNodeInfo 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 | |
| 37 | |
| 38 Format for expected files: | |
| 39 * Blank lines and lines beginning with # are ignored | |
| 40 * Skipped files: if first line of file begins with #<skip then the | |
| 41 test passes. This can be used to indicate desired output with a link | |
| 42 to a bug, or as a way to temporarily disable a test during refactoring. | |
| 43 * Use 2 plus signs for indent to show hierarchy | |
| 44 | |
| 45 Filters: | |
| 46 * By default only some attributes of nodes in the accessibility tree, or | |
| 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 You can add as many @WAIT-FOR: directives as you want, the test won't finish | |
| 89 until all strings appear. | |
| 90 | |
| 91 To skip dumping a particular element, make its accessible name equal to | |
| 92 @NO_DUMP, for example <div aria-label="@NO_DUMP"></div>. | |
| 93 | |
| 94 To skip dumping all children of a particular element, make its accessible | |
| 95 name equal to @NO_CHILDREN_DUMP. | |
| 96 | |
| 97 To load an iframe from a different site, forcing it into a different process, | |
| 98 use /cross-site/HOSTNAME/ in the url, for example: | |
| 99 <iframe src="cross-site/1.com/accessibility/html/frame.html"></iframe> | |
| 100 | |
| 101 Generating expectations and rebaselining: | |
| 102 | |
| 103 If you want to populate the expectation file directly rather than typing it | |
| 104 or copying-and-pasting it, first make sure the file exists (it can be empty), | |
| 105 then run the test with the --generate-accessibility-test-expectations | |
| 106 argument, for example: | |
| 107 | |
| 108 out/Debug/content_browsertests \ | |
| 109 --generate-accessibility-test-expectations | |
| 110 --gtest_filter="DumpAccessibilityTreeTest.AccessibilityA" | |
| 111 | |
| 112 This will replace the -expected-*.txt file with the current output. It's | |
| 113 a great way to rebaseline a bunch of tests after making a change. Please | |
| 114 manually check the diff, of course! | |
| 115 | |
| 116 Adding a new test: | |
| 117 | |
| 118 If you are adding a new test file remember to add a corresponding test case in | |
| 119 content/browser/accessibility/dump_accessibility_events_browsertest.cc | |
| 120 or | |
| 121 content/browser/accessibility/dump_accessibility_tree_browsertest.cc | |
| 122 | |
| 123 More details on DumpAccessibilityEvents tests: | |
| 124 | |
| 125 These tests are similar to DumpAccessibilityTree tests in that they first | |
| 126 load an HTML document, then dump something, then compare the output to | |
| 127 an expectation file. The difference is that what's dumped is accessibility | |
| 128 events that are fired. | |
| 129 | |
| 130 To write a test for accessibility events, your document must contain a | |
| 131 JavaScript function called go(). This function will be called when the document | |
| 132 is loaded (or when the @WAIT_FOR directive passes), and any subsequent | |
| 133 events will be dumped. Filters apply to events just like in tree dumps. | |
| 134 | |
| 135 After calling go(), the system asks the page to generate a sentinel | |
| 136 accessibility event - one you're unlikely to generate in your test. It uses | |
| 137 that event to know when to "stop" dumping events. There isn't currently a | |
| 138 way to test events that occur after some delay, just ones that happen as | |
| 139 a direct result of calling go(). | |
| OLD | NEW |