tor-browser

HTTP Caching Tests

These tests cover HTTP-specified behaviours for caches, primarily from RFC9111, but as seen through the lens of Fetch.

A few notes:

• By its nature, [caching is entirely optional](

https://www.rfc-editor.org/rfc/rfc9111.html#section-2-2); some tests expecting a response to be cached might fail because the client chose not to cache it, or chose to race the cache with a network request.

• Likewise, some tests might fail because there is a separate document-level

cache that's not well defined; see [this issue](https://github.com/whatwg/fetch/issues/354).

• Partial content tests (a.k.a. Range requests) are not specified

in Fetch; tests are included here for interest only.

• Some browser caches will behave differently when reloading /

shift-reloading, despite the cache mode staying the same.

• cache-tests.fyi is another test suite of HTTP caching

which also caters to server/CDN implementations.

Test Format

Each test run gets its own URL and randomized content and operates independently.

Each test is an an array of objects, with the following members:

• name - The name of the test.
• requests - a list of request objects (see below).

Possible members of a request object:

• template - A template object for the request, by name.
• request_method - A string containing the HTTP method to be used.
• requestheaders - An array of `[headernamestring, headervalue_string]` arrays to

emit in the request.

• request_body - A string to use as the request body.
• mode - The mode string to pass to fetch().
• credentials - The credentials string to pass to fetch().
• cache - The cache string to pass to fetch().
• pause_after - Boolean controlling a 3-second pause after the request completes.
• response_status - A [number, string] array containing the HTTP status code

and phrase to return.

• responseheaders - An array of `[headernamestring, headervalue_string]` arrays to

emit in the response. These values will also be checked like expectedresponseheaders, unless there is a third value that is false. See below for special handling considerations.

• response_body - String to send as the response body. If not set, it will contain

the test identifier.

• expectedtype - One of `["cached", "notcached", "lmvalidate", "etagvalidate", "error"]`
• expected_status - A number representing a HTTP status code to check the response for.

If not set, the value of response_status[0] will be used; if that is not set, 200 will be used.

• expectedrequestheaders - An array of [header_name_string, header_value_string] representing

headers to check the request for.

• expectedresponseheaders - An array of [header_name_string, header_value_string] representing

headers to check the response for. See also response_headers.

• expectedresponsetext - A string to check the response body against. If not present, response_body will be checked if present and non-null; otherwise the response body will be checked for the test uuid (unless the status code disallows a body). Set to null to disable all response body checking.
• url_params - A string of url parameters that will be appended to the end of the url, separated by "&" and without leading "&".

Some headers in response_headers are treated specially:

• For date-carrying headers, if the value is a number, it will be interpreted as a delta to the time of the first request at the server.
• For URL-carrying headers, the value will be appended as a query parameter for target.

See the source for exact details.