FastLED 严格 TDD 实现指南：基于 tdd-implement Skill 的特性驱动测试优先开发

• 嵌入式
• 物联网
• 硬件开发
• 驱动开发

本篇指南讲解 FastLED 仓库中.claude/skills/tdd-implement/SKILL.md所定义的"严格测试驱动开发（TDD）"实现流程：如何把一条功能需求或 Bug 修复拆解为可测试行为，并逐个通过 Red-Green-Refactor 完整周期落地。读完本文，你将掌握 FastLED 测试约定（FL_断言宏、bash test包装命令、测试文件镜像放置规则）以及配套测试基础设施（trampoline 层、测试发现与合并机制）的底层原理，可直接在仓库中开展特性开发。

一、Skill 定位：比/tdd更结构化的特性实现工作流

tdd-implement是 FastLED 仓库.claude/skills/目录下的一组 Agent Skill 之一（tdd、test、lint等 Skill 并列存在），其元数据如下：

• name：tdd-implement
• description：使用严格 TDD 实现特性或修复 Bug——先分析需求、创建测试、实现最小代码，再重构；适用于需要测试覆盖的功能请求、Bug 修复或增强。
• argument-hint：<feature request, bug description, or issue reference>
• context：fork（面向派生分支开发场景）
• agent：test-writer-agent（与.claude/agents/test-writer-agent.md对应）

Skill 文档开篇明确说明：这是一个比/tdd（见.claude/skills/tdd/SKILL.md，侧重 Red-Green-Refactor 三个阶段引导）更结构化的工作流——分析需求、把需求拆成可测试行为，然后对每一个行为执行完整的 Red-Green-Refactor 周期。核心纪律是：

Test FIRST, implement SECOND——这个顺序是绝对的。

二、Step 1：需求分析（Requirement Analysis）

2.1 四个标准动作

在写任何测试之前，先完成需求分析：

1. 仔细阅读需求——确定需要改变或新增的行为；
2. 定位相关源码：用 Grep/Glob 找到需要修改的文件；
3. 阅读已有测试：找到受影响代码的现有测试覆盖；
4. 识别可测试行为：把需求拆解为 1～5 个离散、可验证的单元。

2.2 输出模板

分析完成后，按以下模板输出，作为后续每个周期的基线：

## Requirement Analysis **Requirement**: [one-line summary] **Source files**: [list of files that will be modified] **Existing tests**: [list of related test files, or "none found"] **Testable behaviors**: 1. [behavior 1 — what it does, how to verify] 2. [behavior 2 — what it does, how to verify] 3. [behavior 3 — if needed]

这一步的意义在于：把"模糊的功能请求"翻译成可验证的行为清单，每个行为对应后续一个独立的 TDD 周期，避免在实现中途不断"追加需求"导致测试与实现脱节。

三、Step 2：对每个行为执行完整 TDD 周期

对每一个可测试行为，必须依次执行RED → GREEN → REFACTOR三个子阶段，且每个阶段之间都要运行测试验证。

3.1 RED：先写一个失败测试

写一个针对该行为的最小测试，并遵循agents/tests.md（仓库测试约定文档，见agents/tests.md）中的全部约定：

• 使用FL_前缀宏（FL_CHECK_EQ、FL_REQUIRE_TRUE等）；
• 包含test.h与FastLED.h；
• using namespace fl;+ 匿名命名空间；
• 测试文件放置位置镜像源码路径（src/fl/foo.h→tests/fl/foo.cpp）。

随后运行bash test TestName，确认它以"正确的理由"失败——即因为功能缺失或 Bug 存在而失败，而不是编译错误或拼写错误。

3.1.1 断言宏体系：trampoline 层与FL_前缀

为什么强制使用FL_前缀？因为 FastLED 测试套件在tests/test.h中定义了一套trampoline（跳板）层，把所有断言统一转发到fl_unittest.h（tests/shared/fl_unittest.h）定义的原生测试框架上：

// tests/test.h 中的兼容别名示例 #define CHECK(expr) FL_CHECK(expr) #define CHECK_EQ(a, b) FL_CHECK_EQ(a, b) #define CHECK_LT(a, b) FL_CHECK_LT(a, b) #define REQUIRE(expr) FL_REQUIRE(expr) // ... 以及 35+ 个 FL_ 变体

这套 trampoline 让测试代码与底层框架解耦，并保证断言输出包含期望值 vs 实际值的可读错误信息。按agents/tests.md的选型规则：

保留不转换的例外包括：TEST_CASE/SUBCASE（测试结构宏）、CHECK_CLOSE/REQUIRE_CLOSE（自定义浮点比较）、DOCTEST_CONFIG_*（配置宏）。

