jest-environment-jsdom-global v4.0.0
Jest environment for a globally-exposed JSDOM
Similar to the standard
jest-environment-jsdom
, but exposesjsdom
so that you can reconfigure it from your test suites.
For more information, see this discussion in the Jest repository.
Before installing, please check if you need this package, particularly in light of changes in Jest 28.
Installation and configuration
Install the package with yarn
:
yarn add --dev jest-environment-jsdom-global jest-environment-jsdom
or npm
:
npm install --save-dev jest-environment-jsdom-global jest-environment-jsdom
Then, add it to your Jest configuration:
"jest": {
"testEnvironment": "jest-environment-jsdom-global"
}
For more information, see the Jest documentation on testEnvironment
.
Using JSDOM in your test suite
You can access the jsdom
object globally in your test suite. For example, here's a test that changes the URL for your test environment (using reconfigure
):
describe("test suite", () => {
it("should not fail", () => {
jsdom.reconfigure({
url: "https://www.example.com/",
});
});
});
Frequently Asked Questions
Jest 28 update: is this package still useful?
As of Jest 28 (formal docs), you can provide options to JSDOM using inline comments in your tests. For example, to set the URL, you could write a test suite that looks like this:
/**
* @jest-environment jsdom
* @jest-environment-options {"url": "https://jestjs.io/"}
*/
test('use jsdom and set the URL in this test file', () => {
expect(window.location.href).toBe('https://jestjs.io/');
});
This may solve for many previous use cases for this package, and I'd suggest using this approach rather than using jest-environment-jsdom-global
if it suffices for your needs.
Why can't I use Object.defineProperty
?
Jest's browser environment is based on JSDOM. JSDOM used to allow you to use Object.defineProperty
to update certain properties on window
; in particular, you could change parts of window.location
, or window.top
, as you need to.
However, several years ago, JSDOM's API changed; the preferred way to mock window.location
and its child properties is to use reconfigure
. JSDOM 11 became the default back in Jest 22; as a result, tests that used Object.defineProperty
may no longer work on certain properties of window
.
Currently, Jest does not expose the JSDOM reconfigure
method inside test suites. The jest-environment-jsdom-global
package is meant to solve this problem: it adds jsdom
as a global, so you can reconfigure it within your tests.
How can I mock window.location.href
?
In your test, you can set the URL using:
jsdom.reconfigure({
url: "https://www.example.com/",
});
How can I mock window.location.hash
?
You need to provide a full URL, not just the hash. Similarly to above, you can do:
jsdom.reconfigure({
url: "https://www.example.com/#myHash",
});