Update web-platform-tests to revision 8119bc10583682676a3db9806c82ed4044e88e13

tests/wpt/web-platform-tests/docs/writing-tests/python-handlers/index.md

@@ -22,12 +22,15 @@ This function must return a value in one of the following four formats:
     content
 
 Above, `headers` is a list of (field name, value) pairs, and `content` is a
-string or an iterable returning strings. The `main` function may also update
-the response manually. For example, one may use `response.headers.set` to set a
-response header, and only return the content. One may even use this kind of
-handler, but manipulate the output socket directly, in which case the return
-value of the function, and the properties of the response object, will be
-ignored.
+string or an iterable returning strings.
+
+The `main` function may also update the response manually. For example, one may
+use `response.headers.set` to set a response header, and only return the
+content. One may even use this kind of handler, but manipulate the output
+socket directly. The `writer` property of the response exposes a
+`ResponseWriter` object that allows writing specific parts of the request or
+direct access to the underlying socket. If used, the return value of the
+`main` function and the properties of the `response` object will be ignored.
 
 The wptserver implements a number of Python APIs for controlling traffic.
 

tests/wpt/web-platform-tests/docs/writing-tests/server-features.md

@@ -1,12 +1,31 @@
 # Server Features
 
-## Advanced Testing Features
+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:
 
-Certain test scenarios require more than just static HTML
-generation. This is supported through the
-[wptserve](http://wptserve.readthedocs.io) server, and controlled by
-[file name flags](file-names). Several scenarios in particular are common:
+* 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
+
+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.
 
 ### Tests Involving Multiple Origins
 
@@ -90,14 +109,18 @@ the file e.g. `test.html.sub.headers`.
    server-pipes
 ```
 
-For full control over the request and response the server provides the
-ability to write `.asis` files; these are served as literal HTTP
-responses. It also provides the ability to write [Python
+For full control over the request and response, the server provides the ability
+to write `.asis` files; these are served as literal HTTP responses. In other
+words, they are sent byte-for-byte to the server without adding an 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.
+
+The server also provides the ability to write [Python
 "handlers"](python-handlers/index)--Python scripts that have access to request
 data and can manipulate the content and timing of the response. Responses are
 also influenced by [the `pipe` query string parameter](server-pipes).
 
-
 ### Writing tests for HTTP/2.0
 
 The server now has a prototype HTTP/2.0 server which gives you access to

tests/wpt/web-platform-tests/docs/writing-tests/server-pipes.md

@@ -1,5 +1,11 @@
 # wptserve Pipes
 
+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.
+
 ## Enabling
 
 Pipes are functions that may be used when serving files to alter parts
@@ -28,7 +34,9 @@ preventing the use of HTTP 1.1 keepalive.
 ### `sub`
 
 Used to substitute variables from the server environment, or from the
-request into the response.
+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 available: