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 |