Composio Python SDK 集成测试全指南：从环境搭建到 MCP 功能验证

Composio Python SDK 集成测试全指南从环境搭建到 MCP 功能验证【免费下载链接】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 开源仓库中 Python SDK 的集成测试目录展开系统讲解如何搭建测试环境、运行集成测试并深入剖析 MCPModel Context Protocol功能测试套件的设计与底层实现。读完本文你将掌握 Composio Python SDK 集成测试的完整执行流程理解composio.mcp服务管理 API 的 CRUD 与实例生成机制并能在此基础上扩展属于自己的集成测试用例。集成测试在 Composio SDK 中的地位Composio 是一个帮助开发者构建 AI Agent 的工具平台其 Python SDK 提供了工具Tools、工具包Toolkits、触发器Triggers、认证配置AuthConfigs、连接账户ConnectedAccounts以及 MCP 服务管理等一系列能力。与只依赖本地 mock 的单元测试不同集成测试会真实调用 Composio 云服务验证 SDK 与后端 API 之间的实际交互是否正常。集成测试目录 位于python/composio/integration_test/其定位在 README 中写得很明确针对 Composio SDK 功能的集成测试Integration tests for Composio SDK functionality。这类测试的价值在于验证 SDK 方法的参数解析、请求构造与响应处理是否符合预期发现仅在真实网络环境下才会暴露的问题如分页响应结构、过滤参数行为在 SDK 升级或后端 API 变更时提供回归保障通过真实 API Key 验证认证链路是否通畅。环境准备前置要求根据 README 的 Requirements 章节运行集成测试需要满足Python 3.12SDK 及测试代码依赖较新的 Python 语法与类型特性pytest测试框架本体建议同时安装pytest-timeout下文pytest.ini中会用到有效的 Composio API Key集成测试需要真实调用后端服务。配置 API Key集成测试通过环境变量COMPOSIO_API_KEY获取凭证。在 shell 中执行export COMPOSIO_API_KEYyour_api_key_here这里有一个容易被忽略的细节如果你不设置该环境变量测试并不会默默通过而是会直接失败或整体跳过。具体行为取决于入口方式在 test_mcp.py 中模块顶部会执行API_KEY os.getenv(COMPOSIO_API_KEY)若未获取到则调用pytest.fail(COMPOSIO_API_KEY environment variable not set, pytraceFalse)整个测试模块直接报错在 conftest.py 中若COMPOSIO_API_KEY缺失则调用pytest.skip(..., allow_module_levelTrue)收集阶段即跳过全部测试。也就是说即使你只想跑一条用例也必须先准备好 API Key。三种运行方式README 给出了三种等价的运行方式均可从仓库克隆后直接执行方式一从仓库根目录运行cd /path/to/composio python -m pytest python/composio/integration_test/ -v方式二从 python 目录运行cd /path/to/composio/python pytest composio/integration_test/ -v方式三使用 uv 运行cd /path/to/composio/python uv run pytest composio/integration_test/ -v第三种方式依托本仓库的 pyproject.toml 与 uv.lock 管理依赖能够自动创建包含全部依赖的虚拟环境是当前仓库推荐的方式。-v用于输出详细测试进度便于观察每条用例的执行结果。测试基础设施剖析集成测试目录包含五个文件除 README 外每个都有明确职责文件职责init.py将目录声明为 Python 包conftest.py提供 pytest 全局配置与共享 fixturepytest.ini定义 pytest 收集规则与默认参数test_mcp.pyMCP 功能集成测试主体conftest.py共享 fixture 与资源清理conftest.py 承担了四类工作路径注入将python目录插入sys.path确保from composio import Composio能够解析到本地 SDK 源码会话级 fixturesetup_environmentautouse把 API Key 写入环境变量供整个测试会话使用composio_client创建Composio()客户端实例scopesession意味着整个测试会话共享同一个客户端auth_configs调用composio_client.auth_configs.list()获取可用认证配置并兼容多种响应格式数据 fixturesample_mcp_config_data提供 MCP 配置样例test_user_id提供固定的测试用户 ID资源清理 fixturemcp_server_cleanup会在测试结束后调用composio_client.mcp.delete(server_id)删除测试期间创建的 MCP 服务器避免污染云端资源自定义 marker通过pytest_configure注册timeoutmarker。pytest.ini默认运行参数pytest.ini 中的关键配置如下[pytest] testpaths . python_files test_*.py python_classes Test* python_functions test_* addopts -v --tbshort --timeout120 --timeout-methodthread markers slow: marks tests as slow (deselect with -m not slow) integration: marks tests as integration tests值得注意的默认参数--tbshort失败时只输出简短的 traceback聚焦报错核心--timeout120 --timeout-methodthread每条用例最长执行 2 分钟超时即失败。线程模式保证跨平台可用依赖pytest-timeout插件。这一点对 MCP 测试尤为重要——生成 MCP 实例 URL 涉及真实网络请求耗时不可控slow与integration两个 marker分别标识慢速用例与集成用例可通过-m not slow排除慢速用例。MCP 集成测试深度解析test_mcp.py 是当前集成测试目录中唯一存在的测试模块共 600 行文件头注释说明它同时包含结构化 pytest 测试与非认证工具包的直接执行测试。它围绕composio.mcp这一实验性 API 展开测试套件按职责划分为五个类。测试数据与命名规范测试模块顶部定义了TEST_CONFIG_PREFIX pytest_integration_test并通过generate_unique_name()生成带 UUID 前缀的唯一名称def generate_unique_name(prefix: str pytest) - str: Generate a unique test name using UUID to avoid collisions. unique_id str(uuid.uuid4())[:8] return f{prefix}-{unique_id}同时注释明确指出MCP 服务器名称不得超过 30 个字符且只能包含字母、数字、空格与连字符——这是后端 API 的约束测试中通过pytest-create、pytest-work等短前缀配合 8 位 UUID 来满足。默认的 MCP 配置样例test_mcp_config_datafixture使用两个非认证工具包{ name: generate_unique_name(pytest-data), toolkits: [composio_search, text_to_pdf], allowed_tools: [ COMPOSIO_SEARCH_DUCK_DUCK_GO_SEARCH, TEXT_TO_PDF_CONVERT_TEXT_TO_PDF, ], manually_manage_connections: False, }选用非认证工具包的用意在于composio_search网络搜索与text_to_pdf文本转 PDF不需要 OAuth 授权测试无需预先配置连接账户降低了集成测试的准入门槛。结构与 API 可用性测试TestMCPStructure验证 SDK 的接口契约是否完整test_mcp_namespace_exists断言composio_client顶层存在mcp命名空间test_mcp_methods_available通过参数化断言mcp对象必须暴露create、list、get、update、delete、generate六个方法。这类契约测试的价值在于一旦 SDK 重构导致 API 签名变更测试会第一时间捕获。MCP CRUD 操作测试TestMCPOperations覆盖了 MCP 服务器配置的完整生命周期list 操作test_list_mcp_configs断言返回值为字典且必须包含items、current_page、total_pages三个键——这正是 mcp.py 中MCPListResponse的类型定义。分页参数page_no、limit以及toolkits、name过滤参数也都有对应用例。create 操作多个用例覆盖不同输入形态test_create_mcp_config使用 toolkits allowed_tools 的标准创建方式断言返回对象包含id、name、allowed_tools且commands.claude、commands.cursor、commands.windsurf三个客户端命令均已生成test_create_with_string_toolkits验证纯字符串工具包名如[composio_search, text_to_pdf]的简化用法test_create_with_mixed_toolkits验证字符串与对象混用的形态对象格式为{toolkit: text_to_pdf}可附加auth_config_id字段test_create_with_empty_toolkits空工具包列表应抛出ValidationError——对应 mcp.py 中create()开头的if not toolkits: raise ValidationError(At least one toolkit configuration is required)。get 操作test_get_nonexistent_config断言查询不存在的配置 ID 会抛出ValidationError。响应结构test_create_response_structure验证create返回对象的完整字段包括auth_config_ids []、mcp_url存在、三个客户端命令可用、generate可调用。generate 实例生成测试generate是 MCP 功能的核心——它为特定用户生成一个专属的 MCP 服务器实例含用户专属 URL。相关用例包括test_create_mcp_config中的实例生成验证断言server_instance[type] streamable_httpStreamable HTTP 传输协议、包含id、url、type字段test_generate_method_directly验证composio_client.mcp.generate(user_id, mcp_config_id, {manually_manage_connections: False})的直接调用路径断言返回的id与配置 ID 一致、user_id正确传递、type为streamable_http。从 mcp.py 的源码看generate()的底层调用链是调用self._client.mcp.retrieve(mcp_config_id)获取服务器详情调用self._client.mcp.generate.url(mcp_server_id..., user_ids[user_id], managed_auth_by_composio...)生成用户专属 URL组装MCPServerInstance字典返回其中type: streamable_http是硬编码的传输协议类型。而create()返回对象上的generate方法则是通过_add_generate_method()动态绑定到响应对象上的闭包见 mcp.py它内部转发到mcp_instance.generate(user_id, response.id, ...)——这正是从源码结构看Python 端为对齐 TypeScript 端server.generate(userId)行为所做的设计。错误处理与边界用例TestMCPErrorHandling用参数化方式覆盖了多种无效输入pytest.mark.parametrize( invalid_config_id, [, invalid_id, mcp_000000, nonexistent] ) def test_invalid_config_ids(self, composio_client, invalid_config_id): with pytest.raises(ValidationError): composio_client.mcp.get(invalid_config_id)空字符串、非标准 ID、伪造的mcp_000000前缀 ID、不存在的 ID四种形态均应抛出ValidationErrortest_generate_with_invalid_params空 user_id 无效配置 ID 的组合也应校验失败test_create_with_invalid_toolkit_config空的工具包对象{}会在 API 层校验失败。非认证工具包全流程测试TestMCPNoAuthToolkits通过大量print输出模拟真实使用场景直观展示了一次完整的 MCP 使用流程创建服务器composio_client.mcp.create(server_name, toolkits[composio_search, text_to_pdf], allowed_tools[...], manually_manage_connectionsFalse)为用户生成实例mcp_server.generate(test_user_id)拿到id、type、url、user_id、allowed_tools、auth_configs直接调用 generatecomposio_client.mcp.generate(test_user_id _direct, mcp_server.id, {...})URL 连通性检查对生成的 MCP URL 发起HEAD请求超时 3 秒若返回 405 则改用GET但立即关闭连接——注释说明这是为了避免读取 SSE 流导致无限挂起Dont try to read the stream as SSE endpoints can hang indefinitely断言实例类型为streamable_http、user_id 匹配、allowed_tools 非空、auth_configs 为空非认证工具包不需要认证配置。这套流程就是创建配置 → 按用户生成实例 → 客户端连接的真实写照也对应了 docs/content/docs/sessions-via-mcp.mdx 中通过 MCP 使用会话的方式。真实场景与跨 SDK 兼容测试TestMCPRealWorldScenarios包含三个有代表性的用例test_full_workflow_with_no_auth_toolkits完整走通 create → generate → verify 三步流程test_api_compatibility_with_typescript断言 Python API 与 TypeScript SDK 的方法集一致create/list/get/update/delete/generate 六个方法齐全——从源码看Python 端 MCP 类确实在注释中反复声明匹配 TypeScript ExperimentalMCP 类功能test_full_crud_cycle被pytest.mark.skip跳过的用例原因是MCP update bug with custom_tools argument - TypeError in McpResource.update()。这是一个有价值的遗留记录它说明当前 SDK 的update()方法在传递custom_tools参数时存在已知缺陷社区贡献者在修复前应知晓此限制。直接执行模式test_mcp.py 末尾提供了main()函数与if __name__ __main__:入口支持脱离 pytest 直接运行cd /path/to/composio/python python composio/integration_test/test_mcp.py它会初始化Composio()客户端并执行非认证工具包的完整测试方便快速验证 MCP 功能是否可用。底层实现佐证composio.mcp 服务管理 API集成测试所验证的composio.mcp接口其实现在 python/composio/core/models/mcp.py并由 sdk.py 中的self.mcp MCP(clientself._client)挂载到Composio客户端顶层。其核心数据结构包括ConfigToolkit工具包配置TypedDict支持toolkit必填与auth_config_id可选两个字段MCPServerInstance用户专属服务器实例含id、name、type、url、user_id、allowed_tools、auth_configsMCPListResponse分页列表响应含items、current_page、total_pages。在create()的实现中mcp.py字符串形式的工具包名会被归一化为ConfigToolkit(toolkittoolkit)对象再提取去重后的toolkit_names与auth_config_ids最终调用self._client.mcp.custom.create(...)并把manually_manage_connectionsFalse映射为managed_auth_via_composioTrue即连接由 Composio 托管。list()支持page_no、limit、toolkits、auth_config_ids、name、order_by、order_direction等过滤与排序参数delete()返回{id: ..., deleted: ...}结构。值得注意的是该模块的类注释标注了.. deprecated::提示官方推荐改用会话级 MCP 端点composio.create(user_id, mcpTrue)返回的 session 暴露session.mcp.url/session.mcp.headers独立的composio.mcp服务管理 API 仅为向后兼容保留。集成测试聚焦的正是这个旧 API新项目应优先使用会话方式。测试文件清单与当前仓库的差异说明README 的 Test Files 章节列出了两个测试文件test_mcp.pyMCPModel Context Protocol功能测试test_tool_router.pyToolRouter 实验性功能测试。需要说明的是当前仓库的python/composio/integration_test/目录中只存在test_mcp.pyREADME 中提及的test_tool_router.py尚未出现在该目录中。ToolRouter现官方名称为 Sessions APIcomposio.sessions/composio.create的相关测试可在 python/tests/test_tool_execution.py 等单元测试中找到其核心实现位于 python/composio/core/models/tool_router.py含会话创建、sandbox 规格standard/medium/large/xlarge、工具包与工具启停配置等。如果你计划补充 ToolRouter 集成测试可参照test_mcp.py的组织方式新建test_tool_router.py。实战建议与注意事项结合测试代码与底层实现运行或扩展这套集成测试时有几点值得注意API Key 必须真实有效测试会真实创建、查询、删除云端 MCP 配置建议使用独立的测试环境 Key避免影响生产资源命名约束MCP 服务器名称 ≤30 字符且仅含字母、数字、空格、连字符测试中的generate_unique_name()已内置该约束自行编写用例时同样要遵守超时与 SSE 流pytest.ini中 120 秒超时、线程模式、以及 MCP URL 连通性检查中不读取 SSE 流的做法都是针对真实网络环境与流式端点的经验总结值得沿用已知缺陷test_full_crud_cycle因McpResource.update()的custom_tools参数 TypeError 被跳过使用update()方法前应先确认该问题是否已修复API 演进composio.mcp已被标记为 deprecated新代码建议走composio.create(user_id, mcpTrue)的会话级 MCP 路径集成测试同样可以覆盖这条新链路。小结Composio Python SDK 的集成测试虽然目录不大却完整覆盖了 MCP 服务管理的核心链路环境准备、三种运行方式、pytest 基础设施fixture 与配置、六类 API 方法的契约与行为验证、错误边界、非认证工具包的真实全流程以及跨 SDK 的 API 一致性检查。结合 mcp.py 的源码可以清晰看到测试断言与底层实现的对应关系。对于希望为 Composio SDK 贡献测试、或基于composio.mcp构建 MCP 服务的开发者这套集成测试既是质量保障也是理解 API 行为的绝佳教材。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考