README

概览

包包含以下组件

trait ExtraUtilsTrait 包含一组服务方法，用于简化测试
trait ExtraAssertionsTrait 包含一组额外的断言
trait WithVFSTrait 为 mikey179/vfsstream (虚拟文件系统) 提供适配的接口
从 JSON 文件加载测试数据，将每个测试用例包装到测试数据容器中
命令 generate-ide-test-containers 生成用于自动完成的 IDE 使用的服务文件

安装

建议通过 composer 安装

php composer.phar require raptor/test-utils:@stable

使用方法

附加服务方法

将 trait ExtraUtilsTrait 添加到包含测试的类或通用基测试类中。之后，以下静态方法将可用

invokeMethod(object $object, string $methodName, ?array $parameters = null) 使用给定参数调用受保护的或私有方法
expectExceptionExactMessage(string $message) 检查是否抛出了带有确切给定消息的异常

附加断言

将 trait ExtraAssertionsTrait 添加到包含测试的类或通用基测试类中。之后，以下附加断言将可用

assertArraysAreSame(array $expected, array $actual, ?string $message = null) 检查两个数组是否相同（元素顺序，每个级别的类型都相同）。在检查之前，数组被编码为 JSON 字符串，因此不能使用对象或函数作为数组元素。
assertArraysAreSameIgnoringOrder(array $expected, array $actual, ?string $message = null) 检查两个关联数组包含相同元素（在每个级别上），忽略顶级元素顺序。在检查之前，数组被编码为 JSON 字符串，因此不能使用对象或函数作为数组元素。
assertArraysAreSameIgnoringOrderRecursive(array $expected, array $actual, ?string $message = null) 检查两个关联数组包含相同元素，忽略每个级别上的元素顺序。在检查之前，数组被编码为 JSON 字符串，因此不能使用对象或函数作为数组元素。
assertReturnsCarbonNow(callable $func, ?string $message = null) 检查给定的函数返回在运行时调用的 Carbon::now() 的结果
assertReturnsCarbonNowWithoutMicroseconds(callable $func, ?string $message = null) 检查给定的函数返回在运行时调用的 Carbon::now() 的结果，并带有零微秒数
assertStringsAreSameIgnoringEOL(string $expected, string $actual, ?string $message = null) 检查两个给定字符串是否相同，忽略 EOL 字符串的差异

虚拟文件系统

将 trait WithVFSTrait 添加到包含测试的类或通用基测试类中。应在 setUp 方法或测试方法中使用 setupVFS 方法，在调用 trait 的其他方法之前。对于虚拟文件系统不需要进行 tearDown 操作。之后，以下附加方法将可用

addFileToVFS(string $filename, ?int $permissions = null, ?string $content = null) 将具有给定权限和内容的文件添加到虚拟文件系统。
addDirectoryToVFS(string $dirname, ?int $permissions = null) 将具有给定权限的目录添加到虚拟文件系统
addStructure(array $structure) 将目录结构添加到虚拟文件系统。结构表示为树，其中叶子是文件，键为文件名，值为文件内容
getFullPath(string $path) 返回用于虚拟文件系统外部的文件的完整路径

测试数据加载器

数据加载器允许您将测试数据从数据提供程序提取到单独的JSON文件中。数据加载的结果是一组测试用例，其中每个测试用例的数据都封装在容器对象中。特定字段的值通过getter返回。这种方法可以解决以下问题

将测试数据从代码提取到单独的JSON文件中
在方法签名膨胀的情况下传递多个参数给测试方法
在多个测试用例有共同数据时，将测试数据组织成层次结构

对JSON文件的要求

文件应包含数组的JSON对象，数组可以包含单个对象
字段名不应该以下划线开头，除非下面特别说明的情况
字段名应只包含小写字母、数字和下划线
数组中的每个对象应属于两种类型之一
1. 测试用例。此类对象不应包含服务字段 _children 且应包含服务字段 _name
2. 具有某些字段默认值的测试用例数组。此类对象应包含服务字段 _children 且不应包含服务字段 _name
服务字段 _name 应包含字符串，它是测试用例的名称
服务字段 _name 的值应唯一且非空
服务字段 _children 应包含数组，该数组满足与文件根数组相同的要求

第一种类型的对象的处理算法

如果正在处理的对象具有第二种类型的父对象，则
如果父对象包含不属于正在处理的对象的字段，则将这些字段及其相应的值添加到正在处理的对象中
如果父对象也有第二种类型的父对象，则重复对其父对象进行相同的操作，依此类推

数据加载器的中间结果是所有第一种类型对象的数组，其中服务字段 _name 的值作为键。服务字段 _name 本身被排除在对象之外。

然后，将每个数组值封装到 TestDataContainer 对象中。使用getter从容器中检索值。getter的名称遵循标准约定

如果字段名称以 'is' 开头，则getter名称是字段名称转换为驼峰式
否则，如果字段是布尔类型，则getter名称是字段名称转换为帕斯卡大小写并前缀为 'is'
否则，getter名称是字段名称转换为帕斯卡大小写并前缀为 'get'

为IDE生成服务文件

IDE的服务文件用于使用容器对象时的自动完成。通过以下命令调用生成器

    php vendor/raptor/test-utils/generate-ide-test-containers path

其中 path - 包含测试数据的JSON文件的目录路径。目录将被递归处理。对JSON文件的要求

每个JSON文件（不带扩展名）的名称应转换为帕斯卡大小写，转换后所有字符串必须不同。将不会处理重复的名称
每个JSON文件应满足 测试数据加载器 部分的要求

命令执行的结果是在项目根目录下生成了 _ide_test_containers.php 文件。该文件包含了指定目录中每个 JSON 文件的容器类。每个容器类位于根命名空间，其名称是通过将 JSON 文件名转换为 Studly Case 并添加后缀 DataContainer 得到的。在添加了适当的 PHPDoc 注释 @var 和类以及变量后，您可以使用自动完成功能。

使用 WithDataLoaderTrait 特质的示例

    use Raptor\Test\TestDataContainer\TestDataContainer;

    class someTests extends TestCase
    {
        use WithDataLoaderTrait;
             
        ...
        
        /**
         * @dataProvider someDataProvider
         */
        public function testSomething(TestDataContainer $dataContainer): void
        {
            /** @var \SomeTestsDataContainer $dataContainer */
            $value = $dataContainer->getValue();
            ...
        }
        
        public function someDataProvider(): array
        {
            return $this->loadFromFile('some_tests.json'); 
        }
        
        ...
    }

作者

米哈伊尔·卡莫林（Mikhail Kamorin），又名 raptor_MVK
伊戈尔·沃卡（Igor Vodka）

raptor / test-utils

维护者

详细信息