Description
After submitting many CSS tests and after reviewing a bunch of them, I am convinced that the
Writing Tests documentation
should be updated in numerous spots and areas. Here is the start of a list of items that should become part of the Writing Tests documentation. I welcome others to add items to this short list.
1-
No new line at end of file. If a new line character is missing at end of file, then an icon of a red circle with a red minus sign inside of it is visible in the Commits tab. Ideally, someone could explain why the new line character at end of file is important.
And maybe the lint tool should report missing new line character at end of CSS tests files too.
2-
How to restart the Continuous Integration checks of a Pull Request? By closing the Pull Request and reopening it. This should be documented somewhere in the
Writing Tests documentation
as a tip.
3-
Null End Tag. They are not a mistake but they are not needed, not useful, not necessary. They occupy, use 2 bytes each for no reason since CSS tests resort to and require HTML5.
4-
800x600 or 600x600 viewport. The documentation should choose and clarify this.
"
The test renders within a 800x600 viewport
"
coming from
http://web-platform-tests.org/reviewing-tests/checklist.html#visual-tests-only
while elsewhere it is written 600x600
5-
Optional end tags. </p>, </li>, </dt>, </option>, </tr>, </td>, </body>, </head>, </html>, etc... are not necessary, not needed and not useful for CSS testing.
Same thing with optional start tags like <html>, <head>, <body> . The documentation should formally promote the absence of optional HTML tags in CSS tests.
HTML5, §13.1.2.4 Optional tags
6-
Larger line spacing of the documentation itself. By setting line-height: 1.5 to the body node, the Writing Tests documentation itself would be easier to read. The documentation itself should strive to become compliant with WCAG 2 AAA, § 1.4.8 Visual Presentation:
"Line spacing (leading) is at least space-and-a-half within paragraphs, and paragraph spacing is at least 1.5 times larger than the line spacing."
7-
Length of tests filenames. Some tests' filenames are as long as 65 characters. I have not searched extensively (albeit PR43587) but maybe there are some filenames even longer than 65 characters. I suggest a 32-characters long filename as ideal and I would set the limit to 48-characters long. A filename should not substitute or should not try to substitute to a title text, text assert (if and when suitable) and to shepherding comments inside a test.
8-
Where to get maxDifference and totalPixels values. Somewhere inside the Fuzzy Matching section, the documentation could indicate how to get those values.
@gsnedders , @SebastianZ , @dbaron , @fantasai , @frivoal