Manual:JavaScript unit testing

From mediawiki.org
(Redirected from QUnit)
MediaWiki's QUnit test suite running in Chrome.

MediaWiki uses QUnit to unit test its JavaScript code base.

Run from a browser[edit]

  1. Set $wgEnableJavaScriptTest to true. (This is already set if you use MediaWiki-Docker or MediaWiki-Vagrant.)
  2. 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

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.

See also[edit]