- 3. XML 配置文件
<phpunit>
元素backupGlobals
属性backupStaticAttributes
属性bootstrap
属性cacheResult
属性cacheResultFile
属性colors
属性columns
属性convertDeprecationsToExceptions
属性convertErrorsToExceptions
属性convertNoticesToExceptions
属性convertWarningsToExceptions
属性forceCoversAnnotation
属性printerClass
属性printerFile
属性processIsolation
属性stopOnError
属性stopOnFailure
属性stopOnIncomplete
属性stopOnRisky
属性stopOnSkipped
属性stopOnWarning
属性stopOnDefect
属性failOnRisky
属性failOnWarning
属性beStrictAboutChangesToGlobalState
属性beStrictAboutOutputDuringTests
属性beStrictAboutResourceUsageDuringSmallTests
属性beStrictAboutTestsThatDoNotTestAnything
属性beStrictAboutTodoAnnotatedTests
属性beStrictAboutCoversAnnotation
属性enforceTimeLimit
属性defaultTimeLimit
属性timeoutForSmallTests
属性timeoutForMediumTests
属性timeoutForLargeTests
属性testSuiteLoaderClass
属性testSuiteLoaderFile
属性defaultTestSuite
属性verbose
属性stderr
属性reverseDefectList
属性registerMockObjectsFromTestArgumentsRecursively
属性extensionsDirectory
属性executionOrder
属性resolveDependencies
属性testdox
属性noInteraction
属性
<testsuites>
元素<coverage>
元素<logging>
元素<groups>
元素<testdoxGroups>
元素<listeners>
元素<extensions>
元素<php>
元素
3. XML 配置文件
<phpunit>
元素
backupGlobals
属性
可能值:true
或 false
(默认值:false
)
PHPUnit 可选地允许在每个测试之前备份所有全局与超全局变量,并在每个测试结束后还原这些备份。
此属性为所有测试配置此操作,可以在测试用例类和测试方法级别用 @backupGlobals
标注来覆盖此配置。
backupStaticAttributes
属性
可能值:true
或 false
(默认值:false
)
PHPUnit 可选地允许在每个测试之前备份所有已声明类的静态属性,并在每个测试结束后还原这些备份。
此属性为所有测试配置此操作,可以在测试用例类和测试方法级别用 @backupStaticAttributes
标注来覆盖此配置。
bootstrap
属性
此属性配置在执行测试之前加载的引导脚本。此脚本通常仅注册用于加载被测代码的自动加载器回调函数。
cacheResult
属性
可能值:true
或 false
(默认值:true
)
此属性配置测试结果的缓存。该缓存是某些其他功能正常工作所必须的。
cacheResultFile
属性
此属性配置测试结果缓存(见上文)储存在哪个文件中。
colors
属性
可能值:true
或 false
(默认值:false
)
此属性配置 PHPUnit 的输出是否使用彩色。
将此属性设置为 true
等效于使用 --colors=auto
命令行选项。
将此属性设置为 false
等效于使用 --colors=never
命令行选项。
columns
属性
可能值:整数或字符串 max
(默认值:80
)
此属性配置进度输出所用的列数。
如果定义了 max
作为其值,则列数为当前终端的最大值。
convertDeprecationsToExceptions
属性
可能值:true
或 false
(默认值:true
)
此属性配置是否将被测代码所触发的 E_DEPRECATED
和 E_USER_DEPRECATED
事件转换为异常(并将此测试标记为错误)。
convertErrorsToExceptions
属性
可能值:true
或 false
(默认值:true
)
此属性配置是否将被测代码所触发的 E_ERROR
和 E_USER_ERROR
事件转换为异常(并将此测试标记为错误)。
convertNoticesToExceptions
属性
可能值:true
或 false
(默认值:true
)
此属性配置是否将被测代码所触发的 E_STRICT
、E_NOTICE
和 E_USER_NOTICE
事件转换为异常(并将此测试标记为错误)。
convertWarningsToExceptions
属性
可能值:true
或 false
(默认值:true
)
此属性配置是否将被测代码所触发的 E_WARNING
和 E_USER_WARNING
事件转换为异常(并将此测试标记为错误)。
forceCoversAnnotation
属性
可能值:true
或 false
(默认值:false
)
此属性配置的是在没有 @covers 标注时,测试是否要标记为有风险(参见意外的代码覆盖)。
printerClass
属性
默认值:PHPUnit\TextUI\ResultPrinter
此属性配置的是一个类名,这个类是 PHPUnit\TextUI\ResultPrinter
或者是扩展自 PHPUnit\TextUI\ResultPrinter
的类。会使用此类的一个实例对象来打印进度和测试结果。
printerFile
属性
此属性可用于配置 printerClass
所配置的类的声明所在源代码文件,以防此类无法自动加载的情况。
processIsolation
属性
可能值:true
或 false
(默认值:false
)
此属性配置是否应当对每个测试都用单独的 PHP 进程来运行以提高隔离度。
stopOnError
属性
可能值:true
或 false
(默认值:false
)
此属性配置是否应当在第一个以“错误(error)”状态结束的测试之后停止测试套件的执行。
stopOnFailure
属性
可能值:true
或 false
(默认值:false
)
此属性配置是否应当在第一个以“失败(failure)”状态结束的测试之后停止测试套件的执行。
stopOnIncomplete
属性
可能值:true
或 false
(默认值:false
)
此属性配置是否应当在第一个以“未完成(incomplete)”状态结束的测试之后停止测试套件的执行。
stopOnRisky
属性
可能值:true
或 false
(默认值:false
)
此属性配置是否应当在第一个以“有风险(risky)”状态结束的测试之后停止测试套件的执行。
stopOnSkipped
属性
可能值:true
或 false
(默认值:false
)
此属性配置是否应当在第一个以“跳过(skipped)”状态结束的测试之后停止测试套件的执行。
stopOnWarning
属性
可能值:true
或 false
(默认值:false
)
此属性配置是否应当在第一个以“警告(warning)”状态结束的测试之后停止测试套件的执行。
stopOnDefect
属性
可能值:true
或 false
(默认值:false
)
此属性配置是否应当在第一个以“错误(error)”、“失败(failure)”,“有风险(risky)”或“警告(warning)”状态结束的测试之后停止测试套件的执行。
failOnRisky
属性
可能值:true
或 false
(默认值:false
)
此属性配置的是在所有测试都成功但有部分测试被标记为有风险(risky)时,PHPUnit 测试执行器在退出时是否应当使用指示失败的 sell 退出码。
failOnWarning
属性
可能值:true
或 false
(默认值:false
)
此属性配置的是在所有测试都成功但有部分测试有警告(warning)时,PHPUnit 测试执行器在退出时是否应当使用指示失败的 sell 退出码。
beStrictAboutChangesToGlobalState
属性
可能值:true
或 false
(默认值:false
)
此属性配置当被测代码(或测试代码)操纵全局状态时,PHPUnit 是否应将测试标记为有风险(risky)。
beStrictAboutOutputDuringTests
属性
可能值:true
或 false
(默认值:false
)
此属性配置当被测代码(或测试代码)打印输出时,PHPUnit 是否应将测试标记为有风险(risky)。
beStrictAboutResourceUsageDuringSmallTests
属性
可能值:true
或 false
(默认值:false
)
此属性配置的是当标注为 @small
的测试调用对 resource
变量进行操作的 PHP 内建函数或方法时,PHPUnit 是否应将其标记为有风险(risky)。
beStrictAboutTestsThatDoNotTestAnything
属性
可能值:true
或 false
(默认值:true
)
此属性配置在测试未执行任何断言(预期也算在内)时,PHPUnit 是否应将其标记为有风险(risky)。
beStrictAboutTodoAnnotatedTests
属性
可能值:true
或 false
(默认值:false
)
此属性配置在测试有 @todo
标注时,PHPUnit 是否应将其标记为有风险。
beStrictAboutCoversAnnotation
属性
可能值:true
或 false
(默认值:false
)
此属性配置在测试执行未使用 @covers
或 @uses
指定的代码时,PHPUnit 是否应将其标记为有风险。
enforceTimeLimit
属性
可能值:true
或 false
(默认值:false
)
此属性配置是否应实施时间限制。
defaultTimeLimit
属性
可能值:整数(默认值:0
)
此属性配置默认时间限制(以秒为单位)。
timeoutForSmallTests
属性
可能值:整数(默认值:1
)
此属性配置标注为 @small
的测试的时间限制(以秒为单位)。
timeoutForMediumTests
属性
可能值:整数(默认值:10
)
此属性配置标注为 @medium
的测试的时间限制(以秒为单位)。
timeoutForLargeTests
属性
可能值:整数(默认值:60
)
此属性配置标注为 @large
的测试的时间限制(以秒为单位)。
testSuiteLoaderClass
属性
默认值:PHPUnit\Runner\StandardTestSuiteLoader
此属性配置的是一个类名,这个类必须实现 PHPUnit\Runner\TestSuiteLoader
接口。会用此类的一个实例对象来加载测试套件。
testSuiteLoaderFile
属性
此属性可用于配置 testSuiteLoaderClass
所配置的类的声明所在源代码文件,以防此类无法自动加载的情况。
defaultTestSuite
属性
此属性配置默认测试套件名称。
verbose
属性
可能值:true
或 false
(默认值:false
)
此属性配置是否应打印更详细的输出。
stderr
属性
可能值:true
或 false
(默认值:false
)
此属性配置 PHPUnit 是否应将其输出打印到 stderr
而不是 stdout
。
reverseDefectList
属性
可能值:true
或 false
(默认值:false
)
此属性配置是否应以逆序打印不成功的测试。
registerMockObjectsFromTestArgumentsRecursively
属性
可能值:true
或 false
(默认值:false
)
此属性配置是否应对用 @depends
批注从一个测试传递到另一测试的数组和对象图进行递归扫描以查找仿件对象。
extensionsDirectory
属性
当使用 phpunit.phar
时,此属性可用于配置一个目录,这个目录中的所有 * .phar 文件都会被加载作为PHPUnit 测试执行器的扩展。
executionOrder
属性
可能值:default
、defects
、depends
、no-depends
、duration
、random
、reverse
、size
可以使用多个值。这些值之间需要用 ,
分割。
此属性配置测试的执行顺序。
resolveDependencies
属性
可能值:true
或 false
(默认值:true
)
此属性配置是否应解决测试之间(用 @depends
注解表示)的依赖关系。
testdox
属性
可能值:true
或 false
(默认值:false
)
此属性配置是否以 TestDox 格式打印输出。
noInteraction
属性
可能值:true
或 false
(默认值:false
)
此属性配置在使用 TestDox 格式时,比如说,进度是否应当是动画。
<testsuites>
元素
父元素:<phpunit>
此元素是一个或多个 <testsuite>
元素的根元素,用于配置需要执行的测试。
<testsuite>
元素
父元素:<testsuites>
<testsuite>
元素必须拥有 name
属性,可以有一个或多个 <directory>
及 <file>
子元素,分别代表需要搜索测试的目录及元素。
<testsuites>
<testsuite name="unit">
<directory>tests/unit</directory>
</testsuite>
<testsuite name="integration">
<directory>tests/integration</directory>
</testsuite>
<testsuite name="edge-to-edge">
<directory>tests/edge-to-edge</directory>
</testsuite>
</testsuites>
可以用 phpVersion
和 phpVersionOperator
属性来指定 PHP 版本需求:
<testsuites>
<testsuite name="unit">
<directory phpVersion="8.0.0" phpVersionOperator=">=">tests/unit</directory>
</testsuite>
</testsuites>
在上面的示例中,仅当 PHP 版本至少为 8.0.0 时,才会将 tests/unit
目录中的测试添加到测试套件中。phpVersionOperator
属性是可选的,默认为 >=
。
<coverage>
元素
父元素:<phpunit>
<coverage>
元素及其子元素可用于配置代码覆盖率:
<coverage cacheDirectory="/path/to/directory"
includeUncoveredFiles="true"
processUncoveredFiles="true"
pathCoverage="false"
ignoreDeprecatedCodeUnits="true"
disableCodeCoverageIgnore="true">
<!-- ... -->
</coverage>
cacheDirectory
属性
可能值:字符串
当收集并处理代码覆盖率数据时,将执行静态代码分析以改善有关覆盖代码的推理。这是一项昂贵的操作,而其结果可以缓存。设置 cacheDirectory
属性后,静态分析结果将缓存在指定目录中。
includeUncoveredFiles
属性
可能值:true
或 false
(默认值:true
)
当设置为 true
时,所有配置为代码覆盖率分析需要考虑的源代码文件都将包含在代码覆盖率报告中。这包括测试运行时并未执行的源代码文件。
processUncoveredFiles
属性
可能值:true
或 false
(默认值:false
)
当设置为 true
时,所有配置为代码覆盖率分析需要考虑的源代码文件都将被处理。这包括测试运行时并未执行的源代码文件。
ignoreDeprecatedCodeUnits
属性
可能值:true
或 false
(默认值:false
)
此属性配置代码覆盖率是否应忽略标注为 @deprecated
的代码单元。
pathCoverage
属性
可能值:true
或 false
(默认值:false
)
设置为 false
时,将仅收集、处理和报告行覆盖率数据。
设置为 true
时,将收集、处理和报告行覆盖率、分支覆盖率和路径覆盖率数据。这需要支持路径覆盖率的代码覆盖率驱动程序。目前只有 Xdebug 实现了路径覆盖率。
disableCodeCoverageIgnore
属性
可能值:true
或 false
(默认值:false
)
此属性配置是否应忽略 @codeCoverageIgnore*
批注。
The <include>
Element
父元素:<coverage>
配置要包含在代码覆盖率报告中的文件集合。
<include>
<directory suffix=".php">src</directory>
</include>
上面示例指示 PHPUnit 在代码覆盖率报告中要包含在 src
目录及其子目录中的所有带 .php
后缀的源代码文件。
<exclude>
元素
父元素:<coverage>
配置要从代码覆盖率报告中排除的文件集合。
<include>
<directory suffix=".php">src</directory>
</include>
<exclude>
<directory suffix=".php">src/generated</directory>
<file>src/autoload.php</file>
</exclude>
上面示例指示 PHPUnit 在代码覆盖率报告中要包含在 src
目录及其子目录中的所有带 .php
后缀的源代码文件,但要排除 src/generated
目录及其子目录中的所有带 .php
后缀的文件以及 src/autoload.php
文件。
<directory>
元素
父元素:<include>
、<exclude>
配置要包含在代码覆盖率报告中或从代码覆盖率报告中排除的目录及其子目录。
prefix
属性
可能值:字符串
配置基于前缀的过滤器,该过滤器将应用于目录及其子目录中的文件名。
suffix
属性
可能值:string(默认值:'.php'
)
配置基于后缀的过滤器,该过滤器将应用于目录及其子目录中的文件名。
phpVersion
属性
可能值:字符串
配置基于用来运行当前 PHPUnit 进程的 PHP 运行时版本的过滤器。
phpVersionOperator
属性
可能值:'<'
、'lt'
、'<='
、'le'
、'>'
、'gt'
、'>='
、'ge'
、'=='
、'='
、'eq'
, '!='
, '<>'
, 'ne'
(默认值:'>='
)
配置基于用来运行当前 PHPUnit 进程的 PHP 运行时版本的过滤器的 version_compare()
操作所用的比较运算符。
<file>
元素
父元素:<include>
、<exclude>
配置要包含在代码覆盖率报告中或从代码覆盖率报告中排除的文件。
<report>
元素
父元素:<coverage>
配置要生成的代码覆盖率报告。
<report>
<clover outputFile="clover.xml"/>
<crap4j outputFile="crap4j.xml" threshold="50"/>
<html outputDirectory="html-coverage" lowUpperBound="50" highLowerBound="90"/>
<php outputFile="coverage.php"/>
<text outputFile="coverage.txt" showUncoveredFiles="false" showOnlySummary="true"/>
<xml outputDirectory="xml-coverage"/>
</report>
<clover>
元素
父元素:<report>
配置 Clover XML 格式的代码覆盖率报告。
outputFile
属性
可能值:字符串
Clover XML 报告写入的文件。
<crap4j>
元素
父元素:<report>
配置 Crap4J XML 格式的代码覆盖率报告。
outputFile
属性
可能值:字符串
Crap4J XML 报告写入的文件。
threshold
属性
可能值:integer(默认值:50
)
<html>
元素
父元素:<report>
配置 HTML 格式的代码覆盖率报告。
outputDirectory
属性
HTML 报告写入的目录。
lowUpperBound
属性
可能值:integer(默认值:50
)
应当被视为“低覆盖率”的上限。
highLowerBound
属性
可能值:整数(默认值:90
)
应当被视为“高覆盖率”的下限。
<php>
元素
父元素:<report>
配置 PHP 格式的代码覆盖率报告。
outputFile
属性
可能值:字符串
PHP 报告写入的文件。
<text>
元素
父元素:<report>
配置文本格式的代码覆盖率报告。
outputFile
属性
可能值:字符串
文本报告写入的文件。
showUncoveredFiles
属性
可能值:true
或 false
(默认值:false
)
showOnlySummary
属性
可能值:true
或 false
(默认值:false
)
<xml>
元素
父元素:<report>
配置 PHPUnit XML 格式的代码覆盖率报告。
outputDirectory
属性
可能值:字符串
PHPUnit XML 报告写入的目录。
<logging>
元素
父元素:<phpunit>
<logging>
元素及其子元素可用于配置测试执行期间的日志记录。
<logging>
<junit outputFile="junit.xml"/>
<teamcity outputFile="teamcity.txt"/>
<testdoxHtml outputFile="testdox.html"/>
<testdoxText outputFile="testdox.txt"/>
<testdoxXml outputFile="testdox.xml"/>
<text outputFile="logfile.txt"/>
</logging>
<junit>
元素
父元素:<logging>
配置 JUnit XML 格式的测试结果日志文件。
outputFile
属性
可能值:字符串
JUnit XML 格式的测试结果日志写入的文件。
<teamcity>
元素
父元素:<logging>
配置 TeamCity 格式的测试结果日志文件。
outputFile
属性
可能值:字符串
TeamCity 格式的测试结果日志写入的文件。
<testdoxHtml>
元素
父元素:<logging>
配置 TestDox HTML 格式的测试结果日志文件。
outputFile
属性
可能值:字符串
TestDox HTML 格式的测试结果日志写入的文件。
<testdoxText>
元素
父元素:<logging>
配置 TestDox 文本格式的测试结果日志文件。
outputFile
属性
可能值:字符串
TestDox 文本格式的测试结果日志写入的文件。
<testdoxXml>
元素
父元素:<logging>
配置 TestDox XML 格式的测试结果日志文件。
outputFile
属性
可能值:字符串
TestDox XML 格式的测试结果日志写入的文件。
<text>
元素
父元素:<logging>
配置文本格式的测试结果日志文件。
outputFile
属性
可能值:字符串
文本格式的测试结果日志写入的文件。
<groups>
元素
父元素:<phpunit>
<groups>
元素及其 <include>
、<exclude>
、<group>
子元素用于从带有 @group
标注(相关文档参见 @group)的测试中选择需要运行(或不运行)的分组。
<groups>
<include>
<group>name</group>
</include>
<exclude>
<group>name</group>
</exclude>
</groups>
上面的示例等效于以 --group name --exclude-group name
调用 PHPUnit 测试执行器。
<testdoxGroups>
元素
父元素:<phpunit>
… <待完成> …
<listeners>
元素
父元素:<phpunit>
<listeners>
元素及其 <listener>
子元素可用于在测试执行期间附加额外的测试监听器。
<listener>
元素
父元素:<listeners>
<listeners>
<listener class="MyListener" file="/optional/path/to/MyListener.php">
<arguments>
<array>
<element key="0">
<string>Sebastian</string>
</element>
</array>
<integer>22</integer>
<string>April</string>
<double>19.78</double>
<null/>
<object class="stdClass"/>
</arguments>
</listener>
</listeners>
以上 XML 配置对应于将 $listener
对象(见下文)附到测试执行过程上。
$listener = new MyListener(
['Sebastian'],
22,
'April',
19.78,
null,
new stdClass
);
注
请注意,PHPUnit\Framework\TestListener
接口已废弃,将在以后删除。应该改用测试执行器扩展来替代测试监听器。
<extensions>
元素
父元素:<phpunit>
<extensions>
元素及其 <extension>
子元素可用于注册测试执行器扩展。
<extension>
元素
父元素:<extensions>
<extensions>
<extension class="Vendor\MyExtension"/>
</extensions>
<arguments>
元素
父元素:<extension>
<arguments>
元素可用于配置单个 <extension>
。
接受类型的元素的列表,该列表用于配置各个扩展。参数会按照在配置中定义的顺序被传递给扩展类的 __constructor
方法。
可用类型:
<boolean>
<integer>
<string>
<double>
(浮点数)<array>
<object>
<extension class="Vendor\MyExtension">
<arguments>
<integer>1</integer>
<integer>2</integer>
<integer>3</integer>
<string>hello world</string>
<boolean>true</boolean>
<double>1.23</double>
<array>
<element index="0">
<string>value1</string>
</element>
<element index="1">
<string>value2</string>
</element>
</array>
<object class="Vendor\MyPhpClass">
<string>constructor arg 1</string>
<string>constructor arg 2</string>
</object>
</arguments>
</extension>
<php>
元素
父元素:<phpunit>
<php>
元素及其子元素用于配置 PHP 设置、常量以及全局变量。同时也可用于向 include_path
前面添加内容。
<includePath>
元素
父元素:<php>
此元素可用于向 include_path
前面添加一个路径。
<ini>
元素
父元素:<php>
此元素可用于设置 PHP 配置。
<php>
<ini name="foo" value="bar"/>
</php>
以上 XML 配置对应于如下 PHP 代码:
ini_set('foo', 'bar');
<const>
元素
父元素:<php>
此元素可用于设置全局常数。
<php>
<const name="foo" value="bar"/>
</php>
以上 XML 配置对应于如下 PHP 代码:
define('foo', 'bar');
<var>` 元素
父元素:<php>
此元素可用于设置全局变量。
<php>
<var name="foo" value="bar"/>
</php>
以上 XML 配置对应于如下 PHP 代码:
$GLOBALS['foo'] = 'bar';
<env>
元素
父元素:<php>
此元素可用于在超全局数组 $_ENV
中设置一个值。
<php>
<env name="foo" value="bar"/>
</php>
以上 XML 配置对应于如下 PHP 代码:
$_ENV['foo'] = 'bar';
默认情况下,如果环境变量已经存在,则不会覆盖之。要强制覆盖已存在的变量,用 force
属性:
<php>
<env name="foo" value="bar" force="true"/>
</php>
<get>
元素
父元素:<php>
此元素可用于在超全局数组 $_GET
中设置一个值。
<php>
<get name="foo" value="bar"/>
</php>
以上 XML 配置对应于如下 PHP 代码:
$_GET['foo'] = 'bar';
<post>
元素
父元素:<php>
此元素可用于在超全局数组 $_POST
中设置一个值。
<php>
<post name="foo" value="bar"/>
</php>
以上 XML 配置对应于如下 PHP 代码:
$_POST['foo'] = 'bar';
<cookie>
元素
父元素:<php>
此元素可用于在超全局数组 $_COOKIE
中设置一个值。
<php>
<cookie name="foo" value="bar"/>
</php>
以上 XML 配置对应于如下 PHP 代码:
$_COOKIE['foo'] = 'bar';
<server>
元素
父元素:<php>
此元素可用于在超全局数组 $_SERVER
中设置一个值。
<php>
<server name="foo" value="bar"/>
</php>
以上 XML 配置对应于如下 PHP 代码:
$_SERVER['foo'] = 'bar';
<files>
元素
父元素:<php>
此元素可用于在超全局数组 $_FILES
中设置一个值。
<php>
<files name="foo" value="bar"/>
</php>
以上 XML 配置对应于如下 PHP 代码:
$_FILES['foo'] = 'bar';
<request>
元素
父元素:<php>
此元素可用于在超全局数组 $_REQUEST
中设置一个值。
<php>
<request name="foo" value="bar"/>
</php>
以上 XML 配置对应于如下 PHP 代码:
$_REQUEST['foo'] = 'bar';