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