update-w3c-deps import using blink 7f8c8ee3e30dc15b7b821c627fc7ac32331d2253:

LayoutTests/imported/web-platform-tests/server-side.md

-# 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/).