imported/w3c/web-platform-tests should contain top level files of the W3C web-platfor...
authoryouenn.fablet@crf.canon.fr <youenn.fablet@crf.canon.fr@268f45cc-cd09-0410-ab3c-d52691b4dbfc>
Tue, 3 Feb 2015 08:45:14 +0000 (08:45 +0000)
committeryouenn.fablet@crf.canon.fr <youenn.fablet@crf.canon.fr@268f45cc-cd09-0410-ab3c-d52691b4dbfc>
Tue, 3 Feb 2015 08:45:14 +0000 (08:45 +0000)
https://bugs.webkit.org/show_bug.cgi?id=141151

Reviewed by Ryosuke Niwa.

* web-platform-tests/CONTRIBUTING.md: Added.
* web-platform-tests/LICENSE: Added.
* web-platform-tests/README.md: Added.
* web-platform-tests/server-side.md: Added.
* web-platform-tests/w3c-import.log:

git-svn-id: https://svn.webkit.org/repository/webkit/trunk@179542 268f45cc-cd09-0410-ab3c-d52691b4dbfc

LayoutTests/imported/w3c/ChangeLog
LayoutTests/imported/w3c/web-platform-tests/CONTRIBUTING.md [new file with mode: 0644]
LayoutTests/imported/w3c/web-platform-tests/LICENSE [new file with mode: 0644]
LayoutTests/imported/w3c/web-platform-tests/README.md [new file with mode: 0644]
LayoutTests/imported/w3c/web-platform-tests/server-side.md [new file with mode: 0644]
LayoutTests/imported/w3c/web-platform-tests/w3c-import.log

index 2a64c1c3a34099cfe35b3b868da7222d736f4438..ba253729a53f808625610f40b2c1f73720a06e09 100644 (file)
@@ -1,3 +1,16 @@
+2015-02-03  Youenn Fablet  <youenn.fablet@crf.canon.fr>
+
+        imported/w3c/web-platform-tests should contain top level files of the W3C web-platform-tests repository
+        https://bugs.webkit.org/show_bug.cgi?id=141151
+
+        Reviewed by Ryosuke Niwa.
+
+        * web-platform-tests/CONTRIBUTING.md: Added.
+        * web-platform-tests/LICENSE: Added.
+        * web-platform-tests/README.md: Added.
+        * web-platform-tests/server-side.md: Added.
+        * web-platform-tests/w3c-import.log:
+
 2015-01-31  Youenn Fablet  <youenn.fablet@crf.canon.fr>
 
         Import W3C web platform tests infrastructure
