tests/README.md

   1 To run the tests you need to configure it as described in the wiki:
   2
   3 https://wiki.civicrm.org/confluence/display/CRMDOC/Testing
   4
   5 ## Configuration
   6
   7 If the test environment has been created by a common build-profile using
   8 [buildkit](https://github.com/civicrm/civicrm-buildkit/)'s `civibuild`
   9 command (such as `drupal-clean` or `wp-demo`), then you should be able to
  10 execute tests without further configuration.
  11
  12 Otherwise, you need to install [`cv`](https://github.com/civicrm/cv)
  13 and fill in missing test data:
  14
  15  * `cd` into your Drupal/WordPress site and run `cv vars:fill`. This will create a file `~/.cv.json`.
  16    * Tip: If you need to share this installation with other local users, you may specify `export CV_CONFIG=/path/to/shared/file.json`
  17  * Edit the file `~/.cv.json`. You may need to fill some or all of these details:
  18    * Credentials for an administrative CMS user (`ADMIN_USER`, `ADMIN_PASS`, `ADMIN_EMAIL`)
  19    * Credentials for a non-administrative CMS user (`DEMO_USER`, `DEMO_PASS`, `DEMO_EMAIL`)
  20    * Credentials for an empty test database (`TEST_DB_DSN`)
  21
  22 ## Suites
  23
  24 `civicrm-core` includes multiple test suites. Each suite makes use of the environment differently:
  25
  26 | Runner | Suite | Type | CMS | Typical Base Class | Comment |
  27 | ------ | ----- | ---- | --- | ------------------ | ----------- |
  28 | PHPUnit |`api_v3_AllTests`|`headless`|Agnostic|`CiviUnitTestCase`|Requires `CIVICRM_UF=UnitTests`|
  29 | PHPUnit |`Civi\AllTests`|`headless`|Agnostic|`CiviUnitTestCase`|Requires `CIVICRM_UF=UnitTests`|
  30 | PHPUnit |`CRM_AllTests`|`headless`|Agnostic|`CiviUnitTestCase`|Requires `CIVICRM_UF=UnitTests`|
  31 | PHPUnit |`E2E_AllTests`|`e2e`|Agnostic|`CiviEndToEndTestCase`|Useful for command-line scripts and web-services|
  32 | PHPUnit |`WebTest_AllTests`|`e2e`|Drupal|`CiviSeleniumTestCase`|Useful for tests which require a full web-browser|
  33 | Karma ||`unit`|Agnostic|||
  34 | QUnit ||`e2e`|Agnostic||Run each test in a browser. See README.|
  35
  36 Headless test suites like `CRM_AllTests` run on a secondary, headless CiviCRM database.  They use a
  37 fake CMS/UF (named `UnitTests`) and aggressively manipulate the content of the database (e.g.
  38 truncating, dropping, or creating tables at a whim).
  39
  40 E2E tests run against a full installation of CiviCRM with an active, integrated CMS.  These tests
  41 may do some manipulation on the database, so be careful to only run these on developmental
  42 systems...  and have a fallback-plan in case the tests screw-up your database.
  43
  44 ## PHPUnit Usage
  45
  46 You may invoke the PHPUnit tests using the legacy wrapper command (`tools/scripts/phpunit`), e.g.
  47
  48 ```bash
  49 ## Invoke "CRM_AllTests" with the legacy wrapper
  50 cd tools
  51 ./scripts/phpunit CRM_AllTests
  52
  53 ## Invoke "E2E_AllTests" with the legacy wrapper
  54 cd tools
  55 ./scripts/phpunit E2E_AllTests
  56
  57 ```
  58
  59 The advantage of using the legacy wrapper is that works with multiple versions of CiviCRM (e.g.
  60 `4.4` or `4.7`) and has shorter commands.  However, if you try to use it with an IDE, it
  61 may not work well.
  62
  63 Alternatively, you may invoke the PHPUnit tests with a standalone copy of PHPUnit (e.g. `phpunit4`), e.g.
  64
  65 ```bash
  66 ## Invoke "CRM_AllTests" using a standalone copy of PHPUnit
  67 env CIVICRM_UF=UnitTests phpunit4 ./tests/phpunit/CRM/AllTests.php
  68
  69 ## Invoke "E2E_AllTests" using a standalone copy of PHPUnit
  70 phpunit4 ./tests/phpunit/E2E/AllTests.php
  71 ```
  72
  73 The advantage of using a standalone copy of PHPUnit is that integrates better with an IDE.
  74 However, it's only supported on CiviCRM 4.7+, and you may need to set an environment variable.