mirror of
https://gitee.com/ulthon/ulthon_admin.git
synced 2026-08-30 20:55:32 +08:00
3f7050bf65
Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
246 lines
9.9 KiB
PHP
246 lines
9.9 KiB
PHP
<?php
|
||
|
||
namespace base\common\test;
|
||
|
||
use PHPUnit\Framework\TestCase;
|
||
use think\facade\Config;
|
||
use think\facade\Db;
|
||
|
||
/**
|
||
* 框架测试基建基类（内核层）.
|
||
*
|
||
* 提供通用的、与 ThinkPHP 容器/数据库无关的测试基础设施：
|
||
* - 测试数据库安全校验（setUp 第一道：拒绝连非测试库）
|
||
* - 事务回滚隔离（PRIMARY：setUp 开事务 / tearDown 回滚，撤销所有 DB 写入）
|
||
* - DB 断言助手（assertDatabaseHas / assertDatabaseMissing）
|
||
* - 隔离探针（assertIsolationWorks：自验证事务回滚是否真正生效）
|
||
* - Plan B（truncateTables：事务回滚在 think-orm 3.0 下失效时的降级手段）
|
||
*
|
||
* 架构约束（Base/App 铁律）：
|
||
* 本类位于 extend/base/（内核层），只放通用测试基建。
|
||
* 严禁引用 app\ 下任何业务命名空间、严禁硬编码业务表名、
|
||
* 严禁实现业务 fixture 工厂。
|
||
* 这些业务能力一律下沉到 app 层的 app\common\test\TestCase。
|
||
*
|
||
* 继承关系：app 层入口 app\common\test\TestCase 继承本类，
|
||
* 再由具体测试用例继承 app 层入口。
|
||
*/
|
||
abstract class TestCaseBase extends TestCase
|
||
{
|
||
/**
|
||
* 是否在每个测试之间清理容器缓存单例。
|
||
*
|
||
* 默认 false：容器在 tests/bootstrap.php 中一次性引导并跨测试复用，
|
||
* 事务回滚才是真正的隔离手段，容器不需要每个测试重置。
|
||
* 仅当某个测试确实污染了框架级单例时，子类可将其置 true。
|
||
*/
|
||
protected bool $resetContainerBetweenTests = false;
|
||
|
||
/**
|
||
* 每个测试开始前：先做安全校验，再开启事务.
|
||
*
|
||
* {@inheritdoc}
|
||
*/
|
||
protected function setUp(): void
|
||
{
|
||
parent::setUp();
|
||
|
||
// 安全第一道：绝对不能连生产库。事务开启之前必须先校验。
|
||
$this->assertTestDatabase();
|
||
|
||
// 开启事务：本测试所有 DB 写入都在此事务内，tearDown 统一回滚。
|
||
// think-orm 3.0 事务 API：startTrans() 开启 / rollback() 回滚 / commit() 提交。
|
||
Db::startTrans();
|
||
}
|
||
|
||
/**
|
||
* 每个测试结束后：回滚事务撤销所有 DB 写入（PRIMARY 隔离）.
|
||
*
|
||
* 重要：这里【不会】调用 Container::setInstance(null)。
|
||
* 原因：ThinkPHP 容器在 tests/bootstrap.php 中只引导一次（once-bootstrapped 模型），
|
||
* 跨测试复用同一个 App 实例。如果在这里把容器单例置 null，第二个测试起
|
||
* 所有 facade（Db / Config 等）都会失去解析目标，整个测试套件崩溃。
|
||
* 事务回滚才是隔离手段；容器是长生命的共享基础设施，不应被销毁。
|
||
* 若确需清理框架级缓存单例，子类把 $resetContainerBetweenTests 置 true，
|
||
* 由 resetContainerState() 做最小化、安全的清理。
|
||
*
|
||
* {@inheritdoc}
|
||
*/
|
||
protected function tearDown(): void
|
||
{
|
||
// 回滚事务：撤销本测试对数据库的一切写入 —— 真正的隔离在这里。
|
||
// think-orm 3.0 事务 API：startTrans() 开启 / rollback() 回滚 / commit() 提交。
|
||
Db::rollback();
|
||
|
||
if ($this->resetContainerBetweenTests) {
|
||
$this->resetContainerState();
|
||
}
|
||
|
||
parent::tearDown();
|
||
}
|
||
|
||
/**
|
||
* 最小化清理框架级缓存单例（可选）.
|
||
*
|
||
* 默认实现为空：因为容器是跨测试复用的（见 tearDown 注释），
|
||
* 绝大多数场景不需要清理。只有当某测试确实污染了框架级单例、
|
||
* 且事务回滚无法覆盖时，子类重写此方法做定向清理
|
||
* （例如清某个缓存绑定，但【不要】整体销毁容器）。
|
||
*/
|
||
protected function resetContainerState(): void
|
||
{
|
||
// 有意为空：扩展点，子类按需重写。
|
||
}
|
||
|
||
/**
|
||
* 解析当前默认数据库连接的 config 键前缀.
|
||
*
|
||
* 不硬编码连接名（本项目的默认连接是 `main`，但其它 ulthon 应用可能是 `mysql` 或别的）。
|
||
* 动态读取 `database.default`（config/database.php: 'default' => Env::get('database.main', ...)），
|
||
* 拼成 `database.connections.<default>`，供 assertTestDatabase / truncateTables 共用。
|
||
*/
|
||
protected function connectionConfigKey(): string
|
||
{
|
||
$default = (string) Config::get('database.default', 'main');
|
||
|
||
return 'database.connections.' . $default;
|
||
}
|
||
|
||
/**
|
||
* 安全校验：断言当前连接的数据库名包含 "test"，拒绝连生产库.
|
||
*
|
||
* 通用判断（内核层不硬编码任何具体库名）：库名含子串 "test" 视为测试库。
|
||
* 例如 ulthon_admin_test（含 test）会被放行；远程生产库名（不含 test）会被拦截。
|
||
* 这是 setUp 的第一道闸门，在任何 DB 写入之前执行。
|
||
*/
|
||
protected function assertTestDatabase(): void
|
||
{
|
||
$name = (string) Config::get($this->connectionConfigKey() . '.database', '');
|
||
|
||
if ($name === '' || stripos($name, 'test') === false) {
|
||
$this->fail('Refusing to run tests against non-test database: ' . ($name !== '' ? $name : '(unknown)'));
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 断言指定表存在【至少一条】匹配 $where 的记录.
|
||
*
|
||
* @param string $table 逻辑表名（不含前缀，与 Db::name() 一致）
|
||
* @param array $where where 条件
|
||
*/
|
||
protected function assertDatabaseHas(string $table, array $where): void
|
||
{
|
||
$count = Db::name($table)->where($where)->count();
|
||
|
||
if ($count <= 0) {
|
||
$this->fail(sprintf(
|
||
'Failed asserting that table [%s] contains a row matching %s.',
|
||
$table,
|
||
json_encode($where, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES)
|
||
));
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 断言指定表【不存在】任何匹配 $where 的记录.
|
||
*
|
||
* @param string $table 逻辑表名（不含前缀，与 Db::name() 一致）
|
||
* @param array $where where 条件
|
||
*/
|
||
protected function assertDatabaseMissing(string $table, array $where): void
|
||
{
|
||
$count = Db::name($table)->where($where)->count();
|
||
|
||
if ($count > 0) {
|
||
$this->fail(sprintf(
|
||
'Failed asserting that table [%s] does NOT contain any row matching %s (found %d).',
|
||
$table,
|
||
json_encode($where, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES),
|
||
$count
|
||
));
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 隔离探针：自验证事务回滚隔离是否真正生效.
|
||
*
|
||
* 工作原理（跨测试自验证）：
|
||
* 1. 先断言探针行【不存在】—— 若存在，说明上一个测试的事务没有被回滚（隔离失败）；
|
||
* 2. 插入一条探针行；
|
||
* 3. 断言探针行【现在可见】—— 证明本测试事务内写入正常。
|
||
*
|
||
* 完整契约：本方法插入的探针行必须被本测试 tearDown 的 Db::rollback() 撤销，
|
||
* 从而下一个测试再调 assertIsolationWorks() 时，第 1 步的"不存在"断言才能成立。
|
||
* 如果事务回滚失效，第 1 步会在下一个测试立刻失败 —— 这就是探针的报警机制。
|
||
*
|
||
* 内核层不硬编码业务表，探针表/数据由可重写的隔离钩子提供默认值（框架表 system_menu），
|
||
* app 层 app\common\test\TestCase 可重写 isolationProbeTable()/isolationProbeData()
|
||
* 改用真实业务表，使探针更贴近业务写入路径。
|
||
*
|
||
* @api public —— 可直接作为测试用例方法或被测试用例显式调用
|
||
*/
|
||
public function assertIsolationWorks(): void
|
||
{
|
||
$table = $this->isolationProbeTable();
|
||
$data = $this->isolationProbeData();
|
||
|
||
// 1. 前置：探针行必须不存在（证明上一测试已回滚干净）
|
||
$this->assertDatabaseMissing($table, $data);
|
||
|
||
// 2. 插入探针行
|
||
Db::name($table)->insert($data);
|
||
|
||
// 3. 后置：探针行必须可见（证明本测试事务内写入正常）
|
||
$this->assertDatabaseHas($table, $data);
|
||
}
|
||
|
||
/**
|
||
* 隔离探针表（可重写）.
|
||
*
|
||
* 默认返回框架表 system_menu（migrate:run 必建，所有应用都有）。
|
||
* app 层可重写为真实业务表，使探针更贴近业务写入路径。
|
||
* 注意：内核层不允许返回业务表名，那属于 app 层重写。
|
||
*/
|
||
protected function isolationProbeTable(): string
|
||
{
|
||
return 'system_menu';
|
||
}
|
||
|
||
/**
|
||
* 隔离探针插入数据（可重写）.
|
||
*
|
||
* 默认向 system_menu 插入一条带高辨识度标记的行（system_menu 的 title 列有默认值，
|
||
* 仅写 title 即可，其余列走默认）。返回的数组同时作为可见性断言的 where 条件。
|
||
*/
|
||
protected function isolationProbeData(): array
|
||
{
|
||
return ['title' => '__isolation_probe__'];
|
||
}
|
||
|
||
/**
|
||
* Plan B：TRUNCATE 指定表（事务回滚隔离的降级方案）.
|
||
*
|
||
* 用途：如果事务回滚在 think-orm 3.0 下证明不足以隔离（例如某些 DDL / 自动提交场景），
|
||
* 子类可在 setUp 中显式调用本方法清空指定表。事务回滚仍是首选方案，本方法仅作兜底。
|
||
*
|
||
* @param array $tables 逻辑表名数组（不含前缀，与其它方法一致；内部会拼接配置前缀）
|
||
*/
|
||
protected function truncateTables(array $tables): void
|
||
{
|
||
$prefix = (string) Config::get($this->connectionConfigKey() . '.prefix', '');
|
||
|
||
foreach ($tables as $table) {
|
||
$table = (string) $table;
|
||
|
||
// 标识符白名单校验，杜绝 SQL 注入（TRUNCATE 是高危操作）
|
||
if (!preg_match('/^[A-Za-z0-9_]+$/', $table)) {
|
||
throw new \InvalidArgumentException(
|
||
'Refusing to TRUNCATE: invalid table identifier (only [A-Za-z0-9_] allowed): ' . $table
|
||
);
|
||
}
|
||
|
||
Db::execute('TRUNCATE TABLE `' . $prefix . $table . '`');
|
||
}
|
||
}
|
||
}
|