diff --git a/LayoutTests/imported/w3c/web-platform-tests/CONTRIBUTING.md b/LayoutTests/imported/w3c/web-platform-tests/CONTRIBUTING.md
new file mode 100644 (file)
index 0000000..0e7968a
--- /dev/null
@@ -0,0 +1,29 @@
+Grant of License
+----------------
+
+By contributing to this repository, you and the company you represent, if the
+company holds any copyrights in the contribution, grant to the W3C a perpetual,
+non-exclusive, royalty-free, world-wide right and license under all of your
+copyrights in this contribution to copy, publish, use, and modify the
+contribution and to distribute the contribution under a BSD License or one with
+more restrictive terms, as well as a right and license of the same scope to any
+derivative works prepared by the W3C and based on or incorporating all or part
+of the contribution. You further agree that any derivative works of this
+contribution prepared by the W3C shall be solely owned by the W3C.
+
+You state, to the best of your knowledge, that you, or the company you
+represent, have all rights necessary to contribute the materials.
+
+W3C will retain attribution of initial authorship to you. The W3C makes no
+a-priori commitment to support or distribute contributions.
+
+Disclaimer
+----------
+
+All content from this repository is provided as is, and W3C makes no
+representations or warranties, express or implied, including, but not limited
+to, warranties of merchantability, fitness for a particular purpose,
+non-infringement, or title; nor that the contents of this repository are
+suitable for any purpose. We make no representations, express or implied, that
+the content of this repository or the use thereof indicates conformance to a
+specification. All content is provided as-is to help reach interoperability.
diff --git a/LayoutTests/imported/w3c/web-platform-tests/LICENSE b/LayoutTests/imported/w3c/web-platform-tests/LICENSE
new file mode 100644 (file)
index 0000000..f3d6617
--- /dev/null
@@ -0,0 +1,3 @@
+This repository is covered by the dual-licensing approach described in:
+
+    http://www.w3.org/Consortium/Legal/2008/04-testsuite-copyright.html
diff --git a/LayoutTests/imported/w3c/web-platform-tests/README.md b/LayoutTests/imported/w3c/web-platform-tests/README.md
new file mode 100644 (file)
index 0000000..fdaa7a9
--- /dev/null
@@ -0,0 +1,225 @@
+The Web Platform Tests Project [![IRC chat](https://goo.gl/6nCIks)](http://irc.w3.org/?channels=testing)
+==============================
+
+These are test suites for 60+ Web-platform specifications, along
+with test-infrastructure code for running the tests.
+
+Running the Tests
+=================
+
+The tests are designed to be run from your local computer. The test
+environment requires Python 2.7+ (but not Python 3.x). You will also
+need a copy of OpenSSL. For users on Windows this is available from
+[the openssl website](https://www.openssl.org/related/binaries.html).
+
+To get the tests running, you need to set up the test domains in your
+[`hosts` file](http://en.wikipedia.org/wiki/Hosts_%28file%29%23Location_in_the_file_system). The following entries are required:
+
+```
+127.0.0.1      web-platform.test
+127.0.0.1      www.web-platform.test
+127.0.0.1      www1.web-platform.test
+127.0.0.1      www2.web-platform.test
+127.0.0.1      xn--n8j6ds53lwwkrqhv28a.web-platform.test
+127.0.0.1      xn--lve-6lad.web-platform.test
+```
+
+Because web-platform-tests uses git submodules, you must ensure that
+these are up to date. In the root of your checkout, run:
+
+```
+git submodule update --init --recursive
+```
+
+The test environment can then be started using
+
+```
+python serve.py
+```
+
+This will start HTTP servers on two ports and a websockets server on
+one port. By default one web server starts on port 8000 and the other
+ports are randomly-chosen free ports. Tests must be loaded from the
+*first* HTTP server in the output. To change the ports, edit the
+`config.json` file, for example, replacing the part that reads:
+
+```
+"http": [8000, "auto"]
+```
+
+to some port of your choice e.g.
+
+```
+"http":[1234, "auto"]
+```
+
+If you installed OpenSSL in such a way that running `openssl` at a
+command line doesn't work, you also need to adjust the path to the
+OpenSSL binary. This can be done by adding a section to `config.json`
+like:
+
+```
+"ssl": {"openssl": {"binary": "/path/to/openssl"}}
+```
+
+Test Runner
+===========
+
+There is a test runner that is designed to provide a
+convenient way to run the web-platform tests in-browser. It will run
+testharness.js tests automatically but requires manual work for
+reftests and manual tests.
+
+In order to use the runner, it is first necessary to generate a test
+manifest. This must be called `MANIFEST.json` and placed in the
+web-platform-tests root.
+
+You must do this step to use the test runner, even if you are not
+creating a new test suite.
+
+To generate this file, from a command prompt at the root
+directory of the repo, run:
+
+```
+python tools/scripts/manifest.py
+```
+This `tools/scripts/manifest.py` needs python `html5lib` package.
+If you have not installed it yet, run:
+```
+pip install html5lib
+```
+
+On Mac OS X, python is installed with Xcode, but pip is not. Try
+```
+sudo easy_install pip
+```
+if pip is not already on your system.
+
+
+Running the tests requires that the test environment be activated as
+described above. The runner can be found at `/tools/runner/index.html`
+on the local server i.e.
+
+```
+http://web-platform.test:8000/tools/runner/index.html
+```
+
+in the default configuration.
+
+Publication
+===========
+
+The master branch is automatically synced to http://w3c-test.org/.
+
+Pull requests that have been checked are automatically mirrored to
+http://w3c-test.org/submissions/.
+
+Finding Things
+==============
+
+Each top-level directory represents a W3C specification: the name
+matches the shortname used after the canonical address of the said
+specification under http://www.w3.org/TR/ .
+
+For some of the specifications, the tree under the top-level directory
+represents the sections of the respective documents, using the section
+IDs for directory names, with a maximum of three levels deep.
+
+So if you're looking for tests in HTML for "The History interface",
+they will be under `html/browsers/history/the-history-interface/`.
+
+Various resources that tests depend on are in `common`, `images`, and
+`fonts`.
+
+
+If you're looking at a section of the specification and can't figure
+out where the directory is for it in the tree, just run:
+
+```
+node tools/scripts/id2path.js your-id
+```
+
+Branches
+========
+
+In the vast majority of cases the **only** branch that you should need
+to care about is `master`.
+
+There is another branch called `CR`. This is a strict subset of
+`master` that is limited to features that are found in the Candidate
+Recommendation version of the relevant specifications.
+
+If you see other branches in the repository, you can generally safely
+ignore them. Please note that branches prefixed with `temp/` are
+temporary branches and **can** get deleted at some point. So don't
+base any work off them unless you want to see your work destroyed.
+
+Contributing
+============
+
+Save the Web, Write Some Tests!
+
+Absolutely everyone is welcome (and even encouraged) to contribute to
+test development, so long as you fulfill the contribution requirements
+detailed in the [Contributing Guidelines][contributing]. No test is
+too small or too simple, especially if it corresponds to something for
+which you've noted an interoperability bug in a browser.
+
+The way to contribute is just as usual:
+
+* fork this repository (and make sure you're still relatively in sync
+  with it if you forked a while ago);
+* create a branch for your changes:
+  `git checkout -b your-name/topic`;
+* make your changes;
+* push that to your repo;
+* and send in a pull request based on the above.
+
+Please make your pull requests either to `master` or to a feature
+branch (but not to `CR`).
+
+We can sometimes take a little while to go through pull requests
+because we have to go through all the tests and ensure that they match
+the specification correctly. But we look at all of them, and take
+everything that we can.
+
+If you wish to contribute actively, you're very welcome to join the
+public-test-infra@w3.org mailing list (low traffic) by
+[signing up to our mailing list](mailto:public-test-infra-request@w3.org?subject=subscribe).
+The mailing list is [archived][mailarchive].
+
+Join us on irc #testing ([irc.w3.org][ircw3org], port 6665). The channel
+is [archived][ircarchive].
+
+[contributing]: https://github.com/w3c/web-platform-tests/blob/master/CONTRIBUTING.md
+[ircw3org]: https://www.w3.org/wiki/IRC
+[ircarchive]: http://krijnhoetmer.nl/irc-logs/testing/
+[mailarchive]: http://lists.w3.org/Archives/Public/public-test-infra/
+
+Adding command-line scripts ("tools" subdirs)
+----------------------------------------------------
+Sometimes you may want to add a script to the repository that's meant to be used from the
+command line, not from a browser (e.g., a script for generating test files). If you want to
+ensure (e.g., or security reasons) that such scripts won't be handled by the HTTP server,
+but will instead only be usable from the command line, then place them in either:
+
+* the `tools` subdir at the root of the repository, or
+* the `tools` subdir at the root of any top-level directory in the repository which
+  contains the tests the script is meant to be used with
+
+Any files in those `tools` directories won't be handled by the HTTP server; instead the
+server will return a 404 if a user navigates to the URL for a file within them.
+
+If you want to add a script for use with a particular set of tests but there isn't yet any
+`tools` subdir at the root of a top-level directory in the repository containing those
+tests, you can create a `tools` subdir at the root of that top-level directory and place
+your scripts there.
+
+For example, if you wanted to add a script for use with tests in the `notifications`
+directory, create the `notifications/tools` subdir and put your script there.
+
+Documentation
+-------------
+
+* [How to write and review tests](http://testthewebforward.org/docs/)
+* [Documentation for the wptserve server](http://wptserve.readthedocs.org/en/latest/)
diff --git a/LayoutTests/imported/w3c/web-platform-tests/server-side.md b/LayoutTests/imported/w3c/web-platform-tests/server-side.md
new file mode 100644 (file)
index 0000000..46a9e83
--- /dev/null
@@ -0,0 +1,234 @@
+# Writing Complex Tests #
+
+For many tests, writing one or more static HTML files is
+sufficient. However there are a large class of tests for which this
+approach is insufficient, including:
+
+* Tests that require cross-domain access
+
+* Tests that depend on setting specific headers or status codes
+
+* Tests that need to inspect the browser sent request
+
+* Tests that require state to be stored on the server
+
+* Tests that require precise timing of the response.
+
+To make writing such tests possible, we are using a number of
+server-side components designed to make it easy to manipulate the
+precise details of the response:
+
+* *wptserve*, a custom python HTTP server.
+
+* *pywebsocket*, an existing websockets server
+
+This document will concentrate on the features of wptserve available
+to test authors.
+
+## Introduction to wptserve ##
+
+wptserve is a python-based web server. By default it serves static
+files in the testsuite. For more sophisticated requirements, several
+mechanisms are available to take control of the response. These are
+outlined below.
+
+## Pipes ##
+
+Suitable for:
+
+ * Cross domain requests
+ * Adding headers or status codes to static files
+ * Controlling the sending of static file bodies
+
+Pipes are designed to allow simple manipulation of the way that
+static files are sent without requiring any custom code. They are also
+useful for cross-origin tests because they can be used to activate a
+substitution mechanism which can fill in details of ports and server
+names in the setup on which the tests are being run.
+
+Pipes are indicated by adding a query string to a request for a static
+resource, with the parameter name `pipe`. The value of the query
+should be a `|` serperated list of pipe functions. For example to
+return a `.html` file with the status code 410 and a Content-Type of
+text/plain, one might use:
+
+    /resources/example.html?pipe=status(410)|header(Content-Type,text/plain)
+
+There are a selection of pipe functions provided with wptserve and
+more may be added if there are good use cases.
+
+### sub ###
+
+Used to subsitute variables from the server environment, or from the
+request into the response. A typical use case is for testing
+cross-domain since the exact domain name and ports of the servers are
+generally unknown.
+
+Substitutions are marked in a file using a block delimited by `{{`
+and `}}`. Inside the block the following variables are avalible:
+
+* `{{host}}` - the host name of the server exclusing any subdomain part.
+* `{{domains[]}}` - the domain name of a particular subdomain
+    e.g. `{{domains[www]}}` for the `www` subdomain.
+* `{{ports[][]}}` - The port number of servers, by protocol
+    e.g. `{{ports[http][1]}}` for the second (i.e. non-default) http
+  server.
+* `{{headers[]}}` - The HTTP headers in the request
+    e.g. `{{headers[X-Test]}}` for a hypothetical `X-Test` header.
+* `{{GET[]}}` - The query parameters for the request
+    e.g. `{{GET[id]}}` for an id parameter sent with the request.
+
+So, for example, to write a javascript file called `xhr.js` that does a
+cross domain XHR test to a different subdomain and port, one would
+write in the file:
+
+    var server_url = "http://{{domains[www]}}:{{ports[http][1]}}/path/to/resource";
+    //Create the actual XHR and so on
+
+The file would then be included as:
+
+    <script src="xhr.js?pipe=sub"></script>
+
+### status ###
+
+Used to set the HTTP status of the response, for example:
+
+    example.js?pipe=status(410)
+
+### headers ###
+
+Used to add or replace http headers in the response. Takes two or
+three arguments; the header name, the header value and whether to
+append the header rather than replace an existing header (default:
+False). So, for example, a request for:
+
+    example.html?pipe=header(Content-Type,text/plain)
+
+causes example.html to be returned with a text/plain content type
+whereas:
+
+    example.html?pipe=header(Content-Type,text/plain,True)
+
+Will cause example.html to be returned with both text/html and
+text/plain content-type headers.
+
+### slice ###
+
+Used to send only part of a response body. Takes the start and,
+optionally, end bytes as arguments, although either can be null to
+indicate the start or end of the file, respectively. So for example:
+
+    example.txt?pipe=slice(10,20)
+
+Would result in a response with a body containing 10 bytes of
+example.txt including byte 10 but excluding byte 20.
+
+    example.txt?pipe=slice(10)
+
+Would cause all bytes from byte 10 of example.txt to be sent, but:
+
+    example.txt?pipe=slice(null,20)
+
+Would send the first 20 bytes of example.txt.
+
+### trickle ###
+
+Used to send the body of a response in chunks with delays. Takes a
+single argument that is a microsyntax consisting of colon-separated
+commands. There are three types of commands:
+
+* Bare numbers represent a number of bytes to send
+
+* Numbers prefixed `d` indicate a delay in seconds
+
+* Numbers prefixed `r` must only appear at the end of the command, and
+    indicate that the preceding N items must be repeated until there is
+  no more content to send.
+
+In the absence of a repetition command, the entire remainder of the content is
+sent at once when the command list is exhausted. So for example:
+
+    example.txt?pipe=trickle(d1)
+
+causes a 1s delay before sending the entirety of example.txt.
+
+    example.txt?pipe=trickle(100:d1)
+
+causes 100 bytes of example.txt to be sent, followed by a 1s delay,
+and then the remainder of the file to be sent. On the other hand:
+
+    example.txt?pipe=trickle(100:d1:r2)
+
+Will cause the file to be sent in 100 byte chunks separated by a 1s
+delay until the whole content has been sent.
+
+## asis files ##
+
+Suitable for:
+
+ * Static, HTTP-non-compliant responses
+
+asis files are simply files with the extension `.asis`. They are sent
+byte for byte to the server without adding a HTTP status line,
+headers, or anything else. This makes them suitable for testing
+situations where the precise bytes on the wire are static, and control
+over the timing is unnecessary, but the response does not conform to
+HTTP requirements.
+
+## py files ##
+
+Suitable for:
+
+ * All tests requiring dynamic responses
+ * Tests that need to store server side state.
+
+The most flexible mechanism for writing tests is to use `.py`
+files. These are interpreted as code and are suitable for the same
+kinds of tasks that one might achieve using cgi, PHP or a similar
+technology. Unlike cgi or PHP, the file is not executed directly and
+does not produce output by writing to `stdout`. Instead files must
+contain (at least) a function named `main`, with the signature:
+
+    def main(request, response):
+        pass
+
+Here `request` is a `Request` object that contains details of the
+request, and `response` is a `Response` object that can be used to set
+properties of the response. Full details of these objects is
+provided in the [wptserve documentation](http://wptserve.readthedocs.org/en/latest/).
+
+In many cases tests will not need to work with the `response` object
+directly. Instead they can set the status, headers and body simply by
+returning values from the `main` function. If any value is returned,
+it is interpreted as the response body. If two values are returned
+they are interpreted as headers and body, and three values are
+interpreted as status, headers, body. So, for example:
+
+    def main(request, response):
+        return "TEST"
+
+creates a response with no non-default headers and the body
+`TEST`. Headers can be added as follows:
+
+    def main(request, response):
+        return ([("Content-Type", "text/plain"), ("X-Test", "test")],
+                "TEST")
+
+And a status code as:
+
+    def main(request, response):
+        return (410,
+                [("Content-Type", "text/plain"), ("X-Test", "test")],
+              "TEST")
+
+A custom status string may be returned by using a tuple `code, string`
+in place of the code alone.
+
+At the other end of the scale, some tests require precision over the
+exact bytes sent over the wire and their timing. This can be achieved
+using the `writer` property of the response, which exposes a
+`ResponseWriter` object that allows wither writing specific parts of
+the request or direct access to the underlying socket.
+
+For full documentation on the facilities available in `.py` files, see
+the [wptserve documentation](http://wptserve.readthedocs.org/en/latest/).
index b6cd6559e049d5d5a389e408988954830cc3d4cf..0547d6852d047bd6931e87bf99ae258566f05419 100644 (file)
@@ -9,7 +9,7 @@ Then run the Tools/Scripts/import-w3c-tests in Webkit to reimport
 Do NOT modify or remove this file
 
 ------------------------------------------------------------------------
-Last Import: 2015-01-27 10:26
+Last Import: 2015-02-02 11:42
 ------------------------------------------------------------------------
 Properties requiring vendor prefixes:
 None
@@ -17,5 +17,10 @@ Property values requiring vendor prefixes:
 None
 ------------------------------------------------------------------------
 List of files:
+/LayoutTests/imported/w3c/web-platform-tests/CONTRIBUTING.md
+/LayoutTests/imported/w3c/web-platform-tests/LICENSE
+/LayoutTests/imported/w3c/web-platform-tests/README.md
+/LayoutTests/imported/w3c/web-platform-tests/SUBMODULES
 /LayoutTests/imported/w3c/web-platform-tests/config.default.json
 /LayoutTests/imported/w3c/web-platform-tests/serve.py
+/LayoutTests/imported/w3c/web-platform-tests/server-side.md