The wpt Writing Tests documentation should be updated #45943
Comments
|
@gsnedders Where does the web-platform-tests.org documentation even live? |
|
A few comments:
|
|
David, Thank you for taking the time to write your detailed comments.
We have review of tests and there are test reviewers. Professionalisation of tests and testing insure quality of tests and testing. I have never rejected tests unless they were false, bad or fundamentally incorrect. I always have tried to rehabilitate inadequately (or poorly) formated tests as long as they were testing a testable spec statement to begin with. point 3: The null end tag I was referring to is, e.g.: point 5 (Optional end tags): I have been formally asked to remove all optional end tags and optional tags ( If CSS tests do not need optional end tags and optional tags and if minimal - reduced as much as possible - filesize is a recommandable goal in itself and by itself, then such requirement makes sense. As I understand, it takes several hours to several computers to go through all the wpt tests for the 4 browsers. Only necessary filesize makes sense in that regard. Varying HTML content (tags and elements) makes sense for HTML testing, when testing HTML. point 7 (Length of tests filenames): Only a very small minority of CSS tests exceed 60 characters. I wish I knew how to find them (with a grep command) and list them in order to establish precisely their percentage from the whole set of CSS tests. I estimate (just a hunch) that less than 0.1% use, exceed more than 60 characters. A filename should not be a sentence describing a test. A long (> 48 characters) filename does not help review, does not replace a title text and does not replace useful comments or a text assert. I do not see how anyone gets help from a long filename. point 8 (Where to get maxDifference and totalPixels values.)
I never found such information all by myself. And recently, Sebastian Zartner was wondering and asking where he could find those values.
Of course. Agreed. I will be away from web and internet for a week. |
First, my proposal wrt point 5 was not for existing CSS tests but for upcoming CSS tests. |
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.5to 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
The text was updated successfully, but these errors were encountered: