trait AssertPreconditionsTrait

trait AssertPreconditionsTrait {
  
  /**
   * Invokes the test preconditions assertion before the first test is run.
   *
   * "Use" this trait on any Package Manager test class that directly extends a
   * Core test class, i.e., any class that does NOT extend a test class in a
   * Package Manager test namespace. If that class implements this method, too,
   * be sure to call this first thing in it.
   */
  public static function setUpBeforeClass() : void {
    parent::setUpBeforeClass();
    static::failIfUnmetPreConditions('before');
  }
  
  /**
   * Invokes the test preconditions assertion after each test run.
   *
   * This ensures that no test method leaves behind violations of test
   * preconditions. This makes it trivial to discover broken tests.
   */
  protected function tearDown() : void {
    parent::tearDown();
    static::failIfUnmetPreConditions('after');
  }
  
  /**
   * Asserts universal test preconditions before any setup is done.
   *
   * If these preconditions aren't met, automated tests will absolutely fail
   * needlessly with misleading errors. In that case, there's no reason to even
   * begin.
   *
   * Ordinarily, these preconditions would be asserted in
   * ::assertPreConditions(), which PHPUnit provides for exactly this use case.
   * Unfortunately, that method doesn't run until after ::setUp(), so our (many)
   * tests with expensive, time-consuming setup routines wouldn't actually fail
   * very early.
   *
   * @param string $when
   *   Either 'before' (before any test methods run) or 'after' (after any test
   *   method finishes).
   *
   * @see \PHPUnit\Framework\TestCase::assertPreConditions()
   * @see \PHPUnit\Framework\TestCase::setUpBeforeClass()
   * @see self::setupBeforeClass()
   * @see self::tearDown()
   */
  protected static function failIfUnmetPreConditions(string $when) : void {
    assert(in_array($when, [
      'before',
      'after',
    ], TRUE));
    static::assertNoFailureMarker($when);
  }
  
  /**
   * Asserts that there is no failure marker present.
   *
   * @param string $when
   *   Either 'before' (before any test methods run) or 'after' (after any test
   *   method finishes).
   *
   * @see \Drupal\package_manager\FailureMarker
   */
  private static function assertNoFailureMarker(string $when) : void {
    // If the failure marker exists, it will be in the project root. The project
    // root is defined as the directory containing the `vendor` directory.
    // @see \Drupal\package_manager\FailureMarker::getPath()
    $failure_marker = static::getProjectRoot() . '/PACKAGE_MANAGER_FAILURE.yml';
    if (file_exists($failure_marker)) {
      $suffix = $when === 'before' ? 'Remove it to continue.' : 'This test method created this marker but failed to clean up after itself.';
      static::fail("The failure marker '{$failure_marker}' is present in the project. {$suffix}");
    }
  }
  
  /**
   * Returns the absolute path of the project root.
   *
   * @return string
   *   The absolute path of the project root.
   *
   * @see \Drupal\package_manager\PathLocator::getProjectRoot()
   */
  private static function getProjectRoot() : string {
    // This is tricky, because this method has to be static (since
    // ::setUpBeforeClass is), so it can't just get the container from an
    // instance member.
    // Use reflection to extract the vendor directory from the class loader.
    $class_loaders = ClassLoader::getRegisteredLoaders();
    $vendor_directory = key($class_loaders);
    return dirname($vendor_directory);
  }

}