[Web Animations] Update WPT tests related to Web Animations and remove imported Mozil...
[WebKit-https.git] / LayoutTests / imported / w3c / web-platform-tests / README.md
1 The web-platform-tests Project [![IRC chat](https://goo.gl/6nCIks)](http://irc.w3.org/?channels=testing)
2 ==============================
3
4 The web-platform-tests Project is a W3C-coordinated attempt to build a
5 cross-browser testsuite for the Web-platform stack. Writing tests in a way
6 that allows them to be run in all browsers gives browser projects
7 confidence that they are shipping software that is compatible with other
8 implementations, and that later implementations will be compatible with
9 their implementations. This in turn gives Web authors/developers
10 confidence that they can actually rely on the Web platform to deliver on
11 the promise of working across browsers and devices without needing extra
12 layers of abstraction to paper over the gaps left by specification
13 editors and implementors.
14
15 Setting Up the Repo
16 ===================
17
18 Clone or otherwise get https://github.com/w3c/web-platform-tests.
19
20 Running the Tests
21 =================
22
23 The tests are designed to be run from your local computer. The test
24 environment requires [Python 2.7+](http://www.python.org/downloads) (but not Python 3.x).
25
26 On Windows, be sure to add the Python directory (`c:\python2x`, by default) to
27 your `%Path%` [Environment Variable](http://www.computerhope.com/issues/ch000549.htm),
28 and read the [Windows Notes](#windows-notes) section below.
29
30 To get the tests running, you need to set up the test domains in your
31 [`hosts` file](http://en.wikipedia.org/wiki/Hosts_%28file%29%23Location_in_the_file_system). The
32 following entries are required:
33
34 ```
35 127.0.0.1   web-platform.test
36 127.0.0.1   www.web-platform.test
37 127.0.0.1   www1.web-platform.test
38 127.0.0.1   www2.web-platform.test
39 127.0.0.1   xn--n8j6ds53lwwkrqhv28a.web-platform.test
40 127.0.0.1   xn--lve-6lad.web-platform.test
41 0.0.0.0     nonexistent-origin.web-platform.test
42 ```
43
44 If you are behind a proxy, you also need to make sure the domains above are
45 excluded from your proxy lookups.
46
47
48 Running Tests Manually
49 ======================
50
51 The test server can be started using
52
53     ./wpt serve
54
55 This will start HTTP servers on two ports and a websockets server on
56 one port. By default one web server starts on port 8000 and the other
57 ports are randomly-chosen free ports. Tests must be loaded from the
58 *first* HTTP server in the output. To change the ports, copy the
59 `config.default.json` file to `config.json` and edit the new file,
60 replacing the part that reads:
61
62 ```
63 "http": [8000, "auto"]
64 ```
65
66 to some port of your choice e.g.
67
68 ```
69 "http": [1234, "auto"]
70 ```
71
72 Running Tests Automatically
73 ---------------------------
74
75 Tests can be run automatically in a browser using the `run` command of
76 the `wpt` script in the root of the checkout. This requires the hosts
77 file setup documented above, but you must *not* have the
78 test server already running when calling `wpt run`. The basic command
79 line syntax is:
80
81 ```
82 ./wpt run product [tests]
83 ```
84
85 **On Windows**: You will need to preceed the prior command with
86 `python` or the path to the python binary.
87
88 where `product` is currently `firefox` or `chrome` and `[tests]` is a
89 list of paths to tests. This will attempt to automatically locate a
90 browser instance and install required dependencies. The command is
91 very configurable; for examaple to specify a particular binary use
92 `wpt run --binary=path product`. The full range of options can be see
93 with `wpt run --help` and `wpt run --wptrunner-help`.
94
95 Not all dependencies can be automatically installed; in particular the
96 `certutil` tool required to run https tests with Firefox must be
97 installed using a system package manager or similar.
98
99 On Debian/Ubuntu certutil may be installed using:
100
101 ```
102 sudo apt install libnss3-tools
103 ```
104
105 And on macOS with homebrew using:
106
107 ```
108 brew install nss
109 ```
110
111 Command Line Tools
112 ==================
113
114 The `wpt` command provides a frontend to a variety of tools for
115 working with and running web-platform-tests. Some of the most useful
116 commands are:
117
118 * `wpt serve` - For starting the wpt http server
119 * `wpt run` - For running tests in a browser
120 * `wpt lint` - For running the lint against all tests
121 * `wpt manifest` - For updating or generating a `MANIFEST.json` test manifest
122 * `wpt install` - For installing the latest release of a browser or
123   webdriver server on the local machine.
124
125 <span id="submodules">Submodules</span>
126 =======================================
127
128 Some optional components of web-platform-tests (test components from
129 third party software and pieces of the CSS build system) are included
130 as submodules. To obtain these components run the following in the
131 root of your checkout:
132
133 ```
134 git submodule update --init --recursive
135 ```
136
137 Prior to commit `39d07eb01fab607ab1ffd092051cded1bdd64d78` submodules
138 were requried for basic functionality. If you are working with an
139 older checkout, the above command is required in all cases.
140
141 When moving between a commit prior to `39d07eb` and one after it git
142 may complain
143
144 ```
145 $ git checkout master
146 error: The following untracked working tree files would be overwritten by checkout:
147 […]
148 ```
149
150 followed by a long list of files. To avoid this error remove
151 the `resources` and `tools` directories before switching branches:
152
153 ```
154 $ rm -r resources/ tools/
155 $ git checkout master
156 Switched to branch 'master'
157 Your branch is up-to-date with 'origin/master'
158 ```
159
160 When moving in the opposite direction, i.e. to a commit that does have
161 submodules, you will need to `git submodule update`, as above. If git
162 throws an error like:
163
164 ```
165 fatal: No url found for submodule path 'resources/webidl2/test/widlproc' in .gitmodules
166 Failed to recurse into submodule path 'resources/webidl2'
167 fatal: No url found for submodule path 'tools/html5lib' in .gitmodules
168 Failed to recurse into submodule path 'resources'
169 Failed to recurse into submodule path 'tools'
170 ```
171
172 then remove the `tools` and `resources` directories, as above.
173
174 <span id="windows-notes">Windows Notes</span>
175 =============================================
176
177 On Windows `wpt` commands mut bre prefixed with `python` or the path
178 to the python binary (if `python` is not in your `%PATH%`).
179
180 Alternatively, you may also use
181 [Bash on Ubuntu on Windows](https://msdn.microsoft.com/en-us/commandline/wsl/about)
182 in the Windows 10 Anniversary Update build, then access your windows
183 partition from there to launch `wpt` commands.
184
185 Please make sure git and your text editor do not automatically convert
186 line endings, as it will cause lint errors. For git, please set
187 `git config core.autocrlf false` in your working tree.
188
189 Certificates
190 ============
191
192 By default pregenerated certificates for the web-platform.test domain
193 are provided in the repository. If you wish to generate new
194 certificates for any reason it's possible to use OpenSSL when starting
195 the server, or starting a test run, by providing the
196 `--ssl-type=openssl` argument to the `wpt serve` or `wpt run`
197 commands.
198
199 If you installed OpenSSL in such a way that running `openssl` at a
200 command line doesn't work, you also need to adjust the path to the
201 OpenSSL binary. This can be done by adding a section to `config.json`
202 like:
203
204 ```
205 "ssl": {"openssl": {"binary": "/path/to/openssl"}}
206 ```
207
208 On Windows using OpenSSL typically requires installing an OpenSSL distribution.
209 [Shining Light](https://slproweb.com/products/Win32OpenSSL.html)
210 provide a convenient installer that is known to work, but requires a
211 little extra setup, i.e.:
212
213 Run the installer for Win32_OpenSSL_v1.1.0b (30MB). During installation,
214 change the default location for where to Copy OpenSSL Dlls from the
215 System directory to the /bin directory.
216
217 After installation, ensure that the path to OpenSSL (typically,
218 this will be `C:\OpenSSL-Win32\bin`) is in your `%Path%`
219 [Environment Variable](http://www.computerhope.com/issues/ch000549.htm).
220 If you forget to do this part, you will most likely see a 'File Not Found'
221 error when you start wptserve.
222
223 Finally, set the path value in the server configuration file to the
224 default OpenSSL configuration file location. To do this,
225 copy `config.default.json` in the web-platform-tests root to `config.json`.
226 Then edit the JSON so that the key `ssl/openssl/base_conf_path` has a
227 value that is the path to the OpenSSL config file (typically this
228 will be `C:\\OpenSSL-Win32\\bin\\openssl.cfg`).
229
230
231 Publication
232 ===========
233
234 The master branch is automatically synced to http://w3c-test.org/.
235
236 Pull requests are
237 [automatically mirrored](http://w3c-test.org/submissions/) except those
238 that modify sensitive resources (such as `.py`). The latter require
239 someone with merge access to comment with "LGTM" or "w3c-test:mirror" to
240 indicate the pull request has been checked.
241
242 Finding Things
243 ==============
244
245 Each top-level directory matches the shortname used by a standard, with
246 some exceptions. (Typically the shortname is from the standard's
247 corresponding GitHub repository.)
248
249 For some of the specifications, the tree under the top-level directory
250 represents the sections of the respective documents, using the section
251 IDs for directory names, with a maximum of three levels deep.
252
253 So if you're looking for tests in HTML for "The History interface",
254 they will be under `html/browsers/history/the-history-interface/`.
255
256 Various resources that tests depend on are in `common`, `images`, and
257 `fonts`.
258
259 Branches
260 ========
261
262 In the vast majority of cases the **only** upstream branch that you
263 should need to care about is `master`. If you see other branches in
264 the repository, you can generally safely ignore them.
265
266 Contributing
267 ============
268
269 Save the Web, Write Some Tests!
270
271 Absolutely everyone is welcome (and even encouraged) to contribute to
272 test development, so long as you fulfill the contribution requirements
273 detailed in the [Contributing Guidelines][contributing]. No test is
274 too small or too simple, especially if it corresponds to something for
275 which you've noted an interoperability bug in a browser.
276
277 The way to contribute is just as usual:
278
279 * Fork this repository (and make sure you're still relatively in sync
280   with it if you forked a while ago).
281 * Create a branch for your changes:
282   `git checkout -b topic`.
283 * Make your changes.
284 * Run the lint script described below.
285 * Commit locally and push that to your repo.
286 * Send in a pull request based on the above.
287
288 Issues with web-platform-tests
289 ------------------------------
290
291 If you spot an issue with a test and are not comfortable providing a
292 pull request per above to fix it, please
293 [file a new issue](https://github.com/w3c/web-platform-tests/issues/new).
294 Thank you!
295
296 Lint tool
297 ---------
298
299 We have a lint tool for catching common mistakes in test files. You
300 can run it manually by starting the `lint` executable from the root of
301 your local web-platform-tests working directory like this:
302
303 ```
304 ./wpt lint
305 ```
306
307 The lint tool is also run automatically for every submitted pull
308 request, and reviewers will not merge branches with tests that have
309 lint errors, so you must fix any errors the lint tool reports.
310
311 In the unusual case of error reports for things essential to a
312 certain test or that for other exceptional reasons shouldn't prevent
313 a merge of a test, update and commit the `lint.whitelist` file in the
314 web-platform-tests root directory to suppress the error reports.
315
316 For more details, see the [lint-tool documentation][lint-tool].
317
318 [lint-tool]: http://web-platform-tests.org/writing-tests/lint-tool.html
319
320 Adding command-line scripts ("tools" subdirs)
321 ---------------------------------------------
322
323 Sometimes you may want to add a script to the repository that's meant
324 to be used from the command line, not from a browser (e.g., a script
325 for generating test files). If you want to ensure (e.g., for security
326 reasons) that such scripts won't be handled by the HTTP server, but
327 will instead only be usable from the command line, then place them in
328 either:
329
330 * the `tools` subdir at the root of the repository, or
331
332 * the `tools` subdir at the root of any top-level directory in the
333   repository which contains the tests the script is meant to be used
334   with
335
336 Any files in those `tools` directories won't be handled by the HTTP
337 server; instead the server will return a 404 if a user navigates to
338 the URL for a file within them.
339
340 If you want to add a script for use with a particular set of tests but
341 there isn't yet any `tools` subdir at the root of a top-level
342 directory in the repository containing those tests, you can create a
343 `tools` subdir at the root of that top-level directory and place your
344 scripts there.
345
346 For example, if you wanted to add a script for use with tests in the
347 `notifications` directory, create the `notifications/tools` subdir and
348 put your script there.
349
350 Test Review
351 ===========
352
353 We can sometimes take a little while to go through pull requests
354 because we have to go through all the tests and ensure that they match
355 the specification correctly. But we look at all of them, and take
356 everything that we can.
357
358 OWNERS files are used only to indicate who should be notified of pull
359 requests.  If you are interested in receiving notifications of proposed
360 changes to tests in a given directory, feel free to add yourself to the
361 OWNERS file. Anyone with expertise in the specification under test can
362 approve a pull request.  In particular, if a test change has already
363 been adequately reviewed "upstream" in another repository, it can be
364 pushed here without any further review by supplying a link to the
365 upstream review.
366
367 Getting Involved
368 ================
369
370 If you wish to contribute actively, you're very welcome to join the
371 public-test-infra@w3.org mailing list (low traffic) by
372 [signing up to our mailing list](mailto:public-test-infra-request@w3.org?subject=subscribe).
373 The mailing list is [archived][mailarchive].
374
375 Join us on irc #testing ([irc.w3.org][ircw3org], port 6665). The channel
376 is [archived][ircarchive].
377
378 [contributing]: https://github.com/w3c/web-platform-tests/blob/master/CONTRIBUTING.md
379 [ircw3org]: https://www.w3.org/wiki/IRC
380 [ircarchive]: http://logs.glob.uno/?c=w3%23testing
381 [mailarchive]: https://lists.w3.org/Archives/Public/public-test-infra/
382
383 Documentation
384 =============
385
386 * [How to write and review tests](http://web-platform-tests.org/)
387 * [Documentation for the wptserve server](http://wptserve.readthedocs.org/en/latest/)