From 859c578d764666c96cb3ce3c541854a9f7270550 Mon Sep 17 00:00:00 2001 From: Tim Otten Date: Mon, 22 Aug 2016 21:59:42 -0700 Subject: [PATCH] `tests/README` - Rewrite --- tests/README.md | 74 ++++++++++++++++++++++++++++++++++++++++++++++++ tests/README.txt | 16 ----------- 2 files changed, 74 insertions(+), 16 deletions(-) create mode 100644 tests/README.md delete mode 100644 tests/README.txt diff --git a/tests/README.md b/tests/README.md new file mode 100644 index 0000000000..e5fe2ab941 --- /dev/null +++ b/tests/README.md @@ -0,0 +1,74 @@ +To run the tests you need to configure it as described in the wiki: + +https://wiki.civicrm.org/confluence/display/CRMDOC/Testing + +## Configuration + +If the test environment has been created by a common build-profile using +[buildkit](https://github.com/civicrm/civicrm-buildkit/)'s `civibuild` +command (such as `drupal-clean` or `wp-demo`), then you should be able to +execute tests without further configuration. + +Otherwise, you need to install [`cv`](https://github.com/civicrm/cv) +and fill in missing test data: + + * `cd` into your Drupal/WordPress site and run `cv vars:fill`. This will create a file `~/.cv.json`. + * Tip: If you need to share this installation with other local users, you may specify `export CV_CONFIG=/path/to/shared/file.json` + * Edit the file `~/.cv.json`. You may need to fill some or all of these details: + * Credentials for an administrative CMS user (`ADMIN_USER`, `ADMIN_PASS`, `ADMIN_EMAIL`) + * Credentials for a non-administrative CMS user (`DEMO_USER`, `DEMO_PASS`, `DEMO_EMAIL`) + * Credentials for an empty test database (`TEST_DB_DSN`) + +## Suites + +`civicrm-core` includes multiple test suites. Each suite makes use of the environment differently: + +| Runner | Suite | Type | CMS | Typical Base Class | Comment | +| ------ | ----- | ---- | --- | ------------------ | ----------- | +| PHPUnit |`api_v3_AllTests`|`headless`|Agnostic|`CiviUnitTestCase`|Requires `CIVICRM_UF=UnitTests`| +| PHPUnit |`Civi\AllTests`|`headless`|Agnostic|`CiviUnitTestCase`|Requires `CIVICRM_UF=UnitTests`| +| PHPUnit |`CRM_AllTests`|`headless`|Agnostic|`CiviUnitTestCase`|Requires `CIVICRM_UF=UnitTests`| +| PHPUnit |`E2E_AllTests`|`e2e`|Agnostic|`PHPUnit_Framework_TestCase`|Useful for command-line scripts and web-services| +| PHPUnit |`WebTest_AllTests`|`e2e`|Drupal|`CiviSeleniumTestCase`|Useful for tests which require a full web-browser| +| Karma ||`unit`|Agnostic||| +| QUnit ||`e2e`|Agnostic||Run each test in a browser. See README.| + +Headless test suites like `CRM_AllTests` run on a secondary, headless CiviCRM database. They use a +fake CMS/UF (named `UnitTests`) and aggressively manipulate the content of the database (e.g. +truncating, dropping, or creating tables at a whim). + +E2E tests run against a full installation of CiviCRM with an active, integrated CMS. These tests +may do some manipulation on the database, so be careful to only run these on developmental +systems... and have a fallback-plan in case the tests screw-up your database. + +## PHPUnit Usage + +You may invoke the PHPUnit tests using the legacy wrapper command (`tools/scripts/phpunit`), e.g. + +```bash +## Invoke "CRM_AllTests" with the legacy wrapper +cd tools +./scripts/phpunit CRM_AllTests + +## Invoke "E2E_AllTests" with the legacy wrapper +cd tools +./scripts/phpunit E2E_AllTests + +``` + +The advantage of using the legacy wrapper is that works with multiple versions of CiviCRM (e.g. +`4.4` or `4.7`) and has shorter commands. However, if you try to use it with an IDE, it +may not work well. + +Alternatively, you may invoke the PHPUnit tests with a standalone copy of PHPUnit (e.g. `phpunit4`), e.g. + +```bash +## Invoke "CRM_AllTests" using a standalone copy of PHPUnit +env CIVICRM_UF=UnitTests phpunit4 ./tests/phpunit/CRM/AllTests.php + +## Invoke "E2E_AllTests" using a standalone copy of PHPUnit +phpunit4 ./tests/phpunit/E2E/AllTests.php +``` + +The advantage of using a standalone copy of PHPUnit is that integrates better with an IDE. +However, it's only supported on CiviCRM 4.7+, and you may need to set an environment variable. diff --git a/tests/README.txt b/tests/README.txt deleted file mode 100644 index 54cadc733d..0000000000 --- a/tests/README.txt +++ /dev/null @@ -1,16 +0,0 @@ -To run the tests you need to configure it as described in the wiki: - -http://wiki.civicrm.org/confluence/display/CRM/Testing - -The commands to run the tests include: - -$ cd SVNROOT/tools -$ scripts/phpunit -u db_username -pdb_password -h db_host api_v2_ContactTest -$ scripts/phpunit -u db_username -pdb_password -h db_host WebTest_Contact_AddTest -$ scripts/phpunit -u db_username -pdb_password -h db_host WebTest_AllTests -$ scripts/phpunit -u db_username -pdb_password -h db_host api_v3_AllTests - -You can also specify database name using "-bdb_name" option. If database name is not specified it will -use "civicrm_tests_dev" as default db for all the tests. - - -- 2.25.1