allure-configure-reporting

配置 Allure 报告

概述

当主要目标是在现有项目中启用 Allure 报告时，使用此技能。以最小且符合惯例的改动，让项目能够生成 Allure 结果、生成或提供 Allure 报告、保留或发布 CI 构建产物，或添加所需的证据集成，并提供清晰的验证摘要。

如果目标是在报告配置完成后获取 AI/编码 Agent 工作流指导，请使用 allure-configure-agent-workflow。如果目标是通过 Allure Agent 模式编写、审查、调试或丰富测试，请使用 allure-agent-mode。

操作方式

将检查清单用作参考框架，而不是僵化的脚本。

• 优先参考项目本地证据，而不是通用示例。
• 如果包名、配置 API、CI 语法或已安装 CLI 的行为可能已发生变化，请进一步检查项目本地内容或研究官方文档。
• 将包名、操作版本、CLI 标志、配置键和环境变量视为需要来源佐证的事实。引入新内容前，请从项目本地文件、已安装命令的帮助信息、Allure/测试运行器官方文档，或包 README/源代码中确认。
• 除非用户提出要求、验证所需，或项目已有相关预期，否则不要纳入可选范围。
• 除非已验证生成了 Allure 结果，或明确说明尚未验证的部分，否则不要声称配置已生效。

集成范围

按范围考虑。先从符合用户目标的范围入手；但如果报告尚未正常工作，应优先启用测试框架生成结果，再处理更高层的报告或 CI 工作。

1. 测试框架集成：确保测试执行会生成 Allure 结果。
2. Allure 工具安装：通过项目认可的工具提供报告生成、报告服务或 CLI 封装功能。
3. 构建系统脚本和命令：仅在符合项目现有惯例时添加稳定的本地命令。
4. 其他集成：在相关且有用时，配置官方或项目提供的断言匹配器、HTTP 捕获、截图、跟踪记录、图像差异、日志、标签或附件集成。
5. CI 集成：保留 Allure 结果、汇总分片、生成 Allure 报告或发布报告，同时不掩盖测试失败。

参考检查清单

了解项目

• 确认项目使用的语言、包管理器、构建系统、测试运行器和测试命令。
• 查找现有的 Allure 依赖、插件、报告器、Allure 结果路径、报告脚本、CI 构建产物和文档。
• 确定此请求涉及哪些集成范围。
• 如果存在多个可能的运行器或构建系统，请确定请求所涉测试范围实际使用哪一个。

制定计划

• 如果改动并非简单操作，请在编辑前说明计划处理的范围、配置目标、结果目录、验证命令和成功标志。
• 优先选择符合项目情况的最小增量改动。
• 在可行时保留现有测试封装、报告器、包脚本、构建任务和 CI 行为。
• 如果本地证据不完整或可能已过时，请参考 Allure 和测试运行器的最新官方文档。
• 将配置的 Allure 结果路径命名为 allure-results。许多适配器可以写入任意路径，但此技能建议项目将 allure-results 作为稳定的最终目录名。根据语言、构建系统、运行器或项目的输出惯例选择父目录。稳定的目录名也让 Allure 命令能够轻松发现结果，例如会匹配 allure-results 的 allure results pack，或将其作为位置参数的 allure generate/allure open。

配置

• 除非用户明确要求使用其他入口，否则应先添加或更新框架适配器配置，再添加报告生成。
• 明确指定结果路径，并将其命名为 allure-results（基础名称固定，父目录可变）；优先使用已提交的运行器或构建配置文件，而非环境变量；环境变量主要用于单次运行覆盖、密钥或 CI 接线。
• 不要根据命名模式臆造环境变量，包括看似合理的名称，例如 ALLURE_RESULTS_DIR；应根据本地证据和文档确认变量，否则标记为未知。完整规则见 references/concepts.md 中的“结果目录策略”。
• 除非现有设置有此需要，否则不要替换无关的报告器或 CI 步骤。
• 配置 Allure 时，避免大范围重构、格式变动或新增项目结构。

验证

