src/third_party/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/).