summaryrefslogtreecommitdiffstats
path: root/testing/web-platform/tests/server-side.md
diff options
context:
space:
mode:
authorMoonchild <moonchild@palemoon.org>2021-02-04 19:41:06 +0000
committerMoonchild <moonchild@palemoon.org>2021-02-04 19:41:06 +0000
commit914368530ba622ff0117cd34bec058fb0d862155 (patch)
tree6c29459914d1b01ed27fad039d0b982d1dbc32c3 /testing/web-platform/tests/server-side.md
parentc5ad76a2875ca5c06c5bbff7b2f2e3ff7b3599c3 (diff)
downloadUXP-914368530ba622ff0117cd34bec058fb0d862155.tar
UXP-914368530ba622ff0117cd34bec058fb0d862155.tar.gz
UXP-914368530ba622ff0117cd34bec058fb0d862155.tar.lz
UXP-914368530ba622ff0117cd34bec058fb0d862155.tar.xz
UXP-914368530ba622ff0117cd34bec058fb0d862155.zip
Issue #439 - Remove web-platform tests from the tree.
This removes a total of 23,936 files we would never use nor have the capacity to properly maintain or keep up-to-date.
Diffstat (limited to 'testing/web-platform/tests/server-side.md')
-rw-r--r--testing/web-platform/tests/server-side.md234
1 files changed, 0 insertions, 234 deletions
diff --git a/testing/web-platform/tests/server-side.md b/testing/web-platform/tests/server-side.md
deleted file mode 100644
index 46a9e8367..000000000
--- a/testing/web-platform/tests/server-side.md
+++ /dev/null
@@ -1,234 +0,0 @@
-# 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/).