mastra-smoke-test

Mastra 冒烟测试

面向 Mastra 项目的全面冒烟测试。

发布冒烟工作流

采用渐进式披露：在工作流分支出现之前，停留在本文件中；分支确定后，只阅读当前分支对应的参考文件。如需完整地图，可查看简短索引 references/release-smoke.md。

Alpha 发布分支点

在进行 alpha 冒烟测试之前，先确认 alpha 版本号提升 PR 的状态。优先使用标准的 Changesets 发布分支：

gh pr view changeset-release/main \
  --json number,title,state,url,headRefName,baseRefName,isDraft,mergeable,reviewDecision,updatedAt,mergedAt,mergeCommit

预期结构：

title: chore: version packages (alpha)
head: changeset-release/main
base: main

如果该分支查找失败，则搜索未合并和最近已合并的 PR：

gh pr list --state open --search 'version packages alpha in:title' --limit 20
gh pr list --state merged --search 'version packages alpha in:title' --limit 20

然后根据结果分支处理：

• 如果版本号提升 PR 未合并，阅读 references/alpha-versioning-pr.md。
• 如果版本号提升 PR 已合并，阅读 references/alpha-publish.md。
• 如果不存在版本号提升 PR，报告这一情况，并等待计划中的 alpha 版本号提升流程或用户指示。

在自动 alpha 发布工作流完成、且目标包可安装之前，不要创建 alpha 冒烟测试项目。

稳定版发布分支点

如果用户正在运行稳定版/完整发布工作流，阅读 references/stable-release-smoke.md。如果该工作流在部分包已发布后失败，则切换到 references/stable-partial-publish-recovery.md。

范围与定向检查

发布包发布后、运行冒烟测试之前，阅读 references/release-scope-discovery.md，以识别变更的功能。使用默认生成的项目完成基线检查清单，然后针对生成项目未覆盖的变更功能补充定向检查。

当范围发现确定了某个分支时：

• 对于一般变更功能的覆盖，阅读 references/targeted-feature-smoke.md。
• 对于存储/提供方 schema 或迁移变更，阅读 references/storage-provider-migration-smoke.md。

⚠️ 强制测试清单

使用 task_write 跟踪进度。 除非 --test 另有指定，否则运行全部测试。

除非遇到真正的阻碍，否则不要跳过测试。"看起来复杂"或"不确定"都不是有效理由。尝试所有测试，只有在确实无法继续时才停止某项测试。报告你尝试过的内容以及遇到的阻碍。

#	测试	参考文件	何时需要
1	Setup	references/tests/setup.md	始终
2	Agents	references/tests/agents.md	--test agents 或完整运行
3	Tools	references/tests/tools.md	--test tools 或完整运行
4	Workflows	references/tests/workflows.md	--test workflows 或完整运行
5	Traces	references/tests/traces.md	--test traces 或完整运行
6	Scorers	references/tests/scorers.md	--test scorers 或完整运行
7	Memory	references/tests/memory.md	--test memory 或完整运行
8	MCP	references/tests/mcp.md	--test mcp 或完整运行
9	Errors	references/tests/errors.md	--test errors 或完整运行
10	Experiments	references/tests/experiments.md	--test experiments 或本地完整运行
11	Studio Deploy	references/tests/studio.md	--test studio（仅云端）
12	Server Deploy	references/tests/server.md	--test server（仅云端）

完整的 staging 和 production 运行会跳过 Experiments，因为其不适用；companion worker 是本地构建产物。因此，针对 --test experiments 的定向运行需要 --env local。

执行流程

1. 阅读参考文件：对于即将运行的每个测试，先阅读对应的参考文件
2. 执行步骤：按该参考文件中的步骤执行
3. 标记完成：在进入下一个测试之前，先将当前测试标记为完成

部分测试（--test）

如果提供了 --test：

1. 始终执行 Setup（步骤 1）
2. 仅运行指定的测试
3. 跳过其他测试

示例：--test agents,traces → 仅运行步骤 1、2 和 5。

