Coolify 测试实战：laravel-actions 的 AsFake 假对象体系与 Action 编排测试-开发者社区

Coolify 测试实战：laravel-actions 的 AsFake 假对象体系与 Action 编排测试

【免费下载链接】coolifyAn open-source, self-hostable PaaS alternative to Vercel, Heroku & Netlify that lets you easily deploy static sites, databases, full-stack applications and 280+ one-click services on your own servers.项目地址: https://gitcode.com/GitHub_Trending/co/coolify

本文基于 Coolify 仓库中lorisleiva/laravel-actions包的 Action Fakes 参考文档，完整覆盖AsFaketrait 提供的mock、partialMock、spy、shouldRun、shouldNotRun、allowToRun、isFake、clearFake全部假对象方法的语义与用法，并结合 Coolify 源码中真实的 Action 类与 Pest 测试用例（如 Stripe 订阅对账、资源迁移编排），说明如何在真实大型 Laravel 项目中隔离 Action 编排、断言执行与否，并避免 fake 泄漏。读完后你能掌握「只在被测边界做 fake」的两层测试策略，并能写出可验证的分支覆盖测试。

一、问题背景：为什么需要 Action Fakes

Coolify 是一个自托管 PaaS，其业务逻辑大量沉淀在App\Actions命名空间下——仓库中实际有 57 个类使用了Lorisleiva\Actions\Concerns\AsActiontrait（如app/Actions/Stripe/SyncStripeSubscriptions.php、app/Actions/Service/StartService.php等），依赖composer.json中声明的lorisleiva/laravel-actions（版本约束^2.10.2）。

这些 Action 往往同时承担多种入口（HTTP、队列 Job、事件监听器、Artisan 命令），测试时面临两个诉求：

业务正确性：handle(...)里的领域规则必须用真实依赖验证；
编排正确性：上层入口（Controller、Job、Command）调用了哪些下游 Action、参数是否传对，不能被下游的副作用（SSH 连接、Docker 命令、外部 API）拖垮。

AsFake假对象体系就是为此设计的：它允许你用一行静态调用把某个 Action 类替换为 mock/spy，并声明「它应该（或不应该）被执行」。该参考文档的适用场景即「在测试中隔离 action 编排」（isolating action orchestration in tests）。

二、推荐的测试模式：两层策略

参考文档给出的 Recommended pattern 是三条清晰原则，Coolify 的测试组织方式与之完全一致：

直接测试handle(...)验证业务规则：用工厂构造真实模型数据，调用SyncStripeSubscriptions::run(...)后断言数据库最终状态；
测试入口（entrypoint）验证接线与编排：例如执行 Artisan 命令、调用迁移编排方法，只关心下游 Action 是否被正确调度；
只在被测边界处使用 fake：不要把一切全 mock 掉，否则测试失去对行为的信心（这是文档 Common pitfalls 第一条）。

三、AsFake 全部方法详解

以下逐一介绍AsFaketrait 提供的 8 个方法，每个方法均附参考文档的标准示例及其语义边界。

3.1`mock()`：完整 mock

将 Action 整体替换为一个 full mock，所有方法都不再执行真实逻辑，用于「严格期望 + 参数断言」的场景：

FetchContactsFromGoogle::mock() ->shouldReceive('handle') ->with(42) ->andReturn(['Loris', 'Will', 'Barney']);

从源码结构看，mock()底层构建的是 Mockery 风格的期望对象：shouldReceive声明「期望被调用」，with约束参数契约，andReturn指定桩返回值。当被 mock 的 Action 在后续代码路径中被真实触发时，若参数不匹配或未被调用（而期望了调用），测试会失败——这就是「fail fast」的交互契约。

3.2`partialMock()`：部分 mock

保留大部分真实行为，只替换其中一到两个昂贵/内部方法，适合「行为大体真实、仅屏蔽一次外部调用」的场景：

FetchContactsFromGoogle::partialMock() ->shouldReceive('fetch') ->with('some_google_identifier') ->andReturn(['Loris', 'Will', 'Barney']);

Coolify 测试中同样有类似的部分 mock 用法，例如 ServiceTemplatesLastUpdatedHintTest.php 中对 Laravel 的Filefacade 使用File::partialMock()屏蔽文件系统读取——同一个「只截断一条昂贵路径」的思路。

3.3`spy()`：监视器

spy 不预设严格期望，而是「放行调用 + 事后验证」，最适合先执行代码、再回答「它是否带着 X 参数被调用过」的问题：

$spy = FetchContactsFromGoogle::spy() ->allows('handle') ->andReturn(['Loris', 'Will', 'Barney']); // ... $spy->shouldHaveReceived('handle')->with(42);

allows('handle')表示放行该方法并允许指定返回值；shouldHaveReceived(...)是断言端，可在执行完毕后的任意位置调用。

3.4`shouldRun()`：正向编排断言

