third_party/WebKit/LayoutTests/http/tests/fetch/README

   1 Fetch API LayoutTests README
   2
   3 This directory contains Fetch API layout tests.
   4 Tests should conform to Service Worker Testing style[1].
   5
   6 1: http://www.chromium.org/blink/serviceworker/testing
   7
   8 # generator.py
   9
  10 The files under
  11 - /fetch/window/
  12 - /fetch/workers/
  13 - /fetch/serviceworker/
  14 - /fetch/serviceworker-proxied/
  15 are generated by the generator.
  16 Run
  17 $ python generate.py
  18 at this (/LayoutTests/http/tests/fetch/) directory to generate these files
  19 from templates script-tests/TEMPLATE*.html.
  20
  21 There are two kinds of tests. One is regular tests placed on script-tests
  22 directory and another is "thorough" tests placed on script-tests/thorough
  23 directory. Each has its own template files and default option settings.
  24 Note: thorough tests were called as "fetch-access-control" tests. auth.js
  25 was called as fetch-access-control-auth.js, for example.
  26
  27 # Running on window, workers, serviceworker, serviceworker-proxied
  28
  29 As it is exposed to Window and Worker, most (if not all) of tests are expected
  30 to run on Window, DedicatedWorker and ServiceWorker.
  31 For each test (say X), we have
  32 - a script X.js in /fetch/script-tests,
  33 - /fetch/window/X.html Window test file,
  34 - /fetch/workers/X.html Worker test file, and
  35 - /fetch/serviceworker/X.html ServiceWorker test file.
  36
  37 Some tests that require a serviceworker to test CORS requests are executed in
  38 - /fetch/serviceworker-proxied/X.html.
  39
  40 # BASE_ORIGIN, OTHER_ORIGIN, and HTTP/HTTPS OPTIONS
  41
  42 BASE_ORIGIN is the origin of HTML/JS files where tests are executed.
  43 OTHER_ORIGIN is used to test cross-origin requests.
  44 To control whether BASE_ORIGIN/OTHER_ORIGIN is HTTP or HTTPS, OPTIONS string
  45 is used.
  46
  47 ----------------------------- ----------------------- ----------- ------------
  48 Filename                      OPTIONS                 BASE_ORIGIN OTHER_ORIGIN
  49 ----------------------------- ----------------------- ----------- ------------
  50 X.html                        (empty)                 HTTP        HTTP
  51 X-other-https.html            -other-https            HTTP        HTTPS
  52 X-base-https.html             -base-https             HTTPS       HTTP
  53 X-base-https-other-https.html -base-https-other-https HTTPS       HTTPS
  54 ----------------------------- ----------------------- ----------- ------------
  55
  56 X.js is common to all options.
  57 The test switches by location.href at runtime.
  58
  59 The options to be generated is listed in a line in X.js like:
  60 // OPTIONS: ,-other-https,-base-https-other-https
  61 (Three files for OPTIONS = (empty), -other-https, -base-https-other-https are
  62 generated)
  63 Default:
  64   For thorough tests: ,-other-https,-base-https-other-https
  65   For others: ,-base-https-other-https
  66
  67 # File structure
  68
  69 Helper JS files and server side scripts are located on
  70 /fetch/resources and /serviceworker/resources:
  71 - /serviceworker/resources/test-helpers.js
  72     Utility functions for all tests.
  73     Include this before X.js and from HTML files.
  74 - /fetch/resources/fetch-test-options.js
  75     Process test options for X.js. BASE_ORIGIN/OTHER_ORIGIN are defined here.
  76     Include this before X.js and thorough-util.js.
  77 - /fetch/resources/fetch-test-helpers.js
  78     Variables/functions commonly used from X.js.
  79     Include this before X.js.
  80 - /fetch/resources/thorough-util.js
  81     Utility functions for thorough tests.
  82     Include this before X.js in thorough tests.
  83 - /fetch/resources/init.js
  84     Initialization script executed on window.
  85     Include this from HTML files.
  86
  87 Files needed from HTML/X.js files for each tests:
  88 ----------------------------------------------------- ------------ ------------
  89                                                       HTML         X.js
  90 Files                                                 wi wo sw swp wi wo sw swp
  91 ----------------------------------------------------- -- -- -- --- -- -- -- ---
  92 /serviceworker/resources/test-helpers.js              Y  Y  Y  Y   .  .  .  .
  93 /fetch/resources/fetch-test-options.js                Y  -  -  Y   .  .  .  .
  94 /fetch/resources/fetch-test-helpers.js                Y  -  -  Y   .  Y  Y  .
  95 /fetch/resources/thorough-util.js                     Y* -  -  Y*  .  Y* Y* .
  96 /fetch/script-tests/X.js                              Y  -  -  Y
  97 /fetch/resources/init.js                              Y  Y  Y  Y   -  -  -  -
  98 ----------------------------------------------------- ------------ ------------
  99 wi/wo/sw/swp: window/workers/serviceworker/serviceworker-proxied.
 100 Y: to be included.
 101 -: not to be included.
 102 .: included indirectly via HTML or fetch-test-helpers.js.
 103 Y*: thorough tests only.
 104
 105 # PRESUBMIT.py
 106
 107 FIXME: currently PRESUBMIT.py is somehow outdated and thus disabled.
 108
 109 PRESUBMIT.py checks the existence of the files.
 110 For each file in /fetch/script-tests, the
 111 corresponding html files must exist at the paths listed above.