tests/PHPUnit/PHPUnit/Framework/Constraint.php

   1 <?php
   2 /**
   3  * PHPUnit
   4  *
   5  * Copyright (c) 2002-2011, Sebastian Bergmann <sebastian@phpunit.de>.
   6  * All rights reserved.
   7  *
   8  * Redistribution and use in source and binary forms, with or without
   9  * modification, are permitted provided that the following conditions
  10  * are met:
  11  *
  12  *   * Redistributions of source code must retain the above copyright
  13  *     notice, this list of conditions and the following disclaimer.
  14  *
  15  *   * Redistributions in binary form must reproduce the above copyright
  16  *     notice, this list of conditions and the following disclaimer in
  17  *     the documentation and/or other materials provided with the
  18  *     distribution.
  19  *
  20  *   * Neither the name of Sebastian Bergmann nor the names of his
  21  *     contributors may be used to endorse or promote products derived
  22  *     from this software without specific prior written permission.
  23  *
  24  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  25  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  26  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  27  * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
  28  * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  29  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
  30  * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  31  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
  32  * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  33  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
  34  * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  35  * POSSIBILITY OF SUCH DAMAGE.
  36  *
  37  * @package    PHPUnit
  38  * @subpackage Framework
  39  * @author     Sebastian Bergmann <sebastian@phpunit.de>
  40  * @copyright  2002-2011 Sebastian Bergmann <sebastian@phpunit.de>
  41  * @license    http://www.opensource.org/licenses/bsd-license.php  BSD License
  42  * @link       http://www.phpunit.de/
  43  * @since      File available since Release 3.0.0
  44  */
  45
  46 /**
  47  * Abstract base class for constraints. which are placed upon any value.
  48  *
  49  * @package    PHPUnit
  50  * @subpackage Framework
  51  * @author     Sebastian Bergmann <sebastian@phpunit.de>
  52  * @copyright  2002-2011 Sebastian Bergmann <sebastian@phpunit.de>
  53  * @license    http://www.opensource.org/licenses/bsd-license.php  BSD License
  54  * @version    Release: 3.5.13
  55  * @link       http://www.phpunit.de/
  56  * @since      Interface available since Release 3.0.0
  57  */
  58 abstract class PHPUnit_Framework_Constraint implements Countable, PHPUnit_Framework_SelfDescribing
  59 {
  60     /**
  61      * Counts the number of constraint elements.
  62      *
  63      * @return integer
  64      * @since  Method available since Release 3.4.0
  65      */
  66     public function count()
  67     {
  68         return 1;
  69     }
  70
  71     /**
  72      * Creates the appropriate exception for the constraint which can be caught
  73      * by the unit test system. This can be called if a call to evaluate()
  74      * fails.
  75      *
  76      * @param   mixed   $other The value passed to evaluate() which failed the
  77      *                         constraint check.
  78      * @param   string  $description A string with extra description of what was
  79      *                               going on while the evaluation failed.
  80      * @param   boolean $not Flag to indicate negation.
  81      * @throws  PHPUnit_Framework_ExpectationFailedException
  82      */
  83     public function fail($other, $description, $not = FALSE)
  84     {
  85         throw new PHPUnit_Framework_ExpectationFailedException(
  86           $this->failureDescription($other, $description, $not),
  87           NULL
  88         );
  89     }
  90
  91     /**
  92      * @param mixed   $other
  93      * @param string  $description
  94      * @param boolean $not
  95      */
  96     protected function failureDescription($other, $description, $not)
  97     {
  98         $failureDescription = $this->customFailureDescription(
  99           $other, $description, $not
 100         );
 101
 102         if ($failureDescription === NULL) {
 103             $failureDescription = sprintf(
 104               'Failed asserting that %s %s.',
 105
 106                PHPUnit_Util_Type::toString($other),
 107                $this->toString()
 108             );
 109         }
 110
 111         if ($not) {
 112             $failureDescription = self::negate($failureDescription);
 113         }
 114
 115         if (!empty($description)) {
 116             $failureDescription = $description . "\n" . $failureDescription;
 117         }
 118
 119         return $failureDescription;
 120     }
 121
 122     /**
 123      * @param mixed   $other
 124      * @param string  $description
 125      * @param boolean $not
 126      */
 127     protected function customFailureDescription($other, $description, $not)
 128     {
 129     }
 130
 131     /**
 132      * @param  string $string
 133      * @return string
 134      */
 135     public static function negate($string)
 136     {
 137         return str_replace(
 138           array(
 139             'contains ',
 140             'exists',
 141             'has ',
 142             'is ',
 143             'matches ',
 144             'starts with ',
 145             'ends with ',
 146             'not not '
 147           ),
 148           array(
 149             'does not contain ',
 150             'does not exist',
 151             'does not have ',
 152             'is not ',
 153             'does not match ',
 154             'starts not with ',
 155             'ends not with ',
 156             'not '
 157           ),
 158           $string
 159         );
 160     }
 161
 162     /**
 163      * Evaluates the constraint for parameter $other. Returns TRUE if the
 164      * constraint is met, FALSE otherwise.
 165      *
 166      * @param mixed $other Value or object to evaluate.
 167      * @return bool
 168      */
 169     abstract public function evaluate($other);
 170 }