summaryrefslogtreecommitdiffstats
path: root/testing/web-platform/tests/docs/writing-tests/file-names.md
diff options
context:
space:
mode:
Diffstat (limited to 'testing/web-platform/tests/docs/writing-tests/file-names.md')
-rw-r--r--testing/web-platform/tests/docs/writing-tests/file-names.md78
1 files changed, 78 insertions, 0 deletions
diff --git a/testing/web-platform/tests/docs/writing-tests/file-names.md b/testing/web-platform/tests/docs/writing-tests/file-names.md
new file mode 100644
index 0000000000..96296c4ff6
--- /dev/null
+++ b/testing/web-platform/tests/docs/writing-tests/file-names.md
@@ -0,0 +1,78 @@
+# File Name Flags
+
+The test filename is significant in determining the type of test it
+contains, and enabling specific optional features. This page documents
+the various flags available and their meaning.
+
+In some cases flags can also be set via a directory name, such that any file
+that is a (recursive) descendent of the directory inherits the flag value.
+These are individually documented for each flag that supports it.
+
+
+### Test Type
+
+These flags must be the last element in the filename before the
+extension e.g. `foo-manual.html` will indicate a manual test, but
+`foo-manual-other.html` will not. Unlike test features, test types
+are mutually exclusive.
+
+
+`-manual`
+ : Indicates that a test is a non-automated test.
+
+`-visual`
+ : Indicates that a file is a visual test.
+
+
+### Test Features
+
+These flags are preceded by a `.` in the filename, and must
+themselves precede any test type flag, but are otherwise unordered.
+
+
+`.https`
+ : Indicates that a test is loaded over HTTPS.
+
+ `.h2`
+ : Indicates that a test is loaded over HTTP/2.
+
+ `.www`
+ : Indicates that a test is run on the `www` subdomain.
+
+`.sub`
+ : Indicates that a test uses the [server-side substitution](server-pipes.html#sub)
+ feature.
+
+`.window`
+ : (js files only) Indicates that the file generates a test in which
+ it is run in a Window environment.
+
+`.worker`
+ : (js files only) Indicates that the file generates a test in which
+ it is run in a dedicated worker environment.
+
+`.any`
+ : (js files only) Indicates that the file generates tests in which it
+ is [run in multiple scopes](testharness).
+
+`.optional`
+ : Indicates that a test makes assertions about optional behavior in a
+ specification, typically marked by the [RFC 2119] "MAY" or "OPTIONAL"
+ keywords. This flag should not be used for "SHOULD"; such requirements
+ can be tested with regular tests, like "MUST".
+
+`.tentative`
+ : Indicates that a test makes assertions not yet required by any specification,
+ or in contradiction to some specification. This is useful when implementation
+ experience is needed to inform the specification. It should be apparent in
+ context why the test is tentative and what needs to be resolved to make it
+ non-tentative.
+
+ This flag can be enabled for an entire directory (and all its descendents),
+ by naming the directory 'tentative'. For example, every test underneath
+ 'foo/tentative/' will be considered tentative.
+
+It's preferable that `.window`, `.worker`, and `.any` are immediately followed
+by their final `.js` extension.
+
+[RFC 2119]: https://tools.ietf.org/html/rfc2119