6. Asserters collection

To write more explicit and less wordy tests, atoum provide several asserters who give access to specific assertions related to tested var.

As atoum different asserters are specializations of manipulated items, asserters inherits from asserters they specialize. It help keep consistency between asserters and force to use same assertion names.

This is the asserters inheritance tree:

-- asserter (abstract)
    |-- error
    |-- mock
    |-- stream
    |-- variable
    |   |-- array
    |   |    `-- castToArray
    |   |-- boolean
    |   |-- class
    |   |    `-- testedClass
    |   |-- integer
    |   |   |-- float
    |   |   `-- sizeOf
    |   |-- object
    |   |   |-- dateInterval
    |   |   |-- dateTime
    |   |   |   `-- mysqlDateTime
    |   |   |-- exception
    |   |   `-- iterator
    |   |       `-- generator
    |   |-- resource
    |   `-- string
    |       |-- castToString
    |       |-- hash
    |       |-- output
    |       `-- utf8String
    `-- function

Note

The general asserter/assertion syntaxe is: $this->[asserter]($value)->[assertion];

Note

Most of the assertions are fluent, as you will see below.

Note

At the end of this chapter you will find several tips & tricks related to assertion and asserter, don’t forget to read it!

6.1. afterDestructionOf

It’s the dedicated assertion to object destruction.

This assertion check that the given object is valid and check if __destruct() method is defined and then invokes it.

If __destruct() exists and is executed without any error or exception then the test succeeds.

<?php
$this
    ->afterDestructionOf($objectWithDestructor)     // succeed
    ->afterDestructionOf($objectWithoutDestructor)  // fails
;

6.2. array

It’s the assertion dedicated to arrays.

Note

array is a reserved word in PHP, it hasn’t been possible to create an array assertion. It’s therefore called phpArray and an alias array was created. So, you can meet either ->phpArray() or ->array().

It’s recommended to use only ->array() in order to simplify the reading of tests.

6.2.1. Syntactic sugar

In order to simplify the writing of tests with arrays, some syntactic sugar is available. It allows to make various assertions directly on the keys of the tested array.

$a = [
   'foo' => 42,
   'bar' => '1337'
];

$this
   ->array($a)
      ->integer['foo']->isEqualTo(42)
      ->string['bar']->isEqualTo('1337')
;

Note

This writing form is available from PHP 5.4.

6.2.2. child

With child you can assert on a subarray.

<?php
$array = array(
   'ary' => array(
      'key1' => 'abc',
      'key2' => 123,
      'key3' => array(),
   ),
);

$this
   ->array($array)
      ->child['ary'](function($child)
      {
         $child
            ->hasSize(3)
            ->hasKeys(array('key1', 'key2', 'key3'))
            ->contains(123)
            ->child['key3'](function($child)
            {
               $child->isEmpty;
            });
      });

Note

This is available from PHP 5.4.

6.2.3. contains

contains check that array contains some data.

<?php
$fibonacci = array('1', 2, '3', 5, '8', 13, '21');

$this
    ->array($fibonacci)
        ->contains('1')     // succeed
        ->contains(1)       // succeed, but data type...
        ->contains('2')     // ... is not checked
        ->contains(10)      // failed
;

Note

contains doesn’t check recursively.

Warning

contains doesn’t check the data type.
If you want also to check its type, use strictlyContains.

6.2.4. containsValues

containsValues checks that an array contains all data from a given array.

<?php
$fibonacci = array('1', 2, '3', 5, '8', 13, '21');

$this
    ->array($array)
        ->containsValues(array(1, 2, 3))        // succeed
        ->containsValues(array('5', '8', '13')) // succeed
        ->containsValues(array(0, 1, 2))        // failed
;

Note

containsValues doesn’t search recursively.

Warning

containsValues doesn’t test data type.
If you also want to check their types, use strictlyContainsValues.

6.2.5. hasKey

hasKey check that the table contains a given key.

<?php
$fibonacci = array('1', 2, '3', 5, '8', 13, '21');
$atoum     = array(
    'name'        => 'atoum',
    'owner'       => 'mageekguy',
);

$this
    ->array($fibonacci)
        ->hasKey(0)         // passes
        ->hasKey(1)         // passes
        ->hasKey('1')       // passes
        ->hasKey(10)        // failed

    ->array($atoum)
        ->hasKey('name')    // passes
        ->hasKey('price')   // fails
;

Note

hasKey doesn’t search recursively.

Warning

hasKey doesn’t test the key type.

6.2.6. hasKeys

hasKeys checks that an array contains all given keys.

<?php
$fibonacci = array('1', 2, '3', 5, '8', 13, '21');
$atoum     = array(
    'name'        => 'atoum',
    'owner'       => 'mageekguy',
);

$this
    ->array($fibonacci)
        ->hasKeys(array(0, 2, 4))           // passes
        ->hasKeys(array('0', 2))            // passes
        ->hasKeys(array('4', 0, 3))         // passes
        ->hasKeys(array(0, 3, 10))          // fails

    ->array($atoum)
        ->hasKeys(array('name', 'owner'))   // passes
        ->hasKeys(array('name', 'price'))   // fails
;

Note

hasKeys doesn’t search recursively.

Warning

hasKeys doesn’t test the keys type.

6.2.7. hasSize

hasSize checks the size of an array.

<?php
$fibonacci = array('1', 2, '3', 5, '8', 13, '21');

$this
    ->array($fibonacci)
        ->hasSize(7)        // passes
        ->hasSize(10)       // fails
;

Note

hasSize is not recursive.

6.2.8. isEmpty

isEmpty checks that an array is empty.

<?php
$emptyArray    = array();
$nonEmptyArray = array(null, null);

$this
    ->array($emptyArray)
        ->isEmpty()         // passes

    ->array($nonEmptyArray)
        ->isEmpty()         // fails
;

6.2.9. isEqualTo

See also

isEqualTo is a method inherited from the variable asserter. For more information, refer to the documentation of variable::isEqualTo

6.2.10. isIdenticalTo

See also

isIdenticalTo is a method inherited from the variable asserter. For more information, refer to the documentation of variable::isIdenticalTo

6.2.11. isNotEmpty

isNotEmpty checks that an array is not empty.

<?php
$emptyArray    = array();
$nonEmptyArray = array(null, null);

$this
    ->array($emptyArray)
        ->isNotEmpty()      // fails

    ->array($nonEmptyArray)
        ->isNotEmpty()      // passes
;

6.2.12. isNotEqualTo

See also

isNotEqualTo is a method inherited from the variable asserter. For more information, refer to the documentation of variable::isNotEqualTo

6.2.13. isNotIdenticalTo

See also

isNotIdenticalTo is a method inherited from the variable asserter. For more information, refer to the documentation of variable::isNotIdenticalTo

6.2.14. keys

keys allows you to retrieve an asserter array containing the tested table keys.

<?php
$atoum = array(
    'name'  => 'atoum',
    'owner' => 'mageekguy',
);

$this
    ->array($atoum)
        ->keys
            ->isEqualTo(
                array(
                    'name',
                    'owner',
                )
            )
;

6.2.15. notContains

notContains checks that an array doesn’t contains a given data.

<?php
$fibonacci = array('1', 2, '3', 5, '8', 13, '21');

$this
    ->array($fibonacci)
        ->notContains(null)         // passes
        ->notContains(1)            // fails
        ->notContains(10)           // passes
;

Note

notContains doesn’t search recursively.

Warning

notContains doesn’t check the data type.
If you want also to check its type, use strictlyNotContains.

6.2.16. notContainsValues

notContainsValues checks that an array doesn’t contains any data from a given array.

<?php
$fibonacci = array('1', 2, '3', 5, '8', 13, '21');

$this
    ->array($array)
        ->notContainsValues(array(1, 4, 10))    // fails
        ->notContainsValues(array(4, 10, 34))   // passes
        ->notContainsValues(array(1, '2', 3))   // fails
;

Note

notContainsValues doesn’t search recursively.

Warning

notContainsValues doesn’t test the data type.
If you also want to check their types, use strictlyNotContainsValues.

6.2.17. notHasKey

notHasKey checks that an array doesn’t contains a given key.

<?php
$fibonacci = array('1', 2, '3', 5, '8', 13, '21');
$atoum     = array(
    'name'  => 'atoum',
    'owner' => 'mageekguy',
);

$this
    ->array($fibonacci)
        ->notHasKey(0)          // fails
        ->notHasKey(1)          // fails
        ->notHasKey('1')        // fails
        ->notHasKey(10)         // passes

    ->array($atoum)
        ->notHasKey('name')     // fails
        ->notHasKey('price')    // passes
;

Note

notHasKey doesn’t search recursively.

Warning

notHasKey doesn’t test keys type.

6.2.18. notHasKeys

notHasKeys checks that an array doesn’t contains any keys from a given array.

<?php
$fibonacci = array('1', 2, '3', 5, '8', 13, '21');
$atoum     = array(
    'name'        => 'atoum',
    'owner'       => 'mageekguy',
);

$this
    ->array($fibonacci)
        ->notHasKeys(array(0, 2, 4))            // fails
        ->notHasKeys(array('0', 2))             // fails
        ->notHasKeys(array('4', 0, 3))          // fails
        ->notHasKeys(array(10, 11, 12))         // passes

    ->array($atoum)
        ->notHasKeys(array('name', 'owner'))    // fails
        ->notHasKeys(array('foo', 'price'))     // passes
;

Note

notHasKeys doesn’t search recursively.

Warning

notHasKeys doesn’t test keys type.

6.2.19. size

size allow you to retrieve an integer containing the size of tested array.

<?php
$fibonacci = array('1', 2, '3', 5, '8', 13, '21');

$this
    ->array($fibonacci)
        ->size
            ->isGreaterThan(5)
;

6.2.20. strictlyContains

strictlyContains checks that an array contains some data (same value and same type).

<?php
$fibonacci = array('1', 2, '3', 5, '8', 13, '21');

$this
    ->array($fibonacci)
        ->strictlyContains('1')     // passes
        ->strictlyContains(1)       // fails
        ->strictlyContains('2')     // fails
        ->strictlyContains(2)       // passes
        ->strictlyContains(10)      // fails
;

Note

strictlyContains doesn’t search recursively.

Warning

strictlyContains test data type.
If you don’t want to check the type, use contains.

6.2.21. strictlyContainsValues

strictlyContainsValues checks that an array contains all given data (same value and same type).

<?php
$fibonacci = array('1', 2, '3', 5, '8', 13, '21');

$this
    ->array($array)
        ->strictlyContainsValues(array('1', 2, '3'))    // passes
        ->strictlyContainsValues(array(1, 2, 3))        // fails
        ->strictlyContainsValues(array(5, '8', 13))     // passes
        ->strictlyContainsValues(array('5', '8', '13')) // fails
        ->strictlyContainsValues(array(0, '1', 2))      // fails
;

Note

strictlyContainsValue doesn’t search recursively.

Warning

strictlyContainsValues test data type.
If you don’t want to check the types, use containsValues.

6.2.22. strictlyNotContains

strictlyNotContains check that an array doesn’t contains a data (same value and same type).

<?php
$fibonacci = array('1', 2, '3', 5, '8', 13, '21');

$this
    ->array($fibonacci)
        ->strictlyNotContains(null)         // passes
        ->strictlyNotContains('1')          // fails
        ->strictlyNotContains(1)            // passes
        ->strictlyNotContains(10)           // passes
;

Note

strictlyNotContains doesn’t search recursively.

Warning

strictlyNotContains test data type.
If you don’t want to check the type, use contains.

6.2.23. strictlyNotContainsValues

strictlyNotContainsValues checks that an array doesn’t contains any of given data (same value and same type).

<?php
$fibonacci = array('1', 2, '3', 5, '8', 13, '21');

$this
    ->array($array)
        ->strictlyNotContainsValues(array('1', 4, 10))  // fails
        ->strictlyNotContainsValues(array(1, 4, 10))    // passes
        ->strictlyNotContainsValues(array(4, 10, 34))   // passes
        ->strictlyNotContainsValues(array('1', 2, '3')) // fails
        ->strictlyNotContainsValues(array(1, '2', 3))   // passes
;

Note

strictlyNotContainsValues doesn’t search recursively.

Warning

strictlyNotContainsValues tests data type.
If you don’t want to check the types, use notContainsValues.

6.2.24. values

keys allows you to retrieve an asserter array containing the tested table values.

Example:

<?php
$this
    ->given($arr = [0 => 'foo', 2 => 'bar', 3 => 'baz'])
    ->then
      ->array($arr)->values
        ->string[0]->isEqualTo('foo')
        ->string[1]->isEqualTo('bar')
        ->string[2]->isEqualTo('baz')
;

New in version 2.9.0: values assertion added

6.3. boolean

This is the assertion dedicated to booleans.

If you try to test a variable that is not a boolean with this assertion, it will fail.

Note

null is not a boolean. Report the the PHP manual to know what is_bool considers or not to be a boolean.

6.3.1. isEqualTo

See also

isEqualTo is a method inherited from the variable asserter. For more information, refer to the documentation of variable::isEqualTo

6.3.2. isFalse

isFalse check that the boolean is strictly equal to false.

<?php
$true  = true;
$false = false;

$this
    ->boolean($true)
        ->isFalse()     // fails

    ->boolean($false)
        ->isFalse()     // succeed
;

6.3.3. isIdenticalTo

See also

isIdenticalTo is a method inherited from variable asserter. For more information, refer to the documentation of variable::isIdenticalTo

6.3.4. isNotEqualTo

See also

isNotEqualTo is a method inherited from variable asserter. For more information, refer to the documentation of variable::isNotEqualTo

6.3.5. isNotIdenticalTo

See also

isNotIdenticalTo is a method inherited from variable asserter. For more information, refer to the documentation of variable::isNotIdenticalTo

6.3.6. isTrue

isTrue checks that the boolean is strictly equal to true.

<?php
$true  = true;
$false = false;

$this
    ->boolean($true)
        ->isTrue()      // succeed

    ->boolean($false)
        ->isTrue()      // fails
;

6.4. castToArray

It’s the assertion dedicated to tests on the cast of objects to arrays.

<?php
class AtoumVersions {
    private $versions = ['1.0', '2.0', '2.1'];

    public function __toArray() {
        return $this->versions;
    }
}

$this
    ->castToArray(new AtoumVersions())
        ->contains('1.0')
;

See also

castToArray asserter return an instance of array asserter. You can use all assertions from array asserter

6.5. castToString

It’s the assertion dedicated to tests on the cast of objects to strings.

<?php
class AtoumVersion {
    private $version = '1.0';

    public function __toString() {
        return 'atoum v' . $this->version;
    }
}

$this
    ->castToString(new AtoumVersion())
        ->isEqualTo('atoum v1.0')
;

6.5.1. contains

See also

contains is a method herited from string asserter. For more information, refer to the documentation of string::contains

6.5.2. notContains

See also

notContains is a method herited from string asserter. For more information, refer to the documentation of string::notContains

6.5.3. hasLength

See also

hasLength is a method herited from string asserter. For more information, refer to the documentation of string::hasLength

6.5.4. hasLengthGreaterThan

See also

hasLengthGreaterThan is a method inherited from string asserter. For more information, refer to the documentation for string::hasLengthGreaterThan

6.5.5. hasLengthLessThan

See also

hasLengthLessThan is a method inherited from string asserter. For more information, refer to the documentation for string::hasLengthLessThan

6.5.6. isEmpty

See also

isEmpty is a method inherited from string asserter. For more information, refer to the documentation of string::isEmpty

6.5.7. isEqualTo

See also

isEqualTo is a method inherited from variable asserter. For more information, refer to the documentation of variable::isEqualTo

6.5.8. isEqualToContentsOfFile

See also

isEqualToContentsOfFile is a method inherited from string asserter. For more information, refer to the documentation of string::isEqualToContentsOfFile

6.5.9. isIdenticalTo

See also

isIdenticalTo is a method inherited from variable asserter. For more information, refer to the documentation of variable::isIdenticalTo

6.5.10. isNotEmpty

See also

isNotEmpty is a method inherited from string asserter. For more information, refer to the documentation of string::isNotEmpty

6.5.11. isNotEqualTo

See also

isNotEqualTo is a method inherited from variable asserter. For more information, refer to the documentation of variable::isNotEqualTo

6.5.12. isNotIdenticalTo

See also

isNotIdenticalTo is a method inherited from variable asserter. For more information, refer to the documentation of variable::isNotIdenticalTo

6.5.13. matches

See also

matches is a method inherited from string asserter. For more information, refer to the documentation of string::match

6.6. class

It’s the assertion dedicated to classes.

<?php
$object = new \StdClass;

$this
    ->class(get_class($object))

    ->class('\StdClass')
;

Note

The keyword class is a reserved word in PHP, it wasn’t possible to create a class asserter. It’s therefore called phpClass and an alias class has been created. You can meet either ->phpClass() or ->class().

But it’s recommended to only use ->class().

6.6.1. hasConstant

“hasConstant” checks that the class has the tested constant.

<?php
$this
    ->class('\StdClass')
        ->hasConstant('FOO')       // fails

    ->class('\FilesystemIterator')
        ->hasConstant('CURRENT_AS_PATHNAME')       // passes
;

6.6.2. hasInterface

hasInterface checks that the class implements a given interface.

<?php
$this
    ->class('\ArrayIterator')
        ->hasInterface('Countable')     // passes

    ->class('\StdClass')
        ->hasInterface('Countable')     // fails
;

6.6.3. hasMethod

hasMethod checks that the class contains a given method.

<?php
$this
    ->class('\ArrayIterator')
        ->hasMethod('count')    // passes

    ->class('\StdClass')
        ->hasMethod('count')    // fails
;

6.6.4. hasNoParent

hasNoParent checks that the class doesn’t inherit from any class.

<?php
$this
    ->class('\StdClass')
        ->hasNoParent()     // passes

    ->class('\FilesystemIterator')
        ->hasNoParent()     // fails
;

Warning

A class can implement one or more interfaces, and have no inheritance.
hasNoParent doesn’t check interfaces, only the inherited classes.

6.6.5. hasParent

hasParent checks that the class inherits from a given class.

<?php
$this
    ->class('\StdClass')
        ->hasParent()       // fails

    ->class('\FilesystemIterator')
        ->hasParent()       // passes
;

Warning

A class can implement one or more interfaces, and have no inheritance.
hasParent doesn’t check interfaces, only the inherited classes.

6.6.6. isAbstract

isAbstract checks that the class is abstract.

<?php
$this
    ->class('\StdClass')
        ->isAbstract()       // fails
;

6.6.7. isFinal

isFinal checks that the class is final.

In this case, we test a non-final class (StdClass) :

<?php
$this
        ->class('\StdClass')
                ->isFinal()             // fails
;

In this case, the tested class is a final one

<?php
$this
        ->testedClass
                ->isFinal()             // passes
;

$this
        ->testedClass
                ->isFinal               // passes too
;

6.6.8. isSubclassOf

isSubclassOf checks that the tested class inherit from given class.

<?php
$this
    ->class('\FilesystemIterator')
        ->isSubclassOf('\DirectoryIterator')    // passes
        ->isSubclassOf('\SplFileInfo')          // passes
        ->isSubclassOf('\StdClass')             // fails
;

6.7. dateInterval

It’s the assertion dedicated to DateInterval object.

If you try to test a value that is not a DateInterval (or a child class) with this assertion it will fail.

6.7.1. isCloneOf

See also

isCloneOf is a method inherited from asserter object. For more information, refer to the documentation of object::isCloneOf

6.7.2. isEqualTo

isEqualTo checks that the duration of object DateInterval is equals to to the duration of another DateInterval object.

<?php
$di = new DateInterval('P1D');

$this
    ->dateInterval($di)
        ->isEqualTo(                // passes
            new DateInterval('P1D')
        )
        ->isEqualTo(                // fails
            new DateInterval('P2D')
        )
;

6.7.3. isGreaterThan

isGreaterThan checks that the duration of the object DateInterval is higher to the duration of the given DateInterval object.

<?php
$di = new DateInterval('P2D');

$this
    ->dateInterval($di)
        ->isGreaterThan(            // passes
            new DateInterval('P1D')
        )
        ->isGreaterThan(            // fails
            new DateInterval('P2D')
        )
;

6.7.4. isGreaterThanOrEqualTo

isGreaterThanOrEqualTo checks that the duration of the object DateInterval is higher or equals to the duration of another object DateInterval.

<?php
$di = new DateInterval('P2D');

$this
    ->dateInterval($di)
        ->isGreaterThanOrEqualTo(   // passes
            new DateInterval('P1D')
        )
        ->isGreaterThanOrEqualTo(   // passes
            new DateInterval('P2D')
        )
        ->isGreaterThanOrEqualTo(   // fails
            new DateInterval('P3D')
        )
;

6.7.5. isIdenticalTo

See also

isIdenticalTo is an inherited method from object asserter. For more information, refer to the documentation of object::isIdenticalTo

6.7.6. isInstanceOf

See also

isInstanceOf is a method inherited from asserter object. For more information, refer to the documentation of object::isInstanceOf

6.7.7. isLessThan

isLessThan checks that the duration of the object DateInterval is lower than the duration of the given DateInterval object.

<?php
$di = new DateInterval('P1D');

$this
    ->dateInterval($di)
        ->isLessThan(               // passes
            new DateInterval('P2D')
        )
        ->isLessThan(               // fails
            new DateInterval('P1D')
        )
;

6.7.8. isLessThanOrEqualTo

isLessThanOrEqualTo checks that the duration of the object DateInterval is lower or equals to the duration of another object DateInterval.

<?php
$di = new DateInterval('P2D');

$this
    ->dateInterval($di)
        ->isLessThanOrEqualTo(      // passes
            new DateInterval('P3D')
        )
        ->isLessThanOrEqualTo(      // passes
            new DateInterval('P2D')
        )
        ->isLessThanOrEqualTo(      // fails
            new DateInterval('P1D')
        )
;

6.7.9. isNotEqualTo

See also

isNotEqualTo is a method inherited from object asserter. For more information, refer to the documentation of object::isNotEqualTo

6.7.10. isNotIdenticalTo

See also

isNotIdenticalTo is an inherited method from object asserter. For more information, refer to the documentation of object::isNotIdenticalTo

6.7.11. isZero

isZero check the duration of DateInterval is equal to 0.

<?php
$di1 = new DateInterval('P0D');
$di2 = new DateInterval('P1D');

$this
    ->dateInterval($di1)
        ->isZero()      // passes
    ->dateInterval($di2)
        ->isZero()      // fails
;

6.8. dateTime

It’s the assertion dedicated to DateTime object.

If you try to test a value that is not a DateTime (or a child class) with this assertion it will fail.

6.8.1. hasDate

hasDate checks the date part of the DateTime object.

<?php
$dt = new DateTime('1981-02-13');

$this
    ->dateTime($dt)
        ->hasDate('1981', '02', '13')   // passes
        ->hasDate('1981', '2',  '13')   // passes
        ->hasDate(1981,   2,    13)     // passes
;

6.8.2. hasDateAndTime

hasDateAndTime checks date and hour part of the DateTime object.

<?php
$dt = new DateTime('1981-02-13 01:02:03');

$this
    ->dateTime($dt)
        // passes
        ->hasDateAndTime('1981', '02', '13', '01', '02', '03')
        // passes
        ->hasDateAndTime('1981', '2',  '13', '1',  '2',  '3')
        // passes
        ->hasDateAndTime(1981,   2,    13,   1,    2,    3)
;

6.8.3. hasDay

hasDay checks day part of the DateTime object.

<?php
$dt = new DateTime('1981-02-13');

$this
    ->dateTime($dt)
        ->hasDay(13)        // passes
;

6.8.4. hasHours

hasHours checks time part of the DateTime object.

<?php
$dt = new DateTime('01:02:03');

$this
    ->dateTime($dt)
        ->hasHours('01')    // passes
        ->hasHours('1')     // passes
        ->hasHours(1)       // passes
;

6.8.5. hasMinutes

hasMinutes checks minutes part of the DateTime object.

<?php
$dt = new DateTime('01:02:03');

$this
    ->dateTime($dt)
        ->hasMinutes('02')  // passes
        ->hasMinutes('2')   // passes
        ->hasMinutes(2)     // passes
;

6.8.6. hasMonth

hasMonth checks month part of the DateTime object.

<?php
$dt = new DateTime('1981-02-13');

$this
    ->dateTime($dt)
        ->hasMonth(2)       // passes
;

6.8.7. hasSeconds

hasSeconds checks seconds part of the DateTime object.

<?php
$dt = new DateTime('01:02:03');

$this
    ->dateTime($dt)
        ->hasSeconds('03')    // passes
        ->hasSeconds('3')     // passes
        ->hasSeconds(3)       // passes
;

6.8.8. hasTime

hasTime checks time part of the DateTime object.

<?php
$dt = new DateTime('01:02:03');

$this
    ->dateTime($dt)
        ->hasTime('01', '02', '03')     // passes
        ->hasTime('1',  '2',  '3')      // passes
        ->hasTime(1,    2,    3)        // passes
;

6.8.9. hasTimezone

hasTimezone checks timezone part of the DateTime object.

<?php
$dt = new DateTime();

$this
    ->dateTime($dt)
        ->hasTimezone('Europe/Paris')
;

6.8.10. hasYear

hasYear checks year part of the DateTime object.

<?php
$dt = new DateTime('1981-02-13');

$this
    ->dateTime($dt)
        ->hasYear(1981)     // passes
;

6.8.11. isCloneOf

See also

isCloneOf is a method inherited from asserter object. For more information, refer to the documentation of object::isCloneOf

6.8.12. isEqualTo

See also

isEqualTo is a method inherited from object asserter. For more information, refer to the documentation of object::isEqualTo

6.8.13. isIdenticalTo

See also

isIdenticalTo is an inherited method from object asserter. For more information, refer to the documentation of object::isIdenticalTo

6.8.14. isImmutable

isImmutable checks that a DateTime object is immutable.

<?php
$dt = new DateTime('1981-02-13');

$this
    ->dateTime($dt)
        ->isImmutable(1981)     // failed
;

$dt = new DateTimeImmutable('1981-02-13');

$this
    ->dateTime($dt)
        ->isImmutable(1981)     // success
;

6.8.15. isInstanceOf

See also

isInstanceOf is a method inherited from asserter object. For more information, refer to the documentation of object::isInstanceOf

6.8.16. isNotEqualTo

See also

isNotEqualTo is a method inherited from object asserter. For more information, refer to the documentation of object::isNotEqualTo

6.8.17. isNotIdenticalTo

See also

isNotIdenticalTo is an inherited method from object asserter. For more information, refer to the documentation of object::isNotIdenticalTo

6.9. error

It’s the assertion dedicated to errors.

<?php
$this
    ->when(
        function() {
            trigger_error('message');
        }
    )
        ->error()
            ->exists() // or notExists
;

Note

The syntax uses anonymous functions (also called closures) introduced in PHP 5.3. For more details, read the PHP’s documentation on anonymous functions.

Warning

The error types E_ERROR, E_PARSE, E_CORE_ERROR, E_CORE_WARNING, E_COMPILE_ERROR, E_COMPILE_WARNING as well as the E_STRICT can’t be managed with this function.

6.9.1. exists

exists checks that an error was raised during the execution of the previous code.

<?php
$this
    ->when(
        function() {
            trigger_error('message');
        }
    )
        ->error()
            ->exists()      // pass

    ->when(
        function() {
            // code without error
        }
    )
        ->error()
            ->exists()      // failed
;

6.9.2. notExists

notExists checks that no errors was raised during the execution of the previous code.

<?php
$this
    ->when(
        function() {
            trigger_error('message');
        }
    )
        ->error()
            ->notExists()   // fails

    ->when(
        function() {
            // code without error
        }
    )
        ->error()
            ->notExists()   // pass
;

6.9.3. withType

withType checks the type of the raised error.

<?php
$this
    ->when(
        function() {
            trigger_error('message');
        }
    )
    ->error()
        ->withType(E_USER_NOTICE)   // pass
        ->exists()

    ->when(
        function() {
            trigger_error('message');
        }
    )
    ->error()
        ->withType(E_USER_WARNING)  // failed
        ->exists()
;

6.9.4. withAnyType

withAnyType does not check the type of the raised error. That’s the default behaviour. So ->error()->withAnyType()->exists() is the equivalent of ->error()->exists(). This method allow to add semantic to your test.

<?php
$this
    ->when(
        function() {
            trigger_error('message');
        }
    )
    ->error()
        ->withAnyType() // pass
        ->exists()
    ->when(
        function() {
        }
    )
    ->error()
        ->withAnyType()
        ->exists() // fails
;

6.9.5. withMessage

withMessage checks message content of raised error.

<?php
$this
    ->when(
        function() {
            trigger_error('message');
        }
    )
    ->error()
        ->withMessage('message')
        ->exists() // passes
;

$this
    ->when(
        function() {
            trigger_error('message');
        }
    )
    ->error()
        ->withMessage('MESSAGE')
        ->exists() // fails
;

6.9.6. withAnyMessage

withAnyMessage does not check the error message. That’s the default behaviour. So ->error()->withAnyMessage()->exists() is the equivalent of ->error()->exists(). This method allow to add semantic to your test.

<?php
$this
    ->when(
        function() {
            trigger_error();
        }
    )
    ->error()
        ->withAnyMessage()
        ->exists() // passes
;

$this
    ->when(
        function() {
            trigger_error('message');
        }
    )
    ->error()
        ->withAnyMessage()
        ->exists() // passes
;

$this
    ->when(
        function() {
        }
    )
    ->error()
        ->withAnyMessage()
        ->exists() // fails
;

6.9.7. withPattern

withPattern checks message content of raised error against a regular expression.

<?php
$this
    ->when(
        function() {
            trigger_error('message');
        }
    )
    ->error()
        ->withPattern('/^mess.*$/')
        ->exists() // passes
;

$this
    ->when(
        function() {
            trigger_error('message');
        }
    )
    ->error()
        ->withPattern('/^mess$/')
        ->exists() // fails
;

6.10. exception

It’s the assertion dedicated to exceptions.

<?php
$this
    ->exception(
        function() use($myObject) {
            // this code throws an exception: throw new \Exception;
            $myObject->doOneThing('wrongParameter');
        }
    )
;

Note

The syntax uses anonymous functions (also called closures) introduced in PHP 5.3. For more details, read the PHP’s documentation on anonymous functions.

We can easily retrieve the last exception with $this->exception.

<?php
$this
    ->exception(
        function() use($myObject) {
            // This code throws a exception: throw new \Exception('Message', 42);
            $myObject->doOneThing('wrongParameter');
        }
    )->isIdenticalTo($this->exception) // passes
;

$this->exception->hasCode(42); // passes
$this->exception->hasMessage('erreur'); // passes

Note

Before atoum 3.0.0, if you need to make assertion if was required to add atoum\test $test as argument of the closure. After 3.0.0, you can simply use $this inside the closure to make some assertion.

6.10.1. hasCode

hasCode checks exception code.

<?php
$this
    ->exception(
        function() use($myObject) {
            // This code throws a exception: throw new \Exception('Message', 42);
            $myObject->doOneThing('wrongParameter');
        }
    )
        ->hasCode(42)
;

6.10.2. hasDefaultCode

hasDefaultCode checks that exception code is the default value, 0.

<?php
$this
    ->exception(
        function() use($myObject) {
            // this code throws an exception: throw new \Exception;
            $myObject->doOneThing('wrongParameter');
        }
    )
        ->hasDefaultCode()
;

Note

hasDefaultCode is equivalent to hasCode(0).

6.10.3. hasMessage

hasMessage checks exception message.

<?php
$this
    ->exception(
        function() use($myObject) {
            // This code throws a exception: throw new \Exception('Message');
            $myObject->doOneThing('wrongParameter');
        }
    )
        ->hasMessage('Message')     // passes
        ->hasMessage('message')     // fails
;

6.10.4. hasNestedException

hasNestedException checks that the exception contains a reference to another exception. If the exception type is given, this will also checks the exception class.

<?php
$this
    ->exception(
        function() use($myObject) {
            // This code throws a exception: throw new \Exception('Message');
            $myObject->doOneThing('wrongParameter');
        }
    )
        ->hasNestedException()      // fails

    ->exception(
        function() use($myObject) {
            try {
                // This code throws a exception: throw new \FirstException('Message 1', 42);
                $myObject->doOneThing('wrongParameter');
            }
            // ... the exception is caught...
            catch(\FirstException $e) {
                // ... and then throws encapsulated inside a second one
                throw new \SecondException('Message 2', 24, $e);
            }
        }
    )
        ->isInstanceOf('\FirstException')           // fails
        ->isInstanceOf('\SecondException')          // passes

        ->hasNestedException()                      // passes
        ->hasNestedException(new \FirstException)   // passes
        ->hasNestedException(new \SecondException)  // fails
;

6.10.5. isCloneOf

See also

isCloneOf is a method inherited from asserter object. For more information, refer to the documentation of object::isCloneOf

6.10.6. isEqualTo

See also

isEqualTo is a method inherited from object asserter. For more information, refer to the documentation of object::isEqualTo

6.10.7. isIdenticalTo

See also

isIdenticalTo is an inherited method from object asserter. For more information, refer to the documentation of object::isIdenticalTo

6.10.8. isInstanceOf

See also

isInstanceOf is a method inherited from asserter object. For more information, refer to the documentation of object::isInstanceOf

6.10.9. isNotEqualTo

See also

isNotEqualTo is a method inherited from object asserter. For more information, refer to the documentation of object::isNotEqualTo

6.10.10. isNotIdenticalTo

See also

isNotIdenticalTo is an inherited method from object asserter. For more information, refer to the documentation of object::isNotIdenticalTo

6.10.11. message

message allow you to get an asserter of type string containing the tested exception message.

<?php
$this
    ->exception(
        function() {
            throw new \Exception('My custom message to test');
        }
    )
        ->message
            ->contains('message')
;

6.11. extension

It’s the asserter dedicated to PHP extension.

6.11.1. isLoaded

Check if the extension is loaded (installed and enabled).

<?php
$this
        ->extension('json')
                ->isLoaded()
        ;

Note

If you need to run tests only if an extension is present, you can use the PHP annotation.

6.12. float

It’s the assertion dedicated to decimal numbers.

If you try to test a variable that is not a decimal number with this assertion, it will fail.

Note

null is not a decimal number. Refer to the PHP manual to know what is_float considered or not as a float.

6.12.1. isEqualTo

See also

isEqualTo is a method inherited from the variable asserter. For more information, refer to the documentation of variable::isEqualTo

6.12.2. isGreaterThan

See also

isGreaterThan is a method inherited from the integer asserter. For more information, refer to the documentation of integer::isGreaterThan

6.12.3. isGreaterThanOrEqualTo

See also

isGreaterThanOrEqualTo is a method inherited from the integer asserter. For more information, refer to the documentation of integer::isGreaterThanOrEqualTo

6.12.4. isIdenticalTo

See also

isIdenticalTo is a method inherited from the variable asserter. For more information, refer to the documentation of variable::isIdenticalTo

6.12.5. isLessThan

See also

isLessThan is a method inherited from the integer asserter. For more informations, refer to the documentation of integer::isLessThan

6.12.6. isLessThanOrEqualTo

See also

isLessThanOrEqualTo is a method inherited from the integer asserter. For more information, refer to the documentation of integer::isLessThanOrEqualTo

6.12.7. isNearlyEqualTo

isNearlyEqualTo checks that the float is approximately equal to the value received as an argument.

Indeed, in computer science, decimal numbers are managed in a way that does not allow for accurate comparisons without the use of specialized tools. Try for example to run the following command:

$ php -r 'var_dump(1 - 0.97 === 0.03);'
bool(false)

The result should be “true”.

Note

For more information on this topics, read the PHP documentation on the float precision.

This method is therefore seeking to reduce this problem.

<?php
$float = 1 - 0.97;

$this
    ->float($float)
        ->isNearlyEqualTo(0.03) // passes
        ->isEqualTo(0.03)       // fails
;

Note

For more information about the algorithm used, see the floating point guide.

6.12.8. isNotEqualTo

See also

isNotEqualTo is a method inherited from the variable asserter. For more information, refer to the documentation of variable::isNotEqualTo

6.12.9. isNotIdenticalTo

See also

isNotIdenticalTo is a method inherited from the variable asserter. For more information, refer to the documentation of variable::isNotIdenticalTo

6.12.10. isZero

See also

isZero is a method inherited from the integer asserter. For more information, refer to the documentation of integer::isZero

6.13. function

It’s the assertion dedicated to the native function that were mocked.

6.13.1. wasCalled

wasCalled checks that the mocked function was called.

6.13.2. wasCalledWithArguments

wasCalledWithArguments allow to check some of the arguments from the call to the mocked function.

6.13.3. wasCalledWithIdenticalArguments

wasCalledWithIdenticalArguments allow to check all the arguments from the call to the mocked function.

6.13.4. wasCalledWithoutAnyArgument

wasCalledWithoutAnyArgument validated that the call to the mocked function was made without arguments.

6.13.5. Count call

If you want you can do one more assertion by counting the number of call.

<?php
$this->function->error_log = true;

$this
   ->if($this->newTestedInstance())
   ->and($this->testedInstance->methodWithAnErrorLog($notExcepted = uniqid()))
   ->then
       ->function('error_log')
           ->wasCalledWithArguments('Value ' . $notExcepted . ' is not excepted here')
               ->once();

Here, we assert that our mocked function was called once, with the given arguments.

6.13.5.1. after

after checks if the mocked function has been called after the one passed as parameter.

See also

after is the same as the one on the mock asserter. For more information, refer to the documentation of mock::after

6.13.5.2. atLeastOnce

atLeastOnce check if mocked function has been called at least once.

See also

atLeastOnce is the same as the one on the mock asserter. For more information, refer to the documentation of mock::atLeastOnce

6.13.5.3. before

before checks if the mocked function has been called before the one passed as parameter.

See also

before is the same as the one on the mock asserter. For more information, refer to the documentation of mock::before

6.13.5.4. exactly

exactly check that the mocked function has been called a specific number of times.

See also

exactly is the same as the one on the mock asserter. For more information, refer to the documentation of mock::exactly

6.13.5.5. never

never check that the mocked function has never been called.

See also

never is the same as the one on the mock asserter. For more information, refer to the documentation of mock::never

6.13.5.6. once/twice/thrice

This asserters check that the mocked function has been called exactly:

  • once
  • twice
  • thrice

See also

once is the same as the one on the mock asserter. For more information, refer to the documentation of mock::once/twice/thrice

6.14. generator

It’s the assertion dedicated to tests on generators.

The generator asserter extends the iterator asserter, so you can use any assertion from the iterator asserter.

Example:

<?php
$generator = function() {
    for ($i=0; $i<3; $i++) {
        yield ($i+1);
    }
};
$this
    ->generator($generator())
        ->hasSize(3)
;

In this example we create a generator that yields 3 values, and we check that the size of the generator is 3.

6.14.1. yields

yields is used to ease the test on values yielded by the generator. Each time you will call ->yields the next value of the generator will be retrived. You will be able to use any other asserter on this value (for example class, string or variable).

Example:

<?php
$generator = function() {
    for ($i=0; $i<3; $i++) {
        yield ($i+1);
    }
};
$this
    ->generator($generator())
        ->yields->variable->isEqualTo(1)
        ->yields->variable->isEqualTo(2)
        ->yields->integer->isEqualTo(3)
;

In this example we create a generator that yields 3 values: 1, 2 and 3. Then we yield each value and run an assertion on this value to check it’s type and value. In the first two yields we use the variable asserter and only check the value. In the third yields call we add a check on the type of the value by using the integer asserter (any asserter could by used on this value) before checking the value.

6.14.2. returns

Note

This assertion will only work on PHP >= 7.0.

Since the version 7.0 of PHP, generators can return a value that can retrived via a call to the ->getReturn() method. When you call ->returns on the generator asserter, atoum will retrive the value from a call on the ->getReturn() method on the asserter. Then you will be able to use any other asserter on this value just like the yields assertion.

Example:

<?php
$generator = function() {
    for ($i=0; $i<3; $i++) {
        yield ($i+1);
    }
    return 42;
};
$this
    ->generator($generator())
        ->yields->variable->isEqualTo(1)
        ->yields->variable->isEqualTo(2)
        ->yields->integer->isEqualTo(3)
        ->returns->integer->isEqualTo(42)
;

In this example we run some checks on all the yielded values. Then, we checks that the generator returns a integer with a value of 42 (just like a call to the yields assertion, you can use any asserter to check to returned value).

New in version 3.0.0: Generator asserter added

6.15. hash

It’s the assertion dedicated to tests on hashes (digital fingerprints).

6.15.1. contains

See also

contains is a method inherited from the string asserter. For more information, refer to the documentation of string::contains

6.15.2. isEqualTo

See also

isEqualTo is a method inherited from the variable asserter. For more information, refer to the documentation of variable::isEqualTo

6.15.3. isEqualToContentsOfFile

See also

isEqualToContentsOfFile is a method inherited from the string asserter. For more information, refer to the documentation of string::isEqualToContentsOfFile

6.15.4. isIdenticalTo

See also

isIdenticalTo is a method inherited from the variable asserter. For more information, refer to the documentation of variable::isIdenticalTo

6.15.5. isMd5

isMd5 checks that the string is a md5 format, i.r. a hexadecimal string of 32 length.

<?php
$hash    = hash('md5', 'atoum');
$notHash = 'atoum';

$this
    ->hash($hash)
        ->isMd5()       // passes
    ->hash($notHash)
        ->isMd5()       // fails
;

6.15.6. isNotEqualTo

See also

isNotEqualTo is a method inherited from the variable asserter. For more information, refer to the documentation of variable::isNotEqualTo

6.15.7. isNotIdenticalTo

See also

isNotIdenticalTo is a method inherited from the variable asserter. For more information, refer to the documentation of variable::isNotIdenticalTo

6.15.8. isSha1

isSha1 checks that the string is a sha1 format, i.e. a hexadecimal string of 40 length.

<?php
$hash    = hash('sha1', 'atoum');
$notHash = 'atoum';

$this
    ->hash($hash)
        ->isSha1()      // passes
    ->hash($notHash)
        ->isSha1()      // fails
;

6.15.9. isSha256

isSha256 checks that the string is a sha256 format, i.e. a hexadecimal string of 64 length.

<?php
$hash    = hash('sha256', 'atoum');
$notHash = 'atoum';

$this
    ->hash($hash)
        ->isSha256()    // passes
    ->hash($notHash)
        ->isSha256()    // fails
;

6.15.10. isSha512

isSha512 checks that the string is a sha512 format, i.e. a hexadecimal string of 128 length.

<?php
$hash    = hash('sha512', 'atoum');
$notHash = 'atoum';

$this
    ->hash($hash)
        ->isSha512()    // passes
    ->hash($notHash)
        ->isSha512()    // fails
;

6.15.11. notContains

See also

notContains is a method inherited from the string asserter. For more information, refer to the documentation of string::notContains

6.16. integer

It’s the assertion dedicated to integers.

If you try to test a variable that is not an integer with this assertion, it will fail.

Note

null isn’t an integer. Refer to the PHP’s manual is_int to known what’s considered as an integer or not.

6.16.1. isEqualTo

See also

isEqualTo is a method inherited from the variable asserter. For more information, refer to the documentation of variable::isEqualTo

6.16.2. isGreaterThan

isGreaterThan checks that the integer is strictly higher than given one.

<?php
$zero = 0;

$this
    ->integer($zero)
        ->isGreaterThan(-1)     // passes
        ->isGreaterThan('-1')   // fails because "-1"
                                // isn't an integer
        ->isGreaterThan(0)      // fails
;

6.16.3. isGreaterThanOrEqualTo

isGreaterThanOrEqualTo checks that an integer is higher or equal to a given one.

<?php
$zero = 0;

$this
    ->integer($zero)
        ->isGreaterThanOrEqualTo(-1)    // passes
        ->isGreaterThanOrEqualTo(0)     // passes
        ->isGreaterThanOrEqualTo('-1')  // fails because "-1"
                                        // isn't an integer
;

6.16.4. isIdenticalTo

See also

isIdenticalTo is a method inherited from the variable asserter. For more information, refer to the documentation of variable::isIdenticalTo

6.16.5. isLessThan

isLessThan checks that the integer is strictly lower than a given one.

<?php
$zero = 0;

$this
    ->integer($zero)
        ->isLessThan(10)    // passes
        ->isLessThan('10')  // fails because"10" isn't an integer
        ->isLessThan(0)     // fails
;

6.16.6. isLessThanOrEqualTo

isLessThanOrEqualTo checks that an integer is lower or equal to a given one.

<?php
$zero = 0;

$this
    ->integer($zero)
        ->isLessThanOrEqualTo(10)       // passes
        ->isLessThanOrEqualTo(0)        // passes
        ->isLessThanOrEqualTo('10')     // fails because "10"
                                        // isn't an integer
;

6.16.7. isNotEqualTo

See also

isNotEqualTo is a method inherited from the variable asserter. For more information, refer to the documentation of variable::isNotEqualTo

6.16.8. isNotIdenticalTo

See also

isNotIdenticalTo is a method inherited from the variable asserter. For more information, refer to the documentation of variable::isNotIdenticalTo

6.16.9. isZero

isZero checks that the integer is equal to 0.

<?php
$zero    = 0;
$notZero = -1;

$this
    ->integer($zero)
        ->isZero()          // passes

    ->integer($notZero)
        ->isZero()          // fails
;

Note

isZero is equivalent to isEqualTo(0).

6.17. mock

It’s the assertion dedicated to mocks.

<?php
$mock = new \mock\MyClass;

$this
    ->mock($mock)
;

Note

Refer to the documentation of mock for more information on how to create and manage mocks.

6.17.1. call

call let you specify which method of mock to check, it call must be followed by a call to one of the following verification method like atLeastOnce, once/twice/thrice, exactly, etc…

<?php

$this
    ->given($mock = new \mock\MyFirstClass)
    ->and($object = new MySecondClass($mock))

    ->if($object->methodThatCallMyMethod())  // This will call myMethod from $mock
    ->then

    ->mock($mock)
        ->call('myMethod')
            ->once()
;

6.17.1.1. after

after checks if the method has been called after the one passed as parameter.

<?php
$this
    ->when($mock = new \mock\example)
    ->if(
        $mock->test2(),
        $mock->test()
    )
    ->mock($mock)
    ->call('test')
        ->after($this->mock($mock)->call('test2')->once())
        ->once() // passes
;

$this
    ->when($mock = new \mock\example)
    ->if(
        $mock->test(),
        $mock->test2()
    )
    ->mock($mock)
    ->call('test')
        ->after($this->mock($mock)->call('test2')->once())
        ->once() // fails
;

6.17.1.2. atLeastOnce

atLeastOnce check that the tested method (see call) from the mock has been called at least once.

<?php
$mock = new \mock\MyFirstClass;

$this
    ->object(new MySecondClass($mock))

    ->mock($mock)
        ->call('myMethod')
            ->atLeastOnce()
;

6.17.1.3. before

before checks if the method has been called before the one passed as parameter.

<?php
$this
    ->when($mock = new \mock\example)
    ->if(
        $mock->test(),
        $mock->test2()
    )
    ->mock($mock)
    ->call('test')
        ->before($this->mock($mock)->call('test2')->once())
        ->once() // passes
;

$this
    ->when($mock = new \mock\example)
    ->if(
        $mock->test2(),
        $mock->test()
    )
    ->mock($mock)
    ->call('test')
        ->before($this->mock($mock)->call('test2')->once())
        ->once() // fails
;

6.17.1.4. exactly

exactly check that the tested method (see call) has been called a specific number of times.

<?php
$mock = new \mock\MyFirstClass;

$this
    ->object(new MySecondClass($mock))

    ->mock($mock)
        ->call('myMethod')
            ->exactly(2)
;

Note

You can have a simplified version with ->{2}.

6.17.1.5. never

never check that the tested method (see call) has never been called.

<?php
$mock = new \mock\MyFirstClass;

$this
    ->object(new MySecondClass($mock))

    ->mock($mock)
        ->call('myMethod')
            ->never()
;

Note

never is equivalent to exactly(0).

6.17.1.6. once/twice/thrice

This asserters check that the tested method (see call) from the tested mock has been called exactly:

  • once
  • twice
  • thrice
<?php
$mock = new \mock\MyFirstClass;

$this
    ->object(new MySecondClass($mock))

    ->mock($mock)
        ->call('myMethod')
            ->once()
        ->call('mySecondMethod')
            ->twice()
        ->call('myThirdMethod')
            ->thrice()
;

Note

once, twice and thrice are respectively equivalent to exactly(1), exactly(2) and exactly(3).

6.17.1.7. withAnyArguments

withAnyArguments allow to check any argument, non-specified, when we call the tested method (see call) of tested mock.

This method is useful to reset the arguments of tested method, like in the following example:

<?php
$mock = new \mock\MyFirstClass;

$this
    ->object(new MySecondClass($mock))

    ->mock($mock)
        ->call('myMethod')
            ->withArguments('first')     ->once()
            ->withArguments('second')    ->once()
            ->withAnyArguments()->exactly(2)
;

6.17.1.8. withArguments

withArguments let you specify the expected arguments that the tested method should receive when called (see call).

<?php
$mock = new \mock\MyFirstClass;

$this
    ->object(new MySecondClass($mock))

    ->mock($mock)
        ->call('myMethod')
            ->withArguments('first', 'second')->once()
;

Warning

withArguments does not check the arguments type.
If you also want to check the type, use withIdenticalArguments.

6.17.1.9. withIdenticalArguments

withIdenticalArguments let you specify the expected typed arguments that tested method should receive when called (see call).

<?php
$mock = new \mock\MyFirstClass;

$this
    ->object(new MySecondClass($mock))

    ->mock($mock)
        ->call('myMethod')
            ->withIdenticalArguments('first', 'second')->once()
;

Warning

withIdenticalArguments checks the arguments type.
If you do not want to check the type, use withArguments.

6.17.1.10. withAtLeastArguments

withAtLeastArguments let you specify the minimum expected arguments that tested method should receive when called (see call).

<?php
$this
   ->if($mock = new \mock\example)
   ->and($mock->test('a', 'b'))
   ->mock($mock)
   ->call('test')
         ->withAtLeastArguments(array('a'))->once() //passes
         ->withAtLeastArguments(array('a', 'b'))->once() //passes
         ->withAtLeastArguments(array('c'))->once() //fails
;

Warning

withAtLeastArguments does not check the arguments type.
If you also want to check the type, use withAtLeastIdenticalArguments.

6.17.1.11. withAtLeastIdenticalArguments

withAtLeastIdenticalArguments let you specify the minimum expected typed arguments that tested method should receive when called (see call).

<?php
$this
    ->if($mock = new \mock\example)
    ->and($mock->test(1, 2))
    ->mock($mock)
        ->call('test')
        ->withAtLeastIdenticalArguments(array(1))->once() //passes
        ->withAtLeastIdenticalArguments(array(1, 2))->once() //passes
        ->withAtLeastIdenticalArguments(array('1'))->once() //fails
;

Warning

withAtLeastIdenticalArguments checks the arguments type.
If you do not want to check the type, use withIdenticalArguments.

6.17.1.12. withoutAnyArgument

withoutAnyArgument lets you indicate that the method should not receive any argument when called (see call).

<?php
$this
    ->when($mock = new \mock\example)
    ->if($mock->test())
    ->mock($mock)
        ->call('test')
            ->withoutAnyArgument()->once() // passes
    ->if($mock->test2('argument'))
    ->mock($mock)
        ->call('test2')
            ->withoutAnyArgument()->once() // fails
;

Note

withoutAnyArgument is equivalent to call withAtLeastArguments with an empty array: ->withAtLeastArguments(array()).

6.17.2. receive

It’s an alias of call.

<?php
$this
    ->given(
        $connection = new mock\connection
    )
    ->if(
        $this->newTestedInstance($connection)
    )
    ->then
        ->object($this->testedInstance->noMoreValue())->isTestedInstance
        ->mock($connection)->receive('newPacket')->withArguments(new packet)->once;

   // same as
   $this->mock($connection)->call('newPacket')->withArguments(new packet)->once;

6.17.3. wasCalled

wasCalled checks that at least one method of the mock has been called at least once.

<?php
$mock = new \mock\MyFirstClass;

$this
    ->object(new MySecondClass($mock))

    ->mock($mock)
        ->wasCalled()
;

6.17.4. wasNotCalled

wasNotCalled checks that no method of the mock has been called.

<?php
$mock = new \mock\MyFirstClass;

$this
    ->object(new MySecondClass($mock))

    ->mock($mock)
        ->wasNotCalled()
;

6.18. mysqlDateTime

It’s the assertion dedicated to objects representing MySQL date and based on DateTime object.

Dates must use a format compatible with MySQL and many other DBMSS (database management system), i.e. “Y-m-d H:i:s”

Note

For more information, refer to the documentation of the date() function from the PHP manual.

If you try to test a value that’s not a DateTime (or a child class) with this assertion it will fail.

6.18.1. hasDate

See also

hasDate is a method inherited from the dateTime asserter. For more information, refer to the documentation of dateTime::hasDate

6.18.2. hasDateAndTime

See also

hasDateAndTime is a method inherited from the dateTime asserter. For more informations, refer to the documentation of dateTime::hasDateAndTime

6.18.3. hasDay

See also

hasDay is a method inherited from the dateTime asserter. For more information, refer to the documentation of dateTime::hasDay

6.18.4. hasHours

See also

hasHours is a method inherited from the dateTime asserter. For more information, refer to the documentation of dateTime::hasHours

6.18.5. hasMinutes

Hint

hasMinutes is a method inherited from the dateTime asserter. For more information, refer to the documentation of dateTime::hasMinutes

6.18.6. hasMonth

See also

hasMonth is a method inherited from the dateTime asserter. For more information, refer to the documentation of dateTime::hasMonth

6.18.7. hasSeconds

See also

hasSeconds is a method inherited from the dateTime asserter. For more information, refer to the documentation of dateTime::hasSeconds

6.18.8. hasTime

See also

hasTime is a method inherited from the dateTime asserter. For more information, refer to the documentation of dateTime::hasTime

6.18.9. hasTimezone

See also

hasTimezone is a method inherited from the dateTime asserter. For more information, refer to the documentation of dateTime::hasTimezone

6.18.10. hasYear

See also

hasYear is a method inherited from the dateTime asserter. For more information, refer to the documentation of dateTime::hasYear

6.18.11. isCloneOf

See also

isCloneOf is a method inherited from asserter object. For more information, refer to the documentation of object::isCloneOf

6.18.12. isEqualTo

See also

isEqualTo is a method inherited from object asserter. For more information, refer to the documentation of object::isEqualTo

6.18.13. isIdenticalTo

See also

isIdenticalTo is an inherited method from object asserter. For more information, refer to the documentation object::isIdenticalTo

6.18.14. isInstanceOf

Hint

isInstanceOf is a method inherited from asserter object. For more information, refer to the documentation of object::isInstanceOf

6.18.15. isNotEqualTo

See also

isNotEqualTo is a method inherited from object asserter. For more information, refer to the documentation of object::isNotEqualTo

6.18.16. isNotIdenticalTo

See also

isNotIdenticalTo is an inherited method from object asserter. For more information, refer to the documentation of object::isNotIdenticalTo

6.19. object

It’s the assertion dedicated to objects.

If you try to test a variable that is not an object with this assertion, it will fail.

Note

null isn’t an object. Refer to the PHP’s manual is_object to know what is considered as an object or not.

6.19.1. hasSize

hasSize checks the size of an object that implements the interface Countable.

<?php
$countableObject = new GlobIterator('*');

$this
    ->object($countableObject)
        ->hasSize(3)
;

6.19.2. isCallable

<?php
class foo
{
    public function __invoke()
    {
        // code
    }
}

$this
    ->object(new foo)
        ->isCallable()  // passes

    ->object(new StdClass)
        ->isCallable()  // fails
;

Note

To be identified as callable, your objects should be instantiated from classes that implements the magic __invoke.

See also

isCallable is a method inherited from the variable asserter. For more information, refer to the documentation of variable::isCallable

6.19.3. isCloneOf

isCloneOf checks an object is clone of a given one, that is the objects are equal but are not the same instance.

<?php
$object1 = new \StdClass;
$object2 = new \StdClass;
$object3 = clone($object1);
$object4 = new \StdClass;
$object4->foo = 'bar';

$this
    ->object($object1)
        ->isCloneOf($object2)   // passes
        ->isCloneOf($object3)   // passes
        ->isCloneOf($object4)   // fails
;

Note

For more details, read the PHP’s documentation about comparing objects.

6.19.4. isEmpty

isEmpty checks the size of an object that implements the Countable interface is equal to 0.

<?php
$countableObject = new GlobIterator('atoum.php');

$this
    ->object($countableObject)
        ->isEmpty()
;

Note

isEmpty is equivalent to hasSize(0).

6.19.5. isEqualTo

isEqualTo checks that an object is equal to another. Two objects are consider equals when they have the same attributes and values, and they are instances of the same class.

Note

For more details, read the PHP’s documentation about comparing objects.

See also

isEqualTo is a method inherited from the variable asserter. For more information, refer to the documentation of variable::isEqualTo

6.19.6. isIdenticalTo

isIdenticalTo checks that two objects are identical. Two objects are considered identical when they refer to the same instance of the same class.

Note

For more details, read the PHP’s documentation about comparing objects.

See also

isIdenticalTo is a method inherited from the variable asserter. For more information, refer to the documentation of variable::isIdenticalTo

6.19.7. isInstanceOf

isInstanceOf checks that an object is:

  • an instance of the given class,
  • a subclass from the given class (abstract or not),
  • an instance of class that implements a given interface.
<?php
$object = new \StdClass();

$this
    ->object($object)
        ->isInstanceOf('\StdClass')     // passes
        ->isInstanceOf('\Iterator')     // fails
;


interface FooInterface
{
    public function foo();
}

class FooClass implements FooInterface
{
    public function foo()
    {
        echo "foo";
    }
}

class BarClass extends FooClass
{
}

$foo = new FooClass;
$bar = new BarClass;

$this
    ->object($foo)
        ->isInstanceOf('\FooClass')     // passes
        ->isInstanceOf('\FooInterface') // passes
        ->isInstanceOf('\BarClass')     // fails
        ->isInstanceOf('\StdClass')     // fails

    ->object($bar)
        ->isInstanceOf('\FooClass')     // passes
        ->isInstanceOf('\FooInterface') // passes
        ->isInstanceOf('\BarClass')     // passes
        ->isInstanceOf('\StdClass')     // fails
;

Note

The name of the classes and the interfaces must be absolute, because any namespace imports are ignored.

Hint

Notice that with PHP >= 5.5 you can use the keyword class to get the absolute class names, for example $this->object($foo)->isInstanceOf(FooClass::class).

6.19.8. isInstanceOfTestedClass

<?php
$this->newTestedInstance;
$object = new TestedClass();
$this->object($this->testedInstance)->isInstanceOfTestedClass;
$this->object($object)->isInstanceOfTestedClass;

6.19.9. isNotCallable

<?php
class foo
{
    public function __invoke()
    {
        // code
    }
}

$this
    ->variable(new foo)
        ->isNotCallable()   // fails

    ->variable(new StdClass)
        ->isNotCallable()   // passes
;

See also

isNotCallable is a method inherited from the variable asserter. For more information, refer to the documentation of variable::isNotCallable

6.19.10. isNotEqualTo

isEqualTo checks that an object is not equal to another. Two objects are consider equals when they have the same attributes and values, and they are instance of the same class.

Note

For more details, read the PHP’s documentation about comparing objects.

See also

isNotEqualTo is a method inherited from the variable asserter. For more information, refer to the documentation of variable::isNotEqualTo

6.19.11. isNotIdenticalTo

isIdenticalTo checks the two objects are not identical. Two objects are considered identical when they refer to the same instance of same class.

Note

For more details, read the PHP’s documentation about comparing objects.

See also

isNotIdenticalTo is a method inherited from the variable asserter. For more information, refer to the documentation of variable::isNotIdenticalTo

6.19.12. isNotInstanceOf

isNotInstanceOf check that an object is not:

  • an instance of the given class,
  • a subclass from the given class (abstract or not),
  • an instance of class that implements a given interface.
<?php
$object = new \StdClass();

$this
    ->object($object)
        ->isNotInstanceOf('\StdClass')     // fail
        ->isNotInstanceOf('\Iterator')     // pass
;

Note

As for isInstanceOf, the name of the classes and the interfaces must be absolute, because any namespace imports are ignored.

6.19.13. isNotTestedInstance

<?php
$this->newTestedInstance;
$this->object($this->testedInstance)->isNotTestedInstance; // fail

6.19.14. isTestedInstance

<?php
$this->newTestedInstance;
$this->object($this->testedInstance)->isTestedInstance;

$object = new TestedClass();
$this->object($object)->isTestedInstance; // fail

6.19.15. toString

The toString assertion casts the object to a string a returns a string asserter on the casted value.

Example:

<?php
$this
  ->object(
    new class {
      public function __toString()
      {
        return 'foo';
      }
    }
  )
    ->isIdenticalTo('foo') //fails
    ->toString
      ->isIdenticalTo('foo') //passes
;

6.20. output

It’s the assertion dedicated to tests on outputs, so everything witch supposed to be displayed on the screen.

<?php
$this
    ->output(
        function() {
            echo 'Hello world';
        }
    )
;

Note

The syntax uses anonymous functions (also called closures) introduced in PHP 5.3. For more details, read the PHP’s documentation on anonymous functions.

6.20.1. contains

See also

contains is a method inherited from the string asserter. For more information, refer to the documentation of string::contains

6.20.2. hasLength

See also

hasLength is a method inherited from the string asserter. For more information, refer to the documentation of string::hasLength

6.20.3. hasLengthGreaterThan

See also

hasLengthGreaterThan is a method inherited from the string asserter. For more information, refer to the documentation of string::hasLengthGreaterThan

6.20.4. hasLengthLessThan

See also

hasLengthLessThan is a method inherited from the string asserter. For more information, refer to the documentation of string::hasLengthLessThan

6.20.5. isEmpty

See also

isEmpty is a method inherited from the string asserter. For more information, refer to the documentation of string::isEmpty

6.20.6. isEqualTo

See also

isEqualTo is a method inherited from the variable asserter. For more information, refer to the documentation of variable::isEqualTo

6.20.7. isEqualToContentsOfFile

See also

isEqualToContentsOfFile is a method inherited from the string asserter. For more information, refer to the documentation of string::isEqualToContentsOfFile

6.20.8. isIdenticalTo

See also

isIdenticalTo is a method inherited from the variable asserter. For more information, refer to the documentation of variable::isIdenticalTo

6.20.9. isNotEmpty

See also

isNotEmpty is a method inherited from the string asserter. For more information, refer to the documentation of string::isNotEmpty

6.20.10. isNotEqualTo

See also

isNotEqualTo is a method inherited from the variable asserter. For more information, refer to the documentation of variable::isNotEqualTo

6.20.11. isNotIdenticalTo

See also

isNotIdenticalTo is a method inherited from the variable asserter. For more information, refer to the documentation of variable::isNotIdenticalTo

6.20.12. matches

See also

matches is a method inherited from the string asserter. For more information, refer to the documentation of string::match

6.20.13. notContains

See also

notContains is a method herited from the string asserter. For more information, refer to the documentation of string::notContains

6.21. resource

It’s the assertion dedicated to the ´resources <http://php.net/language.types.resource>´_.

6.21.1. isOfType

This method compare the type of resource with the type of the given value provided by the argument. In the following example, we checks that the given value is a stream.

$this
    ->resource($variable)
        ->isOfType('stream')
;

6.21.2. isStream

$this
    ->resource($variable)
        ->isStream()
;
->is*() will match the type of the stream against a pattern computed from the method name:
->isFooBar() will try to match a stream with type foo bar, fooBar, foo_bar, …

6.21.3. type

$this
    ->resource($variable)
        ->type
                        ->isEqualTo('stream')
                        ->matches('/foo.*bar/')
;

->$type is an helper providing a string asserter on the stream type.

6.22. sizeOf

It’s the assertion dedicated to tests on the size of the arrays and objects implementing the interface Countable.

<?php
$array           = array(1, 2, 3);
$countableObject = new GlobIterator('*');

$this
    ->sizeOf($array)
        ->isEqualTo(3)

    ->sizeOf($countableObject)
        ->isGreaterThan(0)
;

6.22.1. isEqualTo

See also

isEqualTo is a method inherited from the variable asserter. For more information, refer to the documentation of variable::isEqualTo

6.22.2. isGreaterThan

See also

isGreaterThan is a method inherited from the integer asserter. For more information, refer to the documentation of integer::isGreaterThan

6.22.3. isGreaterThanOrEqualTo

See also

isGreaterThanOrEqualTo is a method inherited from the integer asserter. For more information, refer to the documentation of integer::isGreaterThanOrEqualTo

6.22.4. isIdenticalTo

See also

isIdenticalTo is a method inherited from the variable asserter. For more information, refer to the documentation of variable::isIdenticalTo

6.22.5. isLessThan

See also

isLessThan is a method inherited from the integer asserter. For more information, refer to the documentation of integer::isLessThan

6.22.6. isLessThanOrEqualTo

See also

isLessThanOrEqualTo is a method inherited from the integer asserter. For more information, refer to the documentation of integer::isLessThanOrEqualTo

6.22.7. isNotEqualTo

See also

isNotEqualTo is a method inherited from the variable asserter. For more information, refer to the documentation of variable::isNotEqualTo

6.22.8. isNotIdenticalTo

See also

isNotIdenticalTo is a method inherited from the variable asserter. For more information, refer to the documentation of variable::isNotIdenticalTo

6.22.9. isZero

See also

isZero is a method inherited from the integer asserter. For more information, refer to the documentation of integer::isZero

6.23. stream

It’s the assertion dedicated to the ´streams <http://php.net/intro.stream>´_.

It’s based on atoum virtual filesystem (VFS). A new stream wrapper will be registered (starting with atoum://).

The mock will create a new file in the VFS and the steam path will be accessible via the getPath method on the stream controller (something like atoum://mockUniqId).

6.23.1. isRead

isRead checks if a mocked stream has been read.

<?php
$this
    ->given(
        $streamController = \atoum\mock\stream::get(),
        $streamController->file_get_contents = 'myFakeContent'
    )
    ->if(file_get_contents($streamController->getPath()))
    ->stream($streamController)
        ->isRead() // passe
;

$this
    ->given(
        $streamController = \atoum\mock\stream::get(),
        $streamController->file_get_contents = 'myFakeContent'
    )
    ->if() // we do nothing
    ->stream($streamController)
        ->isRead() // fails
;

6.23.2. isWritten

isWritten checks if a mocked stream has been written.

<?php
$this
    ->given(
        $streamController = \atoum\mock\stream::get(),
        $streamController->file_put_contents = strlen($content = 'myTestContent')
    )
    ->if(file_put_contents($streamController->getPath(), $content))
    ->stream($streamController)
        ->isWritten() // passes
;

$this
   ->given(
     $streamController = \atoum\mock\stream::get(),
     $streamController->file_put_contents = strlen($content = 'myTestContent')
   )
   ->if() // we do nothing
   ->stream($streamController)
      ->isWritten() // fails
;

6.23.3. isWrited

Hint

isWrited is an alias to the isWritten method. For more information, refer to the documentation of stream::isWritten

6.24. string

It’s the assertion dedicated to the strings.

6.24.1. contains

contains checks that a string contains another given string.

<?php
$string = 'Hello world';

$this
    ->string($string)
        ->contains('ll')    // passes
        ->contains(' ')     // passes
        ->contains('php')   // fails
;

6.24.2. endWith

endWith checks that a string ends with another given string.

<?php
$string = 'Hello world';

$this
    ->string($string)
        ->endWith('world')     // passes
        ->endWith('lo world')  // passes
        ->endWith('Hello')     // fails
        ->endWith(' ')         // fails
;

6.24.3. hasLength

hasLength checks the string size.

<?php
$string = 'Hello world';

$this
    ->string($string)
        ->hasLength(11)     // passes
        ->hasLength(20)     // fails
;

6.24.4. hasLengthGreaterThan

hasLengthGreaterThan checks that the string size is greater that the given one.

<?php
$string = 'Hello world';

$this
    ->string($string)
        ->hasLengthGreaterThan(10)     // passes
        ->hasLengthGreaterThan(20)     // fails
;

6.24.5. hasLengthLessThan

hasLengthLessThan checks that the string size is lower that the given one.

<?php
$string = 'Hello world';

$this
    ->string($string)
        ->hasLengthLessThan(20)     // passes
        ->hasLengthLessThan(10)     // fails
;

6.24.6. isEmpty

isEmpty checks that the string is empty.

<?php
$emptyString    = '';
$nonEmptyString = 'atoum';

$this
    ->string($emptyString)
        ->isEmpty()             // passes

    ->string($nonEmptyString)
        ->isEmpty()             // fails
;

6.24.7. isEqualTo

See also

isEqualTo is a method inherited from the variable asserter. For more information, refer to the documentation of variable::isEqualTo

6.24.8. isEqualToContentsOfFile

isEqualToContentsOfFile checks that the string is equal to the content of a file given by its path.

<?php
$this
    ->string($string)
        ->isEqualToContentsOfFile('/path/to/file')
;

Note

if the file doesn’t exist, the test will fails.

6.24.9. isIdenticalTo

See also

isIdenticalTo is a method inherited from the variable asserter. For more information, refer to the documentation of variable::isIdenticalTo

6.24.10. isNotEmpty

isNotEmpty checks that the string is not empty.

<?php
$emptyString    = '';
$nonEmptyString = 'atoum';

$this
    ->string($emptyString)
        ->isNotEmpty()          // fails

    ->string($nonEmptyString)
        ->isNotEmpty()          // passes
;

6.24.11. isNotEqualTo

See also

isNotEqualTo is a method inherited from the variable asserter. For more information, refer to the documentation of variable::isNotEqualTo

6.24.12. isNotIdenticalTo

See also

isNotIdenticalTo is a method inherited from the variable asserter. For more information, refer to the documentation of variable::isNotIdenticalTo

6.24.13. length

length allows you to get an asserter of type integer that contains the string’s size.

<?php
$string = 'atoum';

$this
    ->string($string)
        ->length
            ->isGreaterThanOrEqualTo(5)
;

6.24.14. match

Hint

match is an alias of the matches method. For more information, refer to the documentation of string::matches

6.24.15. matches

matches checks that a regular expression match the tested string.

<?php
$phone = '0102030405';
$vdm   = "Today at 57 years, my father got a tatoot of a Unicorn on his shoulder. VDM";

$this
    ->string($phone)
        ->matches('#^0[1-9]\d{8}$#')

    ->string($vdm)
        ->matches("#^Today.*VDM$#")
;

6.24.16. notContains

notContains checks that the tested string doesn’t contains another string.

<?php
$string = 'Hello world';

$this
    ->string($string)
        ->notContains('php')   // passes
        ->notContains(';')     // passes
        ->notContains('ll')    // fails
        ->notContains(' ')     // fails
;

6.24.17. notEndWith

notEndWith checks that the tested string doesn’t ends with another string.

<?php
$string = 'Hello world';

$this
    ->string($string)
        ->notEndWith('Hello')     // passes
        ->notEndWith(' ')         // passes
        ->notEndWith('world')  // fails
        ->notEndWith('lo world')        // fails
;

6.24.18. notMatches

notMatches checks that a regular expression does not match the tested string.

<?php
$phone = '0102030405';
$vdm   = "Today at 57 years, my father got a tatoot of a Unicorn on his shoulder. VDM";

$this
    ->string($phone)
        ->notMatches('#qwerty#') // passes
        ->notMatches('#^0[1-9]\d{8}$#') // fails

    ->string($vdm)
        ->notMatches("#^Yesterday.*VDM$#") // passes
        ->notMatches("#^Today.*VDM$#") // fails
;

6.24.19. notStartWith

notStartWith checks that the tested string doesn’t starts with another string.

<?php
$string = 'Hello world';

$this
    ->string($string)
        ->notStartWith('world')    // passes
        ->notStartWith(' ')        // passes
        ->notStartWith('Hello wo')  // fails
        ->notStartWith('He')       // fails
;

6.24.20. startWith

startWith checks that the tested string starts with another string.

<?php
$string = 'Hello world';

$this
    ->string($string)
        ->startWith('Hello wo') // passes
        ->startWith('He')       // passes
        ->startWith('world')    // fails
        ->startWith(' ')        // fails

;

New in version 3.3.0: notMatches assertion added

6.25. utf8String

It’s the asserter dedicated to UTF-8 strings.

Note

utf8Strings use the functions mb_* to manage multi-byte strings. Refer to the PHP manual for more information about mbstring extension.

6.25.1. contains

See also

contains is a method inherited from the string asserter. For more information, refer to the documentation of string::contains

6.25.2. hasLength

See also

hasLength is a method inherited from the string asserter. For more information, refer to the documentation of string::hasLength

6.25.3. hasLengthGreaterThan

See also

hasLengthGreaterThan is a method inherited from the string asserter. For more information, refer to the documentation of string::hasLengthGreaterThan

6.25.4. hasLengthLessThan

See also

hasLengthLessThan is a method inherited from the string asserter. For more information, refer to the documentation of string::hasLengthLessThan

6.25.5. isEmpty

See also

isEmpty is a method inherited from the string asserter. For more information, refer to the documentation of string::isEmpty

6.25.6. isEqualTo

See also

isEqualTo is a method inherited from the variable asserter. For more information, refer to the documentation of variable::isEqualTo

6.25.7. isEqualToContentsOfFile

See also

isEqualToContentsOfFile is a method inherited from the string asserter. For more information, refer to the documentation of string::isEqualToContentsOfFile

6.25.8. isIdenticalTo

See also

isIdenticalTo is a method inherited from the variable asserter. For more information, refer to the documentation of variable::isIdenticalTo

6.25.9. isNotEmpty

See also

isNotEmpty is a method inherited from the string asserter. For more information, refer to the documentation of string::isNotEmpty

6.25.10. isNotEqualTo

See also

isNotEqualTo is a method inherited from the variable asserter. For more information, refer to the documentation of variable::isNotEqualTo

6.25.11. isNotIdenticalTo

See also

isNotIdenticalTo is a method inherited from the variable asserter. For more information, refer to the documentation of variable::isNotIdenticalTo

6.25.12. matches

Hint

matches is a method inherited from the string asserter. For more information, refer to the documentation of string::match

Note

Remember to add u in your regular expression, in the option part. For more precision, read the PHP’s documentation about the options for search in regular expression.

<?php
$vdm = "Today at 57 years, my father got a tatoo of a Unicorn on his shoulder. FML";

$this
    ->utf8String($vdm)
        ->matches("#^Today.*VDM$#u")
;

6.25.13. notContains

See also

notContains is a method inherited from the string asserter. For more information, refer to the documentation of string::notContains

6.26. variable

It’s the basic assertion of all variables. It contains the necessary tests for any type of variable.

6.26.1. isCallable

isCallable verifies that the variable can be called as a function.

<?php
$f = function() {
    // code
};

$this
    ->variable($f)
        ->isCallable()  // succeed

    ->variable('\Vendor\Project\foobar')
        ->isCallable()

    ->variable(array('\Vendor\Project\Foo', 'bar'))
        ->isCallable()

    ->variable('\Vendor\Project\Foo::bar')
        ->isCallable()
;

6.26.2. isEqualTo

isEqualTo verifies that the variable is equal to a given value.

<?php
$a = 'a';

$this
    ->variable($a)
        ->isEqualTo('a')    // passes
;

Warning

isEqualTo doesn’t test the type of variable.
If you also want to check the type, use isIdenticalTo.

6.26.3. isIdenticalTo

isIdenticalTo checks that the variable has the same value and the same type than the given data. In the case of an object, isIdenticalTo checks that the data is referencing the same instance.

<?php
$a = '1';

$this
    ->variable($a)
        ->isIdenticalTo(1)          // fails
;

$stdClass1 = new \StdClass();
$stdClass2 = new \StdClass();
$stdClass3 = $stdClass1;

$this
    ->variable($stdClass1)
        ->isIdenticalTo(stdClass3)  // passes
        ->isIdenticalTo(stdClass2)  // fails
;

Warning

isIdenticalTo test the type of variable.
If you don’t want to check its type, use isEqualTo.

6.26.4. isNotCallable

isNotCallable checks that the variable can’t be called like a function.

<?php
$f = function() {
    // code
};
$int    = 1;
$string = 'nonExistingMethod';

$this
    ->variable($f)
        ->isNotCallable()   // fails

    ->variable($int)
        ->isNotCallable()   // passes

    ->variable($string)
        ->isNotCallable()   // passes

    ->variable(new StdClass)
        ->isNotCallable()   // passes
;

6.26.5. isNotEqualTo

isNotEqualTo checks that the variable does not have the same value as the given one.

<?php
$a       = 'a';
$aString = '1';

$this
    ->variable($a)
        ->isNotEqualTo('b')     // passes
        ->isNotEqualTo('a')     // fails

    ->variable($aString)
        ->isNotEqualTo($a)      // fails
;

Warning

isNotEqualTo doesn’t test the type of variable.
If you also want to check the type, use isNotIdenticalTo.

6.26.6. isNotIdenticalTo

isNotIdenticalTo checks that the variable does not have the same type nor the same value than the given one.

In the case of an object, isNotIdenticalTo checks that the data isn’t referencing on the same instance.

<?php
$a = '1';

$this
    ->variable($a)
        ->isNotIdenticalTo(1)           // passes
;

$stdClass1 = new \StdClass();
$stdClass2 = new \StdClass();
$stdClass3 = $stdClass1;

$this
    ->variable($stdClass1)
        ->isNotIdenticalTo(stdClass2)   // passes
        ->isNotIdenticalTo(stdClass3)   // fails
;

Warning

isNotIdenticalTo test the type of variable.
If you don’t want to check its type, use isNotEqualTo.

6.26.7. isNull

isNull checks that the variable is null.

<?php
$emptyString = '';
$null        = null;

$this
    ->variable($emptyString)
        ->isNull()              // fails
                                // (it's empty but not null)

    ->variable($null)
        ->isNull()              // passes
;

6.26.8. isNotNull

isNotNull checks that the variable is not null.

<?php
$emptyString = '';
$null        = null;

$this
    ->variable($emptyString)
        ->isNotNull()           // passes (it's empty but not null)

    ->variable($null)
        ->isNotNull()           // fails
;

6.26.9. isNotTrue

isNotTrue check that the variable is strictly not equal to true.

<?php
$true  = true;
$false = false;
$this
    ->variable($true)
        ->isNotTrue()     // fails

    ->variable($false)
        ->isNotTrue()     // succeed
;

6.26.10. isNotFalse

isNotFalse check that the variable is strictly not equal to false.

<?php
$true  = true;
$false = false;
$this
    ->variable($false)
        ->isNotFalse()     // fails

    ->variable($true)
        ->isNotFalse()     // succeed
;

6.27. Asserter & assertion tips

Several tips & trick are available for the assertion. Knowing them can simplify your life ;)

The first one is that all assertion are fluent. So you can chain them, just look at the previous examples.

You should also know that all assertions without parameter can be written with or without parenthesis. So $this->integer(0)->isZero() is the same as $this->integer(0)->isZero.

6.27.1. Alias

Sometimes you want to use something that reflect your vocabulary or your domain. atoum provide a simple mechanism, alias. Here is an example:

<?php
namespace tests\units;

use mageekguy\atoum;

class stdClass extends atoum\test
{
    public function __construct(adapter $adapter = null, annotations\extractor $annotationExtractor = null, asserter\generator $asserterGenerator = null, test\assertion\manager $assertionManager = null, \closure $reflectionClassFactory = null)
    {
        parent::__construct($adapter, $annotationExtractor, $asserterGenerator, $assertionManager, $reflectionClassFactory);

        $this
            ->from('string')->use('isEqualTo')->as('equals')
        ;
    }

    public function testFoo()
    {
        $this
            ->string($u = uniqid())->equals($u)
        ;
    }
}

In this example, we create an alias that will create an asserter equals that will act exactly the same as isEqualTo. We could also use beforeTestMethod instead of the constructor. The best is to create a base class for all the test inside your project that you can extends instead of \atoum\test.

6.27.2. Custom asserter

Now that we have seen alias, we can go further by creating a custom asserter. Here is an example of an asserter for credit card.

<?php
namespace tests\units;
use mageekguy\atoum;

class creditcard extends atoum\asserters\string
{
    public function isValid($failMessage = null)
    {
        return $this->match('/(?:\d{4}){4}/', $failMessage ?: $this->_('%s is not a valid credit card number', $this));
    }
}

class stdClass extends atoum\test
{
    public function __construct(adapter $adapter = null, annotations\extractor $annotationExtractor = null, asserter\generator $asserterGenerator = null, test\assertion\manager $assertionManager = null, \closure $reflectionClassFactory = null)
    {
        parent::__construct($adapter, $annotationExtractor, $asserterGenerator, $assertionManager, $reflectionClassFactory);

        $this->getAsserterGenerator()->addNamespace('tests\units');
    }

    public function testFoo()
    {
        $this
            ->creditcard('4444555566660000')->isValid()
        ;
    }
}

So, like the alias, the best is to create a base class your test and declare your custom asserters there.

6.27.3. Short syntax

With alias you can define some intresting things. But because atoum tries to help you in the redaction of your test, we added several aliases.

<?php
namespace tests\units;

use atoum;

class stdClass extends atoum
{
    public function testFoo()
    {
        $this
            ->variable('foo')->{'=='}('foo')
            ->variable('foo')->{'foo'} // same as previous line
            ->variable('foo')->{'!='}('bar')

            ->object($this->newInstance)->{'=='}($this->newInstance)
            ->object($this->newInstance)->{'!='}(new \exception)
            ->object($this->newTestedInstance)->{'==='}($this->testedInstance)
            ->object($this->newTestedInstance)->{'!=='}($this->newTestedInstance)

            ->integer(rand(0, 10))->{'<'}(11)
            ->integer(rand(0, 10))->{'<='}(10)
            ->integer(rand(0, 10))->{'>'}(-1)
            ->integer(rand(0, 10))->{'>='}(0)
        ;
    }
}