chromium/src/third_party/blink/web_tests/http/tests/fetch/README

Fetch API LayoutTests README

This directory contains Fetch API layout tests.
Tests should conform to Service Worker Testing style[1].

1: http://www.chromium.org/blink/serviceworker/testing

# generator.py

The files under
- /fetch/window/
- /fetch/workers/
- /fetch/serviceworker/
- /fetch/serviceworker-proxied/
are generated by the generator.
Run
$ python generate.py
at this (/LayoutTests/http/tests/fetch/) directory to generate these files
from templates script-tests/TEMPLATE*.html.

There are two kinds of tests. One is regular tests placed on script-tests
directory and another is "thorough" tests placed on script-tests/thorough
directory. Each has its own template files and default option settings.
Note: thorough tests were called as "fetch-access-control" tests. auth.js
was called as fetch-access-control-auth.js, for example.

# Running on window, workers, serviceworker, serviceworker-proxied

As it is exposed to Window and Worker, most (if not all) of tests are expected
to run on Window, DedicatedWorker and ServiceWorker.
For each test (say X), we have
- a script X.js in /fetch/script-tests,
- /fetch/window/X.html Window test file,
- /fetch/workers/X.html Worker test file, and
- /fetch/serviceworker/X.html ServiceWorker test file.

Some tests that require a serviceworker to test CORS requests are executed in
- /fetch/serviceworker-proxied/X.html.

# BASE_ORIGIN, OTHER_ORIGIN, and HTTP/HTTPS OPTIONS

BASE_ORIGIN is the origin of HTML/JS files where tests are executed.
OTHER_ORIGIN is used to test cross-origin requests.
To control whether BASE_ORIGIN/OTHER_ORIGIN is HTTP or HTTPS, OPTIONS string
is used.

----------------------------- ----------------------- ----------- ------------
Filename                      OPTIONS                 BASE_ORIGIN OTHER_ORIGIN
----------------------------- ----------------------- ----------- ------------
X.html                        (empty)                 HTTP        HTTP
X-other-https.html            -other-https            HTTP        HTTPS
X-base-https.html             -base-https             HTTPS       HTTP
X-base-https-other-https.html -base-https-other-https HTTPS       HTTPS
----------------------------- ----------------------- ----------- ------------

X.js is common to all options.
The test switches by location.href at runtime.

The options to be generated is listed in a line in X.js like:
// OPTIONS: ,-other-https,-base-https-other-https
(Three files for OPTIONS = (empty), -other-https, -base-https-other-https are
generated)
Default:
  For thorough tests: ,-other-https,-base-https-other-https
  For others: ,-base-https-other-https

# HOSTS and custom hostnames

One can also override the hostnames used for the base origin and other origin.
By default they are '127.0.0.1' and 'localhost', but some tests may require
use of other URLs for behavior that differs between localhost URLs and web URLs.

For example (to use base host 'a.test' and remote host 'b.test'):
  Put this in the script-tests X.js file (and run generate.py):
    // HOSTS: 'a.test', 'b.test'
  Add the same hostnames to the URL getter calls in X.js as well:
    get_fetch_test_options('a.test', 'b.test');
    get_thorough_test_options('a.test', 'b.test');

Then when running the test, there will be a preliminary redirect from the
starting URL of http://127.0.0.1/.../X.html to http://a.test/.../X.html before
proceeding.

TODO(chlily): Finish plumbing work to actually apply custom hostnames. The
get_*_test_options() calls should take the custom hostnames.

# File structure

Helper JS files and server side scripts are located on
/fetch/resources and /serviceworker/resources:
- /serviceworker/resources/test-helpers.js
    Utility functions for all tests.
    Include this before X.js and from HTML files.
- /fetch/resources/fetch-test-options.js
    Process test options for X.js. BASE_ORIGIN/OTHER_ORIGIN are defined here.
    Include this before X.js and thorough-util.js.
- /fetch/resources/fetch-test-helpers.js
    Variables/functions commonly used from X.js.
    Include this before X.js.
- /fetch/resources/thorough-util.js
    Utility functions for thorough tests.
    Include this before X.js in thorough tests.
- /fetch/resources/init.js
    Initialization script executed on window.
    Include this from HTML files.

Files needed from HTML/X.js files for each tests:
----------------------------------------------------- ------------ ------------
                                                      HTML         X.js
Files                                                 wi wo sw swp wi wo sw swp
----------------------------------------------------- -- -- -- --- -- -- -- ---
/serviceworker/resources/test-helpers.js              Y  Y  Y  Y   .  .  .  .
/fetch/resources/fetch-test-options.js                Y  -  -  Y   .  .  .  .
/fetch/resources/fetch-test-helpers.js                Y  -  -  Y   .  Y  Y  .
/fetch/resources/thorough-util.js                     Y* -  -  Y*  .  Y* Y* .
/fetch/script-tests/X.js                              Y  -  -  Y
/fetch/resources/init.js                              Y  Y  Y  Y   -  -  -  -
----------------------------------------------------- ------------ ------------
wi/wo/sw/swp: window/workers/serviceworker/serviceworker-proxied.
Y: to be included.
-: not to be included.
.: included indirectly via HTML or fetch-test-helpers.js.
Y*: thorough tests only.

# PRESUBMIT.py

FIXME: currently PRESUBMIT.py is somehow outdated and thus disabled.

PRESUBMIT.py checks the existence of the files.
For each file in /fetch/script-tests, the
corresponding html files must exist at the paths listed above.