• 运行可用的、范围最窄且有意义的本地检查。
• 确认 Allure 结果是否已在预期目录中创建或更新。
• 检查足够的输出数据，以确认实际测试标识、状态、耗时、标签、步骤、参数或附件（如有）。
• 如果测试失败但已生成 Allure 文件，应区分产品／测试失败与报告集成成功。
• 如果无法运行验证，应说明阻碍因素和仍未验证的内容。

交接

• 总结已配置的入口、变更文件、验证命令、Allure 结果路径及尚未明确的事项。
• 说明是否已验证 Allure 结果输出、Allure 报告生成、CI 制品处理或证据增强。
• 如果项目包含 docs/allure-agent-mode.md，且报告变更影响本地包装脚本、测试命令、Allure 结果路径、集成、CI 制品、运行配置或证据惯例，则更新该文件。
• 如果项目没有 Agent 工作流指南，只有在报告功能正常，或已明确记录缺失的报告功能后，才建议使用 allure-configure-agent-workflow。

暂停并询问

遇到以下情况时，应在继续前询问：

• 所请求的入口在多个正在使用的测试运行器之间存在歧义
• 安装依赖需要网络访问，或需要进行用户尚未批准的变更
• 直接运行运行器命令会绕过自定义包装脚本、环境设置或服务启动流程
• Allure 已配置，但看起来是被有意禁用或替换的
• 验证需要外部服务、凭据、浏览器、容器、付费服务或长时间运行的测试套件
• CI 发布需要新增仓库权限、令牌、分支策略、页面设置或制品保留决策

参考资料路由

仅加载当前入口所需的参考文件：

• 核心模型与结果／报告术语：references/concepts.md
• 测试框架适配器选择与结果输出：references/test-frameworks.md
• Allure CLI、软件包、插件或独立工具的选择：references/tool-installation.md
• 软件包脚本、构建任务、Make 目标或包装命令：references/build-system-commands.md
• 用于匹配器、HTTP 捕获、截图、跟踪、图像差异、标签、附件及相关辅助功能的官方／项目集成：references/additional-integrations.md
• GitHub Actions、GitLab CI、CircleCI、Jenkins、TeamCity、Azure Pipelines、Buildkite 以及制品／报告发布：references/ci-integrations.md
• 可调整的最佳实践示例：references/examples.md

研究指南

优先使用本地文件。遇到以下情况时，搜索 Allure 官方文档、测试运行器官方文档、软件包 README 文件和现有项目示例：

• 适配器软件包、配置 API 或 CLI 选项可能已更改
• 项目中或已安装的帮助信息中尚未出现拟议的环境变量、配置键、操作输入或软件包名称
• CI 语法或操作／插件版本因提供方而异
• 仓库中已有部分自定义 Allure 配置
• 验证失败，且原因似乎是指南已过时
• 用户询问最新或推荐的配置方式

通过查找发现 Allure 官方文档，不要猜测 URL 路径：

1. 打开 https://allurereport.org/docs/、其 Markdown 索引 https://allurereport.org/docs.md，或网站内置的搜索功能。
2. 根据 Frameworks 导航中显示的名称或精确的文档搜索结果找到集成，然后沿实际链接查看 Getting started、Configuration 和 Reference 页面。
3. 如果页面返回 404，请停止使用该 URL，返回文档索引或搜索结果。不要继续根据框架名称试探可能的路径。
4. 使用文档页面中的信息前，先确认页面标题和正文与所选运行器／集成相符，并能提供所需的软件包名称、报告器／插件／监听器名称、配置键、CLI 标志或环境变量。
5. 如果无法访问官方文档，但本地文件、已安装的帮助信息、软件包元数据或技能参考足以支持最小且经过验证的更改，则继续操作并记录文档查询的限制。如果这些信息不足，请指出缺少的信息并停止，不要猜测。

不要直接粘贴通用代码片段；应根据仓库的软件包管理器、封装脚本、Allure 结果路径和 CI 模式进行调整。

最终报告格式

汇报时，优先采用以下格式：

• 已配置：涉及的界面和已更改的文件。
• 已验证：运行的命令及检查的结果目录。
• 证据：观察到的 Allure 结果或附件。
• Agent 工作流指南：已更新、未更改、已建议或不适用。
• 部分完成或受阻：无法验证的内容及原因。
• 下一步建议：可选的后续事项，例如发布到 CI 或完善 Agent 工作流指南。