另一个容易被预处理器"坑"的细节：模板表达式中的逗号。当断言参数是func<T1, T2>(arg)这类包含逗号的模板表达式时，宏会把逗号当作参数分隔符，必须用括号整体包裹：

// 错误：预处理器看到 3 个参数 FL_CHECK_EQ(int_scale<T1, T2>(arg), expected) // 正确：括号保护逗号 FL_CHECK_EQ((int_scale<T1, T2>(arg)), expected) FL_CHECK_TRUE((std::is_same<A, B>::value))

3.1.2 测试文件结构约定

agents/tests.md给出了空白测试模板：文件头注释 +#include "test.h"+#include "FastLED.h"+using namespace fl;+ 一个TEST_CASE。同时要求把测试辅助类/夹具放入匿名命名空间（namespace { ... }，关闭时注释} // anonymous namespace），避免跨测试文件符号冲突，且using namespace fl;必须位于匿名命名空间之前。

3.2 GREEN：最小实现

1. 只写让当前测试通过的最少代码；
2. 不要顺带实现其他行为（一次只做一个行为）；
3. 运行bash test TestName确认PASSES；
4. 运行bash test --cpp确认无回归。

GREEN 阶段的纪律是"不做提前优化，写能通过测试的最简单方案"——这也是tdd/SKILL.md中"no premature optimization"的同一原则。

3.3 REFACTOR：在不改变行为的前提下清理

1. 改善代码质量（消除重复、澄清命名、降低复杂度），不改变行为；
2. 每次改动后都运行测试，确保始终 green。

3.4 每个周期都要输出报告

### Behavior N: [description] - RED: Test written at tests/fl/foo.cpp — FAILS (expected: [reason]) - GREEN: Implemented in src/fl/foo.h — PASSES - REFACTOR: [changes made, or "clean as-is"]

四、Step 3：集成验证（Integration Verification）

所有行为实现完成后：

1. 运行完整测试套件：bash test --cpp；
2. 检查回归：验证 ALL 测试通过，不只是新增测试；
3. 整体审查变更：确保实现内聚；
4. 运行代码审查：对照 FastLED 编码规范检查。

输出模板：

## Integration Verification **Full test suite**: [X/X] tests pass **New tests added**: [count] **Source files modified**: [list] **Regressions**: None / [details if any]

这里体现的另一个仓库级要求（见agents/tests.md）：后台 Agent 在宣告完成前必须跑通bash test，对测试失败零容忍；只有在被编排为多步计划中的子步骤、且编排者明确声明豁免测试指令时，才只跑bash lint由编排者在最终统一执行bash test --cpp。

五、Step 4：最终总结

每个特性实现完成后输出统一格式的总结，便于 Code Review 与提交信息生成：

## TDD Implementation Complete **Requirement**: [what was implemented] **Approach**: [brief description of the solution] ### Files Changed | File | Change Type | Description | |------|-------------|-------------| | tests/fl/foo.cpp | Added | 3 test cases for [feature] | | src/fl/foo.h | Modified | Added [function/method] | ### Test Coverage - [Test case 1]: [what it verifies] - [Test case 2]: [what it verifies] - [Test case 3]: [what it verifies] ### All Tests Passing: Yes

六、关键规则一览

Skill 文档末尾的 8 条硬性规则是整个过程不可违背的约束：

其中"绝不裸跑底层工具"与仓库agents/docs/testing-commands.md的强制要求一致：bash test是唯一入口，WASM 是默认编译目标，硬件平台仅在用户明确要求时才使用。

七、仓库测试基础设施源码解析

7.1bash test包装脚本

仓库根目录的test是 bash 包装脚本，全文仅三行：

#!/bin/bash set -e cd "$(dirname "$0")" uv run test.py "$@"

它把参数原样透传给uv run test.py。因此bash test TestName等价于"用项目 Python 环境构建并运行指定测试"，bash test --cpp则运行完整 C++ 测试套件。testing-commands.md还补充了可组合的常用旗标：--clean（干净重建，禁止手动删除.build缓存）、--debug（ASan+UBSan）、--build-mode release等。另外测试默认 10 秒超时，配合 watchdog 与崩溃处理器（见docs/deadlock-detection.md）可自动检测死循环/死锁并 dump 线程栈。

7.2 测试发现与合并机制

测试发现配置集中在tests/test_config.py：

