Swoole 扩展 PHP 单元测试指南tests 目录的运行机制、PHPT 用例编写与工程实践【免费下载链接】swoole-src Coroutine-based concurrency library for PHP项目地址: https://gitcode.com/gh_mirrors/sw/swoole-src本指南基于 Swoole 仓库 tests/README.md 编写系统讲解 Swoole 扩展ext-src/自带的 PHP 单元测试体系如何初始化测试依赖的数据库、如何通过start.sh全量/部分运行用例、如何理解日志文件与默认配置以及如何用./new快速生成符合 PHPT 规范的测试脚本。读完本文你将能够在本地或 CI 环境中完整跑通 Swoole 扩展测试并独立编写高质量的回归用例。测试体系概览为什么需要一套独立于 phpt 官方的测试框架Swoole 是运行在 PHP 底层的 C/C 扩展涉及协程、异步网络、进程管理、内存表等大量与运行环境强相关的特性。仓库将测试划分为两大部分核心测试core-tests针对src/目录下纯 C 核心库基于 googletest与 PHP 无关详见 docs/TESTS.mdPHP 测试PHP Unit-test针对ext-src/目录下 PHP 扩展代码使用 PHPT.phpt格式运行在真实 PHP 环境中这正是 tests/README.md 描述的主体。整个tests/目录不仅存放测试用例还包含一套完整的测试运行工具链启动脚本 tests/start.sh、数据库初始化脚本 tests/init、日志清理脚本 tests/clean、用例生成器 tests/new 以及测试执行器 tests/run-tests。这些脚本共同保证你安装的 Swoole 扩展确实能正常工作原文Run these tests to make certain that the swoole extension you installed can work well。准备阶段初始化测试依赖的数据库执行 ./init 初始化数据库在运行测试之前需要先执行初始化脚本cd tests ./init该脚本会完成三件工作可通过./init --help查看全部参数参数作用--mysql仅初始化 MySQL 数据库--firebird仅初始化 Firebird 数据库--odbc-mysql仅初始化 ODBC MySQL 配置--help显示帮助信息不传任何参数时默认初始化全部数据库。从 tests/init 源码看MySQL 初始化会读取 tests/test.sql一个基于 Navicat 导出的test库结构脚本逐条执行其中的 SQLFirebird 初始化则创建swoole_test测试表ODBC 初始化会向/etc/odbcinst.ini、/etc/odbc.ini写入名为mysql-test的 DSN。此外脚本还会通过swoole_library_set_option启动默认的 remote object server并初始化 SSH2 测试用户与密钥对详见 tests/swoole_ssh2/ssh2_test.inc。MySQL / Redis 测试服务连接约定README 给出了测试框架对 MySQL 与 Redis 服务的连接参数约定这是编写与运行数据库相关用例的前提配置项mysqlredispath (env)$MYSQL_SERVER_PATH$REDIS_SERVER_PATHpath (actions)${actions}/data/run/mysqld/mysqld.sock${actions}/data/run/redis/redis.sockhost (raw)127.0.0.1127.0.0.1host (docker)mysqlredisport33066379userroot-passwordrootroot(可选)databasetest0上述约定的落地实现在 tests/include/config.php 中所有连接参数都优先读取环境变量、其次按 CI / macOS / Linux 给出合理默认值MySQLMYSQL_SERVER_HOST默认127.0.0.1CI 下为mysql、MYSQL_SERVER_PORT默认3306、MYSQL_SERVER_USER默认root、MYSQL_SERVER_PWD默认root、MYSQL_SERVER_DB默认testRedisREDIS_SERVER_HOST、REDIS_SERVER_PORT默认6379、REDIS_SERVER_PWD、REDIS_SERVER_DB默认0其余如 PostgreSQL、Oracle、Firebird、Sqlite、FTP、HTTP 代理等服务的连接信息也一并集中在此文件中测试用例通过require __DIR__ . /../include/config.php引用。值得一提的细节在 tests/run-tests 的 swoole patch 中测试器会自动调用netstat -ln探测本机正在监听的mysqld.sock与redis.sock路径作为MYSQL_SERVER_PATH/REDIS_SERVER_PATH的兜底发现机制。运行测试start.sh 的三种用法README 给出了三种运行方式对应 tests/start.sh 的实现逻辑1. 全量运行./start.shcd tests ./start.sh不带参数时start.sh使用默认 globswoole_*即遍历tests/下所有以swoole_开头的目录swoole_atomic、swoole_coroutine、swoole_server、swoole_runtime、swoole_http_server等覆盖约两千个.phpt用例。2. 部分运行./start.sh ./swoole_*./start.sh ./swoole_coroutine ./start.sh ./swoole_timer脚本会把传入的参数如tests/swoole_server中的tests/前缀剥掉后作为 glob 传给测试器因此也可以写成./start.sh tests/swoole_server。3. 基础测试./start.sh base./start.sh basebase是脚本内置的基础测试集合只运行最核心、依赖最少的用例组适合快速回归。从 tests/start.sh 源码看该集合包含swoole_atomic swoole_event swoole_function swoole_global swoole_process swoole_process_pool swoole_table swoole_coroutine* swoole_channel_coro swoole_client_coro swoole_http_client_coro swoole_http2_client_coro swoole_server swoole_http_server swoole_websocket_server swoole_redis_server swoole_socket_coro swoole_runtimebase还支持追加参数./start.sh base extra_arg追加的内容会拼在 glob 最前面一并运行。start.sh 的底层执行细节除了 glob 选择tests/start.sh 在调用测试器前还会做几件事理解它们有助于排查环境问题清理残留进程先kill掉所有*.php残留进程排除 phpstorm / php-fpm避免上次测试残留的服务占用端口调整文件描述符若ulimit -n小于 16384则尝试提升到 16384满足高并发用例如 c10k 类压力测试的 socket 需求指定 PHP 可执行文件若未设置TEST_PHP_EXECUTABLE默认使用which php运行结束后再次清理进程并删除/tmp/swoole.log。最终执行的是PHPT1 php -d memory_limit1024m ./run-tests {glob}PHPT1环境变量告诉测试基础设施当前处于 PHPT 运行模式tests/include/config.php 中通过IS_PHPTESTSING常量读取。默认配置与结果日志默认开启的展示项README 明确了 tests/run-tests 默认启用的输出项这一行为在脚本的 swoole patch 中有对应实现$cfg[show][diff] true; $cfg[show][mem] true; $cfg[show][slow] true; $slow_min_ms 1000;配置默认show-diffyesshow-memyesshow-slow1000(ms)含义分别是失败时展示实际输出与期望输出的差异、展示内存占用信息、展示耗时超过 1000ms 的慢用例。测试运行器支持的关键参数tests/run-tests 源自 PHP 官方的run-tests.php文件头保留了 PHP Group 版权声明因此继承了完整的参数体系常用的包括参数作用-jworkers并行执行如-j16使用 16 个 worker 加快测试-p php/-P指定 PHP 可执行文件-q安静模式无需交互等价于环境变量NO_INTERACTION1-x设置SKIP_SLOW_TESTS跳过慢用例--offline设置SKIP_ONLINE_TESTS跳过依赖外网如 httpbin.org、www.baidu.com的用例--show-all/--show-php/--show-diff/--show-slow展示各类文件内容--keep-all保留测试产生的全部中间文件--set-timeout [n]设置单个用例超时默认 60 秒内存检测模式下 300 秒-m/-M tool用 Valgrind 检测内存泄漏-g PASS,FAIL,...只展示指定状态的用例PASS/FAIL/XFAIL/SKIP/BORK/WARN/LEAK 等-l file/-w file从文件读取用例列表 / 把失败用例写入文件日志文件后缀说明每次运行测试都会在用例目录生成带后缀的中间文件README 用一张表说明了它们的用途后缀说明diff实际输出与期望输出的差异out脚本实际输出exp期望输出log以上全部内容的汇总phpPHP 临时脚本文件例如tests/swoole_coroutine/all_asleep.phpt运行后会生成同名的all_asleep.diff、all_asleep.out、all_asleep.exp、all_asleep.log等文件便于逐字节核对失败原因。清理./clean 一键删除日志文件测试会产生大量中间文件README 建议运行./clean清理./clean从 tests/clean 源码看该脚本递归扫描tests/下所有swoole_*目录删除扩展名为diff、exp、log、out、php、sh的文件并在删除时打印DELETE: {path}便于确认。编写测试用例./new 与 PHPT 规范用 ./new 生成用例骨架README 提供了标准的用例创建方式./new [test-script-filename] # 例如 ./new ./swoole_coroutine/co_sleep.phpt从 tests/new 源码看该脚本是一个交互式生成器它会依次向你询问[Test name]用例名将作为文件名[Test intro]用例说明写入--TEST--段随后根据 tests/template 模板生成文件自动执行git add将其纳入暂存区在 macOS 上还会尝试调用 PhpStorm 打开新文件README 原文注明auto open on your ide (MacOS only)。如果目标目录不存在会询问是否创建文件已存在会询问是否覆盖。PHPT 用例的标准结构生成的文件遵循 PHPT 四段式结构下面以模板 tests/template 和真实用例 tests/swoole_coroutine/all_asleep.phpt 说明--TEST-- swoole_coroutine: all asleep --SKIPIF-- ?php require __DIR__ . /../include/skipif.inc; ? --FILE-- ?php require __DIR__ . /../include/bootstrap.php; // 用例主体逻辑…… ? --EXPECT--各段职责如下--TEST--用例名称与简介例如swoole_coroutine: all asleep--SKIPIF--环境预检。当运行环境不满足条件时输出skip让用例跳过不计入失败。仓库提供了非常丰富的跳过辅助函数见 tests/include/skipif.inc例如skip_if_no_ssl()、skip_if_no_http2()、skip_if_offline()、skip_if_in_valgrind()、skip_if_php_version_lower_than(7.0)等几乎覆盖了 Swoole 编译选项与平台差异的所有分支--FILE--用例主体。通常先require bootstrap.php再编写真实测试逻辑--EXPECT--期望输出测试器将其与真实输出做逐字符比对产生diff。测试脚手架bootstrap 与 ProcessManager[--FILE--] 段引用的 tests/include/bootstrap.php 会统一完成环境装配加载 tests/include/config.php、设置memory_limit1024M、开启断言、关闭 DNS 缓存、设置协程socket_timeout5、初始化默认 remote object server 等保证每个用例拥有确定性的运行环境。模板中还使用了SwooleTest\ProcessManager这一核心测试脚手架。它通过parentFunc父进程/childFunc子进程双回调配合childFirst()与run()在单文件内模拟客户端 服务端的多进程场景这是大量swoole_server/swoole_http_server/swoole_websocket_server用例的标准写法$pm new SwooleTest\ProcessManager; $pm-parentFunc function () use ($pm) { // 客户端逻辑发起连接、发送请求、断言结果 }; $pm-childFunc function () use ($pm) { // 服务端逻辑创建 Swoole\Server 并启动 }; $pm-childFirst(); $pm-run();代码风格tests/README.md 明确要求测试代码遵循PSR1/PSR2编码规范。建议在提交前通读 docs/CODE-STYLE.md 并利用 scripts/code-format.sh 对改动做统一格式化保证新用例与既有代码风格一致。在 CI / Docker 环境中运行进阶针对持续集成场景仓库在 docs/TESTS.md 中补充了更完整的运行方案一键多环境测试运行 scripts/route.sh 即可自动创建多个 PHP 版本的 Docker 容器并在其中依次执行 Swoole 的编译与单元测试无需手动搭建环境指定分支时使用SWOOLE_BRANCHalpine ./scripts/route.sh进入容器调试docker exec -it -e LINES$(tput lines) -e COLUMNS$(tput cols) swoole /bin/bash可在容器内复跑用例可用CTRLC取消核心 C 测试如需测试src/下的 C 核心库则需安装 googletest要求 GCC/G 8.0完整支持 C17依次执行cmake . make -j$(nproc) lib-swoole、make -j$(nproc) core-tests再通过./bin/core-tests --gtest_filterserver.*或--gtest_list_tests精确筛选用例。常见问题排查路径用例被跳过而非失败查看是否命中--SKIPIF--段的某个skip分支如缺少 SSL/HTTP2 编译选项、处于离线环境、PHP 版本不符可用-g SKIP单独查看跳过原因数据库用例失败确认 MySQL / Redis 已按上文连接约定启动必要时显式导出MYSQL_SERVER_HOST、REDIS_SERVER_PORT等环境变量覆盖默认值并重新运行./init日志文件干扰调试完毕后运行./clean清理避免残留的diff/out/exp文件混淆判断慢用例或高并发用例失败检查是否因ulimit -n过小导致 socket 创建失败start.sh会自动尝试提升到 16384。小结Swoole 的tests/目录并非简单的用例集合而是一套自包含的测试工程./init负责数据库与服务装配./start.sh负责按 glob 灵活选择用例集合并以正确环境参数启动 tests/run-tests./new tests/template 提供规范的 PHPT 用例生成流水线./clean负责运行产物回收。对开发者而言掌握这套流程既能快速验证自己编译安装的扩展是否可用也能用统一的规范为 Swoole 贡献高质量的回归用例——这正是 tests/README.md 的初衷所在。【免费下载链接】swoole-src Coroutine-based concurrency library for PHP项目地址: https://gitcode.com/gh_mirrors/sw/swoole-src创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考