4 +--------------------------------------------------------------------+
5 | Copyright CiviCRM LLC. All rights reserved. |
7 | This work is published under the GNU AGPLv3 license with some |
8 | permitted exceptions and without any warranty. For full license |
9 | and copyright information, see https://civicrm.org/licensing |
10 +--------------------------------------------------------------------+
16 * @copyright CiviCRM LLC https://civicrm.org/licensing
19 namespace api\v
4\Entity
;
21 use api\v
4\Service\TestCreationParameterProvider
;
22 use api\v
4\Traits\CheckAccessTrait
;
23 use api\v
4\Traits\OptionCleanupTrait
;
24 use api\v
4\Traits\TableDropperTrait
;
25 use Civi\API\Exception\UnauthorizedException
;
26 use Civi\Api4\CustomField
;
27 use Civi\Api4\CustomGroup
;
29 use api\v
4\UnitTestCase
;
30 use Civi\Api4\Event\ValidateValuesEvent
;
31 use Civi\Api4\Service\Spec\CustomFieldSpec
;
32 use Civi\Api4\Service\Spec\FieldSpec
;
33 use Civi\Api4\Service\Spec\SpecGatherer
;
34 use Civi\Api4\Utils\CoreUtil
;
35 use Civi\Core\Event\PostEvent
;
36 use Civi\Core\Event\PreEvent
;
37 use Civi\Test\HookInterface
;
42 class ConformanceTest
extends UnitTestCase
implements HookInterface
{
45 use TableDropperTrait
;
46 use OptionCleanupTrait
{
47 setUp
as setUpOptionCleanup
;
51 * @var \api\v4\Service\TestCreationParameterProvider
53 protected $creationParamProvider;
56 * Set up baseline for testing
58 * @throws \CRM_Core_Exception
60 public function setUp(): void
{
61 // Enable all components
62 \CRM_Core_BAO_ConfigSetting
::enableAllComponents();
63 $this->setUpOptionCleanup();
64 $this->loadDataSet('CaseType');
65 $this->loadDataSet('ConformanceTest');
66 $gatherer = new SpecGatherer();
67 $this->creationParamProvider
= new TestCreationParameterProvider($gatherer);
69 $this->resetCheckAccess();
73 * @throws \API_Exception
74 * @throws \Civi\API\Exception\UnauthorizedException
76 public function tearDown(): void
{
77 CustomField
::delete()->addWhere('id', '>', 0)->execute();
78 CustomGroup
::delete()->addWhere('id', '>', 0)->execute();
83 'civicrm_participant',
87 $this->cleanup(['tablesToTruncate' => $tablesToTruncate]);
92 * Get entities to test.
94 * This is the hi-tech list as generated via Civi's runtime services. It
95 * is canonical, but relies on services that may not be available during
96 * early parts of PHPUnit lifecycle.
100 * @throws \API_Exception
101 * @throws \CRM_Core_Exception
103 public function getEntitiesHitech(): array {
104 // Ensure all components are enabled so their entities show up
105 foreach (array_keys(\CRM_Core_Component
::getComponents()) as $component) {
106 \CRM_Core_BAO_ConfigSetting
::enableComponent($component);
108 return $this->toDataProviderArray(Entity
::get(FALSE)->execute()->column('name'));
112 * Get entities to test.
114 * This is the low-tech list as generated by manual-overrides and direct inspection.
115 * It may be summoned at any time during PHPUnit lifecycle, but it may require
116 * occasional twiddling to give correct results.
120 public function getEntitiesLotech(): array {
122 $manual['remove'] = ['CustomValue'];
123 $manual['transform'] = ['CiviCase' => 'Case'];
126 $srcDir = dirname(__DIR__
, 5);
127 foreach ((array) glob("$srcDir/Civi/Api4/*.php") as $name) {
128 $fileName = basename($name, '.php');
129 $scanned[] = $manual['transform'][$fileName] ??
$fileName;
133 array_unique(array_merge($scanned, $manual['add'])),
137 return $this->toDataProviderArray($names);
141 * Ensure that "getEntitiesLotech()" (which is the 'dataProvider') is up to date
142 * with "getEntitiesHitech()" (which is a live feed available entities).
144 public function testEntitiesProvider(): void
{
145 $this->assertEquals($this->getEntitiesHitech(), $this->getEntitiesLotech(), "The lo-tech list of entities does not match the hi-tech list. You probably need to update getEntitiesLotech().");
149 * @param string $entity
152 * @dataProvider getEntitiesLotech
154 * @throws \API_Exception
156 public function testConformance(string $entity): void
{
157 $entityClass = CoreUtil
::getApiClass($entity);
159 $this->checkEntityInfo($entityClass);
160 $actions = $this->checkActions($entityClass);
162 // Go no further if it's not a CRUD entity
163 if (array_diff(['get', 'create', 'update', 'delete'], array_keys($actions))) {
164 $this->markTestSkipped("The API \"$entity\" does not implement CRUD actions");
167 $this->checkFields($entityClass, $entity);
168 $this->checkCreationDenied($entity, $entityClass);
169 $id = $this->checkCreation($entity, $entityClass);
170 $this->checkGet($entityClass, $id, $entity);
171 $this->checkGetAllowed($entityClass, $id, $entity);
172 $this->checkGetCount($entityClass, $id, $entity);
173 $this->checkUpdateFailsFromCreate($entityClass, $id);
174 $this->checkWrongParamType($entityClass);
175 $this->checkDeleteWithNoId($entityClass);
176 $this->checkDeletionDenied($entityClass, $id, $entity);
177 $this->checkDeletionAllowed($entityClass, $id, $entity);
178 $this->checkPostDelete($entityClass, $id, $entity);
182 * @param \Civi\Api4\Generic\AbstractEntity|string $entityClass
184 protected function checkEntityInfo($entityClass): void
{
185 $info = $entityClass::getInfo();
186 $this->assertNotEmpty($info['name']);
187 $this->assertNotEmpty($info['title']);
188 $this->assertNotEmpty($info['title_plural']);
189 $this->assertNotEmpty($info['type']);
190 $this->assertNotEmpty($info['description']);
191 $this->assertIsArray($info['primary_key']);
192 $this->assertNotEmpty($info['primary_key']);
193 $this->assertRegExp(';^\d\.\d+$;', $info['since']);
194 $this->assertContains($info['searchable'], ['primary', 'secondary', 'bridge', 'none']);
195 // Bridge must be between exactly 2 entities
196 if (in_array('EntityBridge', $info['type'], TRUE)) {
197 $this->assertCount(2, $info['bridge']);
202 * @param \Civi\Api4\Generic\AbstractEntity|string $entityClass
203 * @param string $entity
205 * @throws \API_Exception
207 protected function checkFields($entityClass, $entity) {
208 $fields = $entityClass::getFields(FALSE)
209 ->addWhere('type', '=', 'Field')
213 $idField = CoreUtil
::getIdFieldName($entity);
215 $errMsg = sprintf('%s getfields is missing primary key field', $entity);
217 $this->assertArrayHasKey($idField, $fields, $errMsg);
218 $this->assertEquals('Integer', $fields[$idField]['data_type']);
220 // Ensure that the getFields (FieldSpec) format is generally consistent.
221 foreach ($fields as $field) {
222 $isNotNull = function($v) {
225 $class = empty($field['custom_field_id']) ? FieldSpec
::class : CustomFieldSpec
::class;
226 $spec = (new $class($field['name'], $field['entity']))->loadArray($field, TRUE);
228 array_filter($field, $isNotNull),
229 array_filter($spec->toArray(), $isNotNull)
235 * @param \Civi\Api4\Generic\AbstractEntity|string $entityClass
239 * @throws \API_Exception
241 protected function checkActions($entityClass): array {
242 $actions = $entityClass::getActions(FALSE)
246 $this->assertNotEmpty($actions);
247 return (array) $actions;
251 * @param string $entity
252 * @param \Civi\Api4\Generic\AbstractEntity|string $entityClass
256 protected function checkCreation($entity, $entityClass) {
257 $isReadOnly = $this->isReadOnly($entityClass);
260 $onValidate = function(ValidateValuesEvent
$e) use (&$hookLog) {
261 $hookLog[$e->getEntityName()][$e->getActionName()] = 1 +
($hookLog[$e->getEntityName()][$e->getActionName()] ??
0);
263 \Civi
::dispatcher()->addListener('civi.api4.validate', $onValidate);
264 \Civi
::dispatcher()->addListener('civi.api4.validate::' . $entity, $onValidate);
266 $this->setCheckAccessGrants(["{$entity}::create" => TRUE]);
267 $this->assertEquals(0, $this->checkAccessCounts
["{$entity}::create"]);
269 $requiredParams = $this->creationParamProvider
->getRequired($entity);
270 $createResult = $entityClass::create()
271 ->setValues($requiredParams)
272 ->setCheckPermissions(!$isReadOnly)
276 $idField = CoreUtil
::getIdFieldName($entity);
278 $this->assertArrayHasKey($idField, $createResult, "create missing ID");
279 $id = $createResult[$idField];
280 $this->assertGreaterThanOrEqual(1, $id, "$entity ID not positive");
282 $this->assertEquals(1, $this->checkAccessCounts
["{$entity}::create"]);
284 $this->resetCheckAccess();
286 $this->assertEquals(2, $hookLog[$entity]['create']);
287 \Civi
::dispatcher()->removeListener('civi.api4.validate', $onValidate);
288 \Civi
::dispatcher()->removeListener('civi.api4.validate::' . $entity, $onValidate);
294 * @param string $entity
295 * @param \Civi\Api4\Generic\AbstractEntity|string $entityClass
297 protected function checkCreationDenied(string $entity, $entityClass): void
{
298 $this->setCheckAccessGrants(["{$entity}::create" => FALSE]);
299 $this->assertEquals(0, $this->checkAccessCounts
["{$entity}::create"]);
301 $requiredParams = $this->creationParamProvider
->getRequired($entity);
304 $entityClass::create()
305 ->setValues($requiredParams)
306 ->setCheckPermissions(TRUE)
309 $this->fail("{$entityClass}::create() should throw an authorization failure.");
311 catch (UnauthorizedException
$e) {
312 // OK, expected exception
314 if (!$this->isReadOnly($entityClass)) {
315 $this->assertEquals(1, $this->checkAccessCounts
["{$entity}::create"]);
317 $this->resetCheckAccess();
321 * @param \Civi\Api4\Generic\AbstractEntity|string $entityClass
324 protected function checkUpdateFailsFromCreate($entityClass, int $id): void
{
325 $exceptionThrown = '';
327 $entityClass::create(FALSE)
328 ->addValue('id', $id)
331 catch (\API_Exception
$e) {
332 $exceptionThrown = $e->getMessage();
334 $this->assertStringContainsString('id', $exceptionThrown);
338 * @param \Civi\Api4\Generic\AbstractEntity|string $entityClass
340 * @param string $entity
342 protected function checkGet($entityClass, int $id, string $entity): void
{
343 $getResult = $entityClass::get(FALSE)
344 ->addWhere('id', '=', $id)
347 $errMsg = sprintf('Failed to fetch a %s after creation', $entity);
348 $idField = CoreUtil
::getIdFieldName($entity);
349 $this->assertEquals($id, $getResult->first()[$idField], $errMsg);
350 $this->assertEquals(1, $getResult->count(), $errMsg);
354 * Use a permissioned request for `get()`, with access grnted
355 * via checkAccess event.
357 * @param \Civi\Api4\Generic\AbstractEntity|string $entityClass
359 * @param string $entity
361 protected function checkGetAllowed($entityClass, $id, $entity) {
362 $this->setCheckAccessGrants(["{$entity}::get" => TRUE]);
363 $getResult = $entityClass::get()
364 ->addWhere('id', '=', $id)
367 $errMsg = sprintf('Failed to fetch a %s after creation', $entity);
368 $idField = CoreUtil
::getIdFieldName($entity);
369 $this->assertEquals($id, $getResult->first()[$idField], $errMsg);
370 $this->assertEquals(1, $getResult->count(), $errMsg);
371 $this->resetCheckAccess();
375 * @param \Civi\Api4\Generic\AbstractEntity|string $entityClass
377 * @param string $entity
379 protected function checkGetCount($entityClass, $id, $entity): void
{
380 $idField = CoreUtil
::getIdFieldName($entity);
381 $getResult = $entityClass::get(FALSE)
382 ->addWhere($idField, '=', $id)
385 $errMsg = sprintf('%s getCount failed', $entity);
386 $this->assertEquals(1, $getResult->count(), $errMsg);
388 $getResult = $entityClass::get(FALSE)
391 $this->assertGreaterThanOrEqual(1, $getResult->count(), $errMsg);
395 * @param \Civi\Api4\Generic\AbstractEntity|string $entityClass
397 protected function checkDeleteWithNoId($entityClass) {
399 $entityClass::delete()
401 $this->fail("$entityClass should require ID to delete.");
403 catch (\API_Exception
$e) {
409 * @param \Civi\Api4\Generic\AbstractEntity|string $entityClass
411 protected function checkWrongParamType($entityClass) {
412 $exceptionThrown = '';
415 ->setDebug('not a bool')
418 catch (\API_Exception
$e) {
419 $exceptionThrown = $e->getMessage();
421 $this->assertStringContainsString('debug', $exceptionThrown);
422 $this->assertStringContainsString('type', $exceptionThrown);
426 * Delete an entity - while having a targeted grant (hook_civirm_checkAccess).
428 * @param \Civi\Api4\Generic\AbstractEntity|string $entityClass
430 * @param string $entity
432 protected function checkDeletionAllowed($entityClass, $id, $entity) {
433 $this->setCheckAccessGrants(["{$entity}::delete" => TRUE]);
434 $this->assertEquals(0, $this->checkAccessCounts
["{$entity}::delete"]);
435 $isReadOnly = $this->isReadOnly($entityClass);
437 $idField = CoreUtil
::getIdFieldName($entity);
438 $deleteAction = $entityClass::delete()
439 ->setCheckPermissions(!$isReadOnly)
440 ->addWhere($idField, '=', $id);
442 if (property_exists($deleteAction, 'useTrash')) {
443 $deleteAction->setUseTrash(FALSE);
446 $log = $this->withPrePostLogging(function() use (&$deleteAction, &$deleteResult) {
447 $deleteResult = $deleteAction->execute();
450 if (in_array('DAOEntity', CoreUtil
::getInfoItem($entity, 'type'))) {
451 // We should have emitted an event.
452 $hookEntity = ($entity === 'Contact') ?
'Individual' : $entity;/* ooph */
453 $this->assertContains("pre.{$hookEntity}.delete", $log, "$entity should emit hook_civicrm_pre() for deletions");
454 $this->assertContains("post.{$hookEntity}.delete", $log, "$entity should emit hook_civicrm_post() for deletions");
456 // should get back an array of deleted id
457 $this->assertEquals([['id' => $id]], (array) $deleteResult);
459 $this->assertEquals(1, $this->checkAccessCounts
["{$entity}::delete"]);
462 $this->resetCheckAccess();
466 * Attempt to delete an entity while having explicitly denied permission (hook_civicrm_checkAccess).
468 * @param \Civi\Api4\Generic\AbstractEntity|string $entityClass
470 * @param string $entity
472 protected function checkDeletionDenied($entityClass, $id, $entity) {
473 $this->setCheckAccessGrants(["{$entity}::delete" => FALSE]);
474 $this->assertEquals(0, $this->checkAccessCounts
["{$entity}::delete"]);
477 $entityClass::delete()
478 ->addWhere('id', '=', $id)
480 $this->fail("{$entity}::delete should throw an authorization failure.");
482 catch (UnauthorizedException
$e) {
486 if (!$this->isReadOnly($entityClass)) {
487 $this->assertEquals(1, $this->checkAccessCounts
["{$entity}::delete"]);
489 $this->resetCheckAccess();
493 * @param \Civi\Api4\Generic\AbstractEntity|string $entityClass
495 * @param string $entity
497 protected function checkPostDelete($entityClass, $id, $entity) {
498 $getDeletedResult = $entityClass::get(FALSE)
499 ->addWhere('id', '=', $id)
502 $errMsg = sprintf('Entity "%s" was not deleted', $entity);
503 $this->assertEquals(0, count($getDeletedResult), $errMsg);
507 * @param array $names
508 * List of entity names.
511 * List of data-provider arguments, one for each entity-name.
512 * Ex: ['Foo' => ['Foo'], 'Bar' => ['Bar']]
514 protected function toDataProviderArray($names) {
518 foreach ($names as $name) {
519 $result[$name] = [$name];
525 * @param \Civi\Api4\Generic\AbstractEntity|string $entityClass
528 protected function isReadOnly($entityClass) {
529 return in_array('ReadOnlyEntity', $entityClass::getInfo()['type'], TRUE);
533 * Temporarily enable logging for `hook_civicrm_pre` and `hook_civicrm_post`.
535 * @param callable $callable
536 * Run this function. Create a log while running this function.
538 * Log; list of times the hooks were called.
539 * Ex: ['pre.Event.delete', 'post.Event.delete']
541 protected function withPrePostLogging($callable): array {
544 $listen = function ($e) use (&$log) {
545 if ($e instanceof PreEvent
) {
546 $log[] = "pre.{$e->entity}.{$e->action}";
548 elseif ($e instanceof PostEvent
) {
549 $log[] = "post.{$e->entity}.{$e->action}";
554 \Civi
::dispatcher()->addListener('hook_civicrm_pre', $listen);
555 \Civi
::dispatcher()->addListener('hook_civicrm_post', $listen);
559 \Civi
::dispatcher()->removeListener('hook_civicrm_pre', $listen);
560 \Civi
::dispatcher()->removeListener('hook_civicrm_post', $listen);