Manual:JavaScript unit testing

MediaWiki's QUnit test suite.

MediaWiki uses QUnit to unit test its JavaScript code base.

Run from a browser

  1. Set $wgEnableJavaScriptTest to true.
    This is already set in most developer environments, like Quickstart or MediaWiki-Docker .
  2. Visit Special:JavaScriptTest in a browser to run the tests.

Run from the command line

One-time setup

  • Set the environment variables MW_SERVER and MW_SCRIPT_PATH to the URL of your local wiki. You can also put these in a .bash_profile file in your home directory to automatically set load variables in new Terminal tabs.
    # MediaWiki-Docker
    export MW_SERVER=http://localhost:8080
    export MW_SCRIPT_PATH=/w
    
    # composer serve
    export MW_SERVER=http://localhost:4000
    export MW_SCRIPT_PATH=/
    
  • Navigate to the MediaWiki core directory and run npm ci.

Run

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, or MediaWiki 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.

Security consideration

Consider using Fresh, or if you have another isolated environment already, ensure a comparable version of Node.js and npm are installed (the before-last Node.js LTS is recommended). Why?

  • To enter the isolated environment, run fresh-node -net -env from the MediaWiki core directory. (Fresh automatically finds the MW_SERVER and MW_SCRIPT_PATH variables from MediaWiki-Docker's .env file.)
  • Once inside your isolated shell, run npm ci to install or update any dependencies.
  • To start the tests, run npm run qunit.

How to contribute?

Run tests before committing

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

Write unit tests

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

Write a test

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/resources/ directory.

Register a test

MediaWiki core

Test suites are added to the registration of the test.MediaWiki 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.base/util.js can be found at tests/qunit/resources/mediawiki.util/util.test.js.

Example:

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

Extensions

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

See also