19、测试组织与命名规范：测试文件结构、测试套件命名、测试用例命名的最佳实践

说到测试，很多人第一反应是「怎么写断言」。但我在项目里踩过最大的坑，反而不是测试逻辑本身，而是——找不到测试在哪。

你想想看，一个项目迭代两年，测试文件散落在各个角落，命名随心所欲。新同事接手，光找对应模块的测试就要花半天。这还怎么谈测试驱动开发？

所以这一章，咱们专门聊聊测试的组织与命名。说白了，就是给测试代码「立规矩」。规矩立好了，团队协作效率翻倍，维护成本直线下降。

19.1 测试文件结构：三种主流布局

我个人习惯把测试文件结构分为三种模式。没有绝对的好坏，看项目规模和团队习惯来选。

模式	目录结构	适用场景	我的评价
同目录模式	src/ 下每个 .cpp 旁放一个 _test.cpp	小型项目、个人项目	简单直接，但文件多了很乱
独立测试目录	tests/ 镜像 src/ 的目录结构	中型项目、团队协作	我最推荐的方式
按功能分层	tests/unit/、tests/integration/、tests/e2e/	大型项目、微服务	层次清晰，但目录深度较大

我在团队里推行的是第二种——独立测试目录。举个例子：

project/
├── src/
│   ├── core/
│   │   ├── user_manager.cpp
│   │   └── user_manager.h
│   └── utils/
│       ├── string_helper.cpp
│       └── string_helper.h
└── tests/
    ├── core/
    │   └── user_manager_test.cpp
    └── utils/
        └── string_helper_test.cpp

为什么要镜像？因为这样你从 src/core/user_manager.cpp 就能直接猜到 tests/core/user_manager_test.cpp 的位置。不需要翻来翻去。

19.2 测试套件命名：用类名或模块名

测试套件（Test Suite）在 Google Test 里对应 TEST_F 或 TEST 的第一个参数。这个命名直接决定了你在测试报告里看到的内容。

我建议的规则很简单：测试套件名 = 被测类名或模块名。

// 好的命名
TEST(UserManagerTest, AddUser_ShouldSucceed) { ... }
TEST(UserManagerTest, RemoveUser_ShouldThrowWhenNotFound) { ... }

// 不好的命名
TEST(Test1, AddUser) { ... }
TEST(MySuite, RemoveUser) { ... }

为什么？因为当测试失败时，你看到 UserManagerTest.AddUser_ShouldSucceed，立刻就知道是 UserManager 类的 AddUser 方法出了问题。而 Test1.AddUser 呢？你还得去查这个 Test1 对应哪个模块。

我曾经在一个遗留项目里看到过 TEST(AAA, BBB) 这种命名，问原作者，他说「AAA 是我名字缩写，BBB 是随便写的」。嗯，这种测试基本等于没写。

19.3 测试用例命名：三段式结构

测试用例的命名，我有一套「三段式」模板，用了七八年，团队反馈很好：

TEST(套件名, 方法名_场景_预期行为)

举个例子：

TEST(UserManagerTest, AddUser_ValidUser_ShouldReturnUserId)
{
    // 准备
    UserManager mgr;
    User user{"Alice", "alice@example.com"};

    // 执行
    auto id = mgr.AddUser(user);

    // 验证
    EXPECT_GT(id, 0);
    EXPECT_EQ(mgr.GetUser(id).name, "Alice");
}

TEST(UserManagerTest, AddUser_DuplicateEmail_ShouldThrowException)
{
    UserManager mgr;
    mgr.AddUser({"Alice", "alice@example.com"});

    EXPECT_THROW(mgr.AddUser({"Bob", "alice@example.com"}), std::runtime_error);
}

你看，光看测试名就知道：

• 方法名：AddUser
• 场景：ValidUser / DuplicateEmail
• 预期行为：ShouldReturnUserId / ShouldThrowException

这种命名方式，说白了就是「测试即文档」。新同事看测试用例名，就能理解这个方法的边界条件和行为。

19.4 测试夹具（Test Fixture）的命名

当你用 TEST_F 时，需要定义一个测试夹具类。命名规则也很简单：类名 + Test。

class UserManagerTest : public ::testing::Test
{
protected:
    void SetUp() override
    {
        // 初始化公共数据
        mgr_.reset(new UserManager());
        mgr_->AddUser({"Alice", "alice@example.com"});
    }

    std::unique_ptr<UserManager> mgr_;
};

TEST_F(UserManagerTest, GetUser_ExistingUser_ShouldReturnUser)
{
    auto user = mgr_->GetUser(1);
    EXPECT_EQ(user.name, "Alice");
}

这里有个细节：夹具类名 UserManagerTest 和测试套件名保持一致。这样你在代码里搜索 UserManagerTest，既能找到夹具定义，也能找到所有相关的测试用例。

19.5 目录与文件的组织层次

我建议的完整组织层次如下：

tests/
├── CMakeLists.txt              # 测试构建配置
├── main_test.cpp               # 测试入口（main函数）
├── core/                       # 核心模块测试
│   ├── user_manager_test.cpp
│   ├── order_service_test.cpp
│   └── payment_test.cpp
├── utils/                      # 工具类测试
│   ├── string_helper_test.cpp
│   └── file_util_test.cpp
├── integration/                # 集成测试
│   ├── db_integration_test.cpp
│   └── api_integration_test.cpp
└── mocks/                      # Mock 定义
    ├── mock_user_repository.h
    └── mock_payment_gateway.h

注意几点：

• 测试入口文件：main_test.cpp 只放 main() 和全局初始化，不写具体测试。
• Mock 单独放：mocks/ 目录专门放 Mock 类，方便复用。
• 集成测试隔离：集成测试单独一个目录，避免和单元测试混在一起。

19.6 命名规范速查表

为了方便团队落地，我整理了一张速查表：

元素	规范	示例
测试文件	模块名_test.cpp	user_manager_test.cpp
测试套件	被测类名 + Test	UserManagerTest
测试用例	方法名_场景_预期行为	AddUser_ValidUser_ShouldReturnUserId
测试夹具	被测类名 + Test	class UserManagerTest : public ::testing::Test
Mock 类	Mock + 接口名	MockUserRepository
测试目录	镜像 src/ 结构	tests/core/ 对应 src/core/

19.7 知识体系总览

下面这张图，把测试组织与命名的核心脉络串起来了：

19.8 落地建议

最后，给你几条落地建议：

• 先在团队内达成共识：把命名规范写进项目的 CONTRIBUTING.md，代码评审时严格执行。
• 用模板生成测试文件：我习惯在 IDE 里配一个测试文件模板，新建时自动填充套件名和夹具结构。
• 定期清理：每个迭代末，花 30 分钟检查测试文件是否和源码结构一致。不一致的及时调整。

嗯，这一章就聊到这里。测试组织是基本功，但往往被忽视。把基础打牢，后面的测试工作才能事半功倍。

---