forked from mirrors/gecko-dev
cbe4495e60
Automatic update from web-platform-tests Implement support for injecting a polyfill into wpt tests. (#33338) Adds the --inject-script which will inject the given script into all html files (i.e. tests). Examples: ./wpt serve --inject-script=polyfill.js ./wpt run --inject-script=polyfill.js [browsername] [tests] This will inject polyfill.js into all loaded HTML tests which allows running tests with the polyfill. -- wpt-commits: 4296b5596fd7307ec410eb04332e76d5396bd262 wpt-pr: 33338
67 lines
2.2 KiB
Markdown
67 lines
2.2 KiB
Markdown
# Testing polyfills
|
|
|
|
## Preparing the polyfill
|
|
|
|
The polyfill script-injection feature currently only supports scripts which
|
|
are immediately invoked. The script must be prepared as a single file whose
|
|
contents will be inlined into a script tag served as part of every test page.
|
|
|
|
If your polyfill is only available as an asynchronous module with dependent
|
|
scripts, you can use a tool such as
|
|
[microbundle](https://github.com/developit/microbundle) to repackage it as a
|
|
single synchronous script file, e.g.:
|
|
|
|
```bash
|
|
microbundle -f iife -i polyfill/src/main.js -o polyfill.js
|
|
```
|
|
|
|
## Running the tests
|
|
|
|
Follow the steps for [Running Tests from the Local System](from-local-system) to
|
|
set up your test environment. When running tests via the browser or via the
|
|
command line, add the `--inject-script=polyfill.js` to either command, e.g.
|
|
|
|
Via the browser:
|
|
|
|
```bash
|
|
./wpt serve --inject-script=polyfill.js
|
|
```
|
|
|
|
Then visit http://web-platform.test:8000/ or https://web-platform.test:8443/ to
|
|
run the tests in your browser.
|
|
|
|
Via the command line:
|
|
|
|
```bash
|
|
./wpt run --inject-script=polyfill.js [browsername] [tests]
|
|
```
|
|
|
|
## Limitations
|
|
|
|
Polyfill scripts are injected to an inline script tag which removes itself from
|
|
the DOM after executing. This is done by modifying the server response for
|
|
documents with a `text/html` MIME type to insert the following before the first tag in
|
|
the served response:
|
|
|
|
```html
|
|
<script>
|
|
// <-- The polyfill file is inlined here
|
|
// Remove the injected script tag from the DOM.
|
|
document.currentScript.remove();
|
|
```
|
|
|
|
This approach has a couple limitations:
|
|
* This requires that the polyfill is self-contained and executes
|
|
synchronously in a single inline script. See [Preparing the
|
|
polyfill](#preparing-the-polyfill) for suggestions on transforming polyfills to
|
|
run in that way.
|
|
* Does not inject into python handlers which write directly to the output
|
|
stream.
|
|
* Does not inject into the worker context of `.any.js` tests.
|
|
|
|
### Observability
|
|
|
|
The script tag is removed from the DOM before any other script has run, and runs
|
|
from an inline script. As such, it should not affect mutation observers on the
|
|
same page or resource timing APIs, as it is not a separate resource. The polyfill
|
|
may be observable by a mutation observer added by a parent frame before load.
|