| 1 | <?php |
| 2 | |
| 3 | /* |
| 4 | +--------------------------------------------------------------------+ |
| 5 | | Copyright CiviCRM LLC. All rights reserved. | |
| 6 | | | |
| 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 | +--------------------------------------------------------------------+ |
| 11 | */ |
| 12 | |
| 13 | /** |
| 14 | * |
| 15 | * @package CRM |
| 16 | * @copyright CiviCRM LLC https://civicrm.org/licensing |
| 17 | */ |
| 18 | |
| 19 | |
| 20 | namespace api\v4\Entity; |
| 21 | |
| 22 | use Civi\Api4\Entity; |
| 23 | use api\v4\UnitTestCase; |
| 24 | use Civi\Api4\Utils\CoreUtil; |
| 25 | |
| 26 | /** |
| 27 | * @group headless |
| 28 | */ |
| 29 | class ConformanceTest extends UnitTestCase { |
| 30 | |
| 31 | use \api\v4\Traits\TableDropperTrait; |
| 32 | use \api\v4\Traits\OptionCleanupTrait { |
| 33 | setUp as setUpOptionCleanup; |
| 34 | } |
| 35 | |
| 36 | /** |
| 37 | * @var \api\v4\Service\TestCreationParameterProvider |
| 38 | */ |
| 39 | protected $creationParamProvider; |
| 40 | |
| 41 | /** |
| 42 | * Set up baseline for testing |
| 43 | */ |
| 44 | public function setUp(): void { |
| 45 | $tablesToTruncate = [ |
| 46 | 'civicrm_case_type', |
| 47 | 'civicrm_custom_group', |
| 48 | 'civicrm_custom_field', |
| 49 | 'civicrm_group', |
| 50 | 'civicrm_event', |
| 51 | 'civicrm_participant', |
| 52 | ]; |
| 53 | $this->dropByPrefix('civicrm_value_myfavorite'); |
| 54 | $this->cleanup(['tablesToTruncate' => $tablesToTruncate]); |
| 55 | $this->setUpOptionCleanup(); |
| 56 | $this->loadDataSet('CaseType'); |
| 57 | $this->loadDataSet('ConformanceTest'); |
| 58 | $this->creationParamProvider = \Civi::container()->get('test.param_provider'); |
| 59 | parent::setUp(); |
| 60 | } |
| 61 | |
| 62 | /** |
| 63 | * Get entities to test. |
| 64 | * |
| 65 | * This is the hi-tech list as generated via Civi's runtime services. It |
| 66 | * is canonical, but relies on services that may not be available during |
| 67 | * early parts of PHPUnit lifecycle. |
| 68 | * |
| 69 | * @return array |
| 70 | * |
| 71 | * @throws \API_Exception |
| 72 | * @throws \Civi\API\Exception\UnauthorizedException |
| 73 | */ |
| 74 | public function getEntitiesHitech() { |
| 75 | // Ensure all components are enabled so their entities show up |
| 76 | foreach (array_keys(\CRM_Core_Component::getComponents()) as $component) { |
| 77 | \CRM_Core_BAO_ConfigSetting::enableComponent($component); |
| 78 | } |
| 79 | return $this->toDataProviderArray(Entity::get(FALSE)->execute()->column('name')); |
| 80 | } |
| 81 | |
| 82 | /** |
| 83 | * Get entities to test. |
| 84 | * |
| 85 | * This is the low-tech list as generated by manual-overrides and direct inspection. |
| 86 | * It may be summoned at any time during PHPUnit lifecycle, but it may require |
| 87 | * occasional twiddling to give correct results. |
| 88 | * |
| 89 | * @return array |
| 90 | */ |
| 91 | public function getEntitiesLotech() { |
| 92 | $manual['add'] = []; |
| 93 | $manual['remove'] = ['CustomValue']; |
| 94 | $manual['transform'] = ['CiviCase' => 'Case']; |
| 95 | |
| 96 | $scanned = []; |
| 97 | $srcDir = dirname(__DIR__, 5); |
| 98 | foreach ((array) glob("$srcDir/Civi/Api4/*.php") as $name) { |
| 99 | $fileName = basename($name, '.php'); |
| 100 | $scanned[] = $manual['transform'][$fileName] ?? $fileName; |
| 101 | } |
| 102 | |
| 103 | $names = array_diff( |
| 104 | array_unique(array_merge($scanned, $manual['add'])), |
| 105 | $manual['remove'] |
| 106 | ); |
| 107 | |
| 108 | return $this->toDataProviderArray($names); |
| 109 | } |
| 110 | |
| 111 | /** |
| 112 | * Ensure that "getEntitiesLotech()" (which is the 'dataProvider') is up to date |
| 113 | * with "getEntitiesHitech()" (which is a live feed available entities). |
| 114 | */ |
| 115 | public function testEntitiesProvider() { |
| 116 | $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()."); |
| 117 | } |
| 118 | |
| 119 | /** |
| 120 | * @param string $entity |
| 121 | * Ex: 'Contact' |
| 122 | * |
| 123 | * @dataProvider getEntitiesLotech |
| 124 | * |
| 125 | * @throws \API_Exception |
| 126 | */ |
| 127 | public function testConformance($entity): void { |
| 128 | $entityClass = CoreUtil::getApiClass($entity); |
| 129 | |
| 130 | $this->checkEntityInfo($entityClass); |
| 131 | $actions = $this->checkActions($entityClass); |
| 132 | |
| 133 | // Go no further if it's not a CRUD entity |
| 134 | if (array_diff(['get', 'create', 'update', 'delete'], array_keys($actions))) { |
| 135 | $this->markTestSkipped("The API \"$entity\" does not implement CRUD actions"); |
| 136 | } |
| 137 | |
| 138 | $this->checkFields($entityClass, $entity); |
| 139 | $id = $this->checkCreation($entity, $entityClass); |
| 140 | $this->checkGet($entityClass, $id, $entity); |
| 141 | $this->checkGetCount($entityClass, $id, $entity); |
| 142 | $this->checkUpdateFailsFromCreate($entityClass, $id); |
| 143 | $this->checkWrongParamType($entityClass); |
| 144 | $this->checkDeleteWithNoId($entityClass); |
| 145 | $this->checkDeletion($entityClass, $id); |
| 146 | $this->checkPostDelete($entityClass, $id, $entity); |
| 147 | } |
| 148 | |
| 149 | /** |
| 150 | * @param \Civi\Api4\Generic\AbstractEntity|string $entityClass |
| 151 | */ |
| 152 | protected function checkEntityInfo($entityClass): void { |
| 153 | $info = $entityClass::getInfo(); |
| 154 | $this->assertNotEmpty($info['name']); |
| 155 | $this->assertNotEmpty($info['title']); |
| 156 | $this->assertNotEmpty($info['title_plural']); |
| 157 | $this->assertNotEmpty($info['type']); |
| 158 | $this->assertNotEmpty($info['description']); |
| 159 | $this->assertContains($info['searchable'], ['primary', 'secondary', 'none']); |
| 160 | // Bridge must be between exactly 2 entities |
| 161 | if (in_array('EntityBridge', $info['type'], TRUE)) { |
| 162 | $this->assertCount(2, $info['bridge']); |
| 163 | } |
| 164 | } |
| 165 | |
| 166 | /** |
| 167 | * @param \Civi\Api4\Generic\AbstractEntity|string $entityClass |
| 168 | * @param string $entity |
| 169 | * |
| 170 | * @throws \API_Exception |
| 171 | */ |
| 172 | protected function checkFields($entityClass, $entity) { |
| 173 | $fields = $entityClass::getFields(FALSE) |
| 174 | ->setIncludeCustom(FALSE) |
| 175 | ->execute() |
| 176 | ->indexBy('name'); |
| 177 | |
| 178 | $errMsg = sprintf('%s is missing required ID field', $entity); |
| 179 | $subset = ['data_type' => 'Integer']; |
| 180 | |
| 181 | $this->assertArrayHasKey('data_type', $fields['id'], $errMsg); |
| 182 | $this->assertEquals('Integer', $fields['id']['data_type']); |
| 183 | } |
| 184 | |
| 185 | /** |
| 186 | * @param \Civi\Api4\Generic\AbstractEntity|string $entityClass |
| 187 | * |
| 188 | * @return array |
| 189 | * |
| 190 | * @throws \API_Exception |
| 191 | */ |
| 192 | protected function checkActions($entityClass): array { |
| 193 | $actions = $entityClass::getActions(FALSE) |
| 194 | ->execute() |
| 195 | ->indexBy('name'); |
| 196 | |
| 197 | $this->assertNotEmpty($actions); |
| 198 | return (array) $actions; |
| 199 | } |
| 200 | |
| 201 | /** |
| 202 | * @param string $entity |
| 203 | * @param \Civi\Api4\Generic\AbstractEntity|string $entityClass |
| 204 | * |
| 205 | * @return mixed |
| 206 | */ |
| 207 | protected function checkCreation($entity, $entityClass) { |
| 208 | $requiredParams = $this->creationParamProvider->getRequired($entity); |
| 209 | $createResult = $entityClass::create() |
| 210 | ->setValues($requiredParams) |
| 211 | ->setCheckPermissions(FALSE) |
| 212 | ->execute() |
| 213 | ->first(); |
| 214 | |
| 215 | $this->assertArrayHasKey('id', $createResult, "create missing ID"); |
| 216 | $id = $createResult['id']; |
| 217 | |
| 218 | $this->assertGreaterThanOrEqual(1, $id, "$entity ID not positive"); |
| 219 | |
| 220 | return $id; |
| 221 | } |
| 222 | |
| 223 | /** |
| 224 | * @param \Civi\Api4\Generic\AbstractEntity|string $entityClass |
| 225 | * @param int $id |
| 226 | */ |
| 227 | protected function checkUpdateFailsFromCreate($entityClass, $id): void { |
| 228 | $exceptionThrown = ''; |
| 229 | try { |
| 230 | $entityClass::create(FALSE) |
| 231 | ->addValue('id', $id) |
| 232 | ->execute(); |
| 233 | } |
| 234 | catch (\API_Exception $e) { |
| 235 | $exceptionThrown = $e->getMessage(); |
| 236 | } |
| 237 | $this->assertStringContainsString('id', $exceptionThrown); |
| 238 | } |
| 239 | |
| 240 | /** |
| 241 | * @param \Civi\Api4\Generic\AbstractEntity|string $entityClass |
| 242 | * @param int $id |
| 243 | * @param string $entity |
| 244 | */ |
| 245 | protected function checkGet($entityClass, $id, $entity) { |
| 246 | $getResult = $entityClass::get(FALSE) |
| 247 | ->addWhere('id', '=', $id) |
| 248 | ->execute(); |
| 249 | |
| 250 | $errMsg = sprintf('Failed to fetch a %s after creation', $entity); |
| 251 | $this->assertEquals($id, $getResult->first()['id'], $errMsg); |
| 252 | $this->assertEquals(1, $getResult->count(), $errMsg); |
| 253 | } |
| 254 | |
| 255 | /** |
| 256 | * @param \Civi\Api4\Generic\AbstractEntity|string $entityClass |
| 257 | * @param int $id |
| 258 | * @param string $entity |
| 259 | */ |
| 260 | protected function checkGetCount($entityClass, $id, $entity): void { |
| 261 | $getResult = $entityClass::get(FALSE) |
| 262 | ->addWhere('id', '=', $id) |
| 263 | ->selectRowCount() |
| 264 | ->execute(); |
| 265 | $errMsg = sprintf('%s getCount failed', $entity); |
| 266 | $this->assertEquals(1, $getResult->count(), $errMsg); |
| 267 | |
| 268 | $getResult = $entityClass::get(FALSE) |
| 269 | ->selectRowCount() |
| 270 | ->execute(); |
| 271 | $errMsg = sprintf('%s getCount failed', $entity); |
| 272 | $this->assertGreaterThanOrEqual(1, $getResult->count(), $errMsg); |
| 273 | } |
| 274 | |
| 275 | /** |
| 276 | * @param \Civi\Api4\Generic\AbstractEntity|string $entityClass |
| 277 | */ |
| 278 | protected function checkDeleteWithNoId($entityClass) { |
| 279 | $exceptionThrown = ''; |
| 280 | try { |
| 281 | $entityClass::delete() |
| 282 | ->execute(); |
| 283 | } |
| 284 | catch (\API_Exception $e) { |
| 285 | $exceptionThrown = $e->getMessage(); |
| 286 | } |
| 287 | $this->assertStringContainsString('required', $exceptionThrown); |
| 288 | } |
| 289 | |
| 290 | /** |
| 291 | * @param \Civi\Api4\Generic\AbstractEntity|string $entityClass |
| 292 | */ |
| 293 | protected function checkWrongParamType($entityClass) { |
| 294 | $exceptionThrown = ''; |
| 295 | try { |
| 296 | $entityClass::get() |
| 297 | ->setDebug('not a bool') |
| 298 | ->execute(); |
| 299 | } |
| 300 | catch (\API_Exception $e) { |
| 301 | $exceptionThrown = $e->getMessage(); |
| 302 | } |
| 303 | $this->assertStringContainsString('debug', $exceptionThrown); |
| 304 | $this->assertStringContainsString('type', $exceptionThrown); |
| 305 | } |
| 306 | |
| 307 | /** |
| 308 | * @param \Civi\Api4\Generic\AbstractEntity|string $entityClass |
| 309 | * @param int $id |
| 310 | */ |
| 311 | protected function checkDeletion($entityClass, $id) { |
| 312 | $deleteResult = $entityClass::delete(FALSE) |
| 313 | ->addWhere('id', '=', $id) |
| 314 | ->execute(); |
| 315 | |
| 316 | // should get back an array of deleted id |
| 317 | $this->assertEquals([['id' => $id]], (array) $deleteResult); |
| 318 | } |
| 319 | |
| 320 | /** |
| 321 | * @param \Civi\Api4\Generic\AbstractEntity|string $entityClass |
| 322 | * @param int $id |
| 323 | * @param string $entity |
| 324 | */ |
| 325 | protected function checkPostDelete($entityClass, $id, $entity) { |
| 326 | $getDeletedResult = $entityClass::get(FALSE) |
| 327 | ->addWhere('id', '=', $id) |
| 328 | ->execute(); |
| 329 | |
| 330 | $errMsg = sprintf('Entity "%s" was not deleted', $entity); |
| 331 | $this->assertEquals(0, count($getDeletedResult), $errMsg); |
| 332 | } |
| 333 | |
| 334 | /** |
| 335 | * @param array $names |
| 336 | * List of entity names. |
| 337 | * Ex: ['Foo', 'Bar'] |
| 338 | * @return array |
| 339 | * List of data-provider arguments, one for each entity-name. |
| 340 | * Ex: ['Foo' => ['Foo'], 'Bar' => ['Bar']] |
| 341 | */ |
| 342 | protected function toDataProviderArray($names) { |
| 343 | sort($names); |
| 344 | |
| 345 | $result = []; |
| 346 | foreach ($names as $name) { |
| 347 | $result[$name] = [$name]; |
| 348 | } |
| 349 | return $result; |
| 350 | } |
| 351 | |
| 352 | } |