• EXCLUDED_TEST_FILES：排除doctest_main.cpp、被并入兄弟文件的测试（如tests/fl/map_range.cpp→clamp.cpp等）、独立性能剖析二进制等；
• EXCLUDED_TEST_DIRS：排除tests/shared（runner 基础设施）、tests/data（测试数据）、tests/profile（自带 malloc/free 覆盖，不能当单测编译）等目录；
• 合并（consolidation）模式：某些子目录（如tests/fl/fx/2d/）下的多个.cpp由父文件#include统一编译为一个测试二进制，文件顶部// ok cpp include注释是 lint 豁免标记而非构建注册机制。向合并目录新增测试时，需把文件加进父.cpp的#include列表。

这也呼应了规则"扩展已有测试文件，不要新建"：维护一个精简、合并的测试套件意味着更少的编译单元、更快的构建和更易维护的仓库。

7.3 测试简洁原则与真实示例

agents/tests.md反复强调"绝对简单"：不用 mock、不建辅助类、一个精心设计的测试胜过十个冗余变体。以真实测试文件tests/fl/clamp.cpp为例，它用FL_TEST_CASE("fl::clamp")+ 多个FL_SUBCASE覆盖了整数类型、uint8_t/int8_t/uint16_t/int16_t/uint32_t/int32_t、浮点与 double、边界值、零区间（min==max）等场景：

#include "fl/math/math.h" #include "fl/stl/stdint.h" #include "test.h" using namespace fl; FL_TEST_CASE("fl::clamp") { FL_SUBCASE("integer types") { FL_CHECK_EQ(clamp(5, 0, 10), 5); FL_CHECK_EQ(clamp(-5, 0, 10), 0); FL_CHECK_EQ(clamp(15, 0, 10), 10); // Boundary values FL_CHECK_EQ(clamp(0, 0, 10), 0); FL_CHECK_EQ(clamp(10, 0, 10), 10); // Same min and max FL_CHECK_EQ(clamp(5, 7, 7), 7); } // ...更多 SUBCASE }

注意其文件末尾还#include "tests/fl/map_range.hpp"把相关测试并入同一编译单元，正是合并模式的落地体现。这样的测试"从阅读代码就能看出在测什么"、无需 mock 基础设施、编译更快，且能真正抓住 Bug——与 Skill 的"使用真实对象与真实值"规则一脉相承。

八、在 FastLED 中落地 TDD 的完整工作流

把 Skill 的四个步骤与仓库命令映射到一条可执行流水线：

1. 需求分析：Grep/Glob定位src/fl/下待改文件，搜索tests/fl/已有覆盖；
2. RED：在镜像路径写FL_TEST_CASE（含test.h、FastLED.h、using namespace fl;、匿名命名空间），运行bash test TestName确认因功能缺失而失败；
3. GREEN：在src/fl/写最小实现，bash test TestName通过后再bash test --cpp确认无回归；
4. REFACTOR：清理并每步复测；
5. 集成验证：全量bash test --cpp，按模板输出 Files Changed / Test Coverage；
6. 收尾：由于仓库是只读的研究环境，实践时请在你自己的 fork 分支上执行上述改动与提交。

命令速查：

九、常见边界与陷阱

• 失败原因必须"正确"：RED 阶段测试若因编译错误失败，说明测试本身写错了，必须先修测试；
• 一次一个行为：把多个行为塞进一个周期会让 GREEN 阶段的"最小实现"无法定位，也违背规则；
• 何时新建测试文件：仅当测试完全新的子系统、或与现有测试结构无法逻辑归并时才新建，且位置必须镜像src/fl/对应路径；严禁把测试放进tests/misc/这个 legacy 目录；
• 模板逗号：断言表达式里的func<T1, T2>(...)必须用括号包裹，否则预处理器会把逗号当成宏参数分隔符；
• 不要用裸工具：meson setup、ninja -C、clang++ main.cpp均被禁止，统一走bash test。

十、小结

tdd-implementSkill 把经典 TDD 与 FastLED 仓库的工程约束（trampoline 断言宏、镜像测试路径、合并测试目录、bash test包装命令、无 mock 原则）整合成一套可重复执行的"特性实现流水线"。对开发者的实际价值在于：每个需求都被迫先变成可验证的行为清单与失败测试，实现过程保持最小步进，最后以统一模板输出变更与覆盖证据——既保证了代码质量，也让 Code Review 和 CI 回归有据可依。建议结合agents/tests.md（测试约定）与agents/docs/testing-commands.md（命令与超时机制）一起阅读，即可在 FastLED 上完整闭环地跑通一次严格 TDD 开发。

• 嵌入式
• 物联网
• 硬件开发
• 驱动开发