Commit 4ab88ad5 authored by totten's avatar totten

tests/qunit/README.txt - Migrate to civicrm-dev-docs

As part of https://github.com/civicrm/civicrm-dev-docs/pull/415 , the dev
docs will assimilate and organize more of the instructions about testing.
parent 951656c5
==== QUnit Test Suite for CiviCRM ====
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 details about, see:
http://qunitjs.com/
http://qunitjs.com/cookbook/
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 IRC, 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".
==== TODO ====
* GUI Testing -- Display a browsable list of all tests.
* Automatic Testing -- Add an item to the WebTest suite (e.g.
WebTest_Core_QUnitTestCase) which iteratively executes each QUnit
test-suite and verifies that they pass.
Documentation moved to https://docs.civicrm.org/dev/en/latest/testing/qunit/
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment