★ FEATURED ARTICLE 嵌入式物联网硬件开发驱动开发【免费下载链接】FastLEDThe FastLED library for colored LED animation on Arduino. Please direct questions/requests for help to the FastLED Reddit community: http://fastled.io/r Wed like to use github issues just for tracking library bugs / enhancements.项目地址https://gitcode.com/gh_mirrors/fa/FastLED点击查看免费下载本篇指南面向在 FastLED 仓库中承担测试执行与结果汇报职责的 AI Agent以及需要理解这套 CI 测试入口的开发者系统讲解 test-agent 的角色定位、四步工作流程、uv run test.py全套命令的语义与源码级原理、标准化的通过/失败汇报格式以及必须遵守的六条关键规则。读完你可以直接复用这套流程跑全量测试、定向调试单个用例、驱动 AVR8JS 仿真器测试并产出可被其他 Agent 直接消费的测试结论。角色定位一个只测试、不修复的专职子代理test-agent 是 FastLED 仓库中定义的专职测试子代理其定义文件为 .claude/agents/test-agent.md。从该文件的 YAML front-matter 可以看到它的三个关键属性name:test-agent供.claude工作流按名引用description: Runs test suite and reports pass/fail status——它的全部职责就是运行测试套件并汇报通过/失败状态tools / model: 仅授予Bash工具并使用轻量模型haiku意味着它应尽量做薄执行命令、解析输出、格式化汇报而不承担复杂的代码推理。配套的工作流接线也印证了这一分工命令入口 .claude/commands/test.md 明确要求Use the test-agent sub-agent to execute tests and report results in a clear, actionable format技能文件 .claude/skills/test/SKILL.md 则把context: fork与agent: test-agent绑定在一起。也就是说开发者发起bash test ...Claude Code 会 fork 出 test-agent 去执行再由它返回结构化的测试结论。一个值得强调的边界test-agent 只汇报问题、不修复问题Dont fix issues - only report them (fixing is the job of other agents)。这与仓库中其他专职子代理如 .claude/agents/lint-agent.md、.claude/agents/fix-board-agent.md形成流水线分工。四步工作流程test-agent 的执行过程被固定为四个步骤任何一次测试任务都应遵循Parse arguments解析参数理解用户到底要跑什么——全量测试、单个指定测试、仅 C 测试还是带--run的仿真器测试Run tests运行测试以正确的 flags 执行uv run test.py对应的命令Analyze results分析结果判定测试是通过还是失败失败时提取失败测试名称与原因Report汇报按固定模板输出清晰、可操作的反馈供用户或上游 Agent 直接使用。从源码侧看这四步与 test.py 的主流程一一对应main()先调用 ci/util/test_args.py 的parse_args()完成参数解析与自动补全步骤 1随后根据参数走 fingerprint 缓存判定、测试调度步骤 2测试结果通过异常与退出码汇聚步骤 3最后由 Agent 按模板汇报步骤 4。常用测试命令速查含源码级语义test-agent 文档规定的核心命令均通过uv run test.py执行。下面逐条给出语义并补充源码依据与实用建议。1. 全量测试uv run test.py不指定任何参数时运行全部测试C 单元测试 示例编译测试 Python 测试。源码依据test.py 的main()中无--unit/--examples/--py且带--full时走RunningProcessGroup并行调度Python 测试与示例测试并行执行以缩短墙钟时间见 ci/util/test_runner.py 的RunningProcessGroup用法。若没有任何指定测试且全部 scope 成功FingerprintManager会把cpp、examples、python、wasm四个 scope 的指纹标记为成功下次运行可直接命中缓存详见 ci/util/fingerprint.py 的save_success/mark_failure。2. 仅运行 C 测试uv run test.py --cpp语义等价于--unit --examplesC 单元测试 示例编译并抑制 Python 测试参数定义见 ci/util/test_args.py 中--cpp的 help 文本Run C tests only (equivalent to --unit --examples, suppresses Python tests)。如果你只关心库本身的 C 单元测试可以更进一步用uv run test.py --unit。3. 运行指定测试uv run test.py TestName例如文档中给出的xypath对应 examples/XYPath 示例也可以传 C 单元测试名甚至可以用多个单词做模糊匹配uv run test.py string interner源码依据parse_args会把nargs*收集到的多个单词用空格拼成查询串若该名称不是ci/tests下已有的 Python 测试则交给 ci/util/smart_selector.py 的get_best_match_or_prompt()做智能匹配——它对空格、下划线、连字符做归一化并用 Levenshtein 编辑距离打分能自动判定你指的是单元测试还是示例并自动补全--cpp/--unit/--examples等标志。当匹配到的是示例时会把args.examples置为[匹配名]并开启--cpp匹配到单元测试时会把名称转换为 Meson 目标名如tests/fl/async.cpp→fl_async。4. 强制重建/重跑uv run test.py --no-fingerprint跳过 fingerprint 缓存判定强制重建并重跑。源码警示test.py 中--no-fingerprint会把四个 scope 的 change 标志全部置为True同时把RebuildMode设为NO_CACHE而仓库的测试指南 agents/docs/testing-commands.md 明确把该 flag 标记为LAST RESORT ONLY它会让构建慢 10100 倍只有在怀疑指纹缓存本身损坏而非构建过期时才允许使用。若只是怀疑构建过期应改用--clean。指纹缓存本体在.cache/下由 ci/util/fingerprint.py 的FingerprintManager管理check()方法通过比对源文件哈希与上次指纹决定needs_run。5. 仿真器测试AVR8JS 与 ESP32 QEMU 的分岔uv run test.py --run uno Blink这条命令走 AVR8JS 仿真器由 ci/runners/avr8js_runner.py 负责先以 fbuild 编译示例固件再在 Docker 镜像中运行 AVR 仿真器。源码细节--run的第一个参数是板子名avr8js_runner目前支持的板子为uno、attiny85、attiny88、nano_every后续参数是要测试的示例名若不指定默认测试Test示例。板子到后端backend的映射表位于 ci/runners/backends.json。重要差异ESP32 QEMU 不再有本地 runner。--run esp32s3 ...会走到 test.py 的报错分支——提示你改用 fbuild 的test-emu子命令。具体做法是先暂存配置再仿真命令与 CI 的qemu_template.yml保持一致# 1. 仅暂存源码与配置不编译固件 uv run ci/stage_fbuild_project.py \ --board esp32s3 \ --example Blink \ --define FASTLED_ESP32_IS_QEMU \ --build-dir .build/fbuild/esp32s3 # 2. 用 fbuild 仿真自动下载 Espressif QEMU 二进制 uv run fbuild test-emu \ --emulator qemu \ --environment esp32s3 \ --timeout 120 \ --halt-on-success Blink setup complete - starting blink loop \ --halt-on-error Guru Meditation|abort\\(\\)|Backtrace:|TEST_SUITE_COMPLETE: FAIL|QEMU_LCD_CLOCKLESS_REGISTRATION: FAIL \ .build/fbuild/esp32s3这两条 QEMU 命令在 agents/docs/testing-commands.md 的 QEMU Commands 一节有完整说明是 test-agent 文档中--run一句的落地展开。汇报格式让结果可直接被机器与上游 Agent 消费test-agent 的产出必须遵循三种固定模板保证任何下游都能零成本解析。全部通过✅ TESTS PASSED [X/X] tests passed successfully.存在失败❌ TESTS FAILED Failed tests: - [Test name 1]: [Brief failure reason] - [Test name 2]: [Brief failure reason] Run uv run test.py for full details.未指定具体测试全量✅ TESTS PASSED Ran all tests - [X/X] passed.模板要点通过/失败符号 明确的计数[X/X] 逐条失败列表测试名 简短原因 复跑指引。测试名必须直接从命令输出中复制Report actual test names - copy from output不得凭记忆拼写这样下游 Agent 才能拿这个名字去复现或修复。六条关键规则test-agent 文档的 Key Rules 是它区别于普通脚本执行者的行为契约逐条展开如下Python 命令一律用uv run绝不裸写python。这与仓库统一环境管理一致——pyproject.toml 定义了ci包的完整依赖集meson、ninja、pytest、fbuild2.5.29 等只有通过uv run才能拿到一致的执行环境。始终停留在项目根目录绝不cd到子目录。原因可以从 test.py 开头看到脚本自身os.chdir(Path(__file__).parent)把工作目录钉在仓库根且指纹缓存、.build/、src/等全部按根目录相对路径解析任何目录漂移都会破坏解析。汇报真实的测试名从输出复制不臆造。简洁但信息充分用户需要的是可行动的结论哪些失败、为什么不是原始日志。只报告、不修复修复是其他专职子代理fix 类 Agent的工作test-agent 擅自改动代码会破坏流水线的职责边界。合理设置超时长测试套件要给出足够的 timeout。这一点在源码中有量化依据——ci/util/test_runner.py 里默认单进程超时 240 秒、GitHub Actions 环境 600 秒Python 套件含 fbuild QEMU 冒烟测试冷缓存时子进程最长可达 1860 秒因此顶层看门狗超时被设为_PYTHON_TEST_TIMEOUT 120秒左右顺序 debug 构建带 sanitizer更是会被放宽到 2700 秒见 test.py 的超时调整逻辑。Agent 调用命令时的 shell 超时必须大于这些内部超时否则会在看门狗兜底前就误杀进程。失败排查超时、看门狗与崩溃转储test-agent 只负责汇报但当汇报需要足够信息时理解底层机制能让你给出简短失败原因看门狗双层兜底test.py 启动两个守护线程——主看门狗在超时后先释放构建锁、dump_thread_stacks()抓线程栈再以退出码 2 强制退出若主看门狗自身卡死deadman_timer会在seconds 60s后无条件os._exit(3)。这意味着挂死的测试最终都会留下线程栈证据。崩溃转储提醒test.py 的_check_crash_dumps()会扫描.gdb_crash/crash_*.txt发现新的崩溃转储会给出红色醒目提示可用bash lint清理。测试若崩溃内部 crash handler 会先输出栈信息再叠加外部调试器路径详见 docs/signal-handler-chaining.md 与 docs/deadlock-detection.md。快速失败策略MAX_FAILURES_BEFORE_ABORT 3——全量模式下失败总数超过 3 即中止见 ci/util/test_runner.py避免无效长跑。进阶参数与构建模式test-agent 能力边界的完整画像虽然 test-agent 文档只列出五条常用命令但了解 ci/util/test_args.py 中全部参数有助于 Agent 在解析参数环节做出正确判断。按用途归类类别参数语义测试范围--unit/--py/--examples/--example-group/--full/--check仅 C 单元测试 / 仅 Python 测试 / 示例编译测试可指定示例名/ 按示例组CompileTests、Nightly、Basic、Classic、Advanced、Fx、Experimental 等AutoResearch 组被显式拒绝并提示走bash compile esp32s3 --examples AutoResearch/ 完整编译链接执行 / 静态分析IWYU、clang-tidy自动联动--cpp --clang构建模式--quick/--debug/--debug-thin/--build-modequick默认-O0 -g0最快迭代/ debug-Og -g3 -fsanitizeaddress,undefined/ debug-thin仅 Linux只给 FastLED 核心加 ASanUBSan其余 DLL 与 PCH 不插桩/ release-O2 -DNDEBUG各模式使用独立的.build/meson-{quick,debug,debug-thin,release}/目录互不污染缓存缓存控制--no-fingerprint/--force/--clean禁用指纹缓存 / 等价于--no-fingerprint/ 全量重建不手动删.build/见 agents/docs/testing-commands.md诊断输出-v/--verbose/--show-compile/--show-link/--no-stack-trace/--stack-trace/--log-failures/--debug-test详细输出 / 展示编译命令 / 展示链接命令 / 关闭超时栈转储 / 开启栈转储 / 失败日志写入目录name_compile.log、name_run.log/ 调试 KeyboardInterrupt 处理器环境与调度--no-interactive/--interactive/--no-parallel/--clang/--gcc/--no-pch/--setup-only/--list-tests非交互CI 用/ 交互 / 顺序执行等价于环境变量NO_PARALLEL1/ 编译器选择Windows 默认 clang其余平台默认 gcc/ 关闭预编译头 / 仅生成compile_commands.json供 IntelliSense / 仅列出可用测试参数联动示例来自 ci/util/test_args.py 的自动补全逻辑指定测试名时自动补全--pyPython 测试或--cpp --unitC 单元测试带--examples时自动开启--cpp并在未显式指定 preset 时自动补--quick--debug-thin与--debug/--build-mode互斥且仅限 Linux--no-interactive与--interactive互斥同时传入直接报错退出。这些联动保证了 Agent 即使只给出最简命令测试入口也会落到正确的 scope 与构建模式上。在实际仓库工作流中的接入方式test-agent 并非孤岛它被三个层级串联进 FastLED 的 Agent 工作流命令层.claude/commands/test.md 定义了test命令接受[test-name] [--cpp] [--no-fingerprint] [--run platform]等参数内部直接委托给 test-agent技能层.claude/skills/test/SKILL.md 声明agent: test-agent与context: fork并再次强调Usebash testwrapper (NEVER barepython)——注意技能层推荐bash test包装脚本根目录的 test 脚本内容就是uv run test.py $与 agent 文档中的uv run test.py直调方式互补日常交互优先用bash testAgent 内部精确控制 flags 时用uv run test.py文档层agents/docs/testing-commands.md 是 test-agent 命令清单的完整展开包含禁止直接调 meson/ninja/clang、超时挂死检测、指纹缓存红线、fbuild 默认后端等更细的约束。结语一份可复制的测试执行契约test-agent 的价值不在于会跑测试而在于它把解析参数 → 执行 → 分析 → 汇报固化成了一套可被其他 Agent 与 CI 消费的契约命令有据可查.claude/agents/test-agent.md ci/util/test_args.py行为有规则约束六条 Key Rules产出有标准模板✅/❌ TESTS PASSED/FAILED[X/X]计数。无论你是手工执行uv run test.py还是让 Claude Code fork 出 test-agent 代跑这套契约都能确保测试结论清晰、准确、可行动。赞分享嵌入式物联网硬件开发驱动开发【免费下载链接】FastLEDThe FastLED library for colored LED animation on Arduino. Please direct questions/requests for help to the FastLED Reddit community: http://fastled.io/r Wed like to use github issues just for tracking library bugs / enhancements.项目地址https://gitcode.com/gh_mirrors/fa/FastLED点击查看免费下载相关推荐Tester Agent 测试执行子代理实战dotnet-test 插件中多语言测试运行与结果报告指南Tester Agent 测试执行子代理实战dotnet test 插件中多语言测试运行与结果报告指南 导读 本文聚焦 dotnet test https:/人工智能AI 技能AI 评测Benchmark开发工具Dillinger 项目中的 /test 命令工作流AI Agent 测试生成、执行与覆盖率检查的完整实战指南Dillinger 项目中的 /test 命令工作流AI Agent 测试生成、执行与覆盖率检查的完整实战指南 导读 本文以仓库内 .agent/workfl前端开发工具Webpack 测试体系全解test/ 目录结构、测试套件分类与命令速查Webpack 测试体系全解test/ 目录结构、测试套件分类与命令速查 本文基于 webpack 仓库根目录的 TESTING_DOCS.md https:前端构建开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