这是mock()->shouldReceive('handle')的语法糖，一行代码即可完成「这个 Action 必须被执行」的声明：

FetchContactsFromGoogle::shouldRun(); // Equivalent to: FetchContactsFromGoogle::mock()->shouldReceive('handle');

由于它返回的是期望链对象，可以继续追加once()、with(...)、andReturn(...)等方法。Coolify 的真实用例见 SyncStripeSubscriptionsActionTest.php：

test('the terminal command runs the reconciliation action synchronously', function () { SyncStripeSubscriptions::shouldRun() ->once() ->withArgs(fn (bool $fix, ?Closure $onProgress) => $fix === false && $onProgress instanceof Closure) ->andReturnUsing(function (bool $fix, Closure $onProgress): array { $onProgress('checking', 2, 10); return [ 'total_checked' => 0, 'discrepancies' => [], 'resubscribed' => [], 'errors' => [], 'fixed' => false, ]; }); $this->artisan('cloud:sync-stripe-subscriptions') ->expectsOutputToContain('Checking stale subscriptions against Stripe... 2/10') ->expectsOutput('Total subscriptions checked: 0') ->assertSuccessful(); });

这个用例完整展示了「入口测试」的形态：Artisan 命令cloud:sync-stripe-subscriptions（定义于 SyncStripeSubscriptions.php）本身不含业务逻辑，它只负责调用 SyncStripeSubscriptions Action。测试中用shouldRun()把 Action 换成桩：

->once()断言恰好调用一次；
->withArgs(fn ...)用闭包验证参数契约——默认不带--fix时fix === false，且传入了Closure形式的进度回调；
->andReturnUsing(...)的桩函数甚至主动调用了传入的$onProgress回调，从而让命令输出2/10进度信息，测试同时覆盖了「命令把 Action 的返回值渲染成终端输出」这段接线逻辑。

而同一个文件里紧随其后的另一个用例则用['--fix' => true]断言了fix === true分支的传参，两者共同构成了对命令选项传递的完整参数化验证。

3.5`shouldNotRun()`：守卫子句与分支覆盖

mock()->shouldNotReceive('handle')的语法糖，用于声明「这段代码路径绝对不应触发该 Action」：

FetchContactsFromGoogle::shouldNotRun(); // Equivalent to: FetchContactsFromGoogle::mock()->shouldNotReceive('handle');

Coolify 在 MigrateResourceToDestinationTest.php 中大量使用该模式验证资源迁移的守卫分支：

test('rejects migration to the same destination', function () { StopApplication::shouldNotRun(); $application = createMigrateTestApplication($this); MigrateResourceToDestination::run($application, $this->destination, migrateVolumes: false); })->throws(ValidationException::class);

这里被测编排是MigrateResourceToDestination::run(...)。当目标与源是同一目的地（非法输入）时，编排应该在抛出ValidationException之前绝不触及StopApplication——用shouldNotRun()把这个「不应该发生」写成可执行断言，比仅断言异常存在更强：它同时锁死了「校验先于副作用」的执行顺序。该文件中共出现 7 处StopApplication::shouldNotRun()，分别覆盖不同的拒绝分支（构建服务器作为目标、卷迁移冲突等），是典型的「分支覆盖」测试矩阵。

3.6`allowToRun()`：放行 + 事后断言

spy + 放行handle的组合糖。当你希望代码继续以桩返回值往下跑，但事后还要验证交互时，它比mock()更省事：

$spy = FetchContactsFromGoogle::allowToRun() ->andReturn(['Loris', 'Will', 'Barney']); // ... $spy->shouldHaveReceived('handle')->with(42);

与spy()->allows('handle')的差别在于意图表达：allowToRun()语义上直接声明「允许它跑（桩）」，而spy()更通用，适合需要监视多个方法或动态决定是否放行的场合。

3.7`isFake()`：生命周期检查

返回该类当前是否已被替换为 fake，可用于写「元测试」或调试泄漏问题：

FetchContactsFromGoogle::isFake(); // false FetchContactsFromGoogle::mock(); FetchContactsFromGoogle::isFake(); // true

3.8`clearFake()`：清理与防泄漏

清除已注册的 fake 实例。参考文档把「存在泄漏风险时清理 fake」列入 Checklist，这在长测试文件中尤其重要：一个测试里注册的 fake 若未清理，可能污染同进程内后续测试的依赖解析。

Coolify 的落地做法是在afterEach钩子里统一清理，例如：

SyncStripeSubscriptionsActionTest.php：afterEach(function () { SyncStripeSubscriptions::clearFake(); });
CheckDomainDnsJobTest.php：afterEach(fn () => CheckDomainDns::clearFake());

这种「文件级 afterEach 兜底清理 + 单用例按需注册」的组合，使 fake 的生命周期严格限制在单个用例内，即便用例中途失败也不会把 fake 带入下一个用例。

四、参考文档的完整示例：编排测试与守卫子句测试

