CrewAI 单元测试：3步锁定Agent、Task、Crew的行为

CrewAI 单元测试：3步锁定Agent、Task、Crew的行为

【免费下载链接】crewAIFramework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.项目地址: https://gitcode.com/GitHub_Trending/cr/crewAI

CrewAI 是一个编排多个 AI 代理协作的框架，Agent、Task、Crew 里都藏着大量隐式逻辑，得靠 CrewAI 单元测试把行为锁住。这篇文章帮你三步写出第一个能跑的测试用例。

把第一个测试跑起来 🚀

先克隆仓库、装依赖。项目用 uv 管理依赖和虚拟环境（可以理解为比 pip 更快的 Python 包管理器），clone 完执行这段：

git clone https://gitcode.com/GitHub_Trending/cr/crewAI cd crewAI uv sync --all-groups --all-extras

然后在lib/crewai/tests/下建一个测试文件，内容就这几行：

from unittest.mock import Mock from crewai import Task agent = Mock() agent.execute_task.return_value = "test result" task = Task(description="写一段摘要", agent=agent) result = task.execute_sync(agent=agent) assert result.raw == "test result"

逐行说：Mock()把 Agent 换成假对象，不真调 LLM（慢、不稳、还烧 token）；execute_task.return_value指定"假 LLM"的返回；最后一行assert确认 Task 真的把输出塞进了结果。跑起来（pytest 是 Python 最常用的测试框架）：

cd lib/crewai && uv run pytest tests/my_first_test.py -v

变绿就成了。接下来你可以把断言换成任何想验证的行为。

测试代码放在哪、怎么找

要测哪个模块，先想它属于哪个包，目录结构和源码包是一一对应的，然后去 lib/crewai/tests/ 下找对应子目录：

• agents/→ Agent 行为
• task/→ Task 执行、异步任务
• crew/→ Crew 编排
• a2a/→ 代理之间的通信
• llms/→ 各家 LLM 的集成
• cassettes/→ LLM 调用的录制响应，测试重放时不真正发网络请求

根目录直接放文件的多是核心类测试，比如 test_task.py。在编辑器里全局搜test_<模块名>，十有八九能找到。

用 Mock 和断言把测试"锁死"

Mock（模拟）是 CrewAI 单元测试的核心手法：把"慢、贵、不稳定"的外部依赖换成受控的假对象，被测逻辑保持真身。一句话：不关心的 Mock，被测的别 Mock。

这是企业版的测试配置页：选迭代次数、勾选要测哪个模型，和你在单测里挑"假 LLM"是同一个思路。仓库里 test_task_guardrails.py 就是标准示范：Task 是真的、guardrail 校验逻辑是真的，只 Mock 掉 Agent。你照着写：

# 对：只 Mock LLM 调用，被测的 guardrail 用真对象 agent = Mock() agent.execute_task.return_value = "test result" task = Task(description="test", agent=agent, guardrails=[validate]) assert task.execute_sync(agent=agent).raw == "test result" # 错：你测的是 guardrail 校验逻辑，却把 validate 本身 Mock 掉了 # 测试永远绿，但它什么都没验证

养成这个习惯，测试才不只是"跑一遍看着对"，而是真的在验证行为。

测试失败了先看哪里

红了先看环境，别急着怀疑逻辑。CrewAI 的 LLM 测试用 VCR（一个录制/回放 HTTP 请求的工具）把真实响应存进lib/crewai/tests/cassettes/，该调 LLM 的测试报网络或鉴权错，多半是 cassette 缺失或没匹配上，而不是你的代码写错。

确认是逻辑问题，跑uv run pytest <文件> -k <用例名> -vv看完整断言栈；想搞清楚 Agent 为什么这么干，打开 tracing（执行追踪，逐步记录每个环节的输入输出）：

让测试自动跑起来 ✅

仓库的 .github/workflows/tests.yml 在 pull request 时触发，把完整测试套件切成 8 片并行跑，覆盖 Python 3.10 到 3.13，任何一片失败都会拦住合并。CI 细节不用深究，记住一条：本地uv run pytest过了，PR 大概率是绿的；反过来 PR 红了，就去翻对应分片那一组的日志。

下一步可以做什么

把 Mock 换成真 Agent 加一次真实 LLM 调用，写个集成测试，key 放进.env.test文件（仓库的 conftest.py 会自动加载它）。再翻几个cassettes/下的录制文件，理解请求是怎么被录下来又重放的。这两步做完，给你自己项目里的 Crew 补测试就是小时级的事。

【免费下载链接】crewAIFramework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.项目地址: https://gitcode.com/GitHub_Trending/cr/crewAI