Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(580)

Side by Side Diff: content/test/data/accessibility/readme.md

Issue 2728663004: Added docs on accessibility tests (Closed)
Patch Set: Created 3 years, 9 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View unified diff | Download patch
« no previous file with comments | « no previous file | content/test/data/accessibility/readme.txt » ('j') | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
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().
OLDNEW
« no previous file with comments | « no previous file | content/test/data/accessibility/readme.txt » ('j') | no next file with comments »

Powered by Google App Engine
This is Rietveld 408576698