参考文档 Examples 一节给出了两类最典型的编排测试模板，它们分别对应shouldRun/shouldNotRun两种断言方向：

4.1 编排测试（正向）

it('runs sync contacts for premium teams', function () { SyncGoogleContacts::shouldRun()->once()->with(42)->andReturnTrue(); ImportTeamContacts::run(42, isPremium: true); });

要点：shouldRun()->once()->with(42)把「调用次数、参数值、返回值」三件事压进一行；测试主体只有一个编排调用ImportTeamContacts::run(...)，没有掺杂任何下游副作用。

4.2 守卫子句测试（反向）

it('does not run sync when integration is disabled', function () { SyncGoogleContacts::shouldNotRun(); ImportTeamContacts::run(42, integrationEnabled: false); });

要点：负向断言不需要andReturn，因为它关心的是「没被调用」这件事本身。这类测试专门保护 guard clause——if (! $integrationEnabled) return;这一行代码若被误删，本测试立即变红。

这两类模板组合起来，就构成了对一个分支两侧（走/不走）的完整覆盖：正向用例锁死「该走时怎么走」，反向用例锁死「不该走时绝不走」。

五、参考文档的测试矩阵与方法选择

参考文档 Recommended pattern 与 SKILL 层给出的实践默认值可以整理成一张选择表：

测试目标	推荐方法	适用场景
业务规则正确性	直接调用`handle(...)`（真实依赖/工厂）	默认的第一层测试
编排分支：应调用	`shouldRun()`	读起来像自然语言断言，分支测试首选
编排分支：不应调用	`shouldNotRun()`	guard clause、参数校验前置分支
严格交互契约	`mock()`	参数/次数不匹配时 fail fast
行为大体真实，只截断一个方法	`partialMock()`	屏蔽昂贵或外部依赖方法
放行执行 + 事后验证	`spy()`/`allowToRun()`	需要观察调用但允许流程继续
防跨用例污染	`isFake()`/`clearFake()`	afterEach 兜底、元检查

配套的入口级测试矩阵（来自 SKILL 文档 Testing Guidance）则规定了五类入口各自的验证方式：HTTP 路由测试 fake 下游 Action；Job 测试 dispatch 后断言下游调用；监听器测试 dispatch 事件后断言交互；命令测试执行 artisan 后断言调用与输出；业务规则测试直接调handle(...)。

六、Checklist 与常见陷阱

参考文档收尾部分给出的验收清单与陷阱列表，直接映射到日常评审标准：

Checklist（写完测试后自查）

断言验证的是「调用意图与参数契约」（call intent and argument contracts），而非仅仅「被调用了」；
存在泄漏风险时清理 fake（Coolify 的统一做法：afterEach中clearFake()）；
分支测试优先用shouldRun()/shouldNotRun()，可读性优于裸mock()链。

Common pitfalls（两类典型反模式）

过度 mock：把整条链路全换成假对象，测试通过但你对真实行为毫无信心——fake 应只出现在被测边界，而不是「一切」；
只断言 dispatch，不断言业务正确性：只验证「某个 Action 被分发了」，却从未直接测试过它的handle(...)行为，等于把业务正确性外包给了无人覆盖的代码。

Coolify 的 SyncStripeSubscriptionsActionTest.php 恰好同时规避了两条陷阱：前几个用例直接SyncStripeSubscriptions::run(fix: true)走真实handle(...)逻辑（只 mock 掉StripeClient这一外部 HTTP 边界），配合 Mockery 对 Stripe API 的精细期望（如shouldReceive('retrieve')->with('sub_stale')、shouldNotReceive('retrieve')）验证订阅对账的四种 resolution 分支（delete_stale、manual_review、end_subscription等，对应 SyncStripeSubscriptions.php 中的match表达式）；后两个用例才切换到shouldRun()只测 Artisan 入口的接线。业务层与入口层各得其所，正是文档推荐模式在真实代码库中的完整落地。

七、小结

AsFake提供的 8 个方法覆盖了「替换、放行、断言、清理」四个环节，选择依据只有一个：这个测试要证明什么；
两层策略不可颠倒：handle(...)直测业务，入口测试只测编排，fake 止步于被测边界；
正向分支用shouldRun()，守卫分支用shouldNotRun()，两者合力构成完整的分支覆盖；
以afterEach+clearFake()兜底 fake 生命周期，isFake()可用于泄漏排查；
可参考仓库中 tests/Feature/Subscription/SyncStripeSubscriptionsActionTest.php、tests/Feature/MigrateResourceToDestinationTest.php、tests/Feature/CheckDomainDnsJobTest.php 三个文件，它们是本文模式在 Coolify 中的可直接阅读的范例；方法级参考见 laravel-actions SKILL 文档，其AsFake深度说明与本文同源。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Coolify 测试实战：laravel-actions 的 AsFake 假对象体系与 Action 编排测试