本地 Studio 浏览器冒烟测试

对于本地发布冒烟测试，除非明确请求 --skip-browser 或浏览器访问确实被阻止，否则需要同时执行 API/curl 检查和 Studio 浏览器检查。API 检查用于验证运行时端点是否正常；浏览器检查用于验证 Playground/Studio UI 能否加载、提交表单并显示结果。

打开浏览器之前：

1. 确认开发服务器在预期端口上正常运行：

   curl -s -o /dev/null -w '%{http_code}\n' http://localhost:4111
   lsof -i :4111 || true
   

2. 如果进程已退出，请从生成的项目中重新启动，并等待其就绪：

   cd "$SMOKE_DIR/smoke-project"
   pnpm run dev > "$SMOKE_DIR/logs/dev-server-browser.log" 2>&1 &
   
   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
   

3. 使用浏览器工具导航到 http://localhost:4111。如果 networkidle 超时，但 domcontentloaded 成功且 UI 可用，则继续执行并记录该超时。

推荐的浏览器任务列表：

1. Verify Studio shell loads
2. Smoke test agent chat UI
3. Smoke test tools UI
4. Smoke test workflows UI
5. Smoke test observability, scorers, and MCP pages
6. Report browser smoke results

执行以下页面检查：

区域	路由	需要验证的内容
Studio 外壳	/ 或 /agents	侧边栏/导航可见，Mastra 版本可见，没有崩溃或错误覆盖层
Agents	/agents → Agent 聊天	Agent 列表显示预期的 Agent，聊天输入框可见，发送 What's the weather in Tokyo? 后返回连贯的回复，在预期情况下出现工具调用徽标/结果
Tools	/tools → 工具详情	工具列表显示 get-weather，输入表单正常渲染，提交城市（如 Paris）后显示包含天气字段的 JSON 结果
Workflows	/workflows → 工作流详情	工作流列表显示 weather-workflow，图形/详情正常渲染，以城市（如 Berlin）运行后状态为 success，步骤显示耗时和输出控件
Traces	/observability	最近的 Agent/工作流追踪记录可见，包括浏览器检查过程中触发的运行
Scorers	/scorers	已注册的评分器显示名称和描述，例如 Tool Call Accuracy、Completeness、Translation Quality
MCP	/mcps	页面可加载。对于默认模板，空状态即为通过：No MCP Servers yet

如果浏览器交互的可访问性快照中没有暴露足够的文本，请检查 document.body.innerText 或截图，然后记录可见证据。不要仅依赖 API 输出进行浏览器冒烟测试。

将浏览器测试结果追加到 $SMOKE_DIR/smoke-report.md，并单独列出一个章节，例如：

## Studio Browser Smoke Results

| Area         | Result | Evidence                                                          |
| ------------ | ------ | ----------------------------------------------------------------- |
| Studio shell | PASS   | Browser loaded localhost:4111; sidebar/nav visible; version shown |
| Agents UI    | PASS   | Weather Agent chat returned Tokyo weather and displayed tool call |
| Tools UI     | PASS   | get-weather form returned Paris weather JSON                      |
| Workflows UI | PASS   | weather-workflow Berlin run completed as success                  |
| Traces UI    | PASS   | Recent agent/workflow traces listed                               |
| Scorers UI   | PASS   | Expected scorers listed                                           |
| MCP UI       | PASS   | Expected empty MCP state shown                                    |

请单独说明浏览器冒烟测试是针对本地 Studio 还是云端 Studio/已部署服务器进行的。

---

用法

# Full smoke test
smoke test --env local --existing-project ~/my-app
smoke test --env staging -d ~/projects -n test-app

# Partial testing
smoke test --env local --existing-project ~/my-app --test agents
smoke test --env production --existing-project ~/my-app --test studio,server,traces

# Multi-environment: same project, different targets
smoke test --env staging --existing-project ~/my-app   # Uses .mastra-project-staging.json
smoke test --env production --existing-project ~/my-app # Uses .mastra-project.json

多环境支持

一个项目可以通过使用不同的配置文件面向所有环境：

