Mockery 参数验证（Argument Validation）指南：掌握 with() 匹配器与 Hamcrest 对照用法

示例工程数据库教程后端【免费下载链接】sql-server-samplesAzure Data SQL Samples - Official Microsoft GitHub Repository containing code samples for SQL Server, Azure SQL, Azure Synapse, and Azure SQL Edge项目地址https://gitcode.com/gh_mirrors/sq/sql-server-samples点击查看免费下载导读本文以 sql-server-samples 仓库中 Laravel 示例项目samples/development-frameworks/laravel所依赖的 Mockery 0.9 框架文档为蓝本系统讲解 Mockery 的**参数验证Argument Validation**机制——即通过with()声明为期望expectation设置参数匹配规则从而区分同一方法上的多条期望。读完本文你将掌握 Mockery 内置的全部通用匹配器any、type、on、ducktype、mustBe、not、anyOf、notAnyOf、subset、contains、hasKey、hasValue的语义与用法理解与 Hamcrest 库的对应关系并看到这些匹配器在仓库内源码中的真实实现为在 PHPUnit 单测中编写精确、可维护的 Mock 期望打下基础。说明Mockery 由 composer.json 中mockery/mockery: 0.9.*引入见 samples/development-frameworks/laravel/composer.json其文档位于vendor/mockery/mockery/docs/reference/本文即是对其中 argument_validation.rst 的展开解读。参数匹配的基本原理期望如何与调用对应在 Mockery 中当你设置一个期望时传给with()声明的参数决定了该期望与真实方法调用之间的匹配标准。因此你可以为同一个方法设置多条期望每条期望通过参数不同而相互区分。参数匹配采用best fit最契合优先原则显式匹配优先于泛化匹配。所谓显式匹配是指期望参数与实际参数可以被直接比较即通过或完成判定而更泛化的匹配则借助正则表达式、类型提示class hinting以及 Mockery 提供的通用匹配器实现。泛化匹配器的意义在于允许你用非显式的方式描述参数例如在with()中传入\Mockery::any()表示该位置接受任意参数。从源码结构看这一设计体现在匹配器的抽象基类中。所有内置匹配器都继承自 library/Mockery/Matcher/MatcherAbstract.php其中构造函数接收期望值_expected抽象方法match($actual)负责判断实际参数是否命中——注意实际参数以引用方式传入以保留指向原始方法参数的引用链抽象方法__toString()返回匹配器的字符串表示便于在失败消息中呈现期望内容。例如Any匹配器的match()直接return true见 library/Mockery/Matcher/Any.php这正对应文档中任何参数都能通过的描述。匹配器的入口Mockery 静态工厂方法Mockery 通过 library/Mockery.php 提供一组静态工厂方法来创建上述匹配器实例与文档一一对应文档中的写法工厂方法源码位置返回的匹配器类\Mockery::any()any()Matcher\Any\Mockery::type($expected)type()Matcher\Type\Mockery::ducktype(...)ducktype()Matcher\Ducktype\Mockery::subset(array $part)subset()Matcher\Subset\Mockery::contains(...)contains()Matcher\Contains\Mockery::hasKey($key)hasKey()Matcher\HasKey\Mockery::hasValue($val)hasValue()Matcher\HasValue\Mockery::on($closure)on()Matcher\Closure\Mockery::mustBe($expected)mustBe()Matcher\MustBe\Mockery::not($expected)not()Matcher\Not\Mockery::anyOf(...)anyOf()Matcher\AnyOf\Mockery::notAnyOf(...)notAnyOf()Matcher\NotAnyOf注意ducktype、contains、anyOf、notAnyOf使用func_get_args()收集可变数量的参数因此可以一次传入多个方法名或值。内置匹配器逐一详解以下逐一展开文档中的每个匹配器示例并给出对应的 Hamcrest 等价写法Hamcrest 使用无命名空间的函数Mockery 支持可选接入 Hamcrest 匹配器库以扩展能力Mockery 官方强烈推荐使用 Hamcrest因为 Mockery 无需重复实现 Hamcrest 已有的丰富工具后者还提供贴近自然英语的 DSL。1. 显式值匹配with(1)with(1)匹配整数1。它通过恒等测试同时Mockery 也支持较宽松的相等检查此时字符串1也能匹配该参数位。这是文档所述的显式匹配的基础形态。2. 匹配任意参数with(\Mockery::any())with(\Mockery::any()) // Mockery 写法 with(anything()) // Hamcrest 等价写法匹配任意参数。传在该参数位上的任何值都不受约束地通过实现上即Matcher\Any::match()恒返回true。3. 类型匹配with(\Mockery::type(resource))with(\Mockery::type(resource)) // Mockery 写法 with(resourceValue()) // Hamcrest 等价写法 with(typeOf(resource)) // Hamcrest 的另一种等价写法匹配任何 resource 类型的值即is_resource()返回true。Type 匹配器接受任何可以拼接为is_前缀形成合法类型检查的字符串\Mockery::type(float)或 Hamcrest 的floatValue()、typeOf(float)使用is_float()检查\Mockery::type(callable)或 Hamcrest 的callable()使用is_callable()检查。Type 匹配器还接受类名或接口名此时会对实际参数执行instanceof求值Hamcrest 对应anInstanceOf()。其底层实现可在 library/Mockery/Matcher/Type.php 中看到public function match($actual) { $function is_ . strtolower($this-_expected); if (function_exists($function)) { return $function($actual); } elseif (is_string($this-_expected) (class_exists($this-_expected) || interface_exists($this-_expected))) { return $actual instanceof $this-_expected; } return false; }即先尝试把期望值小写化为is_xxx()函数若不存在该函数再尝试作为类/接口名进行instanceof判断。完整的 PHP 类型检查函数清单可查阅 PHP 手册的 Variable handling 章节Hamcrest 函数列表可浏览其 Hamcrest.php 源码。4. 回调式匹配with(\Mockery::on(closure))with(\Mockery::on(closure))On 匹配器接受一个闭包匿名函数实际参数会被传入该闭包如果闭包返回布尔值true则认为该参数命中期望。当你的参数期望逻辑过于复杂、或现有默认匹配器无法表达时这个匹配器极为有用。Hamcrest 没有对应实现。5. 正则匹配with(/^foo/)with(/^foo/) // Mockery 写法 with(matchesPattern(/^foo/)) // Hamcrest 等价写法参数声明器会假定任何给定的字符串都可能是一条正则表达式用于对实际参数做匹配。正则选项仅在满足以下两个条件时才启用不存在或的显式匹配该正则被验证为合法正则即preg_match()不会返回false。如果你不喜欢这种隐式正则探测的行为Hamcrest 提供了更显式的matchesPattern()函数。6. 鸭子类型匹配with(\Mockery::ducktype(foo, bar))with(\Mockery::ducktype(foo, bar))Ducktype 匹配器是按类类型匹配之外的另一种思路它匹配任何包含给定方法列表的对象即只要对象实现了列出的这些方法就命中而不管其具体类是什么走起来像鸭子、叫起来像鸭子那就是鸭子。Hamcrest 没有对应实现。7. 严格恒等匹配with(\Mockery::mustBe(2))with(\Mockery::mustBe(2)) // Mockery 写法 with(identicalTo(2)) // Hamcrest 等价写法MustBe 匹配器比默认参数匹配器更严格。默认匹配器允许 PHP 的类型转换casting而 MustBe 还要求参数与期望值类型一致。例如默认情况下字符串2可以匹配整数 2经比较但使用 MustBe 时该场景会失败因为期望值是字符串而实际传入的是整数。注意事项对于对象MustBe 匹配器不进行恒等identical比较因为 PHP 中两个对象若不是完全相同的实例比较必然失败——当对象在返回之前才被创建时恒等匹配永远不可能成功这反而成为一种阻碍。因此对象场景请改用其他匹配方式。8. 取反匹配with(\Mockery::not(2))with(\Mockery::not(2)) // Mockery 写法 with(not(2)) // Hamcrest 等价写法Not 匹配器匹配任何不等于且不恒等于其参数的值即与参数既不也不才通过。9. 多选一匹配with(\Mockery::anyOf(1, 2))with(\Mockery::anyOf(1, 2)) // Mockery 写法 with(anyOf(1, 2)) // Hamcrest 等价写法匹配等于给定参数中任意一个的参数即与列表中的任一值相等即命中。10. 全排除匹配with(\Mockery::notAnyOf(1, 2))with(\Mockery::notAnyOf(1, 2))匹配不等于且不恒等于给定参数中任何一个的参数。Hamcrest 没有对应实现。11. 数组子集匹配with(\Mockery::subset(array(0 foo)))with(\Mockery::subset(array(0 foo)))匹配任何包含给定数组子集的数组参数。它同时强制键名与键值的比对——即实际元素的键和值都要与子集中的键值对一一对应。Hamcrest 没有完全对应的实现不过它可以用hasEntry()或hasKeyValuePair()检查单个条目。12. 数组包含值匹配with(\Mockery::contains(value1, value2))with(\Mockery::contains(value1, value2))匹配任何包含所列值的数组参数键名被忽略只关心值是否存在。13. 数组包含键匹配with(\Mockery::hasKey(key))with(\Mockery::hasKey(key))匹配任何包含给定键名的数组参数。14. 数组包含值匹配with(\Mockery::hasValue(value))with(\Mockery::hasValue(value))匹配任何包含给定值的数组参数。在 Laravel 项目中的落地从依赖到测试在 sql-server-samples 仓库的 Laravel 示例项目 samples/development-frameworks/laravel 中Mockery 0.9 是require-dev依赖之一见 composer.json与 PHPUnit~4.0、PHPSpec~2.1一同服务于开发与测试阶段。该项目的运行环境为 PHP 7、Laravel 5.1、SQL Server PHP/ODBC 驱动见 README.md其tests/TestCase.php被注册到autoload-dev的 classmap 中。将本文的匹配器应用到该项目的测试中时典型模式如下$repository Mockery::mock(TodoRepository::class); $repository-shouldReceive(find) -with(\Mockery::type(int)) // 仅匹配整数 id -once() -andReturn($todo); $repository-shouldReceive(update) -with(\Mockery::anyOf(1, 2), \Mockery::subset([status done])) -andReturn(true);第一条期望利用type(int)限定find只接受整数主键第二条期望用anyOf(1, 2)限定可操作的 id用subset校验传入的更新数组必须包含status done键值对。这种写法正是文档所述best fit原则的实践同一方法的多条with()期望共存时Mockery 会优先匹配最显式、最具体的声明保证测试行为可预期。总结与选型建议Mockery 的通用匹配器并不覆盖所有可能性但它提供了可选的 Hamcrest 匹配器库支持作为补充。选型时可遵循以下原则简单值与正则优先使用默认显式匹配与正则探测代码最简洁类型、类与接口约束使用type()或 HamcrestanInstanceOf()/typeOf()复杂判定逻辑使用on()闭包逻辑自由度最高数组结构断言按需选择subset、contains、hasKey、hasValue注意subset同时校验键名与键值contains忽略键名否定与多选not、anyOf、notAnyOf可组合出取反与枚举语义严格类型需要同时约束值与类型时使用mustBe()但切记对象不适合恒等比较。需要进一步深入时可直接查阅仓库内 Mockery 的完整文档目录 vendor/mockery/mockery/docs以及匹配器实现源码 library/Mockery/Matcher 和工厂方法定义 library/Mockery.php。赞分享示例工程数据库教程后端【免费下载链接】sql-server-samplesAzure Data SQL Samples - Official Microsoft GitHub Repository containing code samples for SQL Server, Azure SQL, Azure Synapse, and Azure SQL Edge项目地址https://gitcode.com/gh_mirrors/sq/sql-server-samples点击查看免费下载相关推荐Mockery 参数校验Argument Validation完全指南with() 与全套 Matcher 深入解析Mockery 参数校验Argument Validation完全指南with 与全套 Matcher 深入解析 本文是 Mockery 官方文档 doc测试开发工具终极指南掌握Hamcrest-PHP对象匹配器的10个高级技巧Hamcrest PHP是一个强大的PHP测试框架专门用于编写更具表达力和可读性的断言。作为PHP Hamcrest的官方实现它提供了丰富的对象匹配器让您测试OmenSuperHub终极指南惠普游戏本性能优化神器OmenSuperHub终极指南惠普游戏本性能优化神器 还在为官方OMEN Gaming Hub的臃肿体验而烦恼OmenSuperHub为你带来纯净高效的硬桌面应用硬件开发创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考