PHP教程:PHPUnit学习笔记(四)断言详解

断言(Assertions)是PHPUnit提供的一系列对程序执行结果测试的方法。通俗的讲，就是断言执行程序结果为我们期待的值，如果不是则测试失败，下面是断言方法的详细介绍，内容全部来翻译自PHPUnit的官方文档，部分方法官方介绍的很模糊，我根据官方的源码注释增加了说明和注释

assertArrayHasKey(mixed $key, array $array[, string $message = '']) 
断言数组$array含有索引$key, $message用于自定义输出的错误信息,后同

assertClassHasAttribute(string $attributeName, string $className[, string $message = '']) 
断言类$className含有属性$attributeName

assertClassHasStaticAttribute(string $attributeName, string $className[, string $message = '']) 
断言类$className含有静态属性$attributeName

assertContains(mixed $needle, Iterator|array $haystack[, string $message = '']) 
断言迭代器对象$haystack/数组$haystack含有$needle

assertNotContains() 
与上条相反

assertAttributeContains(mixed $needle, Class|Object $haystack[, string $message = '']) 
断言$needle为一个类/对象$haystack可访问到的属性(public, protected 和 private)

assertAttributeNotContains() 
与上条相反

assertContains(string $needle, string $haystack[, string $message = '']) 
断言字符串$needle在字符串$haystack中

assertContainsOnly(string $type, Iterator|array $haystack[, boolean $isNativeType = NULL, string $message = '']) 
断言迭代器对象/数组$haystack中只有$type类型的值, $isNativeType 设定为PHP原生类型，$message同上

assertNotContainsOnly() 
与上条相反

assertAttributeContainsOnly() 和 assertAttributeNotContainsOnly() 
断言对象的属性只有$type类型和非含有$type类型

assertEmpty(mixed $actual[, string $message = '']) 
断言$actual为空

assertNotEmpty() 
遇上条相反

assertAttributeEmpty() 和 assertAttributeNotEmpty() 
断言对象的所有属性为空或不为空

assertEqualXMLStructure(DOMNode $expectedNode, DOMNode $actualNode[, boolean $checkAttributes = FALSE, string $message = '']) 
断言Dom节点$actualNode和DOM节点$expectedNode相同，$checkAttributes FALSE 不断言节点属性，TRUE则断言属性$message同上

assertEquals(mixed $expected, mixed $actual[, string $message = '']) 
断言复合类型$actual与$expected相同

assertNotEquals() 
与上条相反

assertAttributeEquals() and assertAttributeNotEquals() 
断言类属性$actual与$expected相同

assertEquals(array $expected, array $actual[, string $message = '']) 
断言数组$actual和数组$expected相同

assertFalse(bool $condition[, string $message = '']) 
断言$condition的结果为false

assertFileEquals(string $expected, string $actual[, string $message = '']) 
断言文件$actual和$expected相同

assertFileExists(string $filename[, string $message = '']) 
断言文件$filename存在

assertFileNotExists() 
与上条相反

assertGreaterThan(mixed $expected, mixed $actual[, string $message = '']) 
断言$actual比$expected大

assertAttributeGreaterThan() 
断言类的属性用

assertGreaterThanOrEqual(mixed $expected, mixed $actual[, string $message = '']) 
断言$actual大于等于$expected

assertAttributeGreaterThanOrEqual() 
断言类的属性

assertInstanceOf($expected, $actual[, $message = '']) 
断言$actual为$expected的实例

assertNotInstanceOf() 
与上相反

assertAttributeInstanceOf() and assertAttributeNotInstanceOf() 
断言类属性用

assertInternalType($expected, $actual[, $message = '']) 
断言$actual的类型为$expected

assertNotInternalType() 
与上相反

assertAttributeInternalType() and assertAttributeNotInternalType() 
断言类属性用

assertLessThan(mixed $expected, mixed $actual[, string $message = '']) 
断言$actual小于$expected

assertAttributeLessThan() 
断言类属性小于$expected

assertLessThanOrEqual(mixed $expected, mixed $actual[, string $message = '']) 
断言$actual小于等于$expected

assertAttributeLessThanOrEqual() 
断言类属性小于等于$expected

assertNull(mixed $variable[, string $message = '']) 
断言$variable的值为null

assertNotNull() 
与上条相反

assertObjectHasAttribute(string $attributeName, object $object[, string $message = '']) 
断言$object含有属性$attributeName

assertObjectNotHasAttribute() 
与上条相反

assertRegExp(string $pattern, string $string[, string $message = '']) 
断言字符串$string符合正则表达式$pattern

assertNotRegExp() 
与上条相反

assertStringMatchesFormat(string $format, string $string[, string $message = '']) 
断言$string符合$format定义的格式，例如 %i %s等等

assertStringNotMatchesFormat() 
与上条相反

