We're transitioning from an older model based on separate and obsolete "DOM1," "DOM2," and "DOM3" specs, into one based on the modern DOM and HTML living standards. Nobody has really set aside the time to do the proper sort of architectural overhaul this transition necessitates, so things might seem a bit strange, but in the meantime we're doing OK with the current structure.
The DOM, thankfully, has lots of tests already out there. Those already included in the repository are of three types:
- Auto-generated or adapted from older W3C tests.
- Written by contributors to plug gaps in those tests.
- Imported from the newer w3c/web-platform-tests project.
When contributing, the first question you should ask is:
Can I exhibit how the browsers differ from what jsdom is doing?
If you can, then you've almost certainly found a bug in or missing feature of jsdom, and we'd love to have your contribution. In that case, move on to:
What WHATWG spec covers this potential contribution?
Almost all of our relevant functionality is covered in either the DOM Living Standard or the HTML Living Standard. There are various obsolete W3C specs ("DOM Level 2" etc.) that were never really implemented in browsers, and there is also the "DOM Level 4" W3C fork of the WHATWG DOM Living Standard. But we try to stick to the two main WHATWG specs for jsdom these days.
Once you have that nailed down, you'll want to ask:
Can I get an official test for this functionality?
We ported in some of the tests for the old DOM1 and DOM2 specs, as well as some DOM3 ones that are currently disabled. These are sometimes wrong however (given that browsers never really implemented those specs), and we have had to change, add to, or remove them in the past.
These days the w3c/web-platform-tests project has an ever-growing set of tests for the DOM and HTML standards, and is the best place to try to find good tests to adapt. We have reasonable support for running these tests directly, although I imagine some of them (e.g. those dependent on the web-platform-tests Python server) won't work. See below for details on how to add such tests to the suite.
If there is no official test covering the functionality you're after, then you can write your own. If you're not sure, you can always ask email@example.com, like I did, or stop into the #whatwg IRC channel. You might want to submit a pull request to the web-platform-tests repo too!
Running the tests
First you'll want to
npm install. To run all the tests, use
Using options to
npm test, you can slice and dice which tests your want to run. Usage is as follows:
$ npm test -- --help Run the jsdom test suite Options: -s, --suites suites that you want to run. ie: -s level1/core,1/html,html -f, --fail-fast stop on the first failed test -h, --help show the help -t, --tests choose the test cases to run. ie: -t jquery -d, --debug run in node's interactive debugger mode -v, --verbose show all tests that are being run
So e.g. use
npm test -- -s console to run the console-related tests.
Writing or importing tests
To import a test from w3c/web-platform-tests, add the appropriate line to
test/w3c/index.js. This framework is still in its early days, so feel free to open an issue if it's not working quite like you expect.
If you're just adding a simple fix to existing functionality, you can add an appropriate test to the bottom of the relevant test file, e.g. in
If you're writing a bunch of new tests for a feature, and those tests don't exist in w3c/web-platform-tests, you can do one of two things. The most noble course of action is to submit a pull request to web-platform-tests, get it accepted and merged, then update jsdom to run those tests. That way, all existing browsers will run the test too, improving interoperability for everyone!
Alternately, you can write some tests just for jsdom. The older tests, being a mix of auto-generated and organically-grown, have gotten pretty hairy over time. But for new tests we try to follow a clean and uniform style, which you can see in files like test/living-dom/attributes.js or test/window/history.js. Do your best to follow that.
Note for future reference: to update the submodules used for the web-platform-tests use the command
git submodule update --recursive --remote.
jsdom now has experimental support for web workers! To test this support, we have a special test setup that involves Selenium driving Chrome. To make that work, you need to install Java and have it in your PATH. Then you can use
npm run test-browser to have Selenium open up Chrome, spawn a web worker, and run some jsdom tests inside it.
The browser runner supports the same options as
npm test, as well as a few more specific to running browser tests via WebDriver. Many tests fail at present, so by default
npm run test-browser only runs the suites that pass.
$ npm run test-browser -- --help Run the jsdom test suite in a browser via WebDriver Options: -s, --suites suites that you want to run. ie: -s level1/core,1/html,html -f, --fail-fast stop on the first failed test -h, --help show the help -t, --tests choose the test cases to run. ie: -t jquery -d, --debug run in node's interactive debugger mode -v, --verbose show all tests that are being run --http-port port to run test server on --web-driver-port port to run Selenium on --verbose-web-driver print verbose output from wd to stdout --verbose-browser-console print browser console to stdout
Finally, we have an active and full issue tracker that we'd love you to help with. Go find something broken, and fix it!