Manual:JavaScript unit testing

Translate this page

Languages:

MediaWiki's QUnit test suite running in Chrome.

MediaWiki uses QUnit to unit test its JavaScript code base.

Run from a browser[edit]

Set $wgEnableJavaScriptTest to true. (This is already set if you use MediaWiki-Docker or MediaWiki-Vagrant.)
Visit Special:JavaScriptTest in a browser to run the tests.

Run from the command line[edit]

One-time setup[edit]

Enter an isolated environment where you have Node.js and npm. Why?

If using MediaWiki-Docker:

Consider using Fresh
Run fresh-node -net -env from the MediaWiki core directory. (Fresh automatically finds the MW address in Docker's .env file.)
Once inside your isolated shell, run npm ci to install or update any dependencies.

If using MediaWiki-Vagrant:

Ensure environment variables MW_SERVER and MW_SCRIPT_PATH are set (consider saving this to .bash_profile):
```
export MW_SERVER=http://localhost:8080
export MW_SCRIPT_PATH=/w
```
Run vagrant ssh from the MediaWiki-Vagrant directory.
Once inside the Vagrant VM. navigate to the MediaWiki core directory and run npm ci.

If using a different setup:

Ensure environment variables MW_SERVER and MW_SCRIPT_PATH are set (consider saving this to .bash_profile):

# Adjust to your own environment
export MW_SERVER=http://localhost:8080
export MW_SCRIPT_PATH=/w

Consider using Fresh, or if you have an isolated environment already, ensure a comparable version of Node.js and npm are installed (the before-last LTS should do).
Navigate to the MediaWiki core directory and run npm ci.

Run[edit]

This runs the QUnit tests in Headless Chrome:

$ npm run qunit
 
Running "karma:main" (karma) task
 INFO [launcher]: Starting browser ChromeHeadless
 
 mediawiki.util
     ✔ escapeRegExp
     ✔ debounce
 …
 
 Finished in 5.42 secs
 
 SUMMARY:
 ✔ 440 tests completed

You can run QUnit tests for specific components with the --qunit-component option. Pass the name of an extension or skin, orMediaWiki for MediaWiki core tests.

$ node_modules/grunt/bin/grunt qunit --qunit-component=GrowthExperiments
 
Running "karma:main" (karma) task

INFO [launcher]: Starting browser ChromeHeadless

  testrunner
    ✔ Loader status
    ✔ assert.htmlEqual
  ext.growthExperiments.Utils.js
    ✔ serializeActionData
    ✔ isUserInVariant
  ext.growthExperiments.Help/HelpPanelProcessDialog.js
    ✔ getDefaultPanelForSuggestedEditSession for copyedit
    ✔ updateEditMode for link-recommendation
    ✔ updateEditMode for copyedit, isEditing
  ext.growthExperiments.Homepage.SuggestedEdits/PagerWidget.js
    ✔ constructor
    ✔ setMessage with currentPosition < totalCount
    ✔ setMessage with currentPosition === totalCount
    ✔ setMessage with currentPosition > totalCount
  ext.growthExperiments.NewcomerTaskLogger.js
    ✔ constructor
    ✔ should log impressions
    ✔ should get log metadata
  ext.growthExperiments.StructuredTask/addimage/AddImageUtils.js
    ✔ getRenderData: target width < original width
    ✔ getRenderData: the image file needs to be re-rasterized
    ✔ getRenderData: vector image
    ✔ getRenderData: target width > original width
    ✔ getRenderData: 3x target width
    ✔ getRenderData: 2.5x target width
    ✔ getRenderData: vertical image with landscape viewport
    ✔ getRenderData: with specified render width

Finished in 0.03 secs

SUMMARY:
✔ 46 tests completed

You can use the --qunit-watch argument for QUnit to watch the files associated with a component, and automatically re-run tests when those files change.

How to contribute?[edit]

Run tests before committing[edit]

Make it a habit to run unit tests before committing and submitting your changes to Gerrit.

Write unit tests[edit]

Write unit tests for new functionality, and consider fillling gaps in coverage when changing existing modules in MediaWiki core.

Write a test[edit]

It is the convention to name the test suite file after the module it covers. For example, mediawiki.user.test.js covers the mediawiki.user module.

Inside the test suite should be a call to QUnit.module with the module name.

The unit tests for MediaWiki core are located in the tests/qunit/suites/ directory.

Register a test[edit]

MediaWiki core[edit]

Test suites are added to the registration of the mediawiki.tests.qunit.suites module in /tests/qunit/QUnitTestResources.php.

Tests are organised into a directory structure that matches the directory structure of the code being tested. For example: The unit test for resources/mediawiki.util/mediawiki.util.js can be found at tests/qunit/suites/resources/mediawiki.util/mediawiki.util.test.js.

Example:

 'mediawiki.tests.qunit.suites' => array(
 	'scripts' => array(
 		'tests/qunit/suites/resources/mediawiki/mediawiki.test.js',
+		'tests/qunit/suites/resources/mediawiki/mediawiki.example.test.js',
 		'tests/qunit/suites/resources/mediawiki/mediawiki.user.test.js',
 		'tests/qunit/suites/resources/mediawiki/mediawiki.util.test.js',
 	),
 	'dependencies' => array(
 		'mediawiki',
+		'mediawiki.example',
 		'mediawiki.user',
 		'mediawiki.util',

Extensions[edit]

Extensions register their QUnit tests via the QUnitTestModule attribute in extension.json.