X-Git-Url: https://vcs.fsf.org/?a=blobdiff_plain;f=tests%2Fqunit%2FREADME.txt;h=ccd6a33dd08e91d2eb8803e1527d60ceee177c17;hb=5d30a1cae5d3299874c99ef8c2df79c3dc0f02be;hp=686e95bc011277baa62993f53887c63aca291c66;hpb=42bf93368ea81b2fa70fab038f3c884755e1ab88;p=civicrm-core.git diff --git a/tests/qunit/README.txt b/tests/qunit/README.txt index 686e95bc01..ccd6a33dd0 100644 --- a/tests/qunit/README.txt +++ b/tests/qunit/README.txt @@ -1,114 +1 @@ -==== 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/