Commit | Line | Data |
---|---|---|
6a488035 TO |
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 | ||
b6708aeb | 64 | http://localhost/civicrm/dev/qunit/civicrm/my-stuff |
6a488035 TO |
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/". | |
b6708aeb | 86 | |
6a488035 TO |
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. | |
b6708aeb | 94 | |
6a488035 TO |
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. |