From b4745b47eeec49eb3bc1665781636c86d5ac53d3 Mon Sep 17 00:00:00 2001 From: Adrien Gallou Date: Tue, 29 Dec 2015 18:27:44 +0100 Subject: [PATCH] add description on methods --- .gitattributes | 1 + .gitignore | 1 + bin/updateDoc | 317 +++++++++++++++++ .../atoum/stubs/asserters/adapter.php | 306 +++++++++++++++++ .../atoum/stubs/asserters/boolean.php | 67 +++- .../atoum/stubs/asserters/castToString.php | 20 +- .../atoum/stubs/asserters/dateInterval.php | 80 ++++- .../atoum/stubs/asserters/dateTime.php | 123 ++++++- .../mageekguy/atoum/stubs/asserters/error.php | 283 +++++++++++++++ .../atoum/stubs/asserters/exception.php | 142 +++++++- .../mageekguy/atoum/stubs/asserters/hash.php | 118 ++++++- .../atoum/stubs/asserters/integer.php | 98 +++++- .../mageekguy/atoum/stubs/asserters/mock.php | 40 ++- .../atoum/stubs/asserters/mysqlDateTime.php | 15 +- .../atoum/stubs/asserters/object.php | 114 +++++- .../atoum/stubs/asserters/output.php | 19 +- .../atoum/stubs/asserters/phpArray.php | 324 ++++++++++++++++++ .../atoum/stubs/asserters/phpClass.php | 166 +++++++++ .../atoum/stubs/asserters/phpFloat.php | 40 ++- .../atoum/stubs/asserters/phpString.php | 217 +++++++++++- .../atoum/stubs/asserters/sizeOf.php | 18 +- .../atoum/stubs/asserters/stream.php | 61 ++++ .../atoum/stubs/asserters/utf8String.php | 9 +- .../atoum/stubs/asserters/variable.php | 241 +++++++++++++ 24 files changed, 2805 insertions(+), 15 deletions(-) create mode 100644 .gitattributes create mode 100644 .gitignore create mode 100755 bin/updateDoc diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..8b6c9de --- /dev/null +++ b/.gitattributes @@ -0,0 +1 @@ +bin/updateDoc export-ignore diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..3fec32c --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +tmp/ diff --git a/bin/updateDoc b/bin/updateDoc new file mode 100755 index 0000000..48454f2 --- /dev/null +++ b/bin/updateDoc @@ -0,0 +1,317 @@ +#!/usr/bin/env php + $methods) { + + $explodedHelpLv1Content = explode(PHP_EOL, $methods['content']); + $explodedHelpLv1Content = ltrimArray($explodedHelpLv1Content); + $explodedHelpLv1Content = rtrimArray($explodedHelpLv1Content); + $helps['level1'][$asserter]['content'] = implode(PHP_EOL, $explodedHelpLv1Content); + + foreach ($methods['level2'] as $methodName => $help) { + $explodedHelp = explode(PHP_EOL, $help['content']); + $explodedHelp = ltrimArray($explodedHelp); + $explodedHelp = rtrimArray($explodedHelp); + $helps['level1'][$asserter]['level2'][$methodName]['content'] = implode(PHP_EOL, $explodedHelp); + if (isset($helps['level1'][$asserter]['level2'][$methodName]['level3'])) { + foreach ($helps['level1'][$asserter]['level2'][$methodName]['level3'] as $level3Name => $helpLvl3) { + $explodedHelp = explode(PHP_EOL, $helpLvl3['content']); + $explodedHelp = ltrimArray($explodedHelp); + $explodedHelp = rtrimArray($explodedHelp); + $helps['level1'][$asserter]['level2'][$methodName]['level3'][$level3Name]['content'] = implode(PHP_EOL, $explodedHelp); + } + } + } + } + + return $helps; +} + +function ltrimArray(array $array) { + $tmpArray = array(); + $isArrayBegin = true; + foreach ($array as $line) { + if ($isArrayBegin && (preg_match('/^[-~=]+$/', $line) || 0 === strlen(trim($line)))) { + continue; + } + $isArrayBegin = false; + $tmpArray[] = $line; + } + + + return $tmpArray; +} + +function rtrimArray(array $array) { + return array_reverse(ltrimArray(array_reverse($array))); +} + +function getLevel2Content(array $helps, $level1Name, $level2Name) +{ + if (!isset($helps['level1'][$level1Name]['level2'][$level2Name])) { + throw new \RuntimeException(sprintf('Class : %s, Method %s. Documentation not found', $level1Name, $level2Name)); + } + + return $helps['level1'][$level1Name]['level2'][$level2Name]['content']; +} + +function getMethodHelp(\ReflectionMethod $method, array $helps) +{ + $shortClassname = strtolower($method->getDeclaringClass()->getShortName()); + $methodName = strtolower($method->getName()); + return getLevel2Content($helps, $shortClassname, $methodName); +} + +function getPropertyHelp(\ReflectionProperty $property, array $helps) +{ + $shortClassname = strtolower($property->getDeclaringClass()->getShortName()); + $methodName = strtolower($property->getName()); + return getLevel2Content($helps, $shortClassname, $methodName); +} + +function getClassHelp(\ReflectionClass $class, array $helps) +{ + $shortClassname = strtolower($class->getShortName()); + + if (!isset($helps['level1'][$shortClassname])) { + throw new \RuntimeException(sprintf('Class : %s. Documentation not found', $shortClassname)); + } + + return $helps['level1'][$shortClassname]['content']; +} + +function applyMappings(array $helps) +{ + $helps['level1']['phpstring'] = $helps['level1']['string']; + $helps['level1']['phparray'] = $helps['level1']['array']; + $helps['level1']['phpclass'] = $helps['level1']['class']; + $helps['level1']['phpfloat'] = $helps['level1']['float']; + $helps['level1']['adapter'] = array_merge($helps['level1']['mock']['level2']['call'], $helps['level1']['mock']); + $helps['level1']['adapter']['level2'] = array_merge($helps['level1']['adapter']['level2'], $helps['level1']['adapter']['level3']); + unset($helps['level1']['adapter']['level3']); + $helps['level1']['adapter']['level2']['once'] = $helps['level1']['adapter']['level2']['once/twice/thrice']; + $helps['level1']['adapter']['level2']['twice'] = $helps['level1']['adapter']['level2']['once/twice/thrice']; + $helps['level1']['adapter']['level2']['thrice'] = $helps['level1']['adapter']['level2']['once/twice/thrice']; + return $helps; +} + +function replaceHelpDoc($docComment, $spacesCount, \closure $helpCallback) +{ + $docComment = explode(PHP_EOL, $docComment); + $firstAnnotation = 0; + + foreach ($docComment as $k => $comment) + { + if (preg_match('/^\s+\*\s+@/', $comment) || (preg_match('/^\s+\*\//', $comment))) + { + $firstAnnotation = $k; + + break; + } + } + + try { + $methodHelpLines = explode(PHP_EOL, $helpCallback()); + $methodHelpLines[] = ''; + } catch (\RuntimeException $e) { + return implode(PHP_EOL, $docComment); + } + + + if (count($methodHelpLines) === 1 && $methodHelpLines[0] == '') { + return implode(PHP_EOL, $docComment); + } + + $methodHelp = ''; + foreach ($methodHelpLines as $methodHelpLine) { + $methodHelpLine = preg_replace('/^.. (\w+)::/', '$1: ', $methodHelpLine); + $methodHelpLine = preg_replace('/:ref:`(\w+) <.*?>`/', '$1', $methodHelpLine); + + if (preg_match('/^\s*..\s+[\w\-]+:/', $methodHelpLine)) { + continue; + } + + if (preg_match('/^\s+\|\s/', $methodHelpLine)) { + $methodHelpLine = ltrim($methodHelpLine, ' |'); + } + + $methodHelp .= str_repeat(' ', $spacesCount) . '* ' . rtrim($methodHelpLine) . PHP_EOL; + } + + $methodHelp = preg_replace('/(?:\s{' . $spacesCount . '}\*\s*\n)+/', str_repeat(' ', $spacesCount) . '*' . PHP_EOL, $methodHelp); + $methodHelp = rtrim($methodHelp); + + $doc = '/**' . PHP_EOL; + $doc .= $methodHelp; + $doc .= $methodHelp !== '' ? PHP_EOL : ''; + $doc .= implode(PHP_EOL, array_slice($docComment, $firstAnnotation)); + + return $doc; +} + + +function replaceInFile($file, $docComment, $newDocComment, $suffix) +{ + return file_put_contents( + $file, + preg_replace_callback( + sprintf('/(%s)([\w\s]+%s)/msi', preg_quote($docComment, '/'), preg_quote($suffix, '/s')), + function ($matches) use ($newDocComment) { + return $newDocComment . $matches[2]; + }, + file_get_contents($file) + ) + ); +} + +function updateFile($file, $className, array $helps) +{ + $refectionClass = new \ReflectionClass($className); + foreach ($refectionClass->getMethods() as $method) { + if ($className != $method->getDeclaringClass()->getName()) { + continue; + } + + if (strtolower($method->getName()) == 'isreferenceto') { + continue; + } + + $newDocComment = replaceHelpDoc( + $method->getDocComment(), + 5, + function() use ($helps, $method) { + return getMethodHelp($method, $helps); + } + ); + + replaceInFile($file, $method->getDocComment(), $newDocComment, 'function ' . $method->getName() . "("); + } + + foreach ($refectionClass->getProperties() as $property) { + if ($className != $property->getDeclaringClass()->getName()) { + continue; + } + + $newPropertyDocComment = replaceHelpDoc( + $property->getDocComment(), + 5, + function() use ($helps, $property){ + return getPropertyHelp($property, $helps); + } + ); + + replaceInFile($file, $property->getDocComment(), $newPropertyDocComment, 'public $' . $property->getName() . ";"); + } + + if (false !== $refectionClass->getDocComment()) { + $newClassDocComment = replaceHelpDoc( + $refectionClass->getDocComment(), + 1, + function() use ($helps, $refectionClass){ + return getClassHelp($refectionClass, $helps); + } + ); + replaceInFile($file, $refectionClass->getDocComment(), $newClassDocComment, $refectionClass->getShortName()); + } +} + +passthru('rm -rf tmp && mkdir -p tmp && cd tmp && git clone https://github.com/atoum/atoum-documentation.git && cd atoum-documentation && ./builddoc text'); + +$assertersDocFile = 'tmp/atoum-documentation/build/en/text/asserters.txt'; + +//be careful with the order of the class (because of some extends) +$asserters = array( + 'classes/mageekguy/atoum/stubs/asserters/variable.php', + 'classes/mageekguy/atoum/stubs/asserters/boolean.php', + 'classes/mageekguy/atoum/stubs/asserters/object.php', + 'classes/mageekguy/atoum/stubs/asserters/dateInterval.php', + 'classes/mageekguy/atoum/stubs/asserters/dateTime.php', + 'classes/mageekguy/atoum/stubs/asserters/error.php', + 'classes/mageekguy/atoum/stubs/asserters/exception.php', + 'classes/mageekguy/atoum/stubs/asserters/phpString.php', + 'classes/mageekguy/atoum/stubs/asserters/hash.php', + 'classes/mageekguy/atoum/stubs/asserters/integer.php', + 'classes/mageekguy/atoum/stubs/asserters/phpArray.php', + 'classes/mageekguy/atoum/stubs/asserters/phpClass.php', + 'classes/mageekguy/atoum/stubs/asserters/phpFloat.php', + 'classes/mageekguy/atoum/stubs/asserters/adapter.php', + 'classes/mageekguy/atoum/stubs/asserters/mock.php', + 'classes/mageekguy/atoum/stubs/asserters/mysqlDateTime.php', + 'classes/mageekguy/atoum/stubs/asserters/castToString.php', + 'classes/mageekguy/atoum/stubs/asserters/sizeOf.php', + 'classes/mageekguy/atoum/stubs/asserters/stream.php', + 'classes/mageekguy/atoum/stubs/asserters/utf8String.php', + 'classes/mageekguy/atoum/stubs/asserters/output.php', +); + +include 'classes/mageekguy/atoum/stubs/asserters.php'; +foreach ($asserters as $asserter) { + include $asserter; +} + +$helps = parseFile($assertersDocFile); + +$helps = applyMappings($helps); + +foreach ($asserters as $asserter) { + $path = explode('/', $asserter); + $filename = array_pop($path); + $className = pathinfo($filename, PATHINFO_FILENAME); + updateFile($asserter, 'mageekguy\\atoum\\stubs\\asserters\\' . $className, $helps); +} + diff --git a/classes/mageekguy/atoum/stubs/asserters/adapter.php b/classes/mageekguy/atoum/stubs/asserters/adapter.php index 941cfcc..b3ab5f9 100644 --- a/classes/mageekguy/atoum/stubs/asserters/adapter.php +++ b/classes/mageekguy/atoum/stubs/asserters/adapter.php @@ -9,6 +9,24 @@ class adapter use asserters; /** + * "call" let you specify which method of the mock to check, his call + * must be followed by a call to one of the following verification method + * like atLeastOnce, once/twice/thrice, exactly, etc... + * + * 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() + * ; + * * @param string $function * * @return $this @@ -16,6 +34,34 @@ class adapter public function call($function) {} /** + * "before" checks if the method has been called before the one passed as + * parameter. + * + * 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 + * ; + * * @param adapter $call * * @return $this @@ -23,6 +69,34 @@ public function call($function) {} public function before(self $call) {} /** + * "after" checks if the method has been called after the one passed as + * parameter. + * + * 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 + * ; + * * @param adapter $call * * @return $this @@ -30,6 +104,34 @@ public function before(self $call) {} public function after(self $call) {} /** + * This asserters check that the tested method (see *call*) from the + * tested mock has been called exactly: + * + * * once + * + * * twice + * + * * thrice + * + * 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)", ":ref:`exactly `(2)" and "exactly(3)". + * * @param string $failMessage * * @return $this @@ -37,6 +139,34 @@ public function after(self $call) {} public function once($failMessage = null) {} /** + * This asserters check that the tested method (see *call*) from the + * tested mock has been called exactly: + * + * * once + * + * * twice + * + * * thrice + * + * 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)", ":ref:`exactly `(2)" and "exactly(3)". + * * @param string $failMessage * * @return $this @@ -44,6 +174,34 @@ public function once($failMessage = null) {} public function twice($failMessage = null) {} /** + * This asserters check that the tested method (see *call*) from the + * tested mock has been called exactly: + * + * * once + * + * * twice + * + * * thrice + * + * 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)", ":ref:`exactly `(2)" and "exactly(3)". + * * @param string $failMessage * * @return $this @@ -51,6 +209,20 @@ public function twice($failMessage = null) {} public function thrice($failMessage = null) {} /** + * "atLeastOnce" check that the tested method (see *call*) from the mock + * has been called at least once. + * + * object(new MySecondClass($mock)) + * + * ->mock($mock) + * ->call('myMethod') + * ->atLeastOnce() + * ; + * * @param string $failMessage * * @return $this @@ -58,6 +230,20 @@ public function thrice($failMessage = null) {} public function atLeastOnce($failMessage = null) {} /** + * "exactly" check that the tested method (see *call*) has been called a + * specific number of times. + * + * object(new MySecondClass($mock)) + * + * ->mock($mock) + * ->call('myMethod') + * ->exactly(2) + * ; + * * @param integer $number * @param string $failMessage * @@ -66,6 +252,22 @@ public function atLeastOnce($failMessage = null) {} public function exactly($number, $failMessage = null) {} /** + * "never" check that the tested method (see *call*) has never been + * called. + * + * object(new MySecondClass($mock)) + * + * ->mock($mock) + * ->call('myMethod') + * ->never() + * ; + * + * Note: "never" is equivalent to "exactly(0)". + * * @param string $failMessage * * @return $this @@ -73,6 +275,22 @@ public function exactly($number, $failMessage = null) {} public function never($failMessage = null) {} /** + * "withArguments" let you specify the expected arguments that the tested + * method should receive when called (see *call*). + * + * object(new MySecondClass($mock)) + * + * ->mock($mock) + * ->call('myMethod') + * ->withArguments('first', 'second')->once() + * ; + * + * also want to check the type, use *withIdenticalArguments*. + * * @param mixed ...$arguments * * @return $this @@ -80,6 +298,22 @@ public function never($failMessage = null) {} public function withArguments(...$arguments) {} /** + * "withIdenticalArguments" let you specify the expected arguments that + * tested method should receive when called (see *call*). + * + * object(new MySecondClass($mock)) + * + * ->mock($mock) + * ->call('myMethod') + * ->withIdenticalArguments('first', 'second')->once() + * ; + * + * If you do not want to check the type, use *withArguments*. + * * @param mixed ...$arguments * * @return $this @@ -87,6 +321,23 @@ public function withArguments(...$arguments) {} public function withIdenticalArguments(...$arguments) {} /** + * "withAtLeastArguments" let you specify the minimum expected arguments + * that tested method should receive when called (see *call*). + * + * 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 + * ; + * + * If you also want to check the type, use + * *withAtLeastIdenticalArguments*. + * * @param mixed[] $arguments * * @return $this @@ -94,6 +345,22 @@ public function withIdenticalArguments(...$arguments) {} public function withAtLeastArguments(array $arguments) {} /** + * "withAtLeastIdenticalArguments" let you specify the minimum expected + * arguments that tested method should receive when called (see *call*). + * + * 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 + * ; + * + * If you do not want to check the type, use *withIdenticalArguments*. + * * @param mixed[] $arguments * * @return $this @@ -101,11 +368,50 @@ public function withAtLeastArguments(array $arguments) {} public function withAtLeastIdenticalArguments(array $arguments) {} /** + * "withAnyArguments" allow to check any argument, non-specified, when we + * call the tested method (see *call*) of the tested mock. + * + * This method is useful to reset the arguments of the tested method, + * like in the following example: + * + * object(new MySecondClass($mock)) + * + * ->mock($mock) + * ->call('myMethod') + * ->withArguments('first') ->once() + * ->withArguments('second') ->once() + * ->withAnyArguments()->exactly(2) + * ; + * * @return $this */ public function withAnyArguments() {} /** + * "withoutAnyArgument" lets you indicate that the method should not + * receive any argument when called (see *call*). + * + * 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())". + * * @return $this */ public function withoutAnyArgument() {} diff --git a/classes/mageekguy/atoum/stubs/asserters/boolean.php b/classes/mageekguy/atoum/stubs/asserters/boolean.php index b3c2ed2..0877500 100644 --- a/classes/mageekguy/atoum/stubs/asserters/boolean.php +++ b/classes/mageekguy/atoum/stubs/asserters/boolean.php @@ -2,10 +2,33 @@ namespace mageekguy\atoum\stubs\asserters; - +/** + * This is the assertion dedicated to the booleans. + * + * If you try to test a variable that is not a boolean with this + * assertion, this 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. + * + */ class boolean extends variable { /** + * "isFalse" check that the boolean is strictly equal to "false". + * + * boolean($true) + * ->isFalse() // fails + * + * ->boolean($false) + * ->isFalse() // succeed + * ; + * * @var static * * @link http://docs.atoum.org/en/latest/asserters.html#isfalse @@ -13,6 +36,20 @@ class boolean extends variable public $isFalse; /** + * "isTrue" checks that the boolean is strictly equal to "true". + * + * boolean($true) + * ->isTrue() // succeed + * + * ->boolean($false) + * ->isTrue() // fails + * ; + * * @var static * * @link http://docs.atoum.org/en/latest/asserters.html#istrue @@ -20,6 +57,20 @@ class boolean extends variable public $isTrue; /** + * "isTrue" checks that the boolean is strictly equal to "true". + * + * boolean($true) + * ->isTrue() // succeed + * + * ->boolean($false) + * ->isTrue() // fails + * ; + * * @param string $failMessage * * @link http://docs.atoum.org/en/latest/asserters.html#istrue @@ -29,6 +80,20 @@ class boolean extends variable public function isTrue($failMessage = null) {} /** + * "isFalse" check that the boolean is strictly equal to "false". + * + * boolean($true) + * ->isFalse() // fails + * + * ->boolean($false) + * ->isFalse() // succeed + * ; + * * @param string $failMessage * * @link http://docs.atoum.org/en/latest/asserters.html#isfalse diff --git a/classes/mageekguy/atoum/stubs/asserters/castToString.php b/classes/mageekguy/atoum/stubs/asserters/castToString.php index 178f487..883ce35 100644 --- a/classes/mageekguy/atoum/stubs/asserters/castToString.php +++ b/classes/mageekguy/atoum/stubs/asserters/castToString.php @@ -2,5 +2,23 @@ namespace mageekguy\atoum\stubs\asserters; - +/** + * It's the assertion dedicated to tests on the cast of objects to + * strings. + * + * version; + * } + * } + * + * $this + * ->castToString(new AtoumVersion()) + * ->isEqualTo('atoum v1.0') + * ; + * + */ class castToString extends phpString {} diff --git a/classes/mageekguy/atoum/stubs/asserters/dateInterval.php b/classes/mageekguy/atoum/stubs/asserters/dateInterval.php index ad48993..b0295c4 100644 --- a/classes/mageekguy/atoum/stubs/asserters/dateInterval.php +++ b/classes/mageekguy/atoum/stubs/asserters/dateInterval.php @@ -2,10 +2,32 @@ namespace mageekguy\atoum\stubs\asserters; - +/** + * It's the assertion dedicated to the object DateInterval. + * + * If you try to test a value that's not a "DateInterval" (or a child + * class) with this assertion it will fail. + * + */ class dateInterval extends object { /** + * "isGreaterThan" checks that the duration of the object "DateInterval" + * is longer to the duration of the given "DateInterval" object. + * + * dateInterval($di) + * ->isGreaterThan( // passes + * new DateInterval('P1D') + * ) + * ->isGreaterThan( // fails + * new DateInterval('P2D') + * ) + * ; + * * @param \dateInterval $interval * @param string $failMessage * @@ -16,6 +38,26 @@ class dateInterval extends object public function isGreaterThan(\dateInterval $interval, $failMessage = null) {} /** + * "isGreaterThanOrEqualTo" checks that the duration of the object + * "DateInterval" is longer or equals to the duration of another object + * "DateInterval". + * + * dateInterval($di) + * ->isGreaterThanOrEqualTo( // passes + * new DateInterval('P1D') + * ) + * ->isGreaterThanOrEqualTo( // passes + * new DateInterval('P2D') + * ) + * ->isGreaterThanOrEqualTo( // fails + * new DateInterval('P3D') + * ) + * ; + * * @param \dateInterval $interval * @param string $failMessage * @@ -26,6 +68,22 @@ public function isGreaterThan(\dateInterval $interval, $failMessage = null) {} public function isGreaterThanOrEqualTo(\dateInterval $interval, $failMessage = null) {} /** + * "isLessThan" checks that the duration of the object "DateInterval" is + * shorter than the duration of the given "DateInterval" object. + * + * dateInterval($di) + * ->isLessThan( // passes + * new DateInterval('P2D') + * ) + * ->isLessThan( // fails + * new DateInterval('P1D') + * ) + * ; + * * @param \dateInterval $interval * @param string $failMessage * @@ -36,6 +94,26 @@ public function isGreaterThanOrEqualTo(\dateInterval $interval, $failMessage = n public function isLessThan(\dateInterval $interval, $failMessage = null) {} /** + * "isLessThanOrEqualTo" checks that the duration of the object + * "DateInterval" is shorter or equals to the duration of another object + * "DateInterval". + * + * dateInterval($di) + * ->isLessThanOrEqualTo( // passes + * new DateInterval('P3D') + * ) + * ->isLessThanOrEqualTo( // passes + * new DateInterval('P2D') + * ) + * ->isLessThanOrEqualTo( // fails + * new DateInterval('P1D') + * ) + * ; + * * @param \dateInterval $interval * @param string $failMessage * diff --git a/classes/mageekguy/atoum/stubs/asserters/dateTime.php b/classes/mageekguy/atoum/stubs/asserters/dateTime.php index 0b684b4..ace6d8f 100644 --- a/classes/mageekguy/atoum/stubs/asserters/dateTime.php +++ b/classes/mageekguy/atoum/stubs/asserters/dateTime.php @@ -2,7 +2,13 @@ namespace mageekguy\atoum\stubs\asserters; - +/** + * It's the assertion dedicated to the object DateTime. + * + * If you try to test a value that's not a "DateTime" (or a child class) + * with this assertion it will fail. + * + */ class dateTime extends object { /** @@ -11,6 +17,16 @@ class dateTime extends object public $isImmutable; /** + * "hasTimezone" checks the timezone of the "DateTime" object. + * + * dateTime($dt) + * ->hasTimezone('Europe/Paris') + * ; + * * @param \dateTimezone $timezone * @param string $failMessage * @@ -21,6 +37,16 @@ class dateTime extends object public function hasTimezone(\dateTimezone $timezone, $failMessage = null) {} /** + * "hasYear" checks the year of the "DateTime" object. + * + * dateTime($dt) + * ->hasYear(1981) // passes + * ; + * * @param integer $year * @param string $failMessage * @@ -31,6 +57,16 @@ public function hasTimezone(\dateTimezone $timezone, $failMessage = null) {} public function hasYear($year, $failMessage = null) {} /** + * "hasMonth" checks the month part of objet "DateTime". + * + * dateTime($dt) + * ->hasMonth(2) // passes + * ; + * * @param integer $month * @param string $failMessage * @@ -41,6 +77,16 @@ public function hasYear($year, $failMessage = null) {} public function hasMonth($month, $failMessage = null) {} /** + * "hasDay" checks the day of the "DateTime" object. + * + * dateTime($dt) + * ->hasDay(13) // passes + * ; + * * @param integer $day * @param string $failMessage * @@ -51,6 +97,18 @@ public function hasMonth($month, $failMessage = null) {} public function hasDay($day, $failMessage = null) {} /** + * "hasDate" checks the date part of object "DateTime". + * + * dateTime($dt) + * ->hasDate('1981', '02', '13') // passes + * ->hasDate('1981', '2', '13') // passes + * ->hasDate(1981, 2, 13) // passes + * ; + * * @param integer $year * @param integer $month * @param integer $day @@ -63,6 +121,18 @@ public function hasDay($day, $failMessage = null) {} public function hasDate($year, $month, $day, $failMessage = null) {} /** + * "hasHours" checks the time of the objet "DateTime". + * + * dateTime($dt) + * ->hasHours('01') // passes + * ->hasHours('1') // passes + * ->hasHours(1) // passes + * ; + * * @param integer $hours * @param string $failMessage * @@ -73,6 +143,18 @@ public function hasDate($year, $month, $day, $failMessage = null) {} public function hasHours($hours, $failMessage = null) {} /** + * "hasMinutes" checks the minutes part of the objet "DateTime". + * + * dateTime($dt) + * ->hasMinutes('02') // passes + * ->hasMinutes('2') // passes + * ->hasMinutes(2) // passes + * ; + * * @param integer $minutes * @param string $failMessage * @@ -83,6 +165,18 @@ public function hasHours($hours, $failMessage = null) {} public function hasMinutes($minutes, $failMessage = null) {} /** + * "hasSeconds" checks the seconds of the "DateTime" object. + * + * dateTime($dt) + * ->hasSeconds('03') // passes + * ->hasSeconds('3') // passes + * ->hasSeconds(3) // passes + * ; + * * @param integer $seconds * @param string $failMessage * @@ -93,6 +187,18 @@ public function hasMinutes($minutes, $failMessage = null) {} public function hasSeconds($seconds, $failMessage = null) {} /** + * "hasTime" checks the time part of the objet "DateTime" + * + * dateTime($dt) + * ->hasTime('01', '02', '03') // passes + * ->hasTime('1', '2', '3') // passes + * ->hasTime(1, 2, 3) // passes + * ; + * * @param integer $hours * @param integer $minutes * @param integer $seconds @@ -105,6 +211,21 @@ public function hasSeconds($seconds, $failMessage = null) {} public function hasTime($hours, $minutes, $seconds, $failMessage = null) {} /** + * "hasDateAndTime" checks the date and the hour of the objet "DateTime" + * + * 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) + * ; + * * @param integer $year * @param integer $month * @param integer $day diff --git a/classes/mageekguy/atoum/stubs/asserters/error.php b/classes/mageekguy/atoum/stubs/asserters/error.php index d37618d..926ed9a 100644 --- a/classes/mageekguy/atoum/stubs/asserters/error.php +++ b/classes/mageekguy/atoum/stubs/asserters/error.php @@ -4,11 +4,56 @@ use mageekguy\atoum\stubs\asserters; +/** + * It's assertion dedicated to errors. + * + * 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. + * + */ class error { use asserters; /** + * "exists" checks that an error was raised during the execution of the + * previous code. + * + * when( + * function() { + * trigger_error('message'); + * } + * ) + * ->error() + * ->exists() // pass + * + * ->when( + * function() { + * // code without error + * } + * ) + * ->error() + * ->exists() // failed + * ; + * * @var static * * @link http://docs.atoum.org/en/latest/asserters.html#exists @@ -16,6 +61,28 @@ class error public $exists; /** + * "notExists" checks that an error was raised during the execution of + * the previous code. + * + * when( + * function() { + * trigger_error('message'); + * } + * ) + * ->error() + * ->notExists() // fails + * + * ->when( + * function() { + * // code without error + * } + * ) + * ->error() + * ->notExists() // pass + * ; + * * @var static * * @link http://docs.atoum.org/en/latest/asserters.html#notexists @@ -23,16 +90,100 @@ class error public $notExists; /** + * "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 is here if you want + * to add semantic to your test. + * + * when( + * function() { + * trigger_error('message'); + * } + * ) + * ->error() + * ->withAnyType() // pass + * ->exists() + * ->when( + * function() { + * } + * ) + * ->error() + * ->withAnyType() + * ->exists() // fails + * ; + * * @var static */ public $withAnyType; /** + * "withAnyMessage" does not check the error message. That's the default + * behaviour. So "->error()->withAnyMessage()->exists()" is the + * equivalent of "->error()->exists()". This method is here if you want + * to add semantic to your test. + * + * 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 + * ; + * * @var static */ public $withAnyMessage; /** + * "exists" checks that an error was raised during the execution of the + * previous code. + * + * when( + * function() { + * trigger_error('message'); + * } + * ) + * ->error() + * ->exists() // pass + * + * ->when( + * function() { + * // code without error + * } + * ) + * ->error() + * ->exists() // failed + * ; + * * @link http://docs.atoum.org/en/latest/asserters.html#exists * * @return $this @@ -40,6 +191,28 @@ class error public function exists() {} /** + * "notExists" checks that an error was raised during the execution of + * the previous code. + * + * when( + * function() { + * trigger_error('message'); + * } + * ) + * ->error() + * ->notExists() // fails + * + * ->when( + * function() { + * // code without error + * } + * ) + * ->error() + * ->notExists() // pass + * ; + * * @link http://docs.atoum.org/en/latest/asserters.html#notexists * * @return $this @@ -47,6 +220,29 @@ public function exists() {} public function notExists() {} /** + * "withType" checks the type of the raised error. + * + * when( + * function() { + * trigger_error('message'); + * } + * ) + * ->error() + * ->withType(E_USER_NOTICE) // pass + * ->exists() + * + * ->when( + * function() { + * trigger_error('message'); + * } + * ) + * ->error() + * ->withType(E_USER_WARNING) // fails + * ->exists() + * ; + * * @param integer $type * * @link http://docs.atoum.org/en/latest/asserters.html#withtype @@ -56,11 +252,60 @@ public function notExists() {} public function withType($type) {} /** + * "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 is here if you want + * to add semantic to your test. + * + * when( + * function() { + * trigger_error('message'); + * } + * ) + * ->error() + * ->withAnyType() // pass + * ->exists() + * ->when( + * function() { + * } + * ) + * ->error() + * ->withAnyType() + * ->exists() // fails + * ; + * * @return $this */ public function withAnyType() {} /** + * "withMessage" checks the message content of the raised error. + * + * when( + * function() { + * trigger_error('message'); + * } + * ) + * ->error() + * ->withMessage('message') + * ->exists() // passes + * ; + * + * $this + * ->when( + * function() { + * trigger_error('message'); + * } + * ) + * ->error() + * ->withMessage('MESSAGE') + * ->exists() // fails + * ; + * * @param string $message * * @return $this @@ -75,6 +320,44 @@ public function withMessage($message) {} public function withPattern($pattern) {} /** + * "withAnyMessage" does not check the error message. That's the default + * behaviour. So "->error()->withAnyMessage()->exists()" is the + * equivalent of "->error()->exists()". This method is here if you want + * to add semantic to your test. + * + * 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 + * ; + * * @return $this */ public function withAnyMessage() {} diff --git a/classes/mageekguy/atoum/stubs/asserters/exception.php b/classes/mageekguy/atoum/stubs/asserters/exception.php index a620c99..0bf108f 100644 --- a/classes/mageekguy/atoum/stubs/asserters/exception.php +++ b/classes/mageekguy/atoum/stubs/asserters/exception.php @@ -2,10 +2,58 @@ namespace mageekguy\atoum\stubs\asserters; - +/** + * It's the assertion dedicated to exceptions. + * + * 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". + * + * 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 + * + */ class exception extends object { /** + * "hasDefaultCode" checks that the code of the exception is the default + * value, 0. + * + * exception( + * function() use($myObject) { + * // this code throws an exception: throw new \Exception; + * $myObject->doOneThing('wrongParameter'); + * } + * ) + * ->hasDefaultCode() + * ; + * + * Note: "hasDefaultCode" is equivalent to "hasCode(0)". + * * @var static * * @link http://docs.atoum.org/en/latest/asserters.html#hasdefaultcode @@ -13,11 +61,41 @@ class exception extends object public $hasDefaultCode; /** + * "message" enables you to get an asserter of type *string* containing + * the message of the tested exception. + * + * exception( + * function() { + * throw new \Exception('My custom message to test'); + * } + * ) + * ->message + * ->contains('message') + * ; + * * @var phpString */ public $message; /** + * "hasDefaultCode" checks that the code of the exception is the default + * value, 0. + * + * exception( + * function() use($myObject) { + * // this code throws an exception: throw new \Exception; + * $myObject->doOneThing('wrongParameter'); + * } + * ) + * ->hasDefaultCode() + * ; + * + * Note: "hasDefaultCode" is equivalent to "hasCode(0)". + * * @param string $failMessage * * @link http://docs.atoum.org/en/latest/asserters.html#hasdefaultcode @@ -27,6 +105,19 @@ class exception extends object public function hasDefaultCode($failMessage = null) {} /** + * "hasCode" checks the code of the exception. + * + * exception( + * function() use($myObject) { + * // This code throws a exception: throw new \Exception('Message', 42); + * $myObject->doOneThing('wrongParameter'); + * } + * ) + * ->hasCode(42) + * ; + * * @param integer $code * @param string $failMessage * @@ -37,6 +128,20 @@ public function hasDefaultCode($failMessage = null) {} public function hasCode($code, $failMessage = null) {} /** + * "hasMessage" checks the message from the exception. + * + * exception( + * function() use($myObject) { + * // This code throws a exception: throw new \Exception('Message'); + * $myObject->doOneThing('wrongParameter'); + * } + * ) + * ->hasMessage('Message') // passes + * ->hasMessage('message') // fails + * ; + * * @param string $message * @param string $failMessage * @@ -47,6 +152,41 @@ public function hasCode($code, $failMessage = null) {} public function hasMessage($message, $failMessage = null) {} /** + * "hasNestedException" checks that the exception contains a reference to + * another exception. If the type of the exception is given, this will + * also checks the class of the exception. + * + * 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 + * ; + * * @param \exception $exception * @param string $failMessage * diff --git a/classes/mageekguy/atoum/stubs/asserters/hash.php b/classes/mageekguy/atoum/stubs/asserters/hash.php index ccacd88..b444d87 100644 --- a/classes/mageekguy/atoum/stubs/asserters/hash.php +++ b/classes/mageekguy/atoum/stubs/asserters/hash.php @@ -2,10 +2,28 @@ namespace mageekguy\atoum\stubs\asserters; - +/** + * It's the assertion dedicated to tests on hashes (digital + * fingerprints). + * + */ class hash extends phpString { /** + * "isSha1" checks that the string is a "sha1" format, i.e. a + * hexadecimale string of 40 length. + * + * hash($hash) + * ->isSha1() // passes + * ->hash($notHash) + * ->isSha1() // fails + * ; + * * @var static * * @link http://docs.atoum.org/en/latest/asserters.html#issha1 @@ -13,6 +31,20 @@ class hash extends phpString public $isSha1; /** + * "isSha256" checks that the string is a "sha256" format, i.e. a + * hexadecimale string of 64 length. + * + * hash($hash) + * ->isSha256() // passes + * ->hash($notHash) + * ->isSha256() // fails + * ; + * * @var static * * @link http://docs.atoum.org/en/latest/asserters.html#issha256 @@ -20,6 +52,20 @@ class hash extends phpString public $isSha256; /** + * "isSha512" checks that the string is a "sha512" format, i.e. a + * hexadecimale string of 128 length. + * + * hash($hash) + * ->isSha512() // passes + * ->hash($notHash) + * ->isSha512() // fails + * ; + * * @var static * * @link http://docs.atoum.org/en/latest/asserters.html#issha512 @@ -27,6 +73,20 @@ class hash extends phpString public $isSha512; /** + * "isMd5" checks that the string is a "md5" format, i.r. a hexadecimale + * string of 32 length. + * + * hash($hash) + * ->isMd5() // passes + * ->hash($notHash) + * ->isMd5() // fails + * ; + * * @var static * * @link http://docs.atoum.org/en/latest/asserters.html#ismd5 @@ -34,6 +94,20 @@ class hash extends phpString public $isMd5; /** + * "isSha1" checks that the string is a "sha1" format, i.e. a + * hexadecimale string of 40 length. + * + * hash($hash) + * ->isSha1() // passes + * ->hash($notHash) + * ->isSha1() // fails + * ; + * * @param string $failMessage * * @link http://docs.atoum.org/en/latest/asserters.html#issha1 @@ -43,6 +117,20 @@ class hash extends phpString public function isSha1($failMessage = null) {} /** + * "isSha256" checks that the string is a "sha256" format, i.e. a + * hexadecimale string of 64 length. + * + * hash($hash) + * ->isSha256() // passes + * ->hash($notHash) + * ->isSha256() // fails + * ; + * * @param string $failMessage * * @link http://docs.atoum.org/en/latest/asserters.html#issha256 @@ -52,6 +140,20 @@ public function isSha1($failMessage = null) {} public function isSha256($failMessage = null) {} /** + * "isSha512" checks that the string is a "sha512" format, i.e. a + * hexadecimale string of 128 length. + * + * hash($hash) + * ->isSha512() // passes + * ->hash($notHash) + * ->isSha512() // fails + * ; + * * @param string $failMessage * * @link http://docs.atoum.org/en/latest/asserters.html#issha512 @@ -61,6 +163,20 @@ public function isSha256($failMessage = null) {} public function isSha512($failMessage = null) {} /** + * "isMd5" checks that the string is a "md5" format, i.r. a hexadecimale + * string of 32 length. + * + * hash($hash) + * ->isMd5() // passes + * ->hash($notHash) + * ->isMd5() // fails + * ; + * * @param string $failMessage * * @link http://docs.atoum.org/en/latest/asserters.html#ismd5 diff --git a/classes/mageekguy/atoum/stubs/asserters/integer.php b/classes/mageekguy/atoum/stubs/asserters/integer.php index a1db47c..ea91ae3 100644 --- a/classes/mageekguy/atoum/stubs/asserters/integer.php +++ b/classes/mageekguy/atoum/stubs/asserters/integer.php @@ -2,10 +2,35 @@ namespace mageekguy\atoum\stubs\asserters; - +/** + * It's the assertion dedicated to integers. + * + * If you try to test a variable that is not an integer with this + * assertion, this 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. + * + */ class integer extends variable { /** + * "isZero" checks that the integer is equal to 0. + * + * integer($zero) + * ->isZero() // passes + * + * ->integer($notZero) + * ->isZero() // fails + * ; + * + * Note: "isZero" is equivalent to "isEqualTo(0)". + * * @var static * * @link http://docs.atoum.org/en/latest/asserters.html#integer-is-zero @@ -13,6 +38,22 @@ class integer extends variable public $isZero; /** + * "isZero" checks that the integer is equal to 0. + * + * integer($zero) + * ->isZero() // passes + * + * ->integer($notZero) + * ->isZero() // fails + * ; + * + * Note: "isZero" is equivalent to "isEqualTo(0)". + * * @param string $failMessage * * @link http://docs.atoum.org/en/latest/asserters.html#integer-is-zero @@ -22,6 +63,20 @@ class integer extends variable public function isZero($failMessage = null) {} /** + * "isGreaterThan" checks that the integer is strictly higher than the + * given one. + * + * integer($zero) + * ->isGreaterThan(-1) // passes + * ->isGreaterThan('-1') // fails because "-1" + * // isn't an integer + * ->isGreaterThan(0) // fails + * ; + * * @param integer|float $value * @param string $failMessage * @@ -32,6 +87,20 @@ public function isZero($failMessage = null) {} public function isGreaterThan($value, $failMessage = null) {} /** + * "isGreaterThanOrEqualTo" checks that an integer is higher or equal to + * a given one. + * + * integer($zero) + * ->isGreaterThanOrEqualTo(-1) // passes + * ->isGreaterThanOrEqualTo(0) // passes + * ->isGreaterThanOrEqualTo('-1') // fails because "-1" + * // isn't an integer + * ; + * * @param integer|float $value * @param string $failMessage * @@ -42,6 +111,19 @@ public function isGreaterThan($value, $failMessage = null) {} public function isGreaterThanOrEqualTo($value, $failMessage = null) {} /** + * "isLessThan" checks that the integer is strictly lower than a given + * one. + * + * integer($zero) + * ->isLessThan(10) // passes + * ->isLessThan('10') // fails because"10" isn't an integer + * ->isLessThan(0) // fails + * ; + * * @param integer|float $value * @param string $failMessage * @@ -52,6 +134,20 @@ public function isGreaterThanOrEqualTo($value, $failMessage = null) {} public function isLessThan($value, $failMessage = null) {} /** + * "isLessThanOrEqualTo" checks that an integer is lower or equal to a + * given one. + * + * integer($zero) + * ->isLessThanOrEqualTo(10) // passes + * ->isLessThanOrEqualTo(0) // passes + * ->isLessThanOrEqualTo('10') // fails because "10" + * // isn't an integer + * ; + * * @param integer|float $value * @param string $failMessage * diff --git a/classes/mageekguy/atoum/stubs/asserters/mock.php b/classes/mageekguy/atoum/stubs/asserters/mock.php index 8d014f9..5ef42d7 100644 --- a/classes/mageekguy/atoum/stubs/asserters/mock.php +++ b/classes/mageekguy/atoum/stubs/asserters/mock.php @@ -2,7 +2,20 @@ namespace mageekguy\atoum\stubs\asserters; - +/** + * This is the asserter for mocks. + * + * mock($mock) + * ; + * + * Note: Refer to the documentation on *mock* for more information on + * how to create and manage mocks. + * + */ class mock extends adapter { /** @@ -13,6 +26,19 @@ class mock extends adapter public function receive($function) {} /** + * "wasCalled" checks that at least one method of the mock has been + * called at least once. + * + * object(new MySecondClass($mock)) + * + * ->mock($mock) + * ->wasCalled() + * ; + * * @param string $failMessage * * @link http://docs.atoum.org/en/latest/asserters.html#wascalled @@ -22,6 +48,18 @@ public function receive($function) {} public function wasCalled($failMessage = null) {} /** + * "wasNotCalled" checks that no method of the mock has been called. + * + * object(new MySecondClass($mock)) + * + * ->mock($mock) + * ->wasNotCalled() + * ; + * * @param string $failMessage * * @link http://docs.atoum.org/en/latest/asserters.html#wasnotcalled diff --git a/classes/mageekguy/atoum/stubs/asserters/mysqlDateTime.php b/classes/mageekguy/atoum/stubs/asserters/mysqlDateTime.php index 8a17a46..b2b9367 100644 --- a/classes/mageekguy/atoum/stubs/asserters/mysqlDateTime.php +++ b/classes/mageekguy/atoum/stubs/asserters/mysqlDateTime.php @@ -2,5 +2,18 @@ namespace mageekguy\atoum\stubs\asserters; - +/** + * 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. + * + */ class mysqlDateTime extends dateTime {} diff --git a/classes/mageekguy/atoum/stubs/asserters/object.php b/classes/mageekguy/atoum/stubs/asserters/object.php index 36d6da5..d778dc0 100644 --- a/classes/mageekguy/atoum/stubs/asserters/object.php +++ b/classes/mageekguy/atoum/stubs/asserters/object.php @@ -2,7 +2,16 @@ namespace mageekguy\atoum\stubs\asserters; - +/** + * It's the assertion dedicated to objects. + * + * If you try to test a variable that is not an object with this + * assertion, this 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. + * + */ class object extends variable { /** @@ -11,6 +20,64 @@ class object extends variable public $toArray; /** + * "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. + * + * 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 namesapce imports are not taken into account. + * + * Hint: Note 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)". + * * @param string $value * @param string $failMessage * @@ -25,10 +92,22 @@ public function isInstanceOf($value, $failMessage = null) {} * @param string $failMessage * * @return $this + * */ public function isNotInstanceOf($value, $failMessage = null) {} /** + * "hasSize" checks the size of an objet that implements the interface + * "Countable". + * + * object($countableObject) + * ->hasSize(3) + * ; + * * @param integer $size * @param string $failMessage * @@ -39,6 +118,26 @@ public function isNotInstanceOf($value, $failMessage = null) {} public function hasSize($size, $failMessage = null) {} /** + * "isCloneOf" checks an object is clone of a given one, that is the + * objects are equal but are not the same instance. + * + * 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. + * * @param object $object * @param string $failMessage * @@ -49,6 +148,19 @@ public function hasSize($size, $failMessage = null) {} public function isCloneOf($object, $failMessage = null) {} /** + * "isEmpty" checks the size of an object that implements the "Countable" + * interface is equal to 0. + * + * object($countableObject) + * ->isEmpty() + * ; + * + * Note: "isEmpty" is equivalent to "hasSize(0)". + * * @param string $failMessage * * @link http://docs.atoum.org/en/latest/asserters.html#object-is-empty diff --git a/classes/mageekguy/atoum/stubs/asserters/output.php b/classes/mageekguy/atoum/stubs/asserters/output.php index 21f3984..8de1c9f 100644 --- a/classes/mageekguy/atoum/stubs/asserters/output.php +++ b/classes/mageekguy/atoum/stubs/asserters/output.php @@ -2,5 +2,22 @@ namespace mageekguy\atoum\stubs\asserters; - +/** + * It's the assertion dedicated to tests on outputs, so everything wich + * supposed to be displayed on the screen. + * + * 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. + * + */ class output extends phpString {} diff --git a/classes/mageekguy/atoum/stubs/asserters/phpArray.php b/classes/mageekguy/atoum/stubs/asserters/phpArray.php index 041023f..6dc030f 100644 --- a/classes/mageekguy/atoum/stubs/asserters/phpArray.php +++ b/classes/mageekguy/atoum/stubs/asserters/phpArray.php @@ -7,9 +7,35 @@ mageekguy\atoum\stubs\asserters ; +/** + * 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. S, you can meet both "->phpArray()" or + * "->array()". + * + * It's recommended to use only "->array()" in order to simplify the + * reading of tests. + * + */ class phpArray extends variable implements \arrayAccess { /** + * "isEmpty" checks that an array is empty. + * + * array($emptyArray) + * ->isEmpty() // passes + * + * ->array($nonEmptyArray) + * ->isEmpty() // fails + * ; + * * @var static * * @link http://docs.atoum.org/en/latest/asserters.html#isempty @@ -17,6 +43,20 @@ class phpArray extends variable implements \arrayAccess public $isEmpty; /** + * "isNotEmpty" checks that an array is not empty. + * + * array($emptyArray) + * ->isNotEmpty() // fails + * + * ->array($nonEmptyArray) + * ->isNotEmpty() // passes + * ; + * * @var static * * @link http://docs.atoum.org/en/latest/asserters.html#isnotempty @@ -24,6 +64,19 @@ class phpArray extends variable implements \arrayAccess public $isNotEmpty; /** + * "hasSize" checks the size of an array. + * + * array($fibonacci) + * ->hasSize(7) // passes + * ->hasSize(10) // fails + * ; + * + * Note: "hasSize" is not recursive. + * * @param integer $size * @param string $failMessage * @@ -34,6 +87,20 @@ class phpArray extends variable implements \arrayAccess public function hasSize($size, $failMessage = null) {} /** + * "isEmpty" checks that an array is empty. + * + * array($emptyArray) + * ->isEmpty() // passes + * + * ->array($nonEmptyArray) + * ->isEmpty() // fails + * ; + * * @param string $failMessage * * @link http://docs.atoum.org/en/latest/asserters.html#isempty @@ -43,6 +110,20 @@ public function hasSize($size, $failMessage = null) {} public function isEmpty($failMessage = null) {} /** + * "isNotEmpty" checks that an array is not empty. + * + * array($emptyArray) + * ->isNotEmpty() // fails + * + * ->array($nonEmptyArray) + * ->isNotEmpty() // passes + * ; + * * @param string $failMessage * * @link http://docs.atoum.org/en/latest/asserters.html#isnotempty @@ -52,6 +133,25 @@ public function isEmpty($failMessage = null) {} public function isNotEmpty($failMessage = null) {} /** + * "strictlyContains" checks that an array contains some data (same value + * and same type). + * + * array($fibonacci) + * ->strictlyContains('1') // passes + * ->strictlyContains(1) // fails + * ->strictlyContains('2') // fails + * ->strictlyContains(2) // passes + * ->strictlyContains(10) // fails + * ; + * + * Note: "strictlyContains" doesn't search recursively. + * + * to check the type, use *contains*. + * * @param mixed $value * @param string $failMessage * @@ -62,6 +162,23 @@ public function isNotEmpty($failMessage = null) {} public function strictlyContains($value, $failMessage = null) {} /** + * "contains" check that array contains some data. + * + * 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. + * + * to check its type, use *strictlyContains*. + * * @param mixed $value * @param string $failMessage * @@ -72,6 +189,24 @@ public function strictlyContains($value, $failMessage = null) {} public function contains($value, $failMessage = null) {} /** + * "strictlyNotContains" check that an array doesn't contains a data + * (same value and same type). + * + * array($fibonacci) + * ->strictlyNotContains(null) // passes + * ->strictlyNotContains('1') // fails + * ->strictlyNotContains(1) // passes + * ->strictlyNotContains(10) // passes + * ; + * + * Note: "strictlyNotContains" doesn't search recursively. + * + * want to check the type, use *contains*. + * * @param mixed $value * @param string $failMessage * @@ -82,6 +217,22 @@ public function contains($value, $failMessage = null) {} public function strictlyNotContains($value, $failMessage = null) {} /** + * "notContains" checks that an array doesn't contains the given data. + * + * array($fibonacci) + * ->notContains(null) // passes + * ->notContains(1) // fails + * ->notContains(10) // passes + * ; + * + * Note: "notContains" doesn't search recursively. + * + * also to check its type, use *strictlyNotContains*. + * * @param mixed $value * @param string $failMessage * @@ -92,6 +243,31 @@ public function strictlyNotContains($value, $failMessage = null) {} public function notContains($value, $failMessage = null) {} /** + * "hasKeys" checks that an array contains all the given keys. + * + * '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 type of keys. + * * @param mixed[] $keys * @param string $failMessage * @@ -102,6 +278,32 @@ public function notContains($value, $failMessage = null) {} public function hasKeys(array $keys, $failMessage = null) {} /** + * "notHasKeys" checks that an array doesn't contains any keys from the + * given array. + * + * '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 the type of keys. + * * @param mixed[] $keys * @param string $failMessage * @@ -112,6 +314,31 @@ public function hasKeys(array $keys, $failMessage = null) {} public function notHasKeys(array $keys, $failMessage = null) {} /** + * "hasKey" check that the table contains a given key. + * + * '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 type of keys. + * * @param mixed $key * @param string $failMessage * @@ -122,6 +349,31 @@ public function notHasKeys(array $keys, $failMessage = null) {} public function hasKey($key, $failMessage = null) {} /** + * "notHasKey" checks that an array doesn't contains a given key. + * + * '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 the type of keys. + * * @param mixed $key * @param string $failMessage * @@ -132,6 +384,23 @@ public function hasKey($key, $failMessage = null) {} public function notHasKey($key, $failMessage = null) {} /** + * "containsValues" checks that an array contains all data in from the + * given array. + * + * 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. + * + * also want to check their types, use *strictlyContainsValues*. + * * @param mixed[] $values * @param string $failMessage * @@ -142,6 +411,25 @@ public function notHasKey($key, $failMessage = null) {} public function containsValues(array $values, $failMessage = null) {} /** + * "strictlyContainsValues" checks that an array contains all the given + * data (same value and same type). + * + * 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. + * + * don't want to check the types, use *containsValues*. + * * @param mixed[] $values * @param string $failMessage * @@ -152,6 +440,23 @@ public function containsValues(array $values, $failMessage = null) {} public function strictlyContainsValues(array $values, $failMessage = null) {} /** + * "notContainsValues" checks that an array doesn't contains any data + * from the given array. + * + * 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. + * + * also want to check their types, use *strictlyNotContainsValues*. + * * @param mixed[] $values * @param string $failMessage * @@ -162,6 +467,25 @@ public function strictlyContainsValues(array $values, $failMessage = null) {} public function notContainsValues(array $values, $failMessage = null) {} /** + * "strictlyNotContainsValues" checks that an array doesn't contains any + * of the given data (same value and same type). + * + * 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. + * + * don't want to check the types, use *notContainsValues*. + * * @param mixed[] $values * @param string $failMessage * diff --git a/classes/mageekguy/atoum/stubs/asserters/phpClass.php b/classes/mageekguy/atoum/stubs/asserters/phpClass.php index ce5ebd6..700cae7 100644 --- a/classes/mageekguy/atoum/stubs/asserters/phpClass.php +++ b/classes/mageekguy/atoum/stubs/asserters/phpClass.php @@ -5,6 +5,24 @@ use mageekguy\atoum\stubs\asserters; /** + * It's the assertion dedicated to classes. + * + * 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 both + * "->phpClass()" or "->class()". + * + * But it's recommended to only use "->class()". + * * @method $this extends($class) * @method $this implements($interface) */ @@ -13,6 +31,14 @@ class phpClass use asserters; /** + * "isAbstract" checks that the class is abstract. + * + * class('\StdClass') + * ->isAbstract() // fails + * ; + * * @var static * * @link http://docs.atoum.org/en/latest/asserters.html#isabstract @@ -20,6 +46,29 @@ class phpClass public $isAbstract; /** + * "isFinal" checks that the class is final. + * + * In this case, we test a non-final class ("StdClass") : + * + * class('\StdClass') + * ->isFinal() // fails + * ; + * + * In this case, the tested class is a final one + * + * testedClass + * ->isFinal() // passes + * ; + * + * $this + * ->testedClass + * ->isFinal // passes too + * ; + * * @var static * * @link http://docs.atoum.org/en/latest/asserters.html#isfinal @@ -27,6 +76,20 @@ class phpClass public $isFinal; /** + * "hasNoParent" checks that the class doesn't inherit from any class. + * + * class('\StdClass') + * ->hasNoParent() // passes + * + * ->class('\FilesystemIterator') + * ->hasNoParent() // fails + * ; + * + * from no class. "hasNoParent" doesn't check interfaces, only the + * inherited classes. + * * @var static * * @link http://docs.atoum.org/en/latest/asserters.html#hasnoparent @@ -34,6 +97,20 @@ class phpClass public $hasNoParent; /** + * "hasParent" checks that the class inherits from a given class. + * + * class('\StdClass') + * ->hasParent() // fails + * + * ->class('\FilesystemIterator') + * ->hasParent() // passes + * ; + * + * from no class. "hasParent" doesn't check interfaces, only the + * inherited classes. + * * @param string $parent * @param string $failMessage * @@ -44,15 +121,40 @@ class phpClass public function hasParent($parent, $failMessage = null) {} /** + * "hasNoParent" checks that the class doesn't inherit from any class. + * + * class('\StdClass') + * ->hasNoParent() // passes + * + * ->class('\FilesystemIterator') + * ->hasNoParent() // fails + * ; + * + * from no class. "hasNoParent" doesn't check interfaces, only the + * inherited classes. + * * @param string $failMessage * * @link * @link http://docs.atoum.org/en/latest/asserters.html#hasnoparent * * @return $this + * */ public function hasNoParent($failMessage = null) {} /** + * "isSubclassOf" checks that the class inherit from the given class. + * + * class('\FilesystemIterator') + * ->isSubclassOf('\DirectoryIterator') // passes + * ->isSubclassOf('\SplFileInfo') // passes + * ->isSubclassOf('\StdClass') // fails + * ; + * * @param string $parent * @param string $failMessage * @@ -63,6 +165,17 @@ public function hasNoParent($failMessage = null) {} public function isSubClassOf($parent, $failMessage = null) {} /** + * "hasInterface" checks that the class implements a given interface. + * + * class('\ArrayIterator') + * ->hasInterface('Countable') // passes + * + * ->class('\StdClass') + * ->hasInterface('Countable') // fails + * ; + * * @param string $interface * @param string $failMessage * @@ -73,6 +186,14 @@ public function isSubClassOf($parent, $failMessage = null) {} public function hasInterface($interface, $failMessage = null) {} /** + * "isAbstract" checks that the class is abstract. + * + * class('\StdClass') + * ->isAbstract() // fails + * ; + * * @param string $failMessage * * @link http://docs.atoum.org/en/latest/asserters.html#isabstract @@ -82,6 +203,29 @@ public function hasInterface($interface, $failMessage = null) {} public function isAbstract($failMessage = null) {} /** + * "isFinal" checks that the class is final. + * + * In this case, we test a non-final class ("StdClass") : + * + * class('\StdClass') + * ->isFinal() // fails + * ; + * + * In this case, the tested class is a final one + * + * testedClass + * ->isFinal() // passes + * ; + * + * $this + * ->testedClass + * ->isFinal // passes too + * ; + * * @param string $failMessage * * @link http://docs.atoum.org/en/latest/asserters.html#isfinal @@ -91,6 +235,17 @@ public function isAbstract($failMessage = null) {} public function isFinal($failMessage = null) {} /** + * "hasMethod" checks that the class contains a given method. + * + * class('\ArrayIterator') + * ->hasMethod('count') // passes + * + * ->class('\StdClass') + * ->hasMethod('count') // fails + * ; + * * @param string $method * @param string $failMessage * @@ -101,6 +256,17 @@ public function isFinal($failMessage = null) {} public function hasMethod($method, $failMessage = null) {} /** + * "hasConstant" checks that the class has the tested constant. + * + * class('\StdClass') + * ->hasConstant('FOO') // fails + * + * ->class('\FilesystemIterator') + * ->hasConstant('CURRENT_AS_PATHNAME') // passes + * ; + * * @param string $constant * @param string $failMessage * diff --git a/classes/mageekguy/atoum/stubs/asserters/phpFloat.php b/classes/mageekguy/atoum/stubs/asserters/phpFloat.php index ebdfec4..76f46ef 100644 --- a/classes/mageekguy/atoum/stubs/asserters/phpFloat.php +++ b/classes/mageekguy/atoum/stubs/asserters/phpFloat.php @@ -2,10 +2,48 @@ namespace mageekguy\atoum\stubs\asserters; - +/** + * It's the assertion dedicated to decimal numbers. + * + * If you try to test a variable that is not a decimal number with this + * assertion, this 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. + * + */ class phpFloat extends integer { /** + * "isNearlyEqualTo" checks that the float is approximatively equal to + * the value it receives 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. + * + * float($float) + * ->isNearlyEqualTo(0.03) // passes + * ->isEqualTo(0.03) // fails + * ; + * + * Note: For more information about the algorithm used, see the + * floating point guide. + * * @param float $value * @param float $epsilon * @param string $failMessage diff --git a/classes/mageekguy/atoum/stubs/asserters/phpString.php b/classes/mageekguy/atoum/stubs/asserters/phpString.php index 1f519ce..fa35186 100644 --- a/classes/mageekguy/atoum/stubs/asserters/phpString.php +++ b/classes/mageekguy/atoum/stubs/asserters/phpString.php @@ -2,10 +2,25 @@ namespace mageekguy\atoum\stubs\asserters; - +/** + * It's the assertion dedicated to the strings. + * + */ class phpString extends variable { /** + * "length" allows you to get an asserter of type *integer* that contains + * the string's size. + * + * string($string) + * ->length + * ->isGreaterThanOrEqualTo(5) + * ; + * * @var \mageekguy\atoum\stubs\asserters\integer * * @link http://docs.atoum.org/en/latest/asserters.html#length @@ -13,6 +28,20 @@ class phpString extends variable public $length; /** + * "isEmpty" checks that a string is empty. + * + * string($emptyString) + * ->isEmpty() // passes + * + * ->string($nonEmptyString) + * ->isEmpty() // fails + * ; + * * @var static * * @link http://docs.atoum.org/en/latest/asserters.html#string-is-empty @@ -20,6 +49,20 @@ class phpString extends variable public $isEmpty; /** + * "isNotEmpty" checks that the string is not empty. + * + * string($emptyString) + * ->isNotEmpty() // fails + * + * ->string($nonEmptyString) + * ->isNotEmpty() // passes + * ; + * * @var static * * @link http://docs.atoum.org/en/latest/asserters.html#string-is-not-empty @@ -32,6 +75,20 @@ class phpString extends variable public $toArray; /** + * "isEmpty" checks that a string is empty. + * + * string($emptyString) + * ->isEmpty() // passes + * + * ->string($nonEmptyString) + * ->isEmpty() // fails + * ; + * * @param string $failMessage * * @link http://docs.atoum.org/en/latest/asserters.html#string-is-empty @@ -41,6 +98,20 @@ class phpString extends variable public function isEmpty($failMessage = null) {} /** + * "isNotEmpty" checks that the string is not empty. + * + * string($emptyString) + * ->isNotEmpty() // fails + * + * ->string($nonEmptyString) + * ->isNotEmpty() // passes + * ; + * * @param string $failMessage * * @link http://docs.atoum.org/en/latest/asserters.html#string-is-not-empty @@ -50,6 +121,9 @@ public function isEmpty($failMessage = null) {} public function isNotEmpty($failMessage = null) {} /** + * Hint: "match" is an alias of the "matches" method. For more + * information, refer to the documentation of *string::matches* + * * @param string $pattern * @param string $failMessage * @@ -58,6 +132,20 @@ public function isNotEmpty($failMessage = null) {} public function match($pattern, $failMessage = null) {} /** + * "matches" checks that a regular expression match the string. + * + * string($phone) + * ->matches('#^0[1-9]\d{8}$#') + * + * ->string($vdm) + * ->matches("#^Today.*VDM$#") + * ; + * * @param string $pattern * @param string $failMessage * @@ -68,6 +156,17 @@ public function match($pattern, $failMessage = null) {} public function matches($pattern, $failMessage = null) {} /** + * "isEqualToContentsOfFile" checks that a string is equal to the content + * of a file given by its path. + * + * string($string) + * ->isEqualToContentsOfFile('/path/to/file') + * ; + * + * Note: if the file doesn't exist, the test will fails. + * * @param string $path * @param string $failMessage * @@ -78,6 +177,17 @@ public function matches($pattern, $failMessage = null) {} public function isEqualToContentsOfFile($path, $failMessage = null) {} /** + * "hasLength" checks the size of the string. + * + * string($string) + * ->hasLength(11) // passes + * ->hasLength(20) // fails + * ; + * * @param integer $length * @param string $failMessage * @@ -88,6 +198,18 @@ public function isEqualToContentsOfFile($path, $failMessage = null) {} public function hasLength($length, $failMessage = null) {} /** + * "hasLengthGreaterThan" checks that the size of a string is grater that + * the given one. + * + * string($string) + * ->hasLengthGreaterThan(10) // passes + * ->hasLengthGreaterThan(20) // fails + * ; + * * @param integer $length * @param string $failMessage * @@ -98,6 +220,18 @@ public function hasLength($length, $failMessage = null) {} public function hasLengthGreaterThan($length, $failMessage = null) {} /** + * "hasLengthLessThan" checks that the size of the string is shorter that + * the given one. + * + * string($string) + * ->hasLengthLessThan(20) // passes + * ->hasLengthLessThan(10) // fails + * ; + * * @param integer $length * @param string $failMessage * @@ -108,6 +242,18 @@ public function hasLengthGreaterThan($length, $failMessage = null) {} public function hasLengthLessThan($length, $failMessage = null) {} /** + * "contains" checks that a string contains a given string. + * + * string($string) + * ->contains('ll') // passes + * ->contains(' ') // passes + * ->contains('php') // fails + * ; + * * @param string $fragment * @param string $failMessage * @@ -118,6 +264,20 @@ public function hasLengthLessThan($length, $failMessage = null) {} public function contains($fragment, $failMessage = null) {} /** + * "notContains" checks that a string doesn't contains another given + * string. + * + * string($string) + * ->notContains('php') // passes + * ->notContains(';') // passes + * ->notContains('ll') // fails + * ->notContains(' ') // fails + * ; + * * @param string $fragment * @param string $failMessage * @@ -128,6 +288,20 @@ public function contains($fragment, $failMessage = null) {} public function notContains($fragment, $failMessage = null) {} /** + * "startWith" checks that a string starts with another given string. + * + * string($string) + * ->startWith('Hello wo') // passes + * ->startWith('He') // passes + * ->startWith('world') // fails + * ->startWith(' ') // fails + * + * ; + * * @param string $fragment * @param string $failMessage * @@ -136,6 +310,20 @@ public function notContains($fragment, $failMessage = null) {} public function startWith($fragment, $failMessage = null) {} /** + * "notStartWith" checks that a string doesn't starts with another given + * string. + * + * string($string) + * ->notStartWith('world') // passes + * ->notStartWith(' ') // passes + * ->notStartWith('Hello wo') // fails + * ->notStartWith('He') // fails + * ; + * * @param string $fragment * @param string $failMessage * @@ -144,6 +332,19 @@ public function startWith($fragment, $failMessage = null) {} public function notStartWith($fragment, $failMessage = null) {} /** + * "endWith" checks that a string ends with another given string. + * + * string($string) + * ->endWith('world') // passes + * ->endWith('lo world') // passes + * ->endWith('Hello') // fails + * ->endWith(' ') // fails + * ; + * * @param string $fragment * @param string $failMessage * @@ -152,6 +353,20 @@ public function notStartWith($fragment, $failMessage = null) {} public function endWith($fragment, $failMessage = null) {} /** + * "notEndWith" checks that a string doesn't ends with another given + * string. + * + * string($string) + * ->notEndWith('Hello') // passes + * ->notEndWith(' ') // passes + * ->notEndWith('world') // fails + * ->notEndWith('lo world') // fails + * ; + * * @param string $fragment * @param string $failMessage * diff --git a/classes/mageekguy/atoum/stubs/asserters/sizeOf.php b/classes/mageekguy/atoum/stubs/asserters/sizeOf.php index 275bf1b..da257b5 100644 --- a/classes/mageekguy/atoum/stubs/asserters/sizeOf.php +++ b/classes/mageekguy/atoum/stubs/asserters/sizeOf.php @@ -2,5 +2,21 @@ namespace mageekguy\atoum\stubs\asserters; - +/** + * It's the assertion dedicated to tests on the size of the arrays and + * objects implementing the interface "Countable". + * + * sizeOf($array) + * ->isEqualTo(3) + * + * ->sizeOf($countableObject) + * ->isGreaterThan(0) + * ; + * + */ class sizeOf extends integer {} diff --git a/classes/mageekguy/atoum/stubs/asserters/stream.php b/classes/mageekguy/atoum/stubs/asserters/stream.php index 670bb1f..8838e6c 100644 --- a/classes/mageekguy/atoum/stubs/asserters/stream.php +++ b/classes/mageekguy/atoum/stubs/asserters/stream.php @@ -4,11 +4,45 @@ use mageekguy\atoum\stubs\asserters; +/** + * This is the assertion dedicated to the streams. + * + * 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"). + * + */ class stream { use asserters; /** + * "isRead" checks if a mocked stream has been read. + * + * given( + * $streamController = \atoum\mock\stream::get(), + * $streamController->file_get_contents = 'myFakeContent' + * ) + * ->if(file_get_contents($streamController->getPath())) + * ->stream($streamController) + * ->isRead() // passes + * ; + * + * $this + * ->given( + * $streamController = \atoum\mock\stream::get(), + * $streamController->file_get_contents = 'myFakeContent' + * ) + * ->if() //we do nothing + * ->stream($streamController) + * ->isRead() // fails + * ; + * * @param string $failMessage * * @link http://docs.atoum.org/en/latest/asserters.html#isread @@ -18,6 +52,10 @@ class stream public function isRead($failMessage = null) {} /** + * "isWrited" is an alias to the isWritten method. + * For more information, refer to the documentation of + * *stream::isWritten* + * * @param string $failMessage * * @return $this @@ -25,6 +63,29 @@ public function isRead($failMessage = null) {} public function isWrited($failMessage = null) {} /** + * "isWritten" checks if a mocked stream has been written. + * + * 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 + * ; + * * @param string $failMessage * * @return $this diff --git a/classes/mageekguy/atoum/stubs/asserters/utf8String.php b/classes/mageekguy/atoum/stubs/asserters/utf8String.php index b88259a..87ed18f 100644 --- a/classes/mageekguy/atoum/stubs/asserters/utf8String.php +++ b/classes/mageekguy/atoum/stubs/asserters/utf8String.php @@ -2,5 +2,12 @@ namespace mageekguy\atoum\stubs\asserters; - +/** + * 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. + * + */ class utf8String extends phpString {} diff --git a/classes/mageekguy/atoum/stubs/asserters/variable.php b/classes/mageekguy/atoum/stubs/asserters/variable.php index d5c1e97..34519c1 100644 --- a/classes/mageekguy/atoum/stubs/asserters/variable.php +++ b/classes/mageekguy/atoum/stubs/asserters/variable.php @@ -4,16 +4,48 @@ use mageekguy\atoum\stubs\asserters; +/** + * It's the basic assertion of all variables. It contains the necessary + * tests for any type of variable. + * + */ class variable { use asserters; /** + * "isNotFalse" check that the variable is strictly not equal to "false". + * + * variable($false) + * ->isNotFalse() // fails + * + * ->variable($true) + * ->isNotFalse() // succeed + * ; + * * @var static */ public $isNotFalse; /** + * "isNotNull" checks that the variable is not null. + * + * variable($emptyString) + * ->isNotNull() // passes (it's empty but not null) + * + * ->variable($null) + * ->isNotNull() // fails + * ; + * * @var static * * @link http://docs.atoum.org/en/latest/asserters.html#isnotnull @@ -21,11 +53,39 @@ class variable public $isNotNull; /** + * "isNotTrue" check that the variable is strictly not equal to "true". + * + * variable($true) + * ->isNotTrue() // fails + * + * ->variable($false) + * ->isNotTrue() // succeed + * ; + * * @var static */ public $isNotTrue; /** + * "isNull" checks that the variable is null. + * + * variable($emptyString) + * ->isNull() // fails + * // (it's empty but not null) + * + * ->variable($null) + * ->isNull() // passes + * ; + * * @var static * * @link http://docs.atoum.org/en/latest/asserters.html#isnull @@ -33,6 +93,18 @@ class variable public $isNull; /** + * "isEqualTo" verifies that the variable is equal to a given data. + * + * variable($a) + * ->isEqualTo('a') // passes + * ; + * + * also to check the type, use *isIdenticalTo*. + * * @param mixed $value * @param string $failMessage * @@ -43,6 +115,24 @@ class variable public function isEqualTo($value, $failMessage = null) {} /** + * "isNotEqualTo" checks that the variable is not the same value the the + * given one. + * + * variable($a) + * ->isNotEqualTo('b') // passes + * ->isNotEqualTo('a') // fails + * + * ->variable($aString) + * ->isNotEqualTo($1) // fails + * ; + * + * want also to check the type, use *isNotIdenticalTo*. + * * @param mixed $value * @param string $failMessage * @@ -53,6 +143,31 @@ public function isEqualTo($value, $failMessage = null) {} public function isNotEqualTo($value, $failMessage = null) {} /** + * "isIdenticalTo" checks that the variable has the same value and the + * same type than the given data. Inthe case of an object, + * "isIdenticalTo" checks that the data is referencing on the same + * instance. + * + * variable($a) + * ->isIdenticalTo(1) // fails + * ; + * + * $stdClass1 = new \StdClass(); + * $stdClass2 = new \StdClass(); + * $stdClass3 = $stdClass1; + * + * $this + * ->variable($stdClass1) + * ->isIdenticalTo(stdClass3) // passes + * ->isIdenticalTo(stdClass2) // fails + * ; + * + * want its type, use *isEqualTo*. + * * @param mixed $value * @param string $failMessage * @@ -63,6 +178,32 @@ public function isNotEqualTo($value, $failMessage = null) {} public function isIdenticalTo($value, $failMessage = null) {} /** + * "isNotIdenticalTo" checks that the variable hasn't the same type nor + * the same value than the given one. + * + * Inthe case of an object, "isNotIdenticalTo" checks that the data isn't + * referencing on the same instance. + * + * variable($a) + * ->isNotIdenticalTo(1) // passes + * ; + * + * $stdClass1 = new \StdClass(); + * $stdClass2 = new \StdClass(); + * $stdClass3 = $stdClass1; + * + * $this + * ->variable($stdClass1) + * ->isNotIdenticalTo(stdClass2) // passes + * ->isNotIdenticalTo(stdClass3) // fails + * ; + * + * doesn't want to check its type, use *isNotEqualTo*. + * * @param mixed $value * @param string $failMessage * @@ -73,6 +214,21 @@ public function isIdenticalTo($value, $failMessage = null) {} public function isNotIdenticalTo($value, $failMessage = null) {} /** + * "isNull" checks that the variable is null. + * + * variable($emptyString) + * ->isNull() // fails + * // (it's empty but not null) + * + * ->variable($null) + * ->isNull() // passes + * ; + * * @param string $failMessage * * @link http://docs.atoum.org/en/latest/asserters.html#isnull @@ -82,6 +238,20 @@ public function isNotIdenticalTo($value, $failMessage = null) {} public function isNull($failMessage = null) {} /** + * "isNotNull" checks that the variable is not null. + * + * variable($emptyString) + * ->isNotNull() // passes (it's empty but not null) + * + * ->variable($null) + * ->isNotNull() // fails + * ; + * * @param string $failMessage * * @link http://docs.atoum.org/en/latest/asserters.html#isnotnull @@ -99,6 +269,19 @@ public function isNotNull($failMessage = null) {} public function isReferenceTo(& $reference, $failMessage = null) {} /** + * "isNotFalse" check that the variable is strictly not equal to "false". + * + * variable($false) + * ->isNotFalse() // fails + * + * ->variable($true) + * ->isNotFalse() // succeed + * ; + * * @param string $failMessage * * @return $this @@ -106,6 +289,19 @@ public function isReferenceTo(& $reference, $failMessage = null) {} public function isNotFalse($failMessage = null) {} /** + * "isNotTrue" check that the variable is strictly not equal to "true". + * + * variable($true) + * ->isNotTrue() // fails + * + * ->variable($false) + * ->isNotTrue() // succeed + * ; + * * @param string $failMessage * * @return $this @@ -113,6 +309,27 @@ public function isNotFalse($failMessage = null) {} public function isNotTrue($failMessage = null) {} /** + * "isCallable" verifies that the variable can be called as a function. + * + * variable($f) + * ->isCallable() // succeed + * + * ->variable('\Vendor\Project\foobar') + * ->isCallable() + * + * ->variable(array('\Vendor\Project\Foo', 'bar')) + * ->isCallable() + * + * ->variable('\Vendor\Project\Foo::bar') + * ->isCallable() + * ; + * * @param callable $value * @param string $failMessage * @@ -123,6 +340,30 @@ public function isNotTrue($failMessage = null) {} public function isCallable(callable $value, $failMessage = null) {} /** + * "isNotCallable" checks that the variable can't be called like a + * function. + * + * variable($f) + * ->isNotCallable() // fails + * + * ->variable($int) + * ->isNotCallable() // passes + * + * ->variable($string) + * ->isNotCallable() // passes + * + * ->variable(new StdClass) + * ->isNotCallable() // passes + * ; + * * @param callable $value * @param string $failMessage *