assertStringMatchesFormatFile(string $formatFile, string $string[, string $message = '']) 
断言$string路径的文件的格式和$formatFile文件的格式相同

assertStringNotMatchesFormatFile() 
与上条相反

assertSame(mixed $expected, mixed $actual[, string $message = '']) 
断言$actual和$expected的类型和值相同

assertNotSame() 
与上条相反

assertAttributeSame() and assertAttributeNotSame() 
断言类属性用

assertSame(object $expected, object $actual[, string $message = '']) 
断言对象$actual和对象$expected相同

assertSelectCount(array $selector, integer $count, mixed $actual[, string $message = '', boolean $isHtml = TRUE]) 
断言在$actual文档中（格式为html或xml）css选择器$selector有$count个，或有符合$selector的元素（设定$count为true），或没有符合$selector的元素（设定$count为false）

assertSelectCount("#binder", true, $xml);  // 有一个就行
assertSelectCount(".binder", 3, $xml);     // 必须有3个?

assertSelectEquals(array $selector, string $content, integer $count, mixed $actual[, string $message = '', boolean $isHtml = TRUE]) 
断言在文档$actual中有符合根据$selector的找到符合$content的$count个元素，当$count等于true和false的时候作用如下：

assertSelectEquals("#binder .name", "Chuck", true,  $xml);  // 所有的name等于Chuck
assertSelectEquals("#binder .name", "Chuck", false, $xml);  // 所有的name不等于Chuck

assertSelectRegExp(array $selector, string $pattern, integer $count, mixed $actual[, string $message = '', boolean $isHtml = TRUE])

assertStringEndsWith(string $suffix, string $string[, string $message = '']) 
断言$string的末尾为$suffix结束

assertStringEndsNotWith() 
与上条相反

assertStringEqualsFile(string $expectedFile, string $actualString[, string $message = ''])
断言$actualString在文件$expectedFile的内容中

assertStringNotEqualsFile() 
与上条相反

assertStringStartsWith(string $prefix, string $string[, string $message = '']) 
断言$string的开头为$suffix

assertStringStartsNotWith() 
与上条相反

assertTag(array $matcher, string $actual[, string $message = '', boolean $isHtml = TRUE]) 
断言$actual的内容符合$matcher的定义，matcher的定义如下：
# id: 节点必须带有id属性且名称与id设定的相同
# tags: 节点的名称必须与tags的值匹配
# attributes: 节点的属性必须与$attributes数组中的值相匹配
# content: 文本内容必须与$content的值相同.
# parent: 节点的父节点必须符合$parent数组中定义的内容.
# child: 节点的字节点中有至少一个直系子节点满足 $child 数组中定义的内容. 
At least one of the node's immediate children must meet the criteria described by the $child associative array.
# ancestor: 节点的父节点中有至少一个节点满足 $ancestor 数组中定义的内容.
At least one of the node's ancestors must meet the criteria described by the $ancestor associative array.
# descendant: 节点的字节点中有至少一个子节点满足 $descendant 数组中定义的内容. 
At least one of the node's descendants must meet the criteria described by the $descendant associative array.
# children: 用于计算字节点的联合数组 
Associative array for counting children of a node.
    * count: 符合匹配标准的字节点数目需要和count的值相同 
The number of matching children must be equal to this number.
    * less_than: 符合匹配标准的字节点数目需要比count的值少 
The number of matching children must be less than this number.
    * greater_than: 符合匹配标准的字节点数目需要比count的值多 
The number of matching children must be greater than this number.
    * only: 另外一个联合数组用于定义配合标准的节点，只有这些节点才会被计算入内 
Another associative array consisting of the keys to use to match on the children, and only matching children will be counted

assertTag的代码例子（图片点击放大）：

 

More complex assertions can be formulated using the PHPUnit_Framework_Constraint classes
更加复杂的断言可以通过PHPUnit_Framework_Constraint类来制定

PHPUnit_Framework_Constraint_Attribute attribute(PHPUnit_Framework_Constraint $constraint, $attributeName)
约束允许另外一个约束类为一个类或对象的属性     

Constraint that applies another constraint to an attribute of a class or an object.
PHPUnit_Framework_Constraint_IsAnything anything()
约束接受任意的输入值
Constraint that accepts any input value.

PHPUnit_Framework_Constraint_ArrayHasKey arrayHasKey(mixed $key)     
Constraint that asserts that the array it is evaluated for has a given key.
约束断言评估数组有传入的$key

PHPUnit_Framework_Constraint_TraversableContains contains(mixed $value)     
Constraint that asserts that the array or object that implements the Iterator interface it is evaluated for contains a given value.
约束断言一个数组或者实现迭代器接口的对象含有$value

PHPUnit_Framework_Constraint_IsEqual equalTo($value, $delta = 0, $maxDepth = 10)     
Constraint that checks if one value is equal to another.
约束断言$value和其他的相同

