mock-mediawiki

mock-mediawiki

Honest MediaWiki JS interface mocking in Node.js.

No unnecessary changes to the original source files. Directly copied from MediaWiki core with bare minimum modifications. Includes mw.config, mw.util, mw.Title, mw.Api, mw.user, mw.loader, mw.hook, mw.html, mw.Uri, mw.storage, mw.language, mw.template, mw.Message and mw.jqueryMsg. jQuery is also included from its npm package.

To stay true to the original source, mw and $ are made available as globals, rather than exported from the module.

Licensed under the Lesser General Public License. Can be used from any repository regardless of license. (Note that on the other hand, MW source code copied directly may only be pasted into repos with GPL-compatible licenses).

How to use

Use with Jest

If you're using Jest, tweak your jest.config.js to include: (jsdom testEnvironment used to be the default till Jest v26)

For Jest v29:

Ensure you have the additional package jest-environment-jsdom installed (Jest no longer bundles this).

	"testEnvironment": "jsdom", 
	"setupFilesAfterEnv": ["mock-mediawiki"],
	"testEnvironmentOptions": {
		// this is only needed if you plan to use mw.Api or mw.storage
		"url": "https://test.wikipedia.org/"
	}

For Jest v27:

    "testEnvironment": "jsdom",
    "setupFilesAfterEnv": ["mock-mediawiki"],
    "testURL": "https://test.wikipedia.org" // this is only needed if you plan to use mw.Api or mw.storage

Done! All your Jest tests will now have access to mw and $ as globals. This setup works with both CommonJS module format and ESM.

Jest exposes globally most DOM APIs available via jsdom. So if your gadget code includes references to HTMLSpanElement or XMLDocument et al, they'll just work!

Use with other test runners

Other test runners don't usually have JSDOM integrated. You need to install jsdom separately (npm i -D jsdom) and then include the following in your test files:

CommonJS:

require('mock-mediawiki/with-jsdom');

ESM:

import 'mock-mediawiki/with-jsdom';

Or even better, consider using jsdom-global which injects DOM APIs globally (similar to how Jest does it) and also gives you control over the JSDOM configuration options. Then do require('mock-mediawiki') or its ESM equivalent. That is,

require('jsdom-global')(undefined, { /*... jsdom config parameters ...*/ });
global.performance = window.performance; // Required for node.js v14 and older, until https://github.com/rstacruz/jsdom-global/issues/59 is resolved
require('mock-mediawiki');

It is assumed that ESM tests undergo transformation to CommonJS as part of some build step. Use of this package with native Node.js ESM packages is not supported because of its internal reliance on require().

Notes

If your tests are in TypeScript, you'll need to additionally have types-mediawiki.

For using mw.storage, you must give JSDOM a URL (for Jest this is done via testURL in jest.config.js, for jsdom or jsdom-global, provide url param to the constructor). mock-mediawiki/with-jsdom sets this to https://test.wikipedia.org. If you need it to be something different, consider using jsdom-global or jest instead.

For using mw.Api to make API calls from JSDOM, ensure that your JSDOM URL (see above) is on the same domain as the API URL of mw.Api, which can be set explicitly set via its constructor (api = new mw.Api({ ajax: { url: '<APIURL>' } })) or implicitly set through mw.config.get('wgScriptPath'). Otherwise, you'd get a CORS error. This can also be worked around by using origin: '*' in API calls.

It is possible to use mw.loader for loading and executing scripts with runScripts: 'dangerously' in the JSDOM config (this is on by default in Jest). Do not execute anything from untrusted sources – read more here.

For mw.language, convertGrammar specialisations for non-English languages aren't included (since whether to load them or not depends on the wgUserLanguage).

Please file an issue if anything doesn't work.