qunit.md - Import content from `civicrm-core` README

docs/testing/qunit.md

-### QUnit
+!!! caution "QUnit for CiviCRM is deprecated"
 
-CiviCRM has a small set up of QUnit which is an automated testing system.  It's generally inspired by the xUnit family (JUnit, PHPUnit, etc) and
-allows you to test low- and mid-level component functionality.  It's most suitable for testing pure Javascript components.  For a general
-introduction, see the [README](https://github.com/civicrm/civicrm-core/blob/master/tests/qunit/README.txt) and [example
-test](https://github.com/civicrm/civicrm-core/tree/master/tests/qunit/example) that ship with CiviCRM.  It is currently only run manually through a
-web broweser.
+    This documentation explains the existing QUnit tests.  However, the
+    functionality overlaps a lot with [Karma](/testing/karma.md) and
+    [Protractor](/testing/protractor.md). 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:
+
+ * [http://qunitjs.com/](http://qunitjs.com/)
+ * [http://qunitjs.com/cookbook/](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".