Run Mocha tests in an isolated JSDOM environment.
- Allows modules to run in a pure JSDOM environment that does not pollute node's globals and will not interfere with your server tests. Works by using jsdom-context-require.
- Avoids needing to bring in a bundler for your test suites, popular require hooks work fine, while still having clear separation for server and browser tests.
- Easy to setup!
npm install jsdom mocha-dom -D
When running the Mocha CLI, pass --require mocha-dom
.
By default this will cause all tests loaded to run in a JSDOM environment.
You can configure this to instead match a glob of test files via a root level .mochadomrc
config file.
mocha --require mocha-dom
In your tests a global jsdom
object is exposed that maps to the JSDOM Object API.
This allows you to configure JSDOM during your tests, for example to update the URL you could use the following:
jsdom.reconfigure({ url: "https://example.com/" });
Note if the url
is constant, it would be better to set via the config file.
You can configure this to instead match a glob of test files via a root level [.mochadomrc.js
config file].
The config file can have any extension supported by node, by default .js
or .json
.
module.exports = {
// The test files that should be loaded into the JSDOM environment.
// Defaults to include every test file, example below shows matching a subset
// of test files.
files: "**/*.browser.test.js",
// The initial HTML to load into the document,
// below is the default value.
html: "<!DOCTYPE html><html><head></head><body></body></html>",
// Everything else is forwarded to JSDOM.
// See: https://github.com/jsdom/jsdom#customizing-jsdom
url: "https://example.com/",
};
If using a .mochadomrc.js
file you can import the defineConfig
helper, like so:
module.exports = require("mocha-dom").defineConfig({
files: "...",
});
If using TypeScript you can enable config auto completion by using creating a .mochadomrc.ts
file like the following:
import type { Config } from "mocha-dom";
export default {
files: "...",
} as Config;
Both of these are optional, but will provide autocompletion for the various config options.
For frameworks which do not rely on compiling different code for the browser, existing require/register hooks will work fine. For example, to use React just be sure to run Mocha with @babel/register
, esbuild-register
, @swc/register
or similar and things will just work.
For frameworks which do compile to different code in the browser or server, you can add their require/register hooks within the .mochadomrc
file. When doing so you can usually provide the output target as an option. Any require hooks added via the .mochadomrc
only apply to tests that match the files
option. This means you can use server require/register hooks normally, and just add browser specific ones in the .mochadomrc
.
Below are some example .mochadomrc
configs for frameworks which have browser specific compiled output.
require("@marko/compiler/register")({ output: "dom" });
module.exports = {
files: "**/*.browser.test.js",
};
require("svelte/register")({ generate: "dom" });
module.exports = {
files: "**/*.browser.test.js",
};
require("@babel/register", {
extensions: [".jsx"],
plugins: ["solid"],
});
module.exports = {
files: "**/*.browser.test.js",
};