Civi/Test/CiviTestListener.php

   1 <?php
   2
   3 namespace Civi\Test;
   4
   5 if (class_exists('PHPUnit_Runner_Version') && version_compare(\PHPUnit_Runner_Version::id(), '6.0.0', '<')) {
   6   class_alias('Civi\Test\Legacy\CiviTestListener', 'Civi\Test\CiviTestListener');
   7   // Using an early return instead of a else does not work when using the PHPUnit phar due to some weird PHP behavior (the class
   8   // gets defined without executing the code before it and so the definition is not properly conditional)
   9 }
  10 else {
  11
  12   /**
  13    * Class CiviTestListener
  14    * @package Civi\Test
  15    *
  16    * CiviTestListener participates in test-execution, looking for test-classes
  17    * which have certain tags. If the tags are found, the listener will perform
  18    * additional setup/teardown logic.
  19    *
  20    * @see EndToEndInterface
  21    * @see HeadlessInterface
  22    * @see HookInterface
  23    */
  24   class CiviTestListener extends \PHPUnit\Framework\BaseTestListener {
  25     /**
  26      * @var \CRM_Core_TemporaryErrorScope
  27      */
  28     private $errorScope;
  29
  30     /**
  31      * @var array
  32      *  Ex: $cache['Some_Test_Class']['civicrm_foobar'] = 'hook_civicrm_foobar';
  33      *  Array(string $testClass => Array(string $hookName => string $methodName)).
  34      */
  35     private $cache = [];
  36
  37     /**
  38      * @var \CRM_Core_Transaction|NULL
  39      */
  40     private $tx;
  41
  42     public function startTestSuite(\PHPUnit\Framework\TestSuite $suite) {
  43       $byInterface = $this->indexTestsByInterface($suite->tests());
  44       $this->validateGroups($byInterface);
  45       $this->autoboot($byInterface);
  46     }
  47
  48     public function endTestSuite(\PHPUnit\Framework\TestSuite $suite) {
  49       $this->cache = [];
  50     }
  51
  52     public function startTest(\PHPUnit\Framework\Test $test) {
  53       if ($this->isCiviTest($test)) {
  54         error_reporting(E_ALL);
  55         $this->errorScope = \CRM_Core_TemporaryErrorScope::useException();
  56       }
  57
  58       if ($test instanceof HeadlessInterface) {
  59         $this->bootHeadless($test);
  60       }
  61
  62       if ($test instanceof HookInterface) {
  63         // Note: bootHeadless() indirectly resets any hooks, which means that hook_civicrm_config
  64         // is unsubscribable. However, after bootHeadless(), we're free to subscribe to hooks again.
  65         $this->registerHooks($test);
  66       }
  67
  68       if ($test instanceof TransactionalInterface) {
  69         $this->tx = new \CRM_Core_Transaction(TRUE);
  70         $this->tx->rollback();
  71       }
  72       else {
  73         $this->tx = NULL;
  74       }
  75     }
  76
  77     public function endTest(\PHPUnit\Framework\Test $test, $time) {
  78       if ($test instanceof TransactionalInterface) {
  79         $this->tx->rollback()->commit();
  80         $this->tx = NULL;
  81       }
  82       if ($test instanceof HookInterface) {
  83         \CRM_Utils_Hook::singleton()->reset();
  84       }
  85       if ($this->isCiviTest($test)) {
  86         error_reporting(E_ALL & ~E_NOTICE);
  87         $this->errorScope = NULL;
  88       }
  89     }
  90
  91     /**
  92      * @param HeadlessInterface|\PHPUnit\Framework\Test $test
  93      */
  94     protected function bootHeadless($test) {
  95       if (CIVICRM_UF !== 'UnitTests') {
  96         throw new \RuntimeException('HeadlessInterface requires CIVICRM_UF=UnitTests');
  97       }
  98
  99       // Hrm, this seems wrong. Shouldn't we be resetting the entire session?
 100       $session = \CRM_Core_Session::singleton();
 101       $session->set('userID', NULL);
 102
 103       $test->setUpHeadless();
 104
 105       \CRM_Utils_System::flushCache();
 106       \Civi::reset();
 107       \CRM_Core_Session::singleton()->set('userID', NULL);
 108       // ugh, performance
 109       $config = \CRM_Core_Config::singleton(TRUE, TRUE);
 110
 111       if (property_exists($config->userPermissionClass, 'permissions')) {
 112         $config->userPermissionClass->permissions = NULL;
 113       }
 114     }
 115
 116     /**
 117      * @param \Civi\Test\HookInterface $test
 118      * @return array
 119      *   Array(string $hookName => string $methodName)).
 120      */
 121     protected function findTestHooks(HookInterface $test) {
 122       $class = get_class($test);
 123       if (!isset($this->cache[$class])) {
 124         $funcs = [];
 125         foreach (get_class_methods($class) as $func) {
 126           if (preg_match('/^hook_/', $func)) {
 127             $funcs[substr($func, 5)] = $func;
 128           }
 129         }
 130         $this->cache[$class] = $funcs;
 131       }
 132       return $this->cache[$class];
 133     }
 134
 135     /**
 136      * @param \PHPUnit\Framework\Test $test
 137      * @return bool
 138      */
 139     protected function isCiviTest(\PHPUnit\Framework\Test $test) {
 140       return $test instanceof HookInterface || $test instanceof HeadlessInterface;
 141     }
 142
 143     /**
 144      * Find any hook functions in $test and register them.
 145      *
 146      * @param \Civi\Test\HookInterface $test
 147      */
 148     protected function registerHooks(HookInterface $test) {
 149       if (CIVICRM_UF !== 'UnitTests') {
 150         // This is not ideal -- it's just a side-effect of how hooks and E2E tests work.
 151         // We can temporarily subscribe to hooks in-process, but for other processes, it gets messy.
 152         throw new \RuntimeException('CiviHookTestInterface requires CIVICRM_UF=UnitTests');
 153       }
 154       \CRM_Utils_Hook::singleton()->reset();
 155       /** @var \CRM_Utils_Hook_UnitTests $hooks */
 156       $hooks = \CRM_Utils_Hook::singleton();
 157       foreach ($this->findTestHooks($test) as $hook => $func) {
 158         $hooks->setHook($hook, [$test, $func]);
 159       }
 160     }
 161
 162     /**
 163      * The first time we come across HeadlessInterface or EndToEndInterface, we'll
 164      * try to autoboot.
 165      *
 166      * Once the system is booted, there's nothing we can do -- we're stuck with that
 167      * environment. (Thank you, prolific define()s!) If there's a conflict between a
 168      * test-class and the active boot-level, then we'll have to bail.
 169      *
 170      * @param array $byInterface
 171      *   List of test classes, keyed by major interface (HeadlessInterface vs EndToEndInterface).
 172      */
 173     protected function autoboot($byInterface) {
 174       if (defined('CIVICRM_UF')) {
 175         // OK, nothing we can do. System has booted already.
 176       }
 177       elseif (!empty($byInterface['HeadlessInterface'])) {
 178         putenv('CIVICRM_UF=UnitTests');
 179       // phpcs:disable
 180       eval($this->cv('php:boot --level=full', 'phpcode'));
 181       // phpcs:enable
 182       }
 183       elseif (!empty($byInterface['EndToEndInterface'])) {
 184         putenv('CIVICRM_UF=');
 185       // phpcs:disable
 186       eval($this->cv('php:boot --level=full', 'phpcode'));
 187       // phpcs:enable
 188       }
 189
 190       $blurb = "Tip: Run the headless tests and end-to-end tests separately, e.g.\n"
 191       . "  $ phpunit5 --group headless\n"
 192       . "  $ phpunit5 --group e2e  \n";
 193
 194       if (!empty($byInterface['HeadlessInterface']) && CIVICRM_UF !== 'UnitTests') {
 195         $testNames = implode(', ', array_keys($byInterface['HeadlessInterface']));
 196         throw new \RuntimeException("Suite includes headless tests ($testNames) which require CIVICRM_UF=UnitTests.\n\n$blurb");
 197       }
 198       if (!empty($byInterface['EndToEndInterface']) && CIVICRM_UF === 'UnitTests') {
 199         $testNames = implode(', ', array_keys($byInterface['EndToEndInterface']));
 200         throw new \RuntimeException("Suite includes end-to-end tests ($testNames) which do not support CIVICRM_UF=UnitTests.\n\n$blurb");
 201       }
 202     }
 203
 204     /**
 205      * Call the "cv" command.
 206      *
 207      * This duplicates the standalone `cv()` wrapper that is recommended in bootstrap.php.
 208      * This duplication is necessary because `cv()` is optional, and downstream implementers
 209      * may alter, rename, or omit the wrapper, and (by virtue of its role in bootstrap) there
 210      * it is impossible to define it centrally.
 211      *
 212      * @param string $cmd
 213      *   The rest of the command to send.
 214      * @param string $decode
 215      *   Ex: 'json' or 'phpcode'.
 216      * @return string
 217      *   Response output (if the command executed normally).
 218      * @throws \RuntimeException
 219      *   If the command terminates abnormally.
 220      */
 221     protected function cv($cmd, $decode = 'json') {
 222       $cmd = 'cv ' . $cmd;
 223       $descriptorSpec = [0 => ["pipe", "r"], 1 => ["pipe", "w"], 2 => STDERR];
 224       $oldOutput = getenv('CV_OUTPUT');
 225       putenv("CV_OUTPUT=json");
 226       $process = proc_open($cmd, $descriptorSpec, $pipes, __DIR__);
 227       putenv("CV_OUTPUT=$oldOutput");
 228       fclose($pipes[0]);
 229       $result = stream_get_contents($pipes[1]);
 230       fclose($pipes[1]);
 231       if (proc_close($process) !== 0) {
 232         throw new \RuntimeException("Command failed ($cmd):\n$result");
 233       }
 234       switch ($decode) {
 235         case 'raw':
 236           return $result;
 237
 238         case 'phpcode':
 239           // If the last output is /*PHPCODE*/, then we managed to complete execution.
 240           if (substr(trim($result), 0, 12) !== "/*BEGINPHP*/" || substr(trim($result), -10) !== "/*ENDPHP*/") {
 241             throw new \RuntimeException("Command failed ($cmd):\n$result");
 242           }
 243           return $result;
 244
 245         case 'json':
 246           return json_decode($result, 1);
 247
 248         default:
 249           throw new \RuntimeException("Bad decoder format ($decode)");
 250       }
 251     }
 252
 253     /**
 254      * @param $tests
 255      * @return array
 256      */
 257     protected function indexTestsByInterface($tests) {
 258       $byInterface = ['HeadlessInterface' => [], 'EndToEndInterface' => []];
 259       foreach ($tests as $test) {
 260         /** @var \PHPUnit\Framework\Test $test */
 261         if ($test instanceof HeadlessInterface) {
 262           $byInterface['HeadlessInterface'][get_class($test)] = 1;
 263         }
 264         if ($test instanceof EndToEndInterface) {
 265           $byInterface['EndToEndInterface'][get_class($test)] = 1;
 266         }
 267       }
 268       return $byInterface;
 269     }
 270
 271     /**
 272      * Ensure that any tests have sensible groups, e.g.
 273      *
 274      * `HeadlessInterface` ==> `group headless`
 275      * `EndToEndInterface` ==> `group e2e`
 276      *
 277      * @param array $byInterface
 278      */
 279     protected function validateGroups($byInterface) {
 280       foreach ($byInterface['HeadlessInterface'] as $className => $nonce) {
 281         $clazz = new \ReflectionClass($className);
 282         $docComment = str_replace("\r\n", "\n", $clazz->getDocComment());
 283         if (strpos($docComment, "@group headless\n") === FALSE) {
 284           echo "WARNING: Class $className implements HeadlessInterface. It should declare \"@group headless\".\n";
 285         }
 286         if (strpos($docComment, "@group e2e\n") !== FALSE) {
 287           echo "WARNING: Class $className implements HeadlessInterface. It should not declare \"@group e2e\".\n";
 288         }
 289       }
 290       foreach ($byInterface['EndToEndInterface'] as $className => $nonce) {
 291         $clazz = new \ReflectionClass($className);
 292         $docComment = str_replace("\r\n", "\n", $clazz->getDocComment());
 293         if (strpos($docComment, "@group e2e\n") === FALSE) {
 294           echo "WARNING: Class $className implements EndToEndInterface. It should declare \"@group e2e\".\n";
 295         }
 296         if (strpos($docComment, "@group headless\n") !== FALSE) {
 297           echo "WARNING: Class $className implements EndToEndInterface. It should not declare \"@group headless\".\n";
 298         }
 299       }
 300     }
 301
 302   }
 303 }