Skip to content

QUnit Tests

QUnit for CiviCRM is deprecated

This documentation explains the existing QUnit tests. However, the functionality overlaps a lot with Karma . Karma and Protractor have more powerful test-runners and better support for AngularJS, so the QUnit-CiviCRM suite is deprecated.

QUnit is a JavaScript-based unit-testing framework. It is ideally suited to testing pure-JavaScript modules -- for example, jQuery, Backbone, and many of their plugins test with QUnit. For more background about, see:

CiviCRM is a large application and may include some pure-Javascript components -- one should use QUnit to test these components. Note: CiviCRM also includes many non-Javascript components (MySQL, PHP, etc). For integration-testing that encompasses all of CiviCRM's different technologies, see the CiviCRM WebTest suite. QUnit is only appropriate unit-testing of pure JS.

Note: When making a new JS component, consider designing a package which doesn't depend on CivCRM at all -- put it in its own repo and handle the testing yourself. This is ideal for collaborating with developers on other projects (beside CiviCRM). When the package is stable, you can import your package into CiviCRM's codebase (by way of packages/ or vendors/).

Note: The primary benefit of using this system -- rather than a vanilla QUnit deployment -- is that you can include dependencies based on Civi's conventions. The primary drawback is that the test will require CiviCRM to execute.

However, if you really need to write a Javascript component in CiviCRM core (or in a CiviCRM extension), then proceed with testing it...

Quickstart

To see an example test-suite:

  1. Inspect the example code civicrm/tests/qunit/example

  2. Run the example code by logging into CiviCRM as administrator and visiting:

http://localhost/civicrm/dev/qunit/civicrm/example

(Modify localhost to match your CiviCRM installation.)

To create a new test-suite:

  1. Determine a name for the new test-suite, such as my-stuff.

  2. Copy civicrm/tests/qunit/example to civicrm/tests/qunit/my-stuff

  3. Edit the civicrm/tests/qunit/my-stuff/test.php to load your JS file (my-stuff.js) as well as any special dependencies (jQuery plugins, Backbone, etc).

  4. Edit the civicrm/tests/qunit/my-stuff/test.js

  5. To run the test-suite, login to CiviCRM as administrator and visit:

http://${base_url}/civicrm/dev/qunit/${extension}/${suite}

For example, suppose the base_url is localhost, and suppose the qunit test is part of the core codebase (aka extension=civicrm), and suppose the suite is my-stuff. Then navigate to:

http://localhost/civicrm/dev/qunit/civicrm/my-stuff

Conventions

The following is a quick draft of coding conventions. If there's a problem with it, we can change it -- but please communicate any problems/issues (e.g. via Mattermost chat, mailing-list, or forum).

  • CiviCRM includes multiple test-suites. One test-suite should be created for each logically distinct JavaScript component.

    • Rationale: CiviCRM is a large application with a diverse mix of components written by diverse authors. Each component may present different requirements for testing -- e.g. HTML fixtures, CSS fixtures, third-party JS dependencies, etc.

    • Note: As a rule-of-thumb, if you add a new js file to CiviCRM (civicrm/js/foo.js), and if that file is useful on its own, then you might create a new test-suite for it (civicrm/tests/qunit/foo).

  • Each QUnit test-suite for CiviCRM lives in a subdirectory of tests/qunit/.

    Rationale: Following a predictable naming convention will help us automate testing/loading across all suites, and it will make the code more recognizable to other developers.

  • Each QUnit test-suite may include the file test.php to specify loading of resource files or bundles (such as CSS/JS). The file will be recognized automatically.

    • Rationale: CiviCRM has its own resource-loading conventions. When preparing a test environment, one needs to load JS/CSS dependencies. Since there is no autoloader, this is most easily done with CiviCRM's resource-loader.

  • Each QUnit test-suite may include the file test.tpl to specify any HTML or CSS fixtures. The file will be recognized automatically.

  • Each QUnit test-suite may include the file test.js to specify assertions. The file will be recognized automatically. If one wants to split the tests into multiple JS files, then each file should registered as a resource in test.php.