PHPUnit_Framework_Constraint_Attribute attributeEqualTo($attributeName, $value, $delta = 0, $maxDepth = 10)     
Constraint that checks if a value is equal to an attribute of a class or of an object.
约束断言$value和一个类或对象的属性的值相同

PHPUnit_Framework_Constraint_FileExists fileExists()     
Constraint that checks if the file(name) that it is evaluated for exists.
约束断言文件是存在的

PHPUnit_Framework_Constraint_GreaterThan greaterThan(mixed $value)     
Constraint that asserts that the value it is evaluated for is greater than a given value.
约束断言$value是大于传入的值的

PHPUnit_Framework_Constraint_Or greaterThanOrEqual(mixed $value)     
Constraint that asserts that the value it is evaluated for is greater than or equal to a given value.
约束断言$value是大于或等于传入的值的

PHPUnit_Framework_Constraint_ClassHasAttribute classHasAttribute(string $attributeName)     
Constraint that asserts that the class it is evaluated for has a given attribute.
约束断言类含有属性$attributeName

PHPUnit_Framework_Constraint_ClassHasStaticAttribute classHasStaticAttribute(string $attributeName)     
Constraint that asserts that the class it is evaluated for has a given static attribute.
约束断言类含有静态属性$attributeName

PHPUnit_Framework_Constraint_ObjectHasAttribute hasAttribute(string $attributeName)     
Constraint that asserts that the object it is evaluated for has a given attribute.
约束断言对象含有属性$attributeName

PHPUnit_Framework_Constraint_IsIdentical identicalTo(mixed $value)     
Constraint that asserts that one value is identical to another.
约束断言$value和其他的完全相同

PHPUnit_Framework_Constraint_IsFalse isFalse()     
Constraint that asserts that the value it is evaluated is FALSE.
约束断言$value的值为false

PHPUnit_Framework_Constraint_IsInstanceOf isInstanceOf(string $className)     
Constraint that asserts that the object it is evaluated for is an instance of a given class.
约束断言对象是$className的实例

PHPUnit_Framework_Constraint_IsNull isNull()     
Constraint that asserts that the value it is evaluated is NULL.
约束断言$value的值为NULL

PHPUnit_Framework_Constraint_IsTrue isTrue()     
Constraint that asserts that the value it is evaluated is TRUE.
约束断言$value的值为TRUE

PHPUnit_Framework_Constraint_IsType isType(string $type)     
Constraint that asserts that the value it is evaluated for is of a specified type.
约束断言对象的类型的为$type

PHPUnit_Framework_Constraint_LessThan lessThan(mixed $value)     
Constraint that asserts that the value it is evaluated for is smaller than a given value.
约束断言对象的值小于$value

PHPUnit_Framework_Constraint_Or lessThanOrEqual(mixed $value)     
Constraint that asserts that the value it is evaluated for is smaller than or equal to a given value.
约束断言对象的值小于等于$value

logicalAnd()     
Logical AND.
逻辑的And

logicalNot(PHPUnit_Framework_Constraint $constraint)     
Logical NOT.
逻辑的

logicalOr()     
Logical OR.
逻辑的OR

logicalXor()     
Logical XOR.
逻辑的XOR

PHPUnit_Framework_Constraint_PCREMatch matchesRegularExpression(string $pattern)     
Constraint that asserts that the string it is evaluated for matches a regular expression.
约束断言字符串符合传入的正则表达式$pattern

PHPUnit_Framework_Constraint_StringContains stringContains(string $string, bool $case)     
Constraint that asserts that the string it is evaluated for contains a given string.
约束断言字符串中含有$string

PHPUnit_Framework_Constraint_StringEndsWith stringEndsWith(string $suffix)     
Constraint that asserts that the string it is evaluated for ends with a given suffix.
约束断言字符串由$string结尾

PHPUnit_Framework_Constraint_StringStartsWith stringStartsWith(string $prefix)     
Constraint that asserts that the string it is evaluated for starts with a given prefix. 
约束断言字符串由$string开头

assertThat的用法，使用多个约束和约束逻辑来实现断言（图片点击放大）
 

assertTrue(bool $condition[, string $message = '']) 
断言$condition为True，否则就报告错误

assertXmlFileEqualsXmlFile(string $expectedFile, string $actualFile[, string $message = '']) 
断言$actualFile和$expectedFile的xml文件的内容相同，否则就报告错误

assertXmlStringEqualsXmlFile(string $expectedFile, string $actualXml[, string $message = '']) 
断言$actualXml的内容和$expectedFile相同，否则就报告错误

assertXmlStringEqualsXmlString(string $expectedXml, string $actualXml[, string $message = '']) 
断言$actualXml的内容和$expectedXml相同，否则就报告错误

本篇日记结束，下篇介绍PHPUnit类中的工具方法