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