| 1 | ==== QUnit Test Suite for CiviCRM ==== |
| 2 | |
| 3 | QUnit is a JavaScript-based unit-testing framework. It is ideally suited to |
| 4 | testing pure-JavaScript modules -- for example, jQuery, Backbone, and many |
| 5 | of their plugins test with QUnit. For more details about, see: |
| 6 | |
| 7 | http://qunitjs.com/ |
| 8 | http://qunitjs.com/cookbook/ |
| 9 | |
| 10 | CiviCRM is a large application and may include some pure-Javascript |
| 11 | components -- one should use QUnit to test these components. Note: CiviCRM |
| 12 | also includes many non-Javascript components (MySQL, PHP, etc). For |
| 13 | integration-testing that encompasses all of CiviCRM's different |
| 14 | technologies, see the CiviCRM WebTest suite. QUnit is *only* appropriate |
| 15 | unit-testing of pure JS. |
| 16 | |
| 17 | Note: When making a new JS component, consider designing a package which |
| 18 | doesn't depend on CivCRM at all -- put it in its own repo and handle the |
| 19 | testing yourself. This is ideal for collaborating with developers on other |
| 20 | projects (beside CiviCRM). When the package is stable, you can import your |
| 21 | package into CiviCRM's codebase (by way of "packages/" or "vendors/"). |
| 22 | |
| 23 | Note: The primary benefit of using this system -- rather than a vanilla |
| 24 | QUnit deployment -- is that you can include dependencies based on Civi's |
| 25 | conventions. The primary drawback is that the test will require CiviCRM to |
| 26 | execute. |
| 27 | |
| 28 | However, if you really need to write a Javascript component in CiviCRM core |
| 29 | (or in a CiviCRM extension), then proceed with testing it... |
| 30 | |
| 31 | ==== QUICKSTART ==== |
| 32 | |
| 33 | To see an example test-suite: |
| 34 | |
| 35 | 1. Inspect the example code "civicrm/tests/qunit/example" |
| 36 | |
| 37 | 2. Run the example code by logging into CiviCRM as administrator and |
| 38 | visiting: |
| 39 | |
| 40 | http://localhost/civicrm/dev/qunit/civicrm/example |
| 41 | |
| 42 | (Modify "localhost" to match your CiviCRM installation.) |
| 43 | |
| 44 | To create a new test-suite: |
| 45 | |
| 46 | 1. Determine a name for the new test-suite, such as "my-stuff". |
| 47 | |
| 48 | 2. Copy "civicrm/tests/qunit/example" to "civicrm/tests/qunit/my-stuff" |
| 49 | |
| 50 | 3. Edit the "civicrm/tests/qunit/my-stuff/test.php" to load your JS file |
| 51 | (my-stuff.js) as well as any special dependencies (jQuery plugins, |
| 52 | Backbone, etc). |
| 53 | |
| 54 | 4. Edit the "civcrm/tests/qunit/my-stuff/test.js" |
| 55 | |
| 56 | 5. To run the test-suite, login to CiviCRM as administrator and visit: |
| 57 | |
| 58 | http://${base_url}/civicrm/dev/qunit/${extension}/${suite} |
| 59 | |
| 60 | For example, suppose the base_url is "localhost", and suppose the |
| 61 | qunit test is part of the core codebase (aka extension="civicrm"), |
| 62 | and suppose the suite is "my-stuff". Then navigate to: |
| 63 | |
| 64 | http://localhost/civicrm/dev/qunit/civicrm/my-stuff |
| 65 | |
| 66 | ==== CONVENTIONS ==== |
| 67 | |
| 68 | The following is a quick draft of coding conventions. If there's a problem |
| 69 | with it, we can change it -- but please communicate any problems/issues |
| 70 | (e.g. via IRC, mailing-list, or forum). |
| 71 | |
| 72 | * CiviCRM includes multiple test-suites. One test-suite should be created for |
| 73 | each logically distinct JavaScript component. |
| 74 | |
| 75 | Rationale: CiviCRM is a large application with a diverse mix of |
| 76 | components written by diverse authors. Each component may present |
| 77 | different requirements for testing -- e.g. HTML fixtures, CSS fixtures, |
| 78 | third-party JS dependencies, etc. |
| 79 | |
| 80 | Note: As a rule-of-thumb, if you add a new js file to CiviCRM |
| 81 | ("civicrm/js/foo.js"), and if that file is useful on its own, then you |
| 82 | might create a new test-suite for it ("civicrm/tests/qunit/foo"). |
| 83 | |
| 84 | * Each QUnit test-suite for CiviCRM lives in a subdirectory of |
| 85 | "tests/qunit/". |
| 86 | |
| 87 | Rationale: Following a predictable naming convention will help us automate |
| 88 | testing/loading across all suites, and it will make the code more recognizable |
| 89 | to other developers. |
| 90 | |
| 91 | * Each QUnit test-suite *may* include the file "test.php" to specify |
| 92 | loading of resource files or bundles (such as CSS/JS). The file will |
| 93 | be recognized automatically. |
| 94 | |
| 95 | Rationale: CiviCRM has its own resource-loading conventions. When |
| 96 | preparing a test environment, one needs to load JS/CSS dependencies. |
| 97 | Since there is no autoloader, this is most easily done with CiviCRM's |
| 98 | resource-loader. |
| 99 | |
| 100 | * Each QUnit test-suite *may* include the file "test.tpl" to specify |
| 101 | any HTML or CSS fixtures. The file will be recognized automatically. |
| 102 | |
| 103 | * Each QUnit test-suite *may* include the file "test.js" to specify |
| 104 | assertions. The file will be recognized automatically. If one wants to |
| 105 | split the tests into multiple JS files, then each file should |
| 106 | registered as a resource in "test.php". |
| 107 | |
| 108 | ==== TODO ==== |
| 109 | |
| 110 | * GUI Testing -- Display a browsable list of all tests. |
| 111 | |
| 112 | * Automatic Testing -- Add an item to the WebTest suite (e.g. |
| 113 | WebTest_Core_QUnitTestCase) which iteratively executes each QUnit |
| 114 | test-suite and verifies that they pass. |