Composio 回归测试指南：从复现缺陷到提交可验证的修复-编程实验室

Composio 回归测试指南：从复现缺陷到提交可验证的修复

【免费下载链接】composioComposio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio

导读

本文面向 Composio SDK 的贡献者与维护者，系统讲解在仓库中开展回归测试（Regression Testing）的完整工作流：从复现 Bug、定位根因、修补缺陷，到在正确的测试区域补充回归测试并用聚焦命令验证，最终在 PR 中给出可审计的验证证据。读完本文，你将掌握 TypeScript（ts/）与 Python（python/）两侧的测试布局、常用命令（pnpm filter、pytest、make 目标）以及跨 SDK 的测试惯例，能够把一次缺陷修复变成一条防回归的安全网。

本文基于仓库中的 .agents/skills/bug-fixing/references/regression-testing.md 展开，并结合 bug-fixing 技能说明、Python 验证参考与 TypeScript 测试命令参考等仓库内资源进行深化。

回归测试的核心工作流

回归测试的目标不是"补一个测试了事"，而是确保修复针对根因（root cause）而非症状（symptom），并让该缺陷在后续迭代中持续被 CI 拦截。标准流程分为五步：

复现 Bug：重现缺陷，或识别出失败的断言与 CI 任务（如pnpm test、make tst中的失败项）。
追踪根因：在受影响的最小模块（smallest affected module）中定位根因，而不是在大范围代码中漫无目的地排查。
修补根因：修复缺陷的根源，而非仅仅掩盖表象。从源码结构看，Composio 将核心逻辑收敛在 ts/packages/core/src 与 python/composio 中，缺陷通常能归结到某个具体模型、工具或客户端方法。
添加或更新回归测试：在该功能已有的测试区域中新增或更新回归测试，优先复用现有测试文件，避免为单个缺陷创建一次性（one-off）测试文件。
先跑聚焦测试，再跑最小覆盖范围：先用最窄的命令验证修复，再扩大到覆盖受影响面的最小范围检查（如类型检查、包内全量测试）。

第 4 步的关键原则是"就近放置"：回归测试应放在该功能既有的测试文件里，与功能测试放在一起，方便后续维护者看到缺陷修复与功能契约的关联。

TypeScript 侧：测试布局与命令

测试存放位置与编写约定

TypeScript 测试通常位于ts/packages/<package>/test/下，并遵循各包内已有的 Vitest 模式。以核心包 ts/packages/core/test 为例，测试按功能模块组织为多个子目录：

models/：模型层测试，如 toolRouter.test.ts、customTool.test.ts、triggers.test.ts；
tools/：工具执行与修饰器测试，如 tools.test.ts、fileModifiers.test.ts；
connectedAccounts/、AuthConfigs/、errors/、telemetry/、platform/等：分别覆盖连接账户、认证配置、错误码、遥测与运行时平台。

回归测试应优先加入既有的功能测试文件。例如 toolRouter.test.ts 中用vi.mock隔离遥测与工具依赖、用createMockClient()构造带toolRouter.session.create/retrieve/attach/link/toolkits/search/execute的桩客户端，再断言会话创建、工具路由等行为——如果你修复了 ToolRouter 的缺陷，回归测试就应当写进这个文件，沿用同样的 mock 模式。

常用命令

在仓库根目录（包含pnpm-workspace.yaml与turbo.jsonc）执行：

# 只跑某个包的测试 pnpm --filter @composio/<package> test # 只对某个包做类型检查 pnpm --filter @composio/<package> typecheck # 跑全量测试 pnpm test

例如核心包的聚焦检查：

pnpm --filter @composio/core test pnpm --filter @composio/core typecheck

按 TypeScript 测试命令参考，根目录还提供更广的验证面：

pnpm lint pnpm lint:packages pnpm typecheck pnpm build:packages pnpm test pnpm test:e2e pnpm test:e2e:node pnpm test:e2e:deno pnpm test:e2e:cloudflare pnpm test:e2e:cli

何时使用 E2E：运行时（runtime）打包或模块解析类回归使用 Node/Deno/Cloudflare 的 E2E（位于ts/e2e-tests/runtimes/）；CLI 二进制行为与输出契约类回归使用 CLI E2E（位于ts/e2e-tests/cli/）；运行 runtime 与 CLI E2E 需要本机具备 Docker。

Python 侧：测试布局与命令

测试存放位置与共享夹具

Python 测试位于python/tests/，共享夹具集中在python/tests/conftest.py。该文件提供了项目级的测试基础设施，例如：

mock_client夹具：构造带without_retries自引用的 mock HTTP 客户端，便于断言工具执行路径（生产环境将非幂等写操作路由到禁用重试的客户端克隆）；
triggers夹具：基于 mock 客户端构造Triggers实例；
webhook_fixtures/golden_signatures夹具：加载python/tests/fixtures/webhook/下的 Webhook 签名黄金数据，用于契约测试；
自动生效的guard_real_home_directory夹具：阻止任何测试在真实$HOME目录下创建条目——这是此前一次真实数据被破坏事故后引入的护栏，要求测试用monkeypatch.setenv('HOME', str(tmp_path))沙箱化$HOME。

