Manual:JavaScript unit testing
MediaWiki uses QUnit to unit test its JavaScript code base.
Run from a browser
edit- Set
$wgEnableJavaScriptTest
totrue
.
This is already set in most developer environments, like Quickstart or MediaWiki-Docker . - Visit Special:JavaScriptTest in a browser to run the tests.
Run from the command line
editOne-time setup
edit- Set the environment variables
MW_SERVER
andMW_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
editThis 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
editConsider 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?
editRun tests before committing
editMake it a habit to run unit tests before committing and submitting your changes to Gerrit .
Write unit tests
editWrite unit tests for new functionality, and consider fillling gaps in coverage when changing existing modules in MediaWiki core.
Write a test
editIt 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
editMediaWiki core
editTest 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
editExtensions register their QUnit tests via the QUnitTestModule attribute in extension.json
.
See also
edit- Manual:Hooks/ResourceLoaderTestModules
- Manual:JavaScript unit testing/QUnit guidelines
- Writing Testable JavaScript (May 2013), Rebecca Murphey, A List Apart