Swoole 测试体系实战指南:Core Tests 与 PHP Tests 的构建、运行与用例编写

原创2026-09-20 20:07:461,998 阅读
文章标签:后端异步编程网络并发编程WebSocket通信高性能计算

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 质量保障的完整闭环:

  1. 底层正确性(Core Tests):直接以 C++ 视角验证协程调度(如 core-tests/src/coroutine/base.cpp 中的 coroutine_base.create、yield_resume 等用例)、内存池、网络协议解析等核心实现,无需 PHP 运行时介入,定位问题更快;
  2. 上层行为(PHP Tests):以真实 PHP 脚本验证扩展 API 在真实服务器场景下的行为,覆盖 swoole_coroutine、swoole_http_server、swoole_runtime、swoole_curl 等全部模块(仓库中约 1500 个 .phpt 用例分布在 tests 的各个 swoole_* 目录);
  3. 多环境矩阵(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 的构建、单元测试与集成测试流程,并依据仓库中的真实用例模板继续扩展测试覆盖。

登录后查看全文
swoole-src