Bug 1179746 - Update wpt README file, r=Ms2ger
authorJames Graham <james@hoppipolla.co.uk>
Tue, 30 Jun 2015 16:00:30 +0100
changeset 271787 4e286f0b5adf3ed55d1b4e2ed48f1a6e0925f605
parent 271786 6da4777d2b18f6fa98b5562399ae496bf7e89141
child 271788 4fc6bd8ccab03ef526c8406e2a49f0bfc82fecd4
push id8304
push userjlund@mozilla.com
push dateMon, 10 Aug 2015 19:25:01 +0000
treeherdermozilla-aurora@7308dd0a6c3b [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersMs2ger
bugs1179746
milestone42.0a1
Bug 1179746 - Update wpt README file, r=Ms2ger
testing/web-platform/README.md
--- a/testing/web-platform/README.md
+++ b/testing/web-platform/README.md
@@ -23,39 +23,53 @@ FAQ
   UNEXPECTED-PASS messages when web-platform-tests is run?
 
   You need to update the expectation data for those tests. See the
   section on expectations below.
 
 * I want to write some new tests for the web-platform-tests
   testsuite. How do I do that?
 
-  See the section on tests below. At the moment you will have to
-  submit the tests directly to the W3C and wait for them to be
-  imported into the Mozilla tree.
+  See the section on tests below. You can commit the tests directly to
+  the Mozilla repository and they will be upstreamed next time the
+  test is imported. For this reason please ensure that any tests you
+  write are testing correct-pre-spec behaviour even if we don't yet
+  pass, get proper review, and have a commit message that makes sense
+  outside of the Mozilla context.
+
+* How do I write a test that requires the use of a Mozilla-specific
+  feature?
+
+  Tests in the `mozilla/tests/` directory use the same harness but are
+  not synced with any upstream. Be aware that these tests run on the
+  server with a `/_mozilla/` prefix to their URLs.
 
 * A test is unstable; how do I disable it?
 
   See the section on disabling tests.
 
 Directories
 -----------
 
 `tests/` contains the tests themselves. This is a copy of a certain
-revision of web-platform-tests. The contents of this directory must
-not be modified locally as any modifications will be overwritten
-whenever a new upstream sync is performed.
+revision of web-platform-tests. Any patches modifying this directory
+will be upstreamed next time the tests are imported.
 
 `harness/` contains the [wptrunner](http://github.com/w3c/wptrunner)
 test runner. Again the contents of this directory will be overwritten
 on update.
 
 `meta/` contains Gecko-specific expectation data. This is explained in
 the following section.
 
+`mozilla/tests` contains tests that will not be upstreamed and may
+make use of Mozilla-specific features.
+
+`mozilla/meta` contains metadata for the Mozilla-specific tests.
+
 Expectation Data
 ----------------
 
 With the tests coming from upstream, it is not guaranteed that they
 all pass in Gecko-based browsers. For this reason it is necessary to
 provide metadata about the expected results of each test. This is
 provided in a set of manifest files in the `meta/` subdirectories.
 
@@ -124,16 +138,52 @@ Tests are disabled using the same manife
 expectation values. For example, if a test is unstable on Windows, it
 can be disabled using an ini file with the contents:
 
     [filename.html]
         type: testharness
         disabled:
             if os == "win": https://bugzilla.mozilla.org/show_bug.cgi?id=1234567
 
+Enabling Prefs
+--------------
+
+Some tests require specific prefs to be enabled before running. These
+prefs can be set in the expectation data using a `prefs` key with a
+comma-seperate list of `pref.name:value` items to set e.g.
+
+    [filename.html]
+        prefs: [dom.serviceWorkers.enabled:true,
+                dom.serviceWorkers.interception.enabled:true,
+                dom.serviceWorkers.exemptFromPerDomainMax:true,
+                dom.caches.enabled:true]
+
+Setting per-Directory Metadata
+------------------------------
+
+Occasionally it is useful to set metadata for an entire directory of
+tests e.g. to disable then all, or to enable prefs for every test. In
+that case it is possible to create a `__dir__.ini` file in the
+metadata directory corresponding to the tests for which you want to
+set this metadata e.g. to disable all the tests in
+`tests/feature/unsupported/`, one might create
+`meta/feature/unsupported/__dir__.ini` with the contents:
+
+    disabled: Feature is unsupported
+
+Settings set in this way are inherited into subdirectories. It is
+possible to unset a value that has been set in a parent using the
+special token `@Reset` (usually used with prefs), or to force a value
+to true or false using `@True` and `@False`.  For example to enable
+the tests in `meta/feature/unsupported/subfeature-supported` one might
+create an ini file
+`meta/feature/unsupported/subfeature-supported/__dir__.ini` like:
+
+    disabled: @False
+
 Test Format
 -----------
 
 Javascript tests are written using
 [testharness.js](http://github.com/w3c/testharness.js/). Reftests are
 similar to standard Gecko reftests without an explicit manifest file,
 but with in-test or filename conventions for identifying the
 reference.