test-slack-app

测试 Slack 应用

帮助开发者确认自己已构建的 Slack 应用确实能正常工作。这是构建循环的最后一步，前面由 slack:create-slack-app 技能搭建应用，再由 slack:slack-cli 技能运行应用。

方法简单且安全：

1. 在开发者沙盒或 Free Team 中运行应用： 优先使用沙盒，也可以使用开发者专门创建的 Free Team。绝不要使用有真实同事参与的工作区。
2. 阅读应用的源代码，了解它实际监听哪些事件。
3. 向开发者提供在 Slack 中执行的具体步骤，然后协助他们确认应用是否有响应。

这是有引导的手动检查，并非自动化测试套件：由你来引导设置，并告诉开发者要输入或点击什么，再由他们确认看到的内容。此方法最适合由 Slack CLI 管理的应用；第 2 步也提供了一个尽力支持普通 Bolt 应用的流程。

---

第 1 步：设置安全的测试环境

1a. 检测 Slack CLI

使用 slack:slack-cli 技能（第 1 步：检测 Slack CLI）检查是否已安装官方 Slack CLI，并确定其命令名称。指纹检查、别名回退和安装说明都在该技能中；此处不要重复。下文统一使用 SLACK_CMD 指代已确定的命令。如果尚未安装 CLI，请按照该技能中的相同步骤指导开发者安装，因为运行应用需要用到它。

1b. 确保有安全的测试工作区

测试应在无人工作的工作区中进行：优先使用开发者沙盒，也可以使用开发者专门创建的 Free Team。绝不要使用有真实同事参与的工作区。

• 依据实时文档说明，而不是引用此处的内容。 使用 slack:slack-docs 技能获取并总结 https://docs.slack.dev/tools/developer-sandboxes.md，确保建议始终反映当前文档，而不是使用可能过时的副本。告诉开发者，Slack 建议使用沙盒来构建和测试应用。
• 查找当前目标。 运行 SLACK_CMD auth list，查看已认证的工作区及其团队 ID；然后在项目目录中运行 SLACK_CMD app list，查看已安装的应用及其 ID。
• 确认目标安全。 CLI 无法区分沙盒、Free Team 和有真实用户的工作区，因此要询问开发者当前连接的是哪一个。沙盒或开发者专门为此创建的 Free Team 都可以。有同事参与的工作区则不行：请停止操作，并让他们改用另外两种环境之一。
• 如果目前还没有安全的目标，请使用 slack:create-slack-app 技能（第 3 步：选择应用的安装位置）来设置；该技能负责说明按优先级排列的目标、sandbox list / sandbox create 流程，以及 Developer Program 的链接。两种方式都要在浏览器中完成，因此请让开发者在工作区创建完成并登录后再返回此处。

1c. 快速健康检查

先用 CLI 自带的验证功能排查明显的设置问题，再进行耗时更长的手动检查：

• SLACK_CMD doctor：检查 CLI、语言运行时和身份验证。
• SLACK_CMD manifest validate：如果应用有 manifest，请在项目目录中运行，以确认应用配置格式正确。

继续之前，先告知开发者这两项检查发现的任何问题。

---

步骤 2：运行应用

无论使用下面哪种路径，首先都要将应用的日志级别调高到 debug，以便测试时获得最完整的上下文。优先选择不会改动开发者代码的方式：查看日志记录器的设置，确认它是否读取日志级别环境变量（有些模板会配置 SLACK_LOG_LEVEL 或 LOG_LEVEL 之类的变量）。如果有，就设置该变量，而不是修改源代码。对于由 CLI 管理的应用，SLACK_CMD env set <LOG_LEVEL_VAR> debug 会将其保存到项目的 .env 文件中，供 slack run 读取；对于普通 Bolt 应用，则在应用已读取的环境变量或 .env 文件中设置。只有当日志记录器不读取此类变量时，才应修改源代码：找到设置日志级别的位置，并在本次运行时将其调为 debug。

由 CLI 管理的应用（推荐）

按照 slack:slack-cli 技能中的 步骤 6：在本地运行应用（slack run），在后台启动本地开发服务器。这也会将应用安装到目标工作区，这对于全新的沙盒或尚未安装任何应用的 Free Team 很重要。应用运行后，文件更改会自动重新加载。

