tests/events/*.php - Enforce general compliance with hook/event signatures

CRM/Utils/System/UnitTests.php

@@ -34,6 +34,7 @@ public function initialize() {
       $listenerMap = \Civi\Core\Event\EventScanner::findListeners($test);
       \Civi::dispatcher()->addListenerMap($test, $listenerMap);
     }
+    \Civi\Test::eventChecker()->addListeners();
   }
 
   /**

Civi/Test.php

@@ -212,6 +212,16 @@ public static function example(string $name): array {
     return $result['data'];
   }
 
+  /**
+   * @return \Civi\Test\EventChecker
+   */
+  public static function eventChecker() {
+    if (!isset(self::$singletons['eventChecker'])) {
+      self::$singletons['eventChecker'] = new \Civi\Test\EventChecker();
+    }
+    return self::$singletons['eventChecker'];
+  }
+
   /**
    * Prepare and execute a batch of SQL statements.
    *

Civi/Test/CiviTestListener.php

@@ -65,9 +65,24 @@ public function startTest(\PHPUnit\Framework\Test $test) {
       else {
         $this->tx = NULL;
       }
+
+      if ($this->isCiviTest($test) || $test instanceof \CiviUnitTestCase) {
+        \Civi\Test::eventChecker()->start($test);
+      }
     }
 
     public function endTest(\PHPUnit\Framework\Test $test, $time) {
+      $exception = NULL;
+
+      if ($this->isCiviTest($test) || $test instanceof \CiviUnitTestCase) {
+        try {
+          \Civi\Test::eventChecker()->stop($test);
+        }
+        catch (\Exception $e) {
+          $exception = $e;
+        }
+      }
+
       if ($test instanceof TransactionalInterface) {
         $this->tx->rollback()->commit();
         $this->tx = NULL;
@@ -81,6 +96,10 @@ public function endTest(\PHPUnit\Framework\Test $test, $time) {
         error_reporting(E_ALL & ~E_NOTICE);
         $this->errorScope = NULL;
       }
+
+      if ($exception) {
+        throw $exception;
+      }
     }
 
     /**

Civi/Test/CiviTestListenerPHPUnit7.php

@@ -57,9 +57,24 @@ public function startTest(\PHPUnit\Framework\Test $test): void {
     else {
       $this->tx = NULL;
     }
+
+    if ($this->isCiviTest($test) || $test instanceof \CiviUnitTestCase) {
+      \Civi\Test::eventChecker()->start($test);
+    }
   }
 
   public function endTest(\PHPUnit\Framework\Test $test, float $time): void {
+    $exception = NULL;
+
+    if ($this->isCiviTest($test) || $test instanceof \CiviUnitTestCase) {
+      try {
+        \Civi\Test::eventChecker()->stop($test);
+      }
+      catch (\Exception $e) {
+        $exception = $e;
+      }
+    }
+
     if ($test instanceof TransactionalInterface) {
       $this->tx->rollback()->commit();
       $this->tx = NULL;
@@ -73,6 +88,10 @@ public function endTest(\PHPUnit\Framework\Test $test, float $time): void {
       error_reporting(E_ALL & ~E_NOTICE);
       $this->errorScope = NULL;
     }
+
+    if ($exception) {
+      throw $exception;
+    }
   }
 
   /**

Civi/Test/EventCheck.php

@@ -0,0 +1,81 @@
+<?php
+/*
+ +--------------------------------------------------------------------+
+ | Copyright CiviCRM LLC. All rights reserved.                        |
+ |                                                                    |
+ | This work is published under the GNU AGPLv3 license with some      |
+ | permitted exceptions and without any warranty. For full license    |
+ | and copyright information, see https://civicrm.org/licensing       |
+ +--------------------------------------------------------------------+
+ */
+
+namespace Civi\Test;
+
+use PHPUnit\Framework\Assert;
+
+/**
+ * An EventCheck is a fragment of a unit-test -- it is mixed into
+ * various test-scenarios and applies extra assertions.
+ */
+class EventCheck extends Assert {
+
+  /**
+   * @var \PHPUnit\Framework\Test
+   */
+  private $test;
+
+  /**
+   * Determine whether this check should be used during the current test.
+   *
+   * @param \PHPUnit\Framework\Test|NULL $test
+   *
+   * @return bool|string
+   *   FALSE: The check will be completely skipped.
+   *   TRUE: The check will be enabled. However, if the events never
+   *         execute, that is OK. Useful for general compliance-testing.
+   */
+  public function isSupported($test) {
+    return TRUE;
+  }
+
+  /**
+   * @return \PHPUnit\Framework\Test|NULL
+   */
+  public function getTest() {
+    return $this->test;
+  }
+
+  /**
+   * @param \PHPUnit\Framework\Test|NULL $test
+   */
+  public function setTest($test): void {
+    $this->test = $test;
+  }
+
+  /**
+   * Assert that a variable has a given type.
+   *
+   * @param string|string[] $types
+   *   List of types, per `gettype()` or `get_class()`
+   *   Ex: 'int|string|NULL'
+   *   Ex: [`array`, `NULL`, `CRM_Core_DAO`]
+   * @param mixed $value
+   *   The variable to check
+   * @param string|NULL $msg
+   * @see \CRM_Utils_Type::validatePhpType
+   */
+  public function assertType($types, $value, ?string $msg = NULL) {
+    if (!\CRM_Utils_Type::validatePhpType($value, $types, FALSE)) {
+      $defactoType = is_object($value) ? get_class($value) : gettype($value);
+      $types = is_array($types) ? implode('|', $types) : $types;
+      $this->fail(sprintf("Expected one of (%s) but found %s\n%s", $types, $defactoType, $msg));
+    }
+  }
+
+  public function setUp() {
+  }
+
+  public function tearDown() {
+  }
+
+}

