| 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. |