CiviCRM Unit Testing basic information

Goals

• Get all the API tests to the state where there are no fails or errors
• Introduce simple API behaviour checks - calling each API method with empty params and calling each API method with params of wrong type

Terminology

• test suite - all the tests that we have, a collection of test cases
• test case or test group - a class containing a set of tests
• test or test method - single method in test class

Basic conventions

1. Test case needs to extend CiviUnitTestCase
2. Test methods naming should follow the pattern:
   • start with test
   • name should describe what the test does, e.g. testCreateWithWrongParamsType

The flow

Fresh database (/sql/civicrm.mysql and /sql/civicrm_data.mysql files) is loaded before you start running your test, doesn't matter if you're running the whole suite or just a single test. This happens when you see "Installing civicrm_tests_dev database" message when running tests.

Most of database tables are truncated before each test method is executed (using tests/phpunit/CiviTest/truncate.xml file - if you're running into trouble with test data, you might want to see if you don't need to add specific table to this file), so every time you need to make sure you're providing proper data for your test to run on.

Special test case methods - setUp and tearDown

setUp is executed before each test method, tearDown is executed after each test method. Sometimes it will be convenient to prepare test data for whole test case - in such case, you will want to put all the test data creation code in there.

Guidelines

1. Take a look at the results of test case you are assigned to and see which tests are failing and which throw errors.
2. Go to tests/phpunit/api/v2/<apigroupname>Test.php and fix failing/error tests.
3. For all the API functions represented in your test case, make sure that at least three test methods are available:
   • testing expected successful behaviour (e.g. testCreate)
   • calling given API function with empty params - should usually return error
   • calling given API function with wrong type params (not array) - should also return an error
4. Example test methods to check for two latter scenarios:
5. Sometimes, you'll need to jump into the specific API function and fix it to pass above tests.

   Please DO NOT change API behaviour other than required for successful pass of above three checks (unless you find a bug of course). If there are any inconsistencies, we'll fix them in the next run, controlling backwards compatibility. Most API functions require array $params and return an array with a key is_error (boolean). If an API function (that should accept only array type $params) doesn't return an error, it's because it doesn't follow the right convention as described here .