smoke-test

Smoke Test Skill

使用 create-mastra@<tag> 创建一个新的 Mastra 项目，并在 Chrome 中对 Mastra Studio 进行冒烟测试。

此 Skill 适用于带有 Chrome MCP 服务的 Claude Code。 如果使用内置浏览器工具的 MastraCode，请改用 mastracode-smoke-test。

用法

/smoke-test --directory <path> --name <project-name> --tag <version> [--pm <package-manager>] [--llm <provider>]
/smoke-test -d <path> -n <project-name> -t <version> [-p <package-manager>] [-l <provider>]

参数

参数	简写	描述	必填	默认值
--directory	-d	将创建项目的父目录	是	-
--name	-n	项目名称（将作为子目录创建）	是	-
--tag	-t	create-mastra 的版本标签（例如 latest、alpha、0.10.6）	是	-
--pm	-p	包管理器：npm、yarn、pnpm 或 bun	否	npm
--llm	-l	大模型提供商：openai、anthropic、groq、google、cerebras、mistral	否	openai

示例

# Minimal (required params only)
/smoke-test -d ~/projects -n my-test-app -t latest

# Full specification
/smoke-test --directory ~/projects --name my-test-app --tag alpha --pm pnpm --llm anthropic

# Using short flags
/smoke-test -d ./projects -n smoke-test-app -t 0.10.6 -p bun -l openai

第 0 步：参数校验（必须首先运行）

关键：在继续之前，解析 ARGUMENTS 并进行校验：

1. 解析参数：从上方提供的 ARGUMENTS 字符串中解析参数
2. 检查必填参数：
   • --directory 或 -d：必填，缺失则失败
   • --name 或 -n：必填，缺失则失败
   • --tag 或 -t：必填，缺失则失败
3. 为可选参数应用默认值：
   • --pm 或 -p：未提供时默认为 npm
   • --llm 或 -l：未提供时默认为 openai
4. 校验取值：
   • pm 必须是以下之一：npm、yarn、pnpm、bun
   • llm 必须是以下之一：openai、anthropic、groq、google、cerebras、mistral
   • directory 必须存在（或将被创建）
   • name 应为有效的目录名（不含空格和特殊字符）

如果校验失败：停止并显示用法帮助，同时指出缺失或无效的参数。

如果传入 -h 或 --help：显示此用法信息并停止。

前置条件

此 Skill 需要 Chrome MCP 服务（Claude-in-Chrome）进行浏览器自动化。请确保其已配置并正在运行。

Chrome MCP 服务提供的工具包括 tabs_create_mcp、tabs_context_mcp、navigate_mcp、click_mcp、type_mcp 和 screenshot_mcp。

执行步骤

第 1 步：创建 Mastra 项目

使用明确的参数运行 create-mastra 命令，以避免交互式提示：

# For npm
npx create-mastra@<tag> <project-name> --no-git --llm <llmProvider> --timeout 120000

# For yarn
yarn dlx create-mastra@<tag> <project-name> --no-git --llm <llmProvider> --timeout 120000

# For pnpm
pnpm create mastra@<tag> <project-name> --no-git --llm <llmProvider> --timeout 120000

# For bun
bunx create-mastra@<tag> <project-name> --no-git --llm <llmProvider> --timeout 120000

-c/--components 和 -e/--example 已被移除，不得使用。-l/--llm 仍受支持，即上方所用的参数。默认使用托管模板；如需故意创建空项目，使用 --empty；如需特定模板，使用 --template <template>。如果某个参数被拒绝，请查看初始化程序的帮助信息，而不要重试旧版命令：npm create mastra@<tag> -- --help、npx create-mastra@<tag> --help、pnpm create mastra@<tag> --help、yarn dlx create-mastra@<tag> --help 或 bunx create-mastra@<tag> --help。

等待安装完成。根据网络速度，这可能需要 1 到 2 分钟。

第 2 步：验证项目结构

创建完成后，验证项目包含：

