所谓标注,是指某些编程语言中允许加在源代码中的一种特殊形式的语法元数据。PHP 并没有专门的语言特性来支持对源代码进行标注,然而 PHP 社区早已经形成惯例,通过在文档注释块中使用诸如 @annotation arguments
这样的标签来对标注源代码。在 PHP 中,文档注释块是可反射的:可以通过在函数、方法、类以及属性级别调用反射 API 的 getDocComment()
方法来访问它们。诸如 PHPUnit 这样的应用程序在运行时用这些信息来配置其行为。
注意
PHP中的文档注释块必须以 /**
开头,以 */
结尾。任何其他形式的注释中出现的标注都将被忽略。
本附录列出了 PHPUnit 所支持的所有标注种类。
@author
标注是 @group
标注(参见 “@group”一节)的别名,允许基于作者对测试进行过滤。
@after
标注用于指定若干方法,这些方法在测试用例类中的每个测试方法运行完成之后调用。
class MyTest extends PHPUnit_Framework_TestCase{
/**
* @after
*/
public function tearDownSomeFixtures()
{
// ...
} /**
* @after
*/
public function tearDownSomeOtherFixtures()
{
// ...
}
}
@afterClass
标注用于指定若干静态方法,这些方法在测试类中的所有测试方法都运行完成之后调用,用来清理共享基境。
class MyTest extends PHPUnit_Framework_TestCase{
/**
* @afterClass
*/
public static function tearDownSomeSharedFixtures()
{
// ...
} /**
* @afterClass
*/
public static function tearDownSomeOtherSharedFixtures()
{
// ...
}
}
全局变量的备份与还原操作可以对测试用例类中的所有测试彻底禁用,像这样:
/**
* @backupGlobals disabled
*/class MyTest extends PHPUnit_Framework_TestCase{
// ...}
@backupGlobals
标注也可以用在测试方法这一级别。这样可以对备份与还原操作进行更细粒度的配置:
/**
* @backupGlobals disabled
*/class MyTest extends PHPUnit_Framework_TestCase{
/**
* @backupGlobals enabled
*/
public function testThatInteractsWithGlobalVariables()
{
// ...
}
}
类的静态属性的备份与还原操作可以对测试用例类的所有测试彻底禁用,像这样:
/**
* @backupStaticAttributes disabled
*/class MyTest extends PHPUnit_Framework_TestCase{
// ...}
@backupStaticAttributes
标注也可以用在测试方法这一级别。这样可以对备份与还原操作进行更细粒度的配置:
/**
* @backupStaticAttributes disabled
*/class MyTest extends PHPUnit_Framework_TestCase{
/**
* @backupStaticAttributes enabled
*/
public function testThatInteractsWithStaticAttributes()
{
// ...
}
}
The @before
标注用于指定若干方法,这些方法在测试用例类中的每个测试方法运行之前调用。
class MyTest extends PHPUnit_Framework_TestCase{
/**
* @before
*/
public function setupSomeFixtures()
{
// ...
} /**
* @before
*/
public function setupSomeOtherFixtures()
{
// ...
}
}
@beforeClass
标注用于指定若干静态方法,这些方法在测试类中的任何测试方法运行之前调用,用来建立共享基境。
class MyTest extends PHPUnit_Framework_TestCase{
/**
* @beforeClass
*/
public static function setUpSomeSharedFixtures()
{
// ...
} /**
* @beforeClass
*/
public static function setUpSomeOtherSharedFixtures()
{
// ...
}
}
@codeCoverageIgnore
、@codeCoverageIgnoreStart
和 @codeCoverageIgnoreEnd
标注用于从覆盖率分析中排出掉某些代码行。
用法参见“忽略代码块”一节。
@covers
标注用在测试代码中,来指明测试方法想要对哪些方法进行测试:
/**
* @covers BankAccount::getBalance
*/public function testBalanceIsInitiallyZero(){
$this->assertEquals(0, $this->ba->getBalance());
}
如果提供了这个标注,则只考虑指明的这些方法的测试覆盖率信息。
表 B.1列出了 @covers
标注的语法。
表 B.1. 用于指明测试覆盖哪些方法的标注
标注 | 描述 |
---|
@covers ClassName::methodName | 指明所标注的测试方法覆盖指定的方法。 |
@covers ClassName | 指明所标注的测试方法覆盖给定类的全部方法。 |
@covers ClassName | 指明所标注的测试方法覆盖给定类以及其所有父类与接口的全部方法。 |
@covers ClassName:: | 指明所标注的测试方法覆盖给定类的所有 public 方法。 |
@covers ClassName:: | 指明所标注的测试方法覆盖给定类的所有 protected 方法。 |
@covers ClassName:: | 指明所标注的测试方法覆盖给定类的所有 private 方法。 |
@covers ClassName:: | 指明所标注的测试方法覆盖给定类的所有非 public 方法。 |
@covers ClassName:: | 指明所标注的测试方法覆盖给定类的所有非 protected 方法。 |
@covers ClassName:: | 指明所标注的测试方法覆盖给定类的所有非 private 方法。 |
@covers ::functionName | 指明所标注的测试方法覆盖给定的全局函数。 |
@coversDefaultClass
标注用于指定一个默认的命名空间或类名,这样就不用在每个 @covers
标注中重复长名称。参见例 B.1。
例 B.1: 用 @coversDefaultClass 缩短标注
@coversNothing
标注用在测试代码中,来指明所标注的测试用例不记录任何代码覆盖率信息。
这可以用于集成测试。例子可参见例 11.3。
这个标注可以用在类级别或者方法级别,并且会覆盖掉任何 @covers
标签。
测试方法可以接受任意参数。这些参数可以由数据供给器方法(例 2.5中的 provider()
)提供。所要使用的数据供给器方法用 @dataProvider
标注来指定。
更多细节参见“数据供给器”一节。
PHPUnit支持对测试方法之间的显式依赖关系进行声明。这种依赖关系并不是定义在测试方法的执行顺序中,而是允许生产者(producer)返回一个测试基境(fixture)的实例,并将此实例传递给依赖于它的消费者(consumer)们。例 2.2展示了如何用 @depends
标注来表达测试方法之间的依赖关系。
更多细节参见“测试的依赖关系”一节。
@expectedExceptionCode
标注,与 @expectedException
联合使用时,可以对来对抛出的异常的代号作出断言,这样可以缩小具体异常的范围。
class MyTest extends PHPUnit_Framework_TestCase{
/**
* @expectedException MyException
* @expectedExceptionCode 20
*/
public function testExceptionHasErrorcode20()
{
throw new MyException('Some Message', 20);
}
}
为了方便测试,并减少冗余,可以在 @expectedExceptionCode
中用"@expectedExceptionCode ClassName::CONST
"这样的语法为其指定类常数。
class MyTest extends PHPUnit_Framework_TestCase{
/**
* @expectedException MyException
* @expectedExceptionCode MyClass::ERRORCODE
*/
public function testExceptionHasErrorcode20()
{
throw new MyException('Some Message', 20);
}
}class MyClass{
const ERRORCODE = 20;
}
@expectedExceptionMessage
@expectedExceptionMessage
标注的运作方式类似于 @expectedExceptionCode
,它允许你对异常的错误讯息作出断言。
class MyTest extends PHPUnit_Framework_TestCase{
/**
* @expectedException MyException
* @expectedExceptionMessage Some Message
*/
public function testExceptionHasRightMessage()
{
throw new MyException('Some Message', 20);
}
}
预期讯息可以是异常讯息的子串。在只需要断言传入的特定名称或参数确实出现于异常中时这个特性很有用,这样就无需在测试中关注完整的异常讯息。
class MyTest extends PHPUnit_Framework_TestCase{
/**
* @expectedException MyException
* @expectedExceptionMessage broken
*/
public function testExceptionHasRightMessage()
{
$param = "broken"; throw new MyException('Invalid parameter "'.$param.'".', 20);
}
}
为了方便测试同时减少冗余,可以用"@expectedExceptionMessage ClassName::CONST
"语法将指定类常量作为 @expectedExceptionMessage
。 在“@expectedExceptionCode”一节 中可以看到范例。