ExternalCommandRequirementsTrait.php in Drupal 9

Namespace

Drupal\BuildTests\Framework

File

core/tests/Drupal/BuildTests/Framework/ExternalCommandRequirementsTrait.php

<?php

namespace Drupal\BuildTests\Framework;

use PHPUnit\Framework\SkippedTestError;
use PHPUnit\Util\Test;
use Symfony\Component\Process\ExecutableFinder;

/**
 * Allows test classes to require external command line applications.
 *
 * Use annotation such as '(at)requires externalCommand git'.
 */
trait ExternalCommandRequirementsTrait {

  /**
   * A list of existing external commands we've already discovered.
   *
   * @var string[]
   */
  private static $existingCommands = [];

  /**
   * Checks whether required external commands are available per test class.
   *
   * @throws \PHPUnit\Framework\SkippedTestError
   *   Thrown when the requirements are not met, and this test should be
   *   skipped. Callers should not catch this exception.
   */
  private static function checkClassCommandRequirements() {
    $annotations = Test::parseTestMethodAnnotations(static::class);
    if (!empty($annotations['class']['requires'])) {
      static::checkExternalCommandRequirements($annotations['class']['requires']);
    }
  }

  /**
   * Checks whether required external commands are available per method.
   *
   * @throws \PHPUnit\Framework\SkippedTestError
   *   Thrown when the requirements are not met, and this test should be
   *   skipped. Callers should not catch this exception.
   */
  private static function checkMethodCommandRequirements($name) {
    $annotations = Test::parseTestMethodAnnotations(static::class, $name);
    if (!empty($annotations['method']['requires'])) {
      static::checkExternalCommandRequirements($annotations['method']['requires']);
    }
  }

  /**
   * Checks missing external command requirements.
   *
   * @param string[] $annotations
   *   A list of requires annotations from either a method or class annotation.
   *
   * @throws \PHPUnit\Framework\SkippedTestError
   *   Thrown when the requirements are not met, and this test should be
   *   skipped. Callers should not catch this exception.
   */
  private static function checkExternalCommandRequirements(array $annotations) {

    // Make a list of required commands.
    $required_commands = [];
    foreach ($annotations as $requirement) {
      if (strpos($requirement, 'externalCommand ') === 0) {
        $command = trim(str_replace('externalCommand ', '', $requirement));

        // Use named keys to avoid duplicates.
        $required_commands[$command] = $command;
      }
    }

    // Figure out which commands are not available.
    $unavailable = [];
    foreach ($required_commands as $required_command) {
      if (!in_array($required_command, self::$existingCommands)) {
        if (static::externalCommandIsAvailable($required_command)) {

          // Cache existing commands so we don't have to ask again.
          self::$existingCommands[] = $required_command;
        }
        else {
          $unavailable[] = $required_command;
        }
      }
    }

    // Skip the test if there were some we couldn't find.
    if (!empty($unavailable)) {
      throw new SkippedTestError('Required external commands: ' . implode(', ', $unavailable));
    }
  }

  /**
   * Determine if an external command is available.
   *
   * @param $command
   *   The external command.
   *
   * @return bool
   *   TRUE if external command is available, else FALSE.
   */
  private static function externalCommandIsAvailable($command) {
    $finder = new ExecutableFinder();
    return (bool) $finder
      ->find($command);
  }

}

Traits

Name	Description
ExternalCommandRequirementsTrait	Allows test classes to require external command line applications.