• 含有 mastra 依赖的 package.json
• 导出 Mastra 实例的 src/mastra/index.ts
• .env 文件（可能需要手动创建）

第 2.5 步：添加用于浏览器测试的 Browser Agent

要测试浏览器功能，请添加一个启用浏览器的 Agent：

1. 安装浏览器相关包：

<pm> add @mastra/stagehand
# or for deterministic browser automation:
<pm> add @mastra/agent-browser

2. 在 src/mastra/agents/ 中创建 browser-agent.ts：

import { Agent } from '@mastra/core/agent';
import { Memory } from '@mastra/memory';
import { StagehandBrowser } from '@mastra/stagehand';

export const browserAgent = new Agent({
  id: 'browser-agent',
  name: 'Browser Agent',
  instructions: `You are a helpful assistant that can browse the web to find information.`,
  model: '<provider>/<model>', // e.g., 'openai/gpt-4o'
  memory: new Memory(),
  browser: new StagehandBrowser({
    headless: false,
  }),
});

3. 更新 index.ts 以注册 Browser Agent：

import { browserAgent } from './agents/browser-agent';

// In Mastra config:
agents: { weatherAgent, browserAgent },

步骤 3：配置环境变量

根据所选的大模型服务商，检查所需的 API 密钥：

服务商	所需环境变量
openai	OPENAI_API_KEY
anthropic	ANTHROPIC_API_KEY
groq	GROQ_API_KEY
google	GOOGLE_GENERATIVE_AI_API_KEY
cerebras	CEREBRAS_API_KEY
mistral	MISTRAL_API_KEY

按以下顺序检查：

1. 优先检查全局环境变量：运行 echo $<ENV_VAR_NAME>，查看该密钥是否已在全局设置

   • 如果已全局设置，项目会自动继承，无需 .env 文件
   • 跳到步骤 4

2. 检查项目的 .env 文件：如果全局未设置，检查项目中是否存在 .env 文件，并且其中是否包含该密钥

3. 仅在必要时询问用户：如果全局环境和 .env 中都没有该密钥：

   • 向用户询问 API 密钥
   • 使用提供的密钥创建 .env 文件

只检查与所选服务商对应的那一个密钥，不要检查所有服务商的密钥。

步骤 4：启动开发服务器

进入项目目录并启动开发服务器：

cd <directory>/<project-name>
<packageManager> run dev

服务器通常会在 http://localhost:4111 启动。在继续之前，请等待服务器就绪。

步骤 5：Studio 冒烟测试

使用 Chrome 浏览器自动化工具测试 Mastra Studio。

5.1 初始设置

1. 使用 tabs_context_mcp 获取浏览器上下文
2. 使用 tabs_create_mcp 创建新标签页
3. 导航到 http://localhost:4111

5.2 测试清单

使用 Chrome 自动化工具执行以下冒烟测试:

导航与基础加载

• Studio 加载成功(页面包含 "Mastra Studio" 或显示 agents 列表)
• 对首页截图

Agents 页面 (/agents)

• 导航到 agents 页面
• 验证至少列出一个 agent(来自 --default 的示例 agent)
• 截图

Agent 详情 (/agents/<agentId>/chat)

• 点击一个 agent 查看详情
• 验证 agent 概览面板已加载
• 验证模型设置面板可见
• 截图

Agent 对话

• 向 agent 发送一条测试消息(例如 "What's the weather in Tokyo?")
• 等待响应
• 验证响应出现在对话中
• 对对话截图

Browser Agent (/agents/browser-agent/chat) - 如果添加了 browser agent

• 导航到 browser-agent
• 发送消息:"Go to example.com and tell me what you see"
• 验证 agent 启动浏览器并提取内容
• 验证响应包含页面内容
• 截图

工具页面 (/tools)

• 导航到 tools 页面
• 验证工具列表已加载(应显示 get-weather 工具)
• 截图

工具执行 (/tools/get-weather)

