如何为你的Composer包编写自动化测试？ (PHPUnit集成)

phpUnit 是 composer 包测试默认选择，因其生态适配度高、无需抽象层、直接通过 vendor/bin/phpunit 运行；需在 require-dev 锁定版本，scripts 中用 “test”: “phpunit”，并配置 autoload-dev 映射 tests/ 目录。

为什么 PHPUnit 是 Composer 包测试的默认选择

因为 Composer 生态中绝大多数包都用 PHPUnit，它的配置、断言、Mock 工具链和 CI 兼容性已经深度对齐 composer.json 的生命周期。你不需额外引入测试框架抽象层，直接在 vendor/bin/phpunit 运行即可验证类行为——前提是你的包不依赖 laravel 或 symfony 的完整容器。

如何在 composer.json 中正确声明测试依赖与脚本

测试依赖必须放在 require-dev 里，且版本要锁定（避免 CI 中因 minor 升级导致断言失败）。scripts 中的 test 命令应指向可执行路径，而非硬编码 ./vendor/bin/phpunit ——Composer 会自动解析 bin 路径。

• phpunit 版本建议用 ^9.6 || ^10.5：兼容 PHP 8.0–8.3，且避免 v11 引入的严格类型变更影响老逻辑
• "test": "phpunit" 比 "test": "vendor/bin/phpunit" 更健壮，尤其在使用 composer install --no-dev 后再切换环境时
• 加一条 "test-coverage": "phpunit --coverage-html=build/coverage" 方便本地快速查漏

{     "require-dev": {         "phpunit/phpunit": "^9.6 || ^10.5",         "phpstan/phpstan": "^1.10"     },     "scripts": {         "test": "phpunit",         "test-coverage": "phpunit --coverage-html=build/coverage"     } }

tests 目录结构与 autoloader 配置要点

Composer 默认不加载 tests/ 下的类，但 PHPUnit 需要自动发现测试用例。你必须在 composer.json 的 autoload-dev 中显式声明 psr-4 映射，否则 MyPackageTest 类会报 class not found。

• 测试类文件名必须以 Test.php 结尾（如 StringHelperTest.php），PHPUnit 才能自动识别
• autoload-dev 的命名空间前缀建议与主代码一致，仅后缀加 \Tests\，例如 "MyPackage\Tests\": "tests/"
• 不要把 tests/ 加进 autoload（非 dev）——这会让最终用户无意中加载测试类，引发冲突

{     "autoload": {         "psr-4": {             "MyPackage\": "src/"         }     },     "autoload-dev": {         "psr-4": {             "MyPackage\Tests\": "tests/"         }     } }

如何避免 PHPUnit 在 CI 中因路径或配置失效

本地跑通 ≠ CI 跑通。常见断点是 phpunit.xml 路径未被识别，或 --bootstrap 加载顺序错乱。最简方案是不用 XML 配置文件，全部通过命令行参数控制；若必须用，确保它放在项目根目录，并在 composer.json 的 scripts 中显式指定。

立即学习“PHP免费学习笔记（深入）”；

• CI 中优先用 phpunit --configuration phpunit.xml，而不是依赖默认查找逻辑
• 避免在 phpunit.xml 中写绝对路径（如 /home/runner/work/...），改用 ./ 或 %ROOT_DIR% 变量（v10+ 支持）
• 如果测试依赖 vendor/autoload.php，别在 phpunit.xml 里重复 bootstrap ——Composer 自动加载已覆盖
• CI 环境中记得加 --no-coverage，否则 Xdebug 开销会让超时失败

真正容易被忽略的是：PHP 的 opcache.enable_cli=1 在某些 docker 镜像中默认开启，会导致测试类修改后不重载，表现为“改了代码但测试仍过”。CI 中建议显式关掉：php -d opcache.enable_cli=0 vendor/bin/phpunit。