Civi/Test/EventChecker.php

@@ -0,0 +1,106 @@
+<?php
+/*
+ +--------------------------------------------------------------------+
+ | Copyright CiviCRM LLC. All rights reserved.                        |
+ |                                                                    |
+ | This work is published under the GNU AGPLv3 license with some      |
+ | permitted exceptions and without any warranty. For full license    |
+ | and copyright information, see https://civicrm.org/licensing       |
+ +--------------------------------------------------------------------+
+ */
+
+namespace Civi\Test;
+
+use Civi\Core\Event\EventScanner;
+
+class EventChecker {
+
+  /**
+   * @var \Civi\Test\EventCheck[]|null
+   */
+  private $allChecks = NULL;
+
+  /**
+   * @var \Civi\Test\EventCheck[]|null
+   */
+  private $activeChecks = NULL;
+
+  /**
+   * @param \PHPUnit\Framework\Test $test
+   *
+   * @return $this
+   */
+  public function start(\PHPUnit\Framework\Test $test) {
+    if ($this->activeChecks === NULL) {
+      $this->activeChecks = [];
+      foreach ($this->findAll() as $template) {
+        /** @var EventCheck $template */
+        if ($template->isSupported($test)) {
+          $checker = clone $template;
+          $checker->setTest($test);
+          $this->activeChecks[] = $checker;
+          $checker->setUp();
+        }
+      }
+    }
+    return $this;
+  }
+
+  /**
+   * @return $this
+   */
+  public function addListeners() {
+    $d = \Civi::dispatcher();
+    foreach ($this->activeChecks ?: [] as $checker) {
+      /** @var EventCheck $checker */
+      $d->addListenerMap($checker, EventScanner::findListeners($checker));
+      // For the moment, KISS. But we may want a counter at some point - to ensure things actually run.
+      //foreach (EventScanner::findListeners($checker) as $event => $listeners) {
+      //  foreach ($listeners as $listener) {
+      //    $d->addListener($event,
+      //      function($args...) use ($listener) {
+      //        $count++;
+      //        $m = $listener[1];
+      //        $checker->$m(...$args);
+      //      },
+      //      $listener[1] ?? 0
+      //    );
+      //  }
+      //}
+    }
+    return $this;
+  }
+
+  /**
+   * @return $this
+   */
+  public function stop() {
+    // NOTE: In test environment, dispatcher will be removed regardless.
+    foreach ($this->activeChecks ?? [] as $checker) {
+      /** @var \Civi\Test\EventCheck $checker */
+      Invasive::call([$checker, 'tearDown']);
+      $checker->setTest(NULL);
+    }
+    $this->activeChecks = NULL;
+    return $this;
+  }
+
+  /**
+   * @return EventCheck[]
+   */
+  protected function findAll() {
+    if ($this->allChecks === NULL) {
+      $all = [];
+      $testDir = \Civi::paths()->getPath('[civicrm.root]/tests/events');
+      $files = \CRM_Utils_File::findFiles($testDir, '*.evch.php', TRUE);
+      sort($files);
+      foreach ($files as $file) {
+        $all[$file] = require $testDir . '/' . $file;
+      }
+      $this->allChecks = $all;
+    }
+
+    return $this->allChecks;
+  }
+
+}

Civi/Test/Legacy/CiviTestListener.php

@@ -55,9 +55,24 @@ public function startTest(\PHPUnit_Framework_Test $test) {
     else {
       $this->tx = NULL;
     }
+
+    if ($this->isCiviTest($test) || $test instanceof \CiviUnitTestCase) {
+      \Civi\Test::eventChecker()->start($test);
+    }
   }
 
   public function endTest(\PHPUnit_Framework_Test $test, $time) {
+    $exception = NULL;
+
+    if ($this->isCiviTest($test) || $test instanceof \CiviUnitTestCase) {
+      try {
+        \Civi\Test::eventChecker()->stop($test);
+      }
+      catch (\Exception $e) {
+        $exception = $e;
+      }
+    }
+
     if ($test instanceof \Civi\Test\TransactionalInterface) {
       $this->tx->rollback()->commit();
       $this->tx = NULL;
@@ -71,6 +86,10 @@ public function endTest(\PHPUnit_Framework_Test $test, $time) {
       error_reporting(E_ALL & ~E_NOTICE);
       $this->errorScope = NULL;
     }
+
+    if ($exception) {
+      throw $exception;
+    }
   }
 
   /**

tests/events/civi_region_render.evch.php

@@ -0,0 +1,33 @@
+<?php
+return new class() extends \Civi\Test\EventCheck implements \Civi\Test\HookInterface {
+
+  private $validSnippetTypes = [
+    'callback',
+    'jquery',
+    'markup',
+    'script',
+    'scriptFile',
+    'scriptUrl',
+    'settings',
+    'style',
+    'styleFile',
+    'styleUrl',
+    'template',
+  ];
+
+  private $validRegion = '/^[A-Za-z0-9\\-]+$/';
+
+  /**
+   * Ensure that the hook data is always well-formed.
+   */
+  public function on_civi_region_render(\Civi\Core\Event\GenericHookEvent $e) {
+    $this->assertTrue($e->region instanceof \CRM_Core_Region);
+    /** @var \CRM_Core_Region $region */
+    $region = $e->region;
+    $this->assertRegexp($this->validRegion, $region->_name);
+    foreach ($region->getAll() as $snippet) {
+      $this->assertContains($snippet['type'], $this->validSnippetTypes);
+    }
+  }
+
+};