Bug 647323 - Part a: Document the setup; r=jhammel

dom/tests/mochitest/w3c/README

@@ -0,0 +1,97 @@
+This directory contains tests imported from W3C test suites. In order to make it
+as easy as possible to update these tests, no changes are made to the imported
+files (names for scripted tests do get a test_ prefix to integrate with the test
+runner, however). The scripts to update tests are provided.
+
+
+=======================
+Files in this directory
+=======================
+
+Source;  Usage and purpose;  License
+
+* testharness.js / testharness.css
+  Directly imported from the W3C repository (<http://dvcs.w3.org/hg/resources>),
+  with the updateTestharness.py script.
+  Provide the test harness.
+  W3C Test Suite License / W3C 3-clause BSD License
+
+* idlharness.js
+  Directly imported from the W3C repository (<http://dvcs.w3.org/hg/resources>),
+  with the updateTestharness.py script.
+  Used to test WebIDL.
+  W3C Test Suite License / W3C 3-clause BSD License
+
+* WebIDLParser.js
+  Directly imported from the W3C repository (<http://dvcs.w3.org/hg/resources>),
+  with the updateTestharness.py script.
+  Used by idlharness.js to parse IDL blocks.
+  MIT License
+
+* updateTestharness.py
+  Used to update the above files.
+  MPL
+
+* parseManifest.py
+  Imported from <https://bitbucket.org/ms2ger/test-runner>. Parses MANIFEST
+  files (provided in the W3C repository) as documented at
+  <https://bitbucket.org/ms2ger/test-runner/raw/tip/manifests.txt>.
+  MIT License
+
+* testharnessreport.js.in
+  Glue between testharness.js and our Mochitest runner.
+  MPL
+
+* importTestsuite.py
+  Imports a test suite from a remote repository. Takes one argument, a file in
+  the format described under webapps.txt.
+  Note: removes both source and destination directory before starting. Do not
+        use with outstanding changes in either directory.
+  MPL
+
+* Makefile.in
+  Integration with our build system. Installs support files into /resources and
+  includes a .mk file for each repository.
+  MPL
+
+* failures.txt
+  List of JSON files with expected failures.
+
+* html.json / webapps.json / ...
+  Expected failures for tests in the webapps repository.
+
+* html.mk / webapps.mk / ...
+  Generated by importTestsuite.py from webapps.txt.
+  Contains a list of the directories with tests. To be included in Makefile.in.
+
+* html.txt / webapps.txt / ...
+  Input to importTestsuite.py.
+  Lists the URL of the repository and the destination directory (separated by a
+  vertical bar), followed by a list of directories within the repository
+  (separated by line feeds).
+
+* html / webapps / ...
+  Actual tests.
+  W3C Test Suite License / W3C 3-clause BSD License
+
+* writeReporter.py
+  Generates testharness.js from testharnessreport.js.in and the JSON files for
+  repositories listed in failures.txt.
+  MPL
+
+
+=====================================================================
+Importing an additional directory from an already-imported repository
+=====================================================================
+
+Add a line to the relevant data file (e.g. webapps.txt), with the path to the
+additional directory relative to the root of the remote repository, and then run
+the importTestsuite.py script, passing the data file as its argument.
+
+
+==========================
+Importing a new test suite
+==========================
+
+Create a data file in the format documented above, and run the
+importTestsuite.py script, passing the data file as its argument.