aleph1.co.uk Git - yaffs-website/blob - vendor/phpunit/phpunit/src/Framework/Constraint.php

   1 <?php
   2 /*
   3  * This file is part of PHPUnit.
   4  *
   5  * (c) Sebastian Bergmann <sebastian@phpunit.de>
   6  *
   7  * For the full copyright and license information, please view the LICENSE
   8  * file that was distributed with this source code.
   9  */
  10
  11 use SebastianBergmann\Exporter\Exporter;
  12
  13 /**
  14  * Abstract base class for constraints which can be applied to any value.
  15  *
  16  * @since Interface available since Release 3.0.0
  17  */
  18 abstract class PHPUnit_Framework_Constraint implements Countable, PHPUnit_Framework_SelfDescribing
  19 {
  20     protected $exporter;
  21
  22     public function __construct()
  23     {
  24         $this->exporter = new Exporter;
  25     }
  26
  27     /**
  28      * Evaluates the constraint for parameter $other
  29      *
  30      * If $returnResult is set to false (the default), an exception is thrown
  31      * in case of a failure. null is returned otherwise.
  32      *
  33      * If $returnResult is true, the result of the evaluation is returned as
  34      * a boolean value instead: true in case of success, false in case of a
  35      * failure.
  36      *
  37      * @param mixed  $other        Value or object to evaluate.
  38      * @param string $description  Additional information about the test
  39      * @param bool   $returnResult Whether to return a result or throw an exception
  40      *
  41      * @return mixed
  42      *
  43      * @throws PHPUnit_Framework_ExpectationFailedException
  44      */
  45     public function evaluate($other, $description = '', $returnResult = false)
  46     {
  47         $success = false;
  48
  49         if ($this->matches($other)) {
  50             $success = true;
  51         }
  52
  53         if ($returnResult) {
  54             return $success;
  55         }
  56
  57         if (!$success) {
  58             $this->fail($other, $description);
  59         }
  60     }
  61
  62     /**
  63      * Evaluates the constraint for parameter $other. Returns true if the
  64      * constraint is met, false otherwise.
  65      *
  66      * This method can be overridden to implement the evaluation algorithm.
  67      *
  68      * @param mixed $other Value or object to evaluate.
  69      *
  70      * @return bool
  71      */
  72     protected function matches($other)
  73     {
  74         return false;
  75     }
  76
  77     /**
  78      * Counts the number of constraint elements.
  79      *
  80      * @return int
  81      *
  82      * @since  Method available since Release 3.4.0
  83      */
  84     public function count()
  85     {
  86         return 1;
  87     }
  88
  89     /**
  90      * Throws an exception for the given compared value and test description
  91      *
  92      * @param mixed                                          $other             Evaluated value or object.
  93      * @param string                                         $description       Additional information about the test
  94      * @param SebastianBergmann\Comparator\ComparisonFailure $comparisonFailure
  95      *
  96      * @throws PHPUnit_Framework_ExpectationFailedException
  97      */
  98     protected function fail($other, $description, SebastianBergmann\Comparator\ComparisonFailure $comparisonFailure = null)
  99     {
 100         $failureDescription = sprintf(
 101             'Failed asserting that %s.',
 102             $this->failureDescription($other)
 103         );
 104
 105         $additionalFailureDescription = $this->additionalFailureDescription($other);
 106
 107         if ($additionalFailureDescription) {
 108             $failureDescription .= "\n" . $additionalFailureDescription;
 109         }
 110
 111         if (!empty($description)) {
 112             $failureDescription = $description . "\n" . $failureDescription;
 113         }
 114
 115         throw new PHPUnit_Framework_ExpectationFailedException(
 116             $failureDescription,
 117             $comparisonFailure
 118         );
 119     }
 120
 121     /**
 122      * Return additional failure description where needed
 123      *
 124      * The function can be overridden to provide additional failure
 125      * information like a diff
 126      *
 127      * @param mixed $other Evaluated value or object.
 128      *
 129      * @return string
 130      */
 131     protected function additionalFailureDescription($other)
 132     {
 133         return '';
 134     }
 135
 136     /**
 137      * Returns the description of the failure
 138      *
 139      * The beginning of failure messages is "Failed asserting that" in most
 140      * cases. This method should return the second part of that sentence.
 141      *
 142      * To provide additional failure information additionalFailureDescription
 143      * can be used.
 144      *
 145      * @param mixed $other Evaluated value or object.
 146      *
 147      * @return string
 148      */
 149     protected function failureDescription($other)
 150     {
 151         return $this->exporter->export($other) . ' ' . $this->toString();
 152     }
 153 }