环境	配置文件	执行结果
本地	无	pnpm dev → localhost:4111
预发布	.mastra-project-staging.json	部署到 staging.mastra.cloud
生产	.mastra-project.json	部署到 mastra.cloud

设置详情请参阅 references/tests/setup.md。

参数

参数	是否必需	默认值	说明
--env	是	-	local、staging、production
--directory	*	~/mastra-smoke-tests	新项目的父目录
--name	*	-	项目名称
--existing-project	*	-	现有项目的路径
--tag	否	latest	版本标签（例如 alpha）
--pm	否	pnpm	包管理器
--llm	否	openai	大模型提供方
--db	否	libsql	存储：libsql、pg、turso
--test	否	（全部）	要运行的特定测试
--browser-agent	否	false	添加浏览器 Agent
--skip-browser	否	false	仅使用 curl（无浏览器界面）
--byok	否	false	测试自带密钥（bring-your-own-key）

* 需要提供 --directory + --name 或 --existing-project 之一

测试选项（--test）

选项	说明	环境
agents	Agent 页面与对话	全部
tools	工具页面与执行	全部
workflows	工作流页面与运行	全部
traces	可观测性/追踪	全部
scorers	评估/打分器页面	全部
memory	对话持久化	全部
mcp	MCP 服务页面	全部
errors	错误处理	全部
experiments	实验 Worker 协议	本地
studio	仅 Studio 部署	云端
server	仅服务端部署	云端

前置条件

所有环境：

• Node.js 与包管理器
• 在环境变量或 .env 中配置大模型 API 密钥

本地（--env local）：

• 已启用浏览器工具（/browser on）

云端（--env staging/production）：

• Mastra 平台账户

快速开始流程

1. Setup      → Read references/tests/setup.md, create/verify project
2. Start      → `pnpm run dev` (local) or deploy (cloud)
3. Test       → For each test, read its reference file and execute
4. Verify     → Check all items in reference file's checklist
5. Report     → Summarize pass/fail for each test

参考资料

文件	用途
references/tests/*.md	每项必需测试的详细步骤
references/release-smoke.md	发布冒烟测试简要参考索引
references/alpha-versioning-pr.md	开放 alpha 版本号 PR 的就绪检查
references/alpha-publish.md	已合并 alpha PR 的发布验证
references/stable-release-smoke.md	稳定版发布及最终稳定版冒烟测试
references/stable-partial-publish-recovery.md	稳定版部分发布失败的恢复
references/release-scope-discovery.md	发布 PR 范围发现与规划
references/targeted-feature-smoke.md	针对变更功能的冒烟测试模式
references/storage-provider-migration-smoke.md	存储/提供方迁移冒烟测试模式
references/local-setup.md	本地开发服务器设置
references/cloud-deploy.md	云部署详情
references/cloud-advanced.md	BYOK、存储测试
references/common-errors.md	故障排查
references/gcp-debugging.md	基础设施调试
references/architecture.md	冒烟测试架构说明
references/environment-variables.md	环境变量设置
scripts/test-server.sh	服务器 API 测试脚本
scripts/discover-release-scope.sh	发布 PR 范围发现
scripts/check-versioning-pr.sh	Alpha 版本号 PR 抽查辅助脚本

平台仪表板

• 生产环境：https://projects.mastra.ai
• 预发布环境：https://projects.staging.mastra.ai

如需进行 Gateway API 测试（记忆、线程、通过网关使用 BYOK），请使用 platform-smoke-test。

结果报告

测试完成后，请提供：

## Smoke Test Results

**Environment**: local/staging/production
**Project**: <name>

| Test   | Status | Notes |
| ------ | ------ | ----- |
| Setup  | ✅/❌  |       |
| Agents | ✅/❌  |       |
| Tools  | ✅/❌  |       |
| ...    |        |       |

**Issues Found**: (list any)
**Warnings**: (list any deploy/runtime warnings)
**Skipped Tests**: (list with reason - e.g., "Server Deploy - not applicable in local environment")