third_party/wpt_tools/README.md

   1 # W3C Web Platform Tests in Blink Web Tests
   2
   3 Design Doc: https://goo.gl/iXUaZd
   4
   5 This directory contains checked out and reduced code from web-platform-tests
   6 (https://github.com/web-platform-tests/wpt/) required to run WPT tests as part
   7 of Blink's test infrastructure and some maintenance/configuration code.
   8
   9 For licensing, see README.chromium
  10
  11 **
  12
  13 Files in this directory (non third-party)
  14
  15 README.chromium
  16 ===============
  17 Parseable details on the project name, URL, license, etc.
  18
  19 README.md
  20 =========
  21 This file.
  22
  23 wpt.config.json
  24 ===============
  25 The configuration file used when running WPTServe. Note that this file loads
  26 after wpt/config.default.json and this configuration gets merged onto it. When
  27 changing the ports (HTTP/S, WS/S), make sure to also:
  28
  29 - update `WPT_HOST_AND_PORTS` in
  30   `//third_party/blink/tools/blinkpy/web_tests/port/driver.py`
  31 - update WebTestContentBrowserClient::GetOriginsRequiringDedicatedProcess()
  32
  33 checkout.sh
  34 ===========
  35 Running this script without arguments will remove the existing checkout
  36 (//third_party/wpt_tools/wpt) and perform a fresh one. See "Rolling in WPT".
  37
  38 WPTIncludeList
  39 ==============
  40 The explicit list of files being kept, everything else not on this list is
  41 deleted when running "./checkout.sh reduce". Use this file to control what gets
  42 checked in and try to keep the list as small as possible (use what you need).
  43
  44 certs/
  45 ======
  46 This directory contains a private key and a certificate of WPTServe, and files
  47 for self-signed CA. By default, WPTServe generates these files using the
  48 "openssl" command, but we check in pre-generated files to avoid "openssl"
  49 dependency.
  50
  51 These certificates will expire in January 2025. Here is an instruction to
  52 re-generate them:
  53
  54 1. Make sure the following commands are in $PATH.
  55  - base64
  56  - git
  57  - grep
  58  - openssl
  59  - sed
  60 2. Run update_certs.py
  61 3. Look at the "Not After" date in the output of the command, and update
  62   "January 2025" in this document and expiration_date in wptserve.py to new
  63   expiration date.
  64 4. Update certs/127.0.0.1.sxg.\*.
  65   Please refer to
  66   //third_party/blink/web_tests/http/tests/loading/sxg/resources/README.md
  67 5. git commit
  68 6. git cl upload, etc.
  69
  70 Rolling in WPT
  71 ==============
  72
  73 If there are new files that need to be rolled in, add the intended files to
  74 the WPTIncludeList. Ensure these files are in the correct order by running
  75 "LC_ALL=C sort WPTIncludeList".
  76
  77 When rolling in new versions of WPT support, modify WPT_HEAD in checkout.sh to
  78 the desired HEAD position. You can then call "./checkout.sh clone" which will
  79 pull in all the code.
  80
  81 It is also important to update the hashes in the 'Version:' fields of
  82 //third_party/wpt_tools/README.chromium. While you're in this file, look at the
  83 "Local Modifications" section which lists ways in which Chromium has diverged
  84 from WPT. Make sure these modifications are persisted when reviewing the changes
  85 being made.
  86
  87 You can examine what's pulled in and update WPTIncludeList if some new files are
  88 required to run the updated version.
  89
  90 Once you've cloned the repositories you can call "./checkout.sh reduce" to
  91 remove everything that is not listed in WPTIncludeList.
  92
  93 Note that calling "./checkout.sh" without arguments is equivalent of calling
  94 "./checkout.sh clone reduce".
  95
  96 Configuration
  97 =============
  98
  99 Read instructions in WPT README:
 100 https://github.com/web-platform-tests/wpt/blob/master/README.md
 101
 102 Also, check out the WPTServe Documentation
 103 (https://wptserve.readthedocs.org/en/latest/).
 104
 105 Note that editing /etc/hosts is not required for run_web_tests.py since
 106 content_shell is invoked with flags to map all \*.test domains to 127.0.0.1.
 107
 108 Running web-platform-tests with enabled WPTServe on a local machine
 109 ===================================================================
 110
 111 WPTServe is now enabled by default in run_web_tests.py for tests that live in
 112 web_tests/external/wpt.
 113
 114 WPTServe starts HTTP/S and WS/S servers as separate processes.
 115
 116 The content_shell used to run the tests will receive the URL of each test
 117 (instead of a filename). The document root http://web-platform.test/ maps to
 118 web_test/external/wpt. HTTPS tests are enabled by default.
 119
 120 Example run:
 121
 122 ./tools/run_web_tests.py external/wpt