9 * This trait defines a number of helper functions for testing APIv3. Commonly
10 * used helpers include `callAPISuccess()`, `callAPIFailure()`,
11 * `assertAPISuccess()`, and `assertAPIFailure()`.
13 * This trait is intended for use with PHPUnit-based test cases.
18 * Api version - easier to override than just a define
21 protected $_apiversion = 3;
24 * Check that api returned 'is_error' => 1
25 * else provide full message
26 * @param array $result
28 * @param array $valuesToExclude
29 * @param string $prefix
30 * Extra test to add to message.
32 public function assertAPIArrayComparison($result, $expected, $valuesToExclude = [], $prefix = '') {
33 $valuesToExclude = array_merge($valuesToExclude, ['debug', 'xdebug', 'sequential']);
34 foreach ($valuesToExclude as $value) {
35 if (isset($result[$value])) {
36 unset($result[$value]);
38 if (isset($expected[$value])) {
39 unset($expected[$value]);
42 $this->assertEquals($result, $expected, "api result array comparison failed " . $prefix . print_r($result, TRUE) . ' was compared to ' . print_r($expected, TRUE));
46 * Check that a deleted item has been deleted.
51 public function assertAPIDeleted($entity, $id) {
52 $this->callAPISuccess($entity, 'getcount', ['id' => $id], 0);
56 * Check that api returned 'is_error' => 1.
58 * @param array $apiResult
60 * @param string $prefix
61 * Extra test to add to message.
62 * @param null $expectedError
64 public function assertAPIFailure($apiResult, $prefix = '', $expectedError = NULL) {
65 if (!empty($prefix)) {
68 if ($expectedError && !empty($apiResult['is_error'])) {
69 $this->assertEquals($expectedError, $apiResult['error_message'], 'api error message not as expected' . $prefix);
71 $this->assertEquals(1, $apiResult['is_error'], "api call should have failed but it succeeded " . $prefix . (print_r($apiResult, TRUE)));
72 $this->assertNotEmpty($apiResult['error_message']);
76 * Check that api returned 'is_error' => 0.
78 * @param array $apiResult
80 * @param string $prefix
81 * Extra test to add to message.
83 public function assertAPISuccess($apiResult, $prefix = '') {
84 if (!empty($prefix)) {
87 $errorMessage = empty($apiResult['error_message']) ?
'' : " " . $apiResult['error_message'];
89 if (!empty($apiResult['debug_information'])) {
90 $errorMessage .= "\n " . print_r($apiResult['debug_information'], TRUE);
92 if (!empty($apiResult['trace'])) {
93 $errorMessage .= "\n" . print_r($apiResult['trace'], TRUE);
95 $this->assertEquals(0, $apiResult['is_error'], $prefix . $errorMessage);
99 * This function exists to wrap api functions.
100 * so we can ensure they fail where expected & throw exceptions without litterering the test with checks
101 * @param string $entity
102 * @param string $action
103 * @param array $params
104 * @param string $expectedErrorMessage
106 * @param null $extraOutput
109 public function callAPIFailure($entity, $action, $params, $expectedErrorMessage = NULL, $extraOutput = NULL) {
110 if (is_array($params)) {
112 'version' => $this->_apiversion
,
115 $result = $this->civicrm_api($entity, $action, $params);
116 $this->assertAPIFailure($result, "We expected a failure for $entity $action but got a success", $expectedErrorMessage);
121 * wrap api functions.
122 * so we can ensure they succeed & throw exceptions without litterering the test with checks
124 * @param string $entity
125 * @param string $action
126 * @param array $params
127 * @param mixed $checkAgainst
128 * Optional value to check result against, implemented for getvalue,.
129 * getcount, getsingle. Note that for getvalue the type is checked rather than the value
130 * for getsingle the array is compared against an array passed in - the id is not compared (for
135 public function callAPISuccess($entity, $action, $params, $checkAgainst = NULL) {
136 $params = array_merge([
137 'version' => $this->_apiversion
,
142 switch (strtolower($action)) {
144 return $this->callAPISuccessGetValue($entity, $params, $checkAgainst);
147 return $this->callAPISuccessGetSingle($entity, $params, $checkAgainst);
150 return $this->callAPISuccessGetCount($entity, $params, $checkAgainst);
152 $result = $this->civicrm_api($entity, $action, $params);
153 $this->assertAPISuccess($result, "Failure in api call for $entity $action");
158 * This function exists to wrap api getValue function & check the result
159 * so we can ensure they succeed & throw exceptions without litterering the test with checks
160 * There is a type check in this
161 * @param string $entity
162 * @param array $params
167 public function callAPISuccessGetCount($entity, $params, $count = NULL) {
169 'version' => $this->_apiversion
,
172 $result = $this->civicrm_api($entity, 'getcount', $params);
173 if (!is_int($result) ||
!empty($result['is_error']) ||
isset($result['values'])) {
174 throw new \
Exception('Invalid getcount result : ' . print_r($result, TRUE) . " type :" . gettype($result));
176 if (is_int($count)) {
177 $this->assertEquals($count, $result, "incorrect count returned from $entity getcount");
183 * This function exists to wrap api getsingle function & check the result
184 * so we can ensure they succeed & throw exceptions without litterering the test with checks
186 * @param string $entity
187 * @param array $params
188 * @param array $checkAgainst
189 * Array to compare result against.
200 public function callAPISuccessGetSingle($entity, $params, $checkAgainst = NULL) {
202 'version' => $this->_apiversion
,
204 $result = $this->civicrm_api($entity, 'getsingle', $params);
205 if (!is_array($result) ||
!empty($result['is_error']) ||
isset($result['values'])) {
206 $unfilteredResult = $this->civicrm_api($entity, 'get', $params);
207 throw new \
Exception(
208 'Invalid getsingle result' . print_r($result, TRUE)
209 . "\n entity: $entity . \n params \n " . print_r($params, TRUE)
210 . "\n entities retrieved with blank params \n" . print_r($unfilteredResult, TRUE)
214 // @todo - have gone with the fn that unsets id? should we check id?
215 $this->checkArrayEquals($result, $checkAgainst);
221 * This function exists to wrap api getValue function & check the result
222 * so we can ensure they succeed & throw exceptions without litterering the test with checks
223 * There is a type check in this
225 * @param string $entity
226 * @param array $params
227 * @param string $type
228 * Per http://php.net/manual/en/function.gettype.php possible types.
238 public function callAPISuccessGetValue($entity, $params, $type = NULL) {
240 'version' => $this->_apiversion
,
243 $result = $this->civicrm_api($entity, 'getvalue', $params);
244 if (is_array($result) && (!empty($result['is_error']) ||
isset($result['values']))) {
245 throw new \
Exception('Invalid getvalue result' . print_r($result, TRUE));
248 if ($type == 'integer') {
249 // api seems to return integers as strings
250 $this->assertTrue(is_numeric($result), "expected a numeric value but got " . print_r($result, 1));
253 $this->assertType($type, $result, "returned result should have been of type $type but was ");
260 * A stub for the API interface. This can be overriden by subclasses to change how the API is called.
264 * @param array $params
267 public function civicrm_api($entity, $action, $params) {
268 return civicrm_api($entity, $action, $params);