• 点击 get-weather 工具打开详情页
• 找到城市输入框并输入测试城市(例如 "Tokyo")
• 点击 Submit 按钮
• 等待执行完成
• 验证出现包含天气数据(温度、天气状况等)的 JSON 输出
• 截图

工作流页面 (/workflows)

• 导航到 workflows 页面
• 验证工作流列表已加载(应显示 weather-workflow)
• 截图

工作流执行 (/workflows/weather-workflow)

• 点击 weather-workflow 打开详情页
• 验证可视化图表已显示(展示工作流步骤)
• 找到城市输入框并输入测试城市(例如 "London")
• 点击 Run 按钮
• 等待执行完成
• 验证各步骤显示成功(绿色对勾)
• 点击查看 JSON 输出弹窗
• 验证出现包含耗时的执行详情
• 截图

设置页面 (/settings)

• 导航到 settings 页面
• 验证设置页面已加载
• 截图

可观测性页面 (/observability)

• 导航到 observability 页面
• 验证 traces 列表显示最近的活动(来自之前的测试)
• 点击一条 trace 查看详情
• 验证时间线视图显示步骤与耗时
• 截图

Scorers 页面 (/evaluation?tab=scorers)

• 导航到 /evaluation?tab=scorers(不是 /scorers,该路由不存在)
• 验证 scorers 列表已加载(显示 3 个示例 scorer)
• 截图

其他页面(仅验证加载)

• Templates 页面 (/templates) - 入门模板库
• Request Context 页面 (/request-context) - JSON 编辑器
• Processors 页面 (/processors) - 空状态可接受
• MCP Servers 页面 (/mcps) - 空状态可接受

5.3 报告结果

完成所有测试后,提供一份摘要:

• 通过/失败的测试总数
• 遇到的任何错误
• 已捕获的截图
• 针对发现问题的建议

快速参考

步骤	操作
创建项目	在 <directory> 中使用步骤 1 中对应包管理器的命令
安装依赖	创建过程中自动完成
设置环境变量	先检查全局环境变量,再检查 .env,仅在需要时询问用户
启动服务	cd <directory>/<name> && <pm> run dev
Studio 地址	http://localhost:4111

故障排查

服务无法启动

• 确认 .env 中已配置所需的 API 密钥
• 检查端口 4111 是否可用
• 尝试运行 <pm> install 重新安装依赖

浏览器无法连接

• 等待几秒，让服务完全启动
• 检查终端中是否出现服务就绪的提示信息
• 确认没有防火墙阻止 localhost

Agent 对话失败

• 确认 API 密钥有效
• 检查服务日志中的错误信息
• 确保可以访问大模型提供商的 API

浏览器 Agent 失败

• 确认已安装并可以访问本地 Chromium 内核浏览器，例如 Google Chrome
• 检查是否有其他浏览器实例占用导致阻塞

Studio 路由

功能	路由
Agents	/agents
Workflows	/workflows
Tools	/tools
Evaluation	/evaluation
Scorers	/evaluation?tab=scorers
Observability	/observability/traces
Logs	/observability/logs
MCP Servers	/mcps
Processors	/processors
Templates	/templates
Request Context	/request-context
Settings	/settings

注意事项

• 托管的默认模板会生成一个 Agent、若干工具和存储，这使冒烟测试更有意义；仅当需要不同的起点时，才使用 --empty 或 --template <template>
• 如果用户未指定大模型提供商，默认使用 OpenAI，因为它最为常见
• 在每个主要步骤截图，以便记录文档和调试
• 测试期间让开发服务器在后台保持运行
• 传入明确的参数（--llm、--no-git、--timeout），使创建过程保持非交互式；请使用步骤 1 中记录的、与包管理器对应的初始化命令帮助信息，而不要假设使用旧版参数
• 浏览器 Agent 测试用于验证新的浏览器自动化功能
• 运行 Agent 或工作流后，Observability 追踪记录会自动出现