Mastra 错误处理冒烟测试完整指南从--test errors到 HTTP 状态码回归基线【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra导读本文基于 Mastra 仓库中 .claude/skills/mastra-smoke-test/references/tests/errors.md 编写系统讲解如何对 Mastra 应用执行错误处理专项冒烟测试--test errors既包括对 Studio UI 的 Agent、工具、导航与网络错误的人工验证也包括对本地/云端 HTTP API 的 curl 级回归断言并给出可直接对照的 HTTP 状态码与响应体基线。读完本文你将掌握一套可复用的错误处理冒烟清单、一组即拷即用的 curl 探测命令以及如何结合 Mastra 服务端源码packages/server理解这些错误码背后的实现机制从而在发布前快速捕获堆栈泄漏错误码映射错误等回归问题。一、为什么需要独立的错误处理冒烟测试Mastra 的核心交互面——Agent 对话、工具执行、工作流运行——都是对外的 HTTP API 与 Studio UI。任何一个环节的错误处理出现回归都会直接表现为三种用户可感知的问题堆栈跟踪泄漏、返回Generic Error式无信息错误、页面直接崩溃。错误冒烟测试的目标正是验证应用优雅地处理错误并向用户展示友好的提示信息。在 .claude/skills/mastra-smoke-test/SKILL.md 的强制测试清单中Errors 是第 9 项必测项可通过--test errors单独触发也可随完整冒烟流程一起执行。它在本地--env local、staging--env staging与生产--env production环境都适用。二、前置准备启动本地服务运行错误测试前先确认 dev server 已在 4111 端口就绪。SKILL.md 推荐的做法是curl -s -o /dev/null -w %{http_code}\n http://localhost:4111 lsof -i :4111 || true若进程已退出从生成的冒烟项目中重启并等待就绪cd $SMOKE_DIR/smoke-project pnpm run dev $SMOKE_DIR/logs/dev-server-browser.log 21 for i in {1..60}; do code$(curl -s -o /dev/null -w %{http_code} http://localhost:4111 || true) [ $code 200 ] break sleep 1 done服务就绪后即可按下面的清单逐项测试。三、UI 层错误处理测试清单1. Agent 错误处理导航到/agents选择一个 Agent然后故意输入三类有问题的内容空消息直接发送空字符串超长消息10000 字符纯特殊字符#$%^*()。记录此时显示的错误信息重点判断显示的是堆栈跟踪还是用户友好的提示。2. 工具错误处理导航到/tools选择一个工具用非法输入提交空必填字段清空所有输入后提交错误数据类型在数字字段中输入文本非法格式不符合字段格式要求的值。记录显示的校验信息内容。注意工具层错误在服务端的行为与 Agent/工作流不同——工具无效输入返回200且响应体带error: true与validationErrors详见第五节基线表。3. 导航错误处理导航到无效路由/nonexistent-page记录出现的页面或行为404 页面、重定向或崩溃导航到无效 Agent 详情页/agents/fake-agent-id记录错误处理行为。4. 网络错误恢复启动一个长时间运行的操作尽量短暂断开网络记录错误处理行为注意是否出现重试或恢复选项。5. 需要记录与汇报的观察项检查项需要记录的内容Agent 错误错误消息文本、是否显示堆栈跟踪工具错误校验消息内容API 错误HTTP 状态码、错误消息内容404 页面页面行为与内容网络错误错误处理行为四、错误消息质量评估标准无论 UI 还是 API良好的错误消息都应具备四个特征解释发生了什么What went wrong建议如何修复How to fix it不暴露内部细节Not expose internal details非开发者也能读懂Readable by non-developers。文档给出了正反例对比反面TypeError: Cannot read property x of undefined正面Unable to process your request. Please try again.常见问题速查问题原因修复方向显示堆栈跟踪错误未被捕获添加错误边界Error Boundary通用 Error缺少错误消息改进错误处理逻辑页面崩溃未处理异常检查错误边界从源码看Mastra Playground 前端确实采用了错误边界机制packages/playground/src/components/layout.tsx 中ErrorBoundary包裹在路由内容外层并通过resetKeys{[pathname]}在路由切换时清除错误状态其实现位于 packages/playground-ui/src/ds/components/ErrorBoundary/ErrorBoundary.tsx使用 React 的componentDidCatch捕获渲染期异常。这为页面崩溃→检查错误边界这条修复建议提供了直接的实现落点。五、API 层错误测试curl 探测命令本地与云端的通用探测以下 curl 命令本地与云端通用云端staging/production需要额外携带Authorization: Bearer api-key请求头api-key 从平台控制台获取并将server-url替换为你的环境地址。# 未知 Agent curl -sw \nHTTP %{http_code}\n -X POST \ http://localhost:4111/api/agents/nonexistent/generate \ -H Content-Type: application/json \ -d {messages:[{role:user,content:hi}]} # 工作流缺少必填输入字段 curl -sw \nHTTP %{http_code}\n -X POST \ http://localhost:4111/api/workflows/workflowId/start-async \ -H Content-Type: application/json \ -d {inputData:{}} # 工具缺少必填输入字段 curl -sw \nHTTP %{http_code}\n -X POST \ http://localhost:4111/api/tools/toolId/execute \ -H Content-Type: application/json \ -d {data:{}} # 未知工具 curl -sw \nHTTP %{http_code}\n -X POST \ http://localhost:4111/api/tools/nonexistent/execute \ -H Content-Type: application/json \ -d {data:{}}云端环境的补充场景针对--env staging或--env production文档还给出了三类典型异常输入# 无效 Agent curl -X POST server-url/api/agents/nonexistent-agent/generate \ -H Authorization: Bearer your-api-key \ -H Content-Type: application/json \ -d {messages:[{role:user,content:test}]} # 无效 JSON非法的请求体 curl -X POST server-url/api/agents/agent-id/generate \ -H Authorization: Bearer your-api-key \ -H Content-Type: application/json \ -d not valid json # 缺少必填字段 curl -X POST server-url/api/agents/agent-id/generate \ -H Authorization: Bearer your-api-key \ -H Content-Type: application/json \ -d {}对以上每个请求需要记录返回的 HTTP 状态码、错误消息内容、响应体中是否出现堆栈跟踪。线程记忆场景的专项测试文档还特别要求测试一个线程作用域thread-scoped的 Observational Memory Agent 且未携带 memory payload的场景curl -sw \nHTTP %{http_code}\n -X POST \ http://localhost:4111/api/agents/agentKey/generate \ -H Content-Type: application/json \ -d {messages:[{role:user,content:test}]}这里threadId的必填要求是有意设计的但由此产生的500被视为潜在的 API/UX 错误映射问题如果提供了memory.resource而未提供memory.thread请求可能提前被 schema 以400拒绝。文档要求将两条路径分别记录。六、HTTP 状态码与响应体基线回归断言核心这是错误冒烟测试最关键的产出以下基线是当前服务端实际返回的、用于断言对照的值任何偏差都应标记为回归。场景HTTP响应体形状未知 Agent id404{ error: Agent with id id not found }或类似未知工具 id404{ error: Tool not found }未知工作流 id404{ error: Workflow not found }工作流缺少必填输入500{ error: Invalid input data: field expected ... }工具缺少必填输入200{ error: true, validationErrors: { ... } }无效 JSON 请求体400{ error: ... }Hono body 解析失败通过标准Pass Criteria每条错误响应都包含可读的error字段工具场景为validationErrors响应体中不泄漏堆栈跟踪HTTP 状态码与上表一致或属于已记录的偏差。需要特别关注的已知问题文档明确要求以批判眼光看待当前基线而非无条件接受工作流 schema 校验失败返回 500客户端输入导致的校验失败通常应映射为 4xx因此将工作流缺少必填输入返回 500分类为潜在的服务端/API 错误映射 bug而非可接受的通过项工具无效输入返回 200响应体虽带error: true但与工作流、Agent 的 HTTP 语义不一致被文档标记为已知不一致known inconsistency。七、源码佐证基线背后的服务端实现上述基线并非凭空假设而是与packages/server中的实际实现一一对应。为理解这些行为可以对照以下源码位置未知 Agent → 404packages/server/src/server/handlers/agents.ts 中throw new HTTPException(404, { message:Agent with id ${agentId} not found})与基线{ error: Agent with id id not found }一致packages/server/src/server/handlers/agent-versions.ts 也有同样的 404 语义未知工具 → 404packages/server/src/server/handlers/tools.ts 与同文件多处L261、L325、L358均为throw new HTTPException(404, { message: Tool not found })未知工作流 → 404packages/server/src/server/handlers/workflows.ts 起、贯穿该文件的十余处分支均抛出HTTPException(404, { message: Workflow not found })统一错误出口packages/server/src/server/handlers/error.ts 的handleError被接入所有路由对MODEL_NOT_ALLOWED模型权限错误映射为422对WORKFLOW_RESUME_ALREADY_CLAIMED并发恢复冲突映射为409对WORKFLOW_SCHEMA_VALIDATION_FAILED映射为400其余则回退到ApiError自带的status || details.status || 500。值得留意的是 error.ts 中的isZodError采用了结构化 duck-typing 判断name ZodError且存在issues数组而非instanceof ZodError这是因为不同依赖可能解析到不同的 zod 实例zod3 与 zod4instanceof会失效并导致校验错误丢失字段路径信息。这种实现细节解释了为什么错误冒烟测试要求记录每条响应的error字段内容——校验错误是否携带字段级信息本身就是可观测的回归信号。八、浏览器自动化操作参考文档同时给出了可在浏览器工具中复现的最小操作序列# Agent 错误测试 Navigate to: /agents Click: Select agent Type: #$%^*() Send: Message Verify: Error is user-friendly # 工具错误测试 Navigate to: /tools Click: Select tool Clear: All inputs Click: Submit Verify: Validation error shown # 404 测试 Navigate to: /this-page-does-not-exist Verify: 404 or redirect, not crash执行--test errors时若 UI 交互无法从无障碍快照中暴露足够文本文档建议检查document.body.innerText或截图留存可见证据参见 SKILL.md 的浏览器冒烟说明而不是只依赖 API 输出。九、结果汇报模板完成全部测试后将结论写入$SMOKE_DIR/smoke-report.md参考 SKILL.md 的汇报结构## Smoke Test Results **Environment**: local/staging/production **Project**: name | Test | Status | Notes | | ------ | ------ | ----- | | Setup | ✅/❌ | | | Errors | ✅/❌ | | **Issues Found**: (list any) **Warnings**: (list any deploy/runtime warnings) **Skipped Tests**: (list with reason)汇报时务必把第五节中已知不一致与疑似 500 映射 bug单独列出并给出具体的请求命令、状态码与响应体便于后续在 packages/server 侧定位修复。十、小结Mastra 的错误处理冒烟测试--test errors是一条覆盖 UI 与 API 双层的回归防线UI 侧重点验证 Agent、工具、导航与网络四类场景的用户体验API 侧则用 curl 固定住 404/400/500 等状态码与响应体基线。结合 errors.md 的通过标准与 packages/server 的源码实现测试者既能快速发现堆栈泄漏页面崩溃这类明显回归也能识别出工具返回 200 error:true这类语义不一致的隐藏问题——这正是发布前错误处理质量保障的最小且高效的实践。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Mastra 错误处理冒烟测试完整指南：从 `--test errors` 到 HTTP 状态码回归基线
Mastra 错误处理冒烟测试完整指南从--test errors到 HTTP 状态码回归基线【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra导读本文基于 Mastra 仓库中 .claude/skills/mastra-smoke-test/references/tests/errors.md 编写系统讲解如何对 Mastra 应用执行错误处理专项冒烟测试--test errors既包括对 Studio UI 的 Agent、工具、导航与网络错误的人工验证也包括对本地/云端 HTTP API 的 curl 级回归断言并给出可直接对照的 HTTP 状态码与响应体基线。读完本文你将掌握一套可复用的错误处理冒烟清单、一组即拷即用的 curl 探测命令以及如何结合 Mastra 服务端源码packages/server理解这些错误码背后的实现机制从而在发布前快速捕获堆栈泄漏错误码映射错误等回归问题。一、为什么需要独立的错误处理冒烟测试Mastra 的核心交互面——Agent 对话、工具执行、工作流运行——都是对外的 HTTP API 与 Studio UI。任何一个环节的错误处理出现回归都会直接表现为三种用户可感知的问题堆栈跟踪泄漏、返回Generic Error式无信息错误、页面直接崩溃。错误冒烟测试的目标正是验证应用优雅地处理错误并向用户展示友好的提示信息。在 .claude/skills/mastra-smoke-test/SKILL.md 的强制测试清单中Errors 是第 9 项必测项可通过--test errors单独触发也可随完整冒烟流程一起执行。它在本地--env local、staging--env staging与生产--env production环境都适用。二、前置准备启动本地服务运行错误测试前先确认 dev server 已在 4111 端口就绪。SKILL.md 推荐的做法是curl -s -o /dev/null -w %{http_code}\n http://localhost:4111 lsof -i :4111 || true若进程已退出从生成的冒烟项目中重启并等待就绪cd $SMOKE_DIR/smoke-project pnpm run dev $SMOKE_DIR/logs/dev-server-browser.log 21 for i in {1..60}; do code$(curl -s -o /dev/null -w %{http_code} http://localhost:4111 || true) [ $code 200 ] break sleep 1 done服务就绪后即可按下面的清单逐项测试。三、UI 层错误处理测试清单1. Agent 错误处理导航到/agents选择一个 Agent然后故意输入三类有问题的内容空消息直接发送空字符串超长消息10000 字符纯特殊字符#$%^*()。记录此时显示的错误信息重点判断显示的是堆栈跟踪还是用户友好的提示。2. 工具错误处理导航到/tools选择一个工具用非法输入提交空必填字段清空所有输入后提交错误数据类型在数字字段中输入文本非法格式不符合字段格式要求的值。记录显示的校验信息内容。注意工具层错误在服务端的行为与 Agent/工作流不同——工具无效输入返回200且响应体带error: true与validationErrors详见第五节基线表。3. 导航错误处理导航到无效路由/nonexistent-page记录出现的页面或行为404 页面、重定向或崩溃导航到无效 Agent 详情页/agents/fake-agent-id记录错误处理行为。4. 网络错误恢复启动一个长时间运行的操作尽量短暂断开网络记录错误处理行为注意是否出现重试或恢复选项。5. 需要记录与汇报的观察项检查项需要记录的内容Agent 错误错误消息文本、是否显示堆栈跟踪工具错误校验消息内容API 错误HTTP 状态码、错误消息内容404 页面页面行为与内容网络错误错误处理行为四、错误消息质量评估标准无论 UI 还是 API良好的错误消息都应具备四个特征解释发生了什么What went wrong建议如何修复How to fix it不暴露内部细节Not expose internal details非开发者也能读懂Readable by non-developers。文档给出了正反例对比反面TypeError: Cannot read property x of undefined正面Unable to process your request. Please try again.常见问题速查问题原因修复方向显示堆栈跟踪错误未被捕获添加错误边界Error Boundary通用 Error缺少错误消息改进错误处理逻辑页面崩溃未处理异常检查错误边界从源码看Mastra Playground 前端确实采用了错误边界机制packages/playground/src/components/layout.tsx 中ErrorBoundary包裹在路由内容外层并通过resetKeys{[pathname]}在路由切换时清除错误状态其实现位于 packages/playground-ui/src/ds/components/ErrorBoundary/ErrorBoundary.tsx使用 React 的componentDidCatch捕获渲染期异常。这为页面崩溃→检查错误边界这条修复建议提供了直接的实现落点。五、API 层错误测试curl 探测命令本地与云端的通用探测以下 curl 命令本地与云端通用云端staging/production需要额外携带Authorization: Bearer api-key请求头api-key 从平台控制台获取并将server-url替换为你的环境地址。# 未知 Agent curl -sw \nHTTP %{http_code}\n -X POST \ http://localhost:4111/api/agents/nonexistent/generate \ -H Content-Type: application/json \ -d {messages:[{role:user,content:hi}]} # 工作流缺少必填输入字段 curl -sw \nHTTP %{http_code}\n -X POST \ http://localhost:4111/api/workflows/workflowId/start-async \ -H Content-Type: application/json \ -d {inputData:{}} # 工具缺少必填输入字段 curl -sw \nHTTP %{http_code}\n -X POST \ http://localhost:4111/api/tools/toolId/execute \ -H Content-Type: application/json \ -d {data:{}} # 未知工具 curl -sw \nHTTP %{http_code}\n -X POST \ http://localhost:4111/api/tools/nonexistent/execute \ -H Content-Type: application/json \ -d {data:{}}云端环境的补充场景针对--env staging或--env production文档还给出了三类典型异常输入# 无效 Agent curl -X POST server-url/api/agents/nonexistent-agent/generate \ -H Authorization: Bearer your-api-key \ -H Content-Type: application/json \ -d {messages:[{role:user,content:test}]} # 无效 JSON非法的请求体 curl -X POST server-url/api/agents/agent-id/generate \ -H Authorization: Bearer your-api-key \ -H Content-Type: application/json \ -d not valid json # 缺少必填字段 curl -X POST server-url/api/agents/agent-id/generate \ -H Authorization: Bearer your-api-key \ -H Content-Type: application/json \ -d {}对以上每个请求需要记录返回的 HTTP 状态码、错误消息内容、响应体中是否出现堆栈跟踪。线程记忆场景的专项测试文档还特别要求测试一个线程作用域thread-scoped的 Observational Memory Agent 且未携带 memory payload的场景curl -sw \nHTTP %{http_code}\n -X POST \ http://localhost:4111/api/agents/agentKey/generate \ -H Content-Type: application/json \ -d {messages:[{role:user,content:test}]}这里threadId的必填要求是有意设计的但由此产生的500被视为潜在的 API/UX 错误映射问题如果提供了memory.resource而未提供memory.thread请求可能提前被 schema 以400拒绝。文档要求将两条路径分别记录。六、HTTP 状态码与响应体基线回归断言核心这是错误冒烟测试最关键的产出以下基线是当前服务端实际返回的、用于断言对照的值任何偏差都应标记为回归。场景HTTP响应体形状未知 Agent id404{ error: Agent with id id not found }或类似未知工具 id404{ error: Tool not found }未知工作流 id404{ error: Workflow not found }工作流缺少必填输入500{ error: Invalid input data: field expected ... }工具缺少必填输入200{ error: true, validationErrors: { ... } }无效 JSON 请求体400{ error: ... }Hono body 解析失败通过标准Pass Criteria每条错误响应都包含可读的error字段工具场景为validationErrors响应体中不泄漏堆栈跟踪HTTP 状态码与上表一致或属于已记录的偏差。需要特别关注的已知问题文档明确要求以批判眼光看待当前基线而非无条件接受工作流 schema 校验失败返回 500客户端输入导致的校验失败通常应映射为 4xx因此将工作流缺少必填输入返回 500分类为潜在的服务端/API 错误映射 bug而非可接受的通过项工具无效输入返回 200响应体虽带error: true但与工作流、Agent 的 HTTP 语义不一致被文档标记为已知不一致known inconsistency。七、源码佐证基线背后的服务端实现上述基线并非凭空假设而是与packages/server中的实际实现一一对应。为理解这些行为可以对照以下源码位置未知 Agent → 404packages/server/src/server/handlers/agents.ts 中throw new HTTPException(404, { message:Agent with id ${agentId} not found})与基线{ error: Agent with id id not found }一致packages/server/src/server/handlers/agent-versions.ts 也有同样的 404 语义未知工具 → 404packages/server/src/server/handlers/tools.ts 与同文件多处L261、L325、L358均为throw new HTTPException(404, { message: Tool not found })未知工作流 → 404packages/server/src/server/handlers/workflows.ts 起、贯穿该文件的十余处分支均抛出HTTPException(404, { message: Workflow not found })统一错误出口packages/server/src/server/handlers/error.ts 的handleError被接入所有路由对MODEL_NOT_ALLOWED模型权限错误映射为422对WORKFLOW_RESUME_ALREADY_CLAIMED并发恢复冲突映射为409对WORKFLOW_SCHEMA_VALIDATION_FAILED映射为400其余则回退到ApiError自带的status || details.status || 500。值得留意的是 error.ts 中的isZodError采用了结构化 duck-typing 判断name ZodError且存在issues数组而非instanceof ZodError这是因为不同依赖可能解析到不同的 zod 实例zod3 与 zod4instanceof会失效并导致校验错误丢失字段路径信息。这种实现细节解释了为什么错误冒烟测试要求记录每条响应的error字段内容——校验错误是否携带字段级信息本身就是可观测的回归信号。八、浏览器自动化操作参考文档同时给出了可在浏览器工具中复现的最小操作序列# Agent 错误测试 Navigate to: /agents Click: Select agent Type: #$%^*() Send: Message Verify: Error is user-friendly # 工具错误测试 Navigate to: /tools Click: Select tool Clear: All inputs Click: Submit Verify: Validation error shown # 404 测试 Navigate to: /this-page-does-not-exist Verify: 404 or redirect, not crash执行--test errors时若 UI 交互无法从无障碍快照中暴露足够文本文档建议检查document.body.innerText或截图留存可见证据参见 SKILL.md 的浏览器冒烟说明而不是只依赖 API 输出。九、结果汇报模板完成全部测试后将结论写入$SMOKE_DIR/smoke-report.md参考 SKILL.md 的汇报结构## Smoke Test Results **Environment**: local/staging/production **Project**: name | Test | Status | Notes | | ------ | ------ | ----- | | Setup | ✅/❌ | | | Errors | ✅/❌ | | **Issues Found**: (list any) **Warnings**: (list any deploy/runtime warnings) **Skipped Tests**: (list with reason)汇报时务必把第五节中已知不一致与疑似 500 映射 bug单独列出并给出具体的请求命令、状态码与响应体便于后续在 packages/server 侧定位修复。十、小结Mastra 的错误处理冒烟测试--test errors是一条覆盖 UI 与 API 双层的回归防线UI 侧重点验证 Agent、工具、导航与网络四类场景的用户体验API 侧则用 curl 固定住 404/400/500 等状态码与响应体基线。结合 errors.md 的通过标准与 packages/server 的源码实现测试者既能快速发现堆栈泄漏页面崩溃这类明显回归也能识别出工具返回 200 error:true这类语义不一致的隐藏问题——这正是发布前错误处理质量保障的最小且高效的实践。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考