Swoole 测试体系实战指南:Core Tests 与 PHP Tests 的构建、运行与用例编写
Swoole 测试体系实战指南:Core Tests 与 PHP Tests 的构建、运行与用例编写
Swoole 作为基于协程的 PHP 并发编程库,其质量保障依赖一套双轨并行的自动化测试体系:面向 src/ 核心 C++ 库的 Core Tests(基于 googletest)与面向 ext-src/ PHP 扩展层的 PHP Tests(基于 PHPT 框架)。本文以仓库中的 docs/TESTS.md 为核心骨架,结合 CMakeLists.txt、core-tests 目录与 tests 目录中的真实源码与脚本,完整讲解两套测试环境的依赖、构建、运行、容器编排与用例编写方法,读完即可在本地或 CI 中复现 Swoole 的完整测试流程。
一、测试体系总览:两条彼此独立的验证链路
Swoole 源码仓库从物理结构上被划分为两大部分,对应两套测试:
| 测试体系 | 被测对象 | 测试语言 | 依赖框架 | 入口文档/脚本 |
|---|---|---|---|---|
| Core Tests | src/ 目录下的 C++ 核心库(与 PHP 无关的纯 C++ 库) |
C++ | googletest | docs/TESTS.md |
| PHP Tests | ext-src/ 目录下的 PHP 扩展代码 |
PHP(PHPT 格式) | PHP 环境 + PHPT 测试运行器 | tests/README.md、scripts/route.sh |
两条链路的关键区别在于是否依赖 PHP 运行时:Core Tests 将 Swoole 作为独立 C++ 库直接链接测试,速度更快、更贴近底层实现;PHP Tests 则完整模拟真实使用场景,覆盖扩展层的 API 行为。从仓库目录结构看,core-tests/src/ 下按 _lib、core、coroutine、lock、memory、network、os、protocol、reactor、server 等子目录组织测试用例,与 src/ 源码目录一一对应;而 tests/ 下则按 swoole_coroutine、swoole_http_server、swoole_runtime 等模块组织 .phpt 文件,全部对齐扩展的类命名空间。
二、Core Tests:C++ 核心库的单元测试
Core Tests 用于验证 src/ 目录的核心代码,被测目标只作为 C++ 库存在,与 PHP 无任何关系,因此测试用例必须使用 C++ 编写,且依赖 googletest 框架。
2.1 环境要求
- 已安装 googletest(本文档以 v1.15.2 为例);
- GCC/G++ 8.0 及以上版本,需完整支持 C++17。
注意:虽然 CMakeLists.txt 中库本身设置的是 CMAKE_CXX_STANDARD 14,但 core-tests 用例源码大量使用现代 C++ 特性,文档明确要求编译器完整支持 C++17,建议使用较新的 GCC 发行版。
2.2 第一步:编译安装 googletest
由于 Swoole 核心单元测试依赖 googletest,必须先编译它:
wget https://github.com/google/googletest/releases/download/v1.15.2/googletest-1.15.2.tar.gz
tar zxf googletest-1.15.2.tar.gz
cd googletest-1.15.2
mkdir ./build && cd ./build
cmake ..
make -j
sudo make install
安装完成后,googletest 的头文件与静态库会进入系统默认路径(/usr/local/include、/usr/local/lib),供下一步 CMake 探测。
2.3 第二步:构建 libswoole.so
Core Tests 链接的是以共享库形式编译的 Swoole 核心库,需要先构建它:
cd swoole-src
cmake .
make -j$(nproc) lib-swoole
cmake . 会读取仓库根目录的 CMakeLists.txt 并生成构建系统。其中 lib-swoole 目标(CMakeLists.txt)将 src/*.c、src/*.cc 以及 thirdparty/ 下的 hiredis、llhttp、multipart_parser、boost asm 等第三方源码一起编成名为 libswoole.so 的共享库,输出到 lib/ 目录,版本号取自 SWOOLE_VERSION。编译时会自动探测 OpenSSL、liburing、c-ares(通过 config.h 中的 SW_USE_CARES 宏)、brotli 等可选依赖。
2.4 第三步:构建 core-tests 可执行文件
make -j$(nproc) core-tests
core-tests 目标在 CMakeLists.txt 中定义:通过 find_package(GTest REQUIRED) 强制要求 googletest 存在(找不到会直接 FATAL_ERROR),并递归收集 core-tests/src/*.cpp 及 thirdparty/llhttp/*.c 作为测试源文件,链接 swoole pthread ssl crypto 以及 googletest 库和 nghttp2 库。因此若上一步 googletest 未正确安装,此步骤会失败。
构建产物 core-tests 可执行文件会输出到构建目录的 bin/ 下(见 CMakeLists.txt 的 EXECUTABLE_OUTPUT_PATH)。
2.5 第四步:运行 core-tests
# 1. 启动全部依赖服务(httpbin / proxy 等)
cd core-tests
docker compose up -d
# 2. 运行全部测试
./bin/core-tests
# 3. 只运行部分用例(如所有 server 相关用例)
./bin/core-tests --gtest_filter=server.*
# 4. 列出全部用例
./bin/core-tests --gtest_list_tests
三个运行姿势的要点:
- 依赖服务:部分用例(如 HTTP 客户端、代理、DNS 相关)需要外部服务配合。core-tests/docker-compose.yml 定义了
httpbin(HTTP 测试站点)、tinyproxy(HTTP 代理,映射 8888 端口)、socks5(带认证的 SOCKS5 代理,映射 8080 端口)、socks5-no-auth(免认证 SOCKS5 代理,映射 8081 端口)四个服务,docker compose up -d一键拉起。 - 过滤与枚举:
--gtest_filter=server.*是 googletest 标准的通配过滤语法(用例组.用例名),可用于只跑某个模块;--gtest_list_tests仅列出所有已注册的测试而不执行。 - 注意:原文档第 45 行的
core_tests为笔误,实际可执行文件名为core-tests(与 CMake 目标一致),--gtest_list_tests同样作用于此可执行文件。
2.6 编写 Core Test 用例
测试用例位于 core-tests/src 目录,使用 googletest 的 TEST 宏,例如 core-tests/src/coroutine/base.cpp:
#include "test_coroutine.h"
using namespace swoole;
using swoole::coroutine::System;
TEST(coroutine_base, create) {
long _cid;
long cid = Coroutine::create([](void *arg) { *(long *) arg = Coroutine::get_current_cid(); }, &_cid);
ASSERT_GT(cid, 0);
ASSERT_EQ(cid, _cid);
}
结构要点:
- 每个测试文件包含对应的
test_*.h头文件(如 core-tests/include/test_coroutine.h),这些头文件负责引入被测的 Swoole 核心 API; - 通过
TEST(SuiteName, CaseName)注册用例,SuiteName即为--gtest_filter中server.*的server部分; - 断言统一使用 googletest 的
ASSERT_*/EXPECT_*宏,而不是裸assert; - 用例与
src/目录结构一一对应:网络相关看 core-tests/src/network、协程相关看 core-tests/src/coroutine、内存池看 core-tests/src/memory。
2.7 进阶:覆盖率与调试构建
CMakeLists.txt 提供了可选的 CODE_COVERAGE 开关:cmake -DCODE_COVERAGE=ON . 会为库与测试注入 --coverage(-fprofile-arcs -ftest-coverage)编译参数并链接 gcov,便于生成覆盖率报告。此外还支持 -Denable_asan=ON(开启 AddressSanitizer)、-Denable_trace_log=ON(开启跟踪日志)、-Denable_thread=ON(开启线程上下文)等编译选项,供针对性验证。
三、PHP Tests:扩展层的端到端测试
PHP Tests 用于验证 ext-src/ 目录中的 PHP 扩展代码,测试用例必须用 PHP 编写,并依赖完整的 PHP 环境(php-dev 相关组件必须安装,因为编译扩展需要 phpize 与 php-config)。
3.1 第一步:构建并安装 ext-swoole
cd swoole-src
phpize
./configure ${options}
make -j$(nproc)
make install
phpize基于仓库根目录的 config.m4 生成 configure 脚本;${options}可按需传入--enable-swoole-*系列编译选项(如 SSL、cURL、异步 IO、线程等特性开关);make install会将swoole.so安装到php-config --extension-dir对应的扩展目录。
3.2 第二步:启用扩展
编译完成后需要在 php.ini 中加入一行以启用 ext-swoole:
extension=swoole.so
之后可用 php -m | grep swoole 验证扩展已加载。
3.3 第三步:初始化测试环境(数据库与账号)
PHP 测试大量依赖 MySQL、Redis 等服务。运行测试前,可执行 tests/init 初始化数据库与测试账号:
cd tests
./init # 默认初始化全部(MySQL / Firebird / ODBC-MySQL)
./init --mysql # 只初始化 MySQL
./init --firebird # 只初始化 Firebird
./init --odbc-mysql # 只初始化 ODBC MySQL
./init --help # 查看帮助
依据 tests/README.md,默认连接信息如下:
| 项目 | MySQL | Redis |
|---|---|---|
| 路径(环境变量) | $MYSQL_SERVER_PATH |
$REDIS_SERVER_PATH |
| 路径(GitHub Actions) | ${actions}/data/run/mysqld/mysqld.sock |
${actions}/data/run/redis/redis.sock |
| 主机(裸机) | 127.0.0.1 | 127.0.0.1 |
| 主机(Docker) | mysql | redis |
| 端口 | 3306 | 6379 |
| 用户 | root | - |
| 密码 | root | root(可选) |
| 数据库 | test | 0 |
实际连接常量定义在 tests/include/config.php(如 MYSQL_SERVER_HOST 等),tests/test.sql 中存放 MySQL 初始化 SQL。
3.4 第四步:运行 PHP 测试
最推荐的运行方式是仓库根目录的编排脚本:
./scripts/route.sh
依据 scripts/route.sh 的实现,该脚本的执行流程为:校验 Docker 环境(不存在则自动下载指定版本的 docker-compose)→ 准备 scripts/data 数据目录 → 通过 docker-compose up -d 拉起多个 PHP 版本容器 → 在名为 swoole 的容器内执行 scripts/docker-route.sh 完成各版本的编译与单元测试。这套自动化脚本不仅适用于 GitHub Actions CI,基于 Docker 容器技术它可以运行在任何系统上,你只需运行 route.sh 即可自动创建多个 PHP 环境容器,并在多个系统上自动执行 Swoole 的构建测试与单元测试。
3.5 使用特殊分支
通过环境变量指定目标分支(例如 Alpine 分支):
SWOOLE_BRANCH=alpine ./scripts/route.sh
依据 scripts/route.sh,当 SWOOLE_BRANCH=alpine 时,PHP_VERSION 会被追加 -alpine 后缀(如 8.3-alpine),从而拉取 Alpine 版的 PHP 镜像进行测试。
3.6 进入容器手动调试
提示:可以用
CTRL+C取消正在进行的单元测试。
docker exec -it -e LINES=$(tput lines) -e COLUMNS=$(tput cols) swoole /bin/bash
传入 LINES/COLUMNS 是为了让容器内的终端排版与宿主机保持一致;进入后可直接在 /swoole-src 下操作已构建好的扩展与测试脚本。
3.7 本地直接运行 PHPT 测试(不依赖 Docker)
如果不想用 Docker,也可以直接在宿主机上运行 tests/start.sh:
cd tests
./start.sh # 运行全部 swoole_* 模块测试
./start.sh swoole_coroutine swoole_http_server # 运行部分模块
./start.sh base # 只运行基础核心模块
依据 tests/start.sh 的实现细节:
- 运行前会清理残留的 PHP 测试进程,并尝试把
ulimit -n提升到 16384(避免大量并发连接用例触发文件描述符耗尽); - 通过
TEST_PHP_EXECUTABLE环境变量指定 PHP 解释器(默认which php); - 内部调用 PHP 官方 PHPT 运行器 tests/run-tests,并注入
memory_limit=1024m防止用例 OOM; base参数对应一组精选的「基础模块」glob(atomic、event、function、global、process、process_pool、table、各类 coroutine、server 系列等),并支持在其后追加更多模块参数。
3.8 日志文件与清理
依据 tests/README.md,每次运行会在各测试目录生成如下日志后缀:
| 后缀 | 含义 |
|---|---|
diff |
输出与期望结果之间的差异 |
out |
脚本实际输出 |
exp |
期望输出 |
log |
以上全部内容汇总 |
php |
PHP 临时脚本文件 |
运行 ./clean 可删除所有测试日志文件(见 tests/clean)。
3.9 编写 PHPT 测试用例
在 tests 目录下,每个模块一个子目录(如 swoole_coroutine),内部全部是 .phpt 文件。典型的用例结构如下(节选自 tests/swoole_coroutine/after_start_server_1.phpt):
--TEST--
swoole_coroutine: co::create after server start [1]
--SKIPIF--
<?php require __DIR__ . '/../include/skipif.inc'; skip_if_win(); ?>
--FILE--
<?php
require __DIR__ . '/../include/bootstrap.php';
$pm = new SwooleTest\ProcessManager;
$pm->parentFunc = function ($pid) use ($pm) { ... };
$pm->childFunc = function () use ($pm) { ... };
?>
--EXPECT--
--TEST--:用例标题,会显示在测试结果中;--SKIPIF--:条件跳过逻辑,例如 tests/include/skipif.inc 中的skip_if_win()用于在 Windows 上跳过该用例;--FILE--:实际执行的 PHP 脚本,通常引入 tests/include/bootstrap.php,并使用测试基础设施(如SwooleTest\ProcessManager管理多进程、Assert断言、SwooleTest\RandStr生成随机数据);--EXPECT--:期望输出,PHPT 运行器会与脚本实际输出对比,不一致则写入.diff日志。
新增用例可通过 ./new [test-script-filename] 生成模板,例如 ./new ./swoole_coroutine/co_sleep.phpt(见 tests/README.md)。测试代码遵循 PSR1/PSR2 编码规范。
四、两套测试如何配合:从源码到扩展的完整验证链路
将两套测试组合起来,可以勾勒出 Swoole 质量保障的完整闭环:
- 底层正确性(Core Tests):直接以 C++ 视角验证协程调度(如 core-tests/src/coroutine/base.cpp 中的
coroutine_base.create、yield_resume等用例)、内存池、网络协议解析等核心实现,无需 PHP 运行时介入,定位问题更快; - 上层行为(PHP Tests):以真实 PHP 脚本验证扩展 API 在真实服务器场景下的行为,覆盖
swoole_coroutine、swoole_http_server、swoole_runtime、swoole_curl等全部模块(仓库中约 1500 个.phpt用例分布在 tests 的各个swoole_*目录); - 多环境矩阵(route.sh):通过 Docker 同时验证多个 PHP 版本、Alpine 分支、不同架构(scripts/route.sh 中对 aarch64 会额外构建 golang-h2demo 与 PHP 镜像)的组合兼容性。
五、实践建议
- 修改
src/下核心代码后,先跑./bin/core-tests --gtest_filter=<受影响模块>.*快速回归;由于 Core Tests 不依赖 PHP,编译与执行开销远小于 PHPT 全量测试; - 修改扩展层代码(
ext-src/)后,使用./scripts/route.sh走完整容器流程,确保多 PHP 版本下行为一致; - 本地开发时优先
cd tests && ./init && ./start.sh swoole_<模块>做针对性验证,全量./start.sh留到提交前执行; - 若 googletest 版本或编译器过旧导致
find_package(GTest REQUIRED)失败,请先按上文 2.2 节升级依赖,再重新执行cmake .。
通过本文的步骤,你可以在任意 Linux 环境完整复现 Swoole 的构建、单元测试与集成测试流程,并依据仓库中的真实用例模板继续扩展测试覆盖。