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 to repackage it as a single synchronous script file, e.g.:

microbundle -f iife -i polyfill/src/main.js -o polyfill.js

Running the tests

Follow the steps for Running Tests from the 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:

./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:

./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:

<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 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.