回归测试应当复用这些既有夹具，而不是在单个测试文件中重复造轮子。

常用命令

从python/目录执行（也可直接运行 pytest）：

make chk # ruff 检查 + mypy 类型检查 make tst # pytest 全量测试套件 make snt # 快速 sanity 测试（imports 与 SDK 初始化） pytest tests/test_<feature>.py # 聚焦单个功能测试文件

make目标由 python/Makefile 定义，另有友好别名：make check（chk）、make test（tst）、make sanity（snt）。其底层由 python/noxfile.py 的 nox 会话实现：

fmt：Ruff import 修复与格式化（ruff check --select I --fix+ruff format）；
chk：对composio/、providers/、tests/、scripts/运行 Ruff 检查，并对同一批模块逐个跑 mypy；
tst：安装核心包与 crewai/langchain/langgraph provider 后，运行pytest（可通过 posargs 追加路径，如make tst -- tests/test_foo.py直接透传）；
tst_autogen：在隔离的 protobuf 兼容环境中跑 Autogen 回归用例；
snt：默认跑tests/test_imports.py与tests/test_sdk.py；
type_inference：安装全部 provider 后对tests/test_type_inference*.py系列文件跑 mypy，验证 provider 返回类型推断。

pytest 的默认行为见 python/pytest.ini：testpaths = tests，测试文件命名test_*.py，默认addopts = -v --tb=short且忽略test_type_inference*.py；内置标记包括slow、integration、unit、schema。编写回归测试时应选择与受影响包或 provider 匹配的 pytest 标记（如-m "not slow"跳过慢测试），并考虑在标记为integration时是否应放入独立于单元测试的路径。

如何定位"最小的受影响模块"

"最小模块"的定位依赖对仓库结构的理解：

Python 核心：python/composio/下按职责拆分，核心模型位于python/composio/core/models/（如tool_router.py、triggers.py），客户端与 SDK 入口见 python/composio/sdk.py 与 python/composio/client。
TypeScript 核心：ts/packages/core/src/下模型层models/、类型层types/、工具层models/Tools与models/CustomTool等，测试目录与之镜像对应（ts/packages/core/test/models/、test/tools/）。
Provider 层：Python 在python/providers/<name>/，TypeScript 在ts/packages/providers/，各 provider 的测试与实现一一对应。

举例：若缺陷出现在 ToolRouter 会话创建，Python 侧可追踪 test_tool_router.py 中mock_client夹具对tool_router.session.create的桩，以及 composio/core/models/tool_router.py 的模型定义；TypeScript 侧对应 toolRouter.test.ts 与src/models/ToolRouter。两个 SDK 对同一功能都有对称的测试面，这也是回归测试可以"跨语言对照"的切入点。

跨 SDK 回归的对照验证

Composio 同时维护 TypeScript 与 Python 两套 SDK，同类功能往往两侧各有实现与测试。仓库内已有对照先例：

Webhook 签名契约：Python 侧的golden_signatures夹具加载 python/tests/fixtures/webhook/ 数据，而 conftest 中get_ts_fixtures_dir()会跨目录引用 ts/packages/core/test/fixtures/webhook 下的 TypeScript 夹具——两侧共享同一份 golden 数据做契约对照。
JSON Schema 转换语料：get_py_json_schema_corpus_dir()与get_ts_json_schema_corpus_dir()分别指向python/tests/fixtures/json-schema-conversion/与ts/packages/core/test/fixtures/json-schema-conversion/，供test_schema_*系列与jsonSchema*.test.ts使用。

这意味着：当修复涉及两侧 SDK 的公共行为（如 Schema 转换、Webhook 签名、工具参数序列化）时，回归测试应当在两侧同时补齐，并复用共享语料/黄金数据，保证"同一缺陷、同一契约、两个实现"的一致性。

PR 说明的规范

在 PR 描述中必须交代三件事：

缺陷是什么：明确写出被修复的 Bug 名称或失败断言/CI 任务；
回归测试是什么：指出新增或更新的测试文件与用例（如python/tests/test_tool_router.py::test_xxx或ts/packages/core/test/models/toolRouter.test.ts）；
验证命令输出：贴出聚焦测试、类型检查或 CI 任务的真实输出，证明修复有效且未破坏周边功能。

若某个测试被有意跳过（skip），必须说明原因（如环境限制、依赖未就绪），并尽可能给出后续跟进方式。这套规范让审阅者无需猜测即可复核修复的完整证据链。

快速核对清单

完成一次回归修复后，逐项自检：

已复现缺陷或确认失败断言/CI 任务；
根因定位在最小受影响模块，而非大范围改动；
修复针对根因而非症状；
回归测试加入该功能既有测试文件（TS 在ts/packages/<package>/test/，Python 在python/tests/），未创建一次性测试文件；
聚焦验证通过：pnpm --filter @composio/<package> test或pytest tests/test_<feature>.py；
最小覆盖范围检查通过：pnpm --filter @composio/<package> typecheck/pnpm typecheck，或make chk/make snt；
Python 测试复用了 python/tests/conftest.py 中的既有夹具，未破坏$HOME沙箱护栏；
PR 描述包含 Bug 名称、回归测试位置与验证命令输出，跳过的测试有明确理由。