不使用 CLI 的普通 Bolt 应用（尽力而为）

如果这是通过 node 或 python 启动、而非通过 Slack CLI 启动的普通 Bolt 应用，这项技能仍可提供帮助，但此运行方式只能尽力而为，并非主要流程：

• 将应用指向测试工作区：在应用读取的环境变量或 .env 文件中，设置来自该工作区应用设置的机器人令牌和应用级令牌。
• 优先使用 socket 模式，这样应用就不需要公开 URL。只有当应用的代码支持 socket 模式，且应用级令牌具有 connections:write 权限时，这种方式才有效；向为 HTTP 搭建的应用添加令牌并不能让它接收事件。
• 使用应用自身的命令启动应用（例如 npm start 或 python app.py），并查看其日志。

请明确说明，这种方式只能尽力而为，而通过 CLI 管理的应用体验最顺畅。

---

步骤 3：在 Slack 中试用并确认运行正常

这是这项技能的核心。不要只给开发者一份通用检查清单，而要让每个步骤都基于这个应用实际注册的内容。

3a. 阅读源代码，了解应用会监听什么

阅读应用的监听器代码，并列出它注册的交互。根据所用框架，这些交互可能包括：

• 斜杠命令： 已注册的命令名称，例如 /ship。
• 快捷方式： 带有回调 ID 的全局快捷方式或消息快捷方式。
• 事件： 已订阅的事件，例如 app_mention、message 或 reaction_added。
• 操作： 带有操作 ID 的交互式组件（按钮、选择菜单）。
• 视图提交： 模态框提交处理器（view_submission）。
• App Home： app_home_opened 处理器或已发布的 Home 标签页。
• 助手 / Agent： 助手或 assistant_thread_started 处理器，这在 Agent 模板中很常见。

请写出找到的具体标识符（实际命令名和回调名称），不要使用占位符。

3b. 将每项都转化为“执行此操作，预期得到该结果”的步骤

对于每项已注册的交互，都要为开发者提供一个具体步骤，并说明正常运行的应用应如何响应。有些地方不太直观，请明确说明：

• 斜杠命令 → 在测试工作区的频道或私信中输入命令（例如 /ship）→ 预期看到处理程序发送的响应。
• 全局快捷方式 → 打开快捷方式菜单（根据客户端不同，点击消息编辑器中的闪电图标或 + 按钮），然后选择该快捷方式 → 预期看到它打开的模态框或消息。
• 消息快捷方式 → 将鼠标悬停在一条消息上，打开 更多操作（⋯ 菜单），然后选择该快捷方式 → 预期看到它的响应。
• 事件，例如 app_mention → 在应用所属的频道中 @ 提及该应用 → 预期看到它的回复。
• 按钮或选择菜单 → 点击应用发布的消息或模态框中的组件 → 预期看到操作处理程序执行的内容。
• 模态框提交（view_submission）→ 提交模态框 → 预期看到确认信息或副作用。
• 应用主页 → 点击左侧边栏中的应用以打开其 主页 标签页 → 预期看到已发布的视图。

3c. 确认并汇报

开发者操作时，帮助他们确认功能是否正常：

• 如果应用通过 slack run 运行，请查看其日志（询问“向我展示 slack run 的输出”），以确认事件已到达并查看任何错误。
• 如果响应看起来不正确（消息格式错误、Block Kit 视图异常或 API 错误），请使用 slack:block-kit 和 slack:slack-api 技能检查载荷或方法。

最后简要总结：你和开发者确认了哪些功能正常，以及他们还需要自行检查哪些内容。请记住，这是人工检查：你是在帮助开发者观察应用的响应，而不是执行自动化的通过或失败判定。

---

注意事项

• SLACK_CMD 是占位符：请始终替换为步骤 1a 中解析出的实际命令名称。
• 范围：此技能用于测试已存在的应用。若要创建或搭建应用，请使用 slack:create-slack-app 技能；若需了解原始 CLI 操作，请使用 slack:slack-cli 技能；若需了解消息或 Block Kit 格式，请使用 slack:slack-messaging 和 slack:block-kit 技能。
• 暂不涉及：Bolt 自动化测试框架、以编程方式模拟用户交互，以及通过浏览器操作 Slack 界面。目前由开发者执行交互；此技能会确保他们清楚具体要做什么以及预期看到什么。