Some updates to do in documentation files, or discussions/clarifications to have

Geoffrey,

1-
Reference File
"All metadata is removed."
http://web-platform-tests.org/writing-tests/reftests.html#reference-file

Actually, that is usually true but sometimes not true. If a reference 
file uses some flag(s), then a <meta name="flags" content=""> will be 
required.


2-
Support Files
http://web-platform-tests.org/writing-tests/general-guidelines.html#support-files

Somehow, somewhere, it must be said that all images (new and old ones) 
must be put into a separate, distinct /support folder. Images can not be 
alongside tests. At least 20 tests (imported from vendors) into 
/css-backgrounds-3 folder have problems because of that.


3-
Controlling When Comparison Occurs
http://web-platform-tests.org/writing-tests/reftests.html#controlling-when-comparison-occurs

"reftest-wait" and "reftest-print"

Mozilla people have been adding "reftest-print" to print related tests. 
Discussion starts here:
https://bugzilla.mozilla.org/show_bug.cgi?id=685012#c49
We may have to have a discussion on this and eventually add a paragraph 
about this.


4-
Ahem usage
http://web-platform-tests.org/writing-tests/ahem.html#usage

"as such, the font shorthand should normally be used." "doesn't use font 
shorthand;": font shorthand should not be recommended. I think it should 
be neutral: not encouraged, not discouraged. When I create a test that 
uses font shorthand, then I can not easily and quickly examine 
subproperties with web inspection tools. Also, font shorthand is more 
"sensitive", demanding: if only 1 subproperty is invalid, then the 
shorthand is rejected, ignored while declaring subproperties in 
individual declarations will only affect the invalid declarations and 
not the other valid subproperty declarations.


5-
Recommended versus to avoid:
http://web-platform-tests.org/writing-tests/ahem.html#usage

a) I would put a green border around the recommended block and a red 
border around the to avoid block. Otherwise would use a light red-ish 
background and a light green-ish background.

b) Also
.highlight .c {
     color: #998;
this color is too light; insufficient color contrast.


6-
Be short
http://web-platform-tests.org/writing-tests/general-guidelines.html#be-short
"
For reftests in particular scrollbars at 800×600px window size must be 
avoided unless scrolling behavior is specifically being tested.
"
This, I believe, was changed to 600px by 600px. Thread starts here:
Reftest Maximum Viewport Size
https://lists.w3.org/Archives/Public/public-css-testsuite/2012Sep/0020.html

Also:
"the two files render pixel-for-pixel identically within a 600x600 
window including scroll-bars if present;"
http://web-platform-tests.org/writing-tests/reftests.html#components-of-a-reftest

"The device has a viewport width of at least 800px."
http://web-platform-tests.org/writing-tests/assumptions.html
If pixel comparison involves only 600px, then why should we require a 
minimum of 800?

I am wondering if the documentation is consistently coherent with 
regards to viewport width and presence of scrollbars.

"The test renders within a 600x600 viewport, only displaying scrollbars 
if their presence is being tested. "
http://web-platform-tests.org/reviewing-tests/checklist.html


7-
Fixing lint errors
http://web-platform-tests.org/writing-tests/lint-tool.html#fixing-lint-errors

fix: replace all setTimeout(...) calls with step_timeout(...) calls.

What is the problem, what is wrong with
<body onload="setTimeout(test, 5)">
?
eg
http://test.csswg.org/shepherd/testcase/background-root-101/


8-
Linking to a shared reference file which is across folders is no longer 
recommended or doable. But this is not mentioned in
http://web-platform-tests.org/writing-tests/reftests.html#writing-a-good-reftest


9-
Use extended form in title for abbreviations. eg <abbr title="Common 
Interface">CI</abbr>
Can't remember what CI means...
http://web-platform-tests.org/reviewing-tests/checklist.html#all-tests

Avoid "here" as links.
http://web-platform-tests.org/writing-tests/general-guidelines.html#be-cross-platform


10-
http://web-platform-tests.org/writing-tests/css-metadata.html#requirement-flags
Example 2 uses 2 obsolete flag tokens.


11-
<link rel="help" href="https://www.w3.org/TR/CSS21/visudet.html#q7" />
in
http://web-platform-tests.org/writing-tests/css-metadata.html#specification-links
should be removed from example 2 since q7 target has no anchor and never 
was in specification's Table of Contents on top of everything.


12-
Nit: "whether a test has passed of failed.": or
http://web-platform-tests.org/writing-tests/general-guidelines.html#be-self-describing

Nit: "Various support files are available in in the /common/ and 
/media/": 2 in
http://web-platform-tests.org/writing-tests/general-guidelines.html#support-files


- - - - - - - -


HTML5 doctype is recommended but is XHTML 1 strict doctype declaration 
forbidden for tests? The current documentation does not mention this.

Gérard

Received on Saturday, 25 March 2017 21:13:58 UTC