★ FEATURED ARTICLE 做接口自动化测试或者 UI 自动化测试跑完用例只是第一步把执行结果变成一份团队能看懂、能追溯、能拿去跟研发对问题的测试报告才是真正让人头疼的部分。Allure2 是我用过一段时间后觉得最顺手的报告方案它不绑定具体语言Java、Python、JavaScript 技术栈都能接入而且生成出来的报告结构清晰、信息密度高不是那种干巴巴的表格堆砌。这篇内容主要梳理 Allure2 从用例执行到报告生成的完整流程重点放在 pytest 技术栈下的接入方式、每一步命令背后的数据流向、基础报告里哪些信息真正有参考价值以及我实际操作中踩过的一些坑。适合刚接触自动化测试报告、想把测试结果做得更规范的同学参考。1. 环境准备Allure2 与 pytest 的基础集成1.1 先搞清楚 Allure2 在技术栈里的位置很多同学第一次接触 Allure2 时会有一个认知上的偏差以为它是 pytest 的一个插件pip install 之后就能直接生成漂亮报告。实际上 Allure2 由两部分组成一部分是命令行工具负责把测试结果数据处理成 HTML 报告另一部分是测试框架侧的适配器负责在用例执行过程中把结果按照约定格式写入本地文件。你对 pytest 配置的插件只是适配器真正渲染报告的是命令行工具本身。这个拆分设计决定了它的跨语言能力。只要测试框架能把执行结果写到符合 Allure 数据格式的目录里命令行工具就能统一生成报告跟用例是用 Python 写的还是 Java 写的没有关系。理解了这一点后面配置过程中的很多困惑就迎刃而解了。1.2 安装命令行工具与适配器命令行工具本身依赖 Java 运行时环境因为 Allure2 是用 Java 开发的。所以第一步不是下载工具而是确认电脑上有可用的 Java 环境版本 8 以上基本都够用。没有 Java 环境的话后续执行任何 allure 命令都会直接报错而且报错信息往往比较隐晦新手很容易被带到“是不是工具没装好”的排查方向上去。安装命令行工具的方式跟在哪个系统上关系比较大macOS 上可以通过系统包管理器直接装一条命令就能完成。Linux 环境一般也是用包管理器或者直接下载压缩包解压把可执行文件路径加到环境变量里。Windows 环境推荐下载 zip 包解压后手动配置 PATH也可以在包管理器里装。装完之后在终端执行allure --version能看到版本号就说明命令已经可用。这里多说一句版本号能正常输出只代表命令存在的不代表可以生成报告还得确认 Java 环境没有问题否则生成阶段会卡住。适配器安装就简单了pytest 技术栈下执行pip install pytest pip install allure-pytestallure-pytest这个名字很关键。网上有人写pytest-allure早期版本确实有过这种命名但现在的官方适配器包名是allure-pytest。安装错包名的话pytest 根本识别不到 Allure 的 hook执行完用例也不会产生结果数据。1.3 基础配置与开启结果收集安装好适配器之后需要在 pytest 的配置里告诉它把结果写到哪个目录。最省事的方案是在项目根目录的 pytest.ini 里加一段[pytest] addopts --alluredir./allure-results --clean-alluredir--alluredir指定结果数据目录--clean-alluredir表示每次执行用例之前清空旧数据。这两个参数放在配置文件里之后日常执行 pytest 的时候不需要再手动加适配器会主动在测试结束后把数据写入指定文件夹。为什么我强调要加--clean-alluredir因为 Allure 的结果文件是按照用例动态生成的如果你不清理旧文件第二次执行后目录里会混着上一次的 json 数据生成报告时统计结果会被污染出现“昨天删除的用例今天还在报告里显示”这种诡异现象。所以要么在配置里加这个参数要么在执行命令时手动加上总之不能让它裸奔累积。另外还有一种常见场景是动态指定目录比如并发执行、多进程跑测试时希望每个进程的结果分开存再统一合并。这种做法后面讲多进程的时候再展开基础阶段直接在配置里写死目录就好。2. 执行流程拆解测试结果如何一步步变成报告2.1 从 pytest 到 Allure2 的三段式命令链Allure2 的完整执行流程不是一条命令搞定的而是分三个阶段执行用例、生成报告、查看报告。这三个阶段各司其职理解了这条命令链你在 CI 环境里才不会被各种“没有报告”的问题绕晕。第一步是跑用例产生原始结果数据pytest --alluredir./allure-results --clean-alluredir执行过程中适配器会监听 pytest 的各个生命周期事件比如用例开始、断言失败、用例结束然后把这些事件转成对应的 json 数据写入目录。这里需要特别注意的是--alluredir只负责“写数据”它不会帮你生成任何 HTML 页面。你跑完用例之后去打开 allure-results 目录看到的是一堆 json 文件和附件而不是报告页面。第二步是把原始数据生成成静态 HTML 报告allure generate ./allure-results -o ./allure-report --clean这条命令做的事情是把 allure-results 里的数据经过解析、聚合、渲染输出到allure-report目录。-o指定报告输出路径--clean表示清空输出目录里的旧报告避免新旧文件混在一起。如果你之前生成的报告已经传到了某个共享目录这一步会把它替换成最新版本。第三步是查看报告。最直接的两种方式# 方式一基于已有报告目录打开 allure open ./allure-report # 方式二临时启动服务并自动打开 allure serve ./allure-resultsallure serve会临时起一个本地服务自动用默认浏览器打开报告页面但它不会生成静态报告目录适合本地调试用例结果时快速看一眼。allure open则适合你已经有生成好的报告目录想重新打开浏览器查看的场景。这三条命令背后的逻辑用生活里的例子类比就是pytest 是厨师负责把菜做出来盛到盘子里allure-resultsgenerate 是摆盘师傅把菜按一定造型摆好allure-reportserve 或者 open 就是上菜的传菜员。厨师不负责摆盘摆盘师傅不上灶台分工非常明确。2.2 allure-results 目录里到底存了什么跑完 pytest 之后打开 allure-results 目录最常见的是大量 json 文件文件名带着一串 uuid另一个部分是以.txt、.png结尾的附件。很多人看到这种目录会慌觉得是不是报告生成失败了其实这些文件恰恰是 Allure 报告的数据源头。每一个 json 文件都对应一条测试用例在某个执行阶段的数据快照。Allure 会把一条用例的完整生命周期拆成多个事件写入多个 json 文件比如用例开始一条、用例结束一条中途每调用一次测试步骤也会产生记录。这也是为什么明明只有 20 条用例目录里却躺着 100 多个 json 文件的原因属于正常现象不用管数量。这些数据的组织方式本质上是一个事件流generate 命令读到的就是这个事件流。如果你不小心删掉了其中某个 json 文件最直观的后果是报告里某条用例的“表现”会变得不完整比如只有名称没有执行结果或者附件展示不出来。所以本地调试时尽量不要手动去编辑或者删减 allure-results 目录里的文件让工具自己管理才是正确姿势。还有一个容易忽略的文件叫categories.json它由用户自己定义用来给失败用例做归类。比如你想把所有超时问题归为一类把断言失败归为另一类就可以在这个 json 文件里写好规则。默认情况下这个文件不存在Allure 会按内置规则把失败原因分成“产品缺陷”和“测试缺陷”两大类。这个后面会单独说但至少你要知道你看到的报告分类不是凭空生成的规则就在结果目录里。2.3 serve 与 generate 的取舍不少同学在本地调试时习惯用allure serve ./allure-results看完顺手关掉。这个流程本身没问题但如果项目已经接入 CI或者报告需要长期保存共享就不能依赖 serve 了。allure serve的本质是“临时起本地服务动态读取结果数据渲染页面”它不落盘、不保留静态文件服务停止之后页面就访问不到了。而allure generate生成的是纯静态的 HTML 资源目录你完全可以把整个 allure-report 目录打包归档放到共享盘、对象存储或者 CI 平台的工作产物里随时回看历史记录。我做项目时一般这样分工本地写用例阶段多用 serve因为改代码频率高快速看一眼结果就行涉及交付、回归、发布验证的时候一定用 generate生成带时间戳或者固定名称的报告目录作为可追溯的交付物。CI 平台里更是只用 generate因为流水线是一次性的服务进程结束之后 serve 的临时数据就没了静态报告却可以通过平台的“归档产物”功能留存下来。3. 基础测试报告解读概览、套件与缺陷信息怎么看3.1 Overview 主页的数据卡片怎么看生成完报告打开首页第一眼看到的是一个统计面板里面有总用例数、通过的、失败的、中断的、跳过的等几个关键数字下面通常还有柱状图和饼图。按我的经验这个面板信息量很大但也是最容易被过度解读的地方。总用例数首先要确认跟实际执行数对得上。我见过不少次“报告显示 100 条实际只执行了 80 条”的情况多半是执行历史结果没清理干净旧数据混进来了。所以在看 Overview 之前先确认结果目录是干净的否则统计数字没有意义。几个关键指标的理解要注意失败failed表示用例执行了但断言没通过这种情况最需要关注中断broken表示用例执行过程中抛了异常可能环境问题也可能代码问题跳过skipped往往是前置条件不满足比如 pytest 的 skip 标记生效。在给团队同步结论时我会明确区分“失败的用例”和“异常中断的用例”这两个问题的责任方通常不一样。Overview 页还会展示严重程度的分布图也就是 blocker、critical、normal、minor、trivial 这几档。这个分布图的准确度完全取决于用例代码里有没有标注 severity。如果项目还没做标注那这块内容基本就是摆设清一色 normal 也得不出有效结论。所以别急着看图表先去确认用例标注做到什么程度。3.2 Suites 页与用例详情里的有效信息Suites 页展示的是用例树形结构按模块、文件或者类来组织所有用例一层层列在左侧面板里。点开任意一条用例右侧会展示这条用例的完整生命周期开始时间、结束时间、运行时长、前置操作步骤、每一个测试步骤的执行结果、失败时的堆栈信息。这些信息看起来非常多但实际定位问题的时候我建议优先看三个位置。第一个是失败时的异常堆栈。Allure 会把 pytest 的完整 traceback 展示出来而且支持折叠查看错误信息长也不会刷屏。研发拿到报告后最关心的就是这一块你完全可以把堆栈直接贴给他们。第二个是测试步骤的耗时分布。如果一条用例整体执行了 30 秒其中 29 秒都在同一个步骤上那瓶颈就在那个步骤。Allure 允许你对关键操作添加步骤描述这样报告中每一步都有独立的耗时展示性能问题的定位就会快很多。第三个是附件。如果用例执行过程中保存了截图、日志或者接口返回的响应体这些内容会以附件形式展示在用例详情里。UI 自动化测试的截图、接口测试的请求响应体在排查问题时的价值甚至比堆栈信息还要高。前提是代码里记得用allure.attach把数据挂上去。3.3 用注解让报告自动分类和定级基础报告默认展示的信息其实比较朴素的真正让报告变得好用靠的是代码里的 Allure 注解。这些注解不是锦上添花而是决定报告能不能被团队高效使用的关键。先讲最常用的分组维度。用 feature 和 story 两个层级来组织用例相当于产品模块和功能点的两级目录。比如登录模块是一个 feature获取验证码、密码登录、扫码登录这些是下面的 story。加了这两层之后Suites 页里的树形结构会从“按目录结构展示”变成“按业务模块展示”研发和产品一眼就能看到哪个功能点的失败了。import allure allure.feature(登录模块) class TestLogin: allure.story(密码登录) allure.title(输入正确账号密码可以登录成功) def test_login_success(self): ...severity 注解用来标注用例的重要程度适合在资源有限、需要优先处理关键失败时使用。blocker 和 critical 的用例失败在概览页会显示得特别醒目。有同学认为这只是个标签实际作用不大我个人的经验是当自动化用例规模超过 500 条的时候按严重程度过滤的能力释放出来的效率提升是非常明显的。还有一个容易被忽略的是allure.step它可以把用例内部的关键步骤显式地标记出来。如果不加这个注解报告里只能看到“用例开始”和“用例结束”两个节点执行过程中的细节全部消失。加了步骤标注之后报告里能看到每一步做了什么、花了多久、在哪一步失败的这个信息对于快速定位帮助很大。4. 高频问题排查与 CI 集成经验4.1 六个真实踩过的高频问题问题一执行 pytest 后找不到 allure-results 目录。这个基本可以确定适配器装漏了检查pip list里有没有 allure-pytest。有个容易踩的误区是你装了 allure 命令行工具但没装 pytest 适配器跑完用例自然没有任何结果数据生成因为 pytest 根本不知道该往哪里写数据。反过来只看代码不装命令行也不会生成报告。两边都需要装齐。问题二生成了结果目录但是 allure generate 报错“找不到命令”。大部分情况是命令行工具没有加入 PATH 环境变量。在终端里执行allure --version如果提示 command not found那就是环境变量问题需要先把工具所在目录加进 PATH。Windows 上特别容易出现解压 zip 后忘记配置 PATH 的情况。问题三报告生成成功但打开全是空白页或者样式加载不出来。这个问题在本地环境里多半和浏览器的静态资源拦截策略有关。Allure 报告页面打开的默认路径包含了大量静态 js、css 资源如果通过 serve 方式访问时端口被占用或者代理配置异常就会出现页面加载不完整。建议先确认服务日志有没有报错再用不带代理的浏览器环境访问试试。问题四报告里显示的用例数比实际执行数多。前面已经提到了十有八九是历史结果文件没有清理干净。检查 pytest 执行命令里有没有加--clean-alluredir或者 allure generate 的--clean参数是否生效。这里我建议两个 clean 参数都保留一个清理结果数据目录一个清理报告输出目录各管各的缺一不可。问题五报告中失败堆栈里的中文乱码。这个问题出在控制台日志编码和报告渲染编码不一致。pytest 执行过程中输出的日志如果编码不是 UTF-8Allure 在解析时就会变成乱码。处理办法是在 pytest 配置文件中把日志编码固定为 UTF-8并确认用例输出内容本身已经是 UTF-8 编码。问题六附件上传之后报告里显示不出来页面提示 404。这种情况要确认附件是否真的存在于结果目录中。Allure 报告是纯静态页面HTML 文件里只记录了附件的相对路径如果生成报告之后你又手动移动了报告目录附件路径就失效了。生成之后不要随意挪动整个报告目录要迁移就完整打包迁移。4.2 保留历史趋势与环境信息的小技巧很多团队用 Allure 报告不只是看当下这一次结果还想看“最近的失败趋势在变好还是变差”。Allure 报告内置了历史趋势页但默认情况下如果你每次都把结果目录清理干净再重新生成报告趋势页只有当前这次的数据看不到历史曲线因为历史数据本来就没了。保留趋势的方法是在生成新报告之前把上一次报告目录里的history子目录复制到新的结果目录中。具体来说让生成命令读取的结果目录里带一个 history 文件夹Allure 会自动读取并追加这次的结果最终报告就能呈现多次执行的趋势图。我在实际项目里的做法是维护一个固定版本号分隔的目录结构每次 CI 构建执行前先检查前一次报告目录是否存在存在就把它的 history 目录拷贝到本次结果目录。这个逻辑写成一两行 shell 命令就行效果却很直观质量趋势图、历史成功率曲线全部出来了研发不用翻一堆历史报告也能看出整体走向。另外一个非常实用的小技巧是在结果目录里放一个environment.properties文件里面写上环境信息、应用版本、数据库地址、执行人等字段。报告生成后概览页会展示一个环境信息区块团队拿到报告就能知道“这份结果是哪个环境、哪个版本出来的”避免两份报告对不上号时反复确认。4.3 在 CI 流水线中生成稳定报告把 Allure2 接进 CI 时最稳妥的方案不是用 serve 而是用 generate然后让平台归档整个 HTML 目录。流水线里的操作顺序通常是这样的先安装依赖再执行 pytest 并把结果目录指定成固定路径之后执行 allure generate最后把 allure-report 目录设置为构建产物。这里有一个非常容易被忽视的点CI 环境每次构建可能从零开始工作空间是全新目录。如果你只在流水线里安装命令行工具却没有把工具的 bin 目录加进 PATH那 generate 命令同样会失败。所以 CI 配置文件里要显式写出工具安装后的 PATH 设置不要依赖个人电脑上的默认环境。另一个建议是每次构建用唯一标识命名报告目录比如带上构建序号或时间戳避免多分支构建并行时互相覆盖。流水线同时跑多个任务如果都往同一个 allure-report 目录写文件轻则报告混在一起重则生成过程中目录被其他进程清理掉最后平台归档出来的产物是残缺的。还有一点是关于失败结果的处理。有些项目的流水线设计是“测试执行有失败用例就直接让构建失败”结果报告反而没有被正确处理人只能去翻原始日志。我的建议是把“执行测试”和“生成报告”拆成两个步骤即便测试步骤有失败用例后续的 generate 步骤也必须执行这样失败时的报告也能完整保留下来。很多团队实践下来这份失败报告比测试步骤本身的状态信息有用得多。我个人在实际项目里还有一个体会不要一开始就把报告玩得很花什么漂亮的分类、复杂的自定义插件全上。先把执行流程跑通让报告里的总用例数跟你真正跑的用例数对得上再逐步加 severity 标注、加 environment 信息、加 history 趋势。每一步都验证清楚再走下一步远比一次配一堆功能然后出了问题到处排查要快得多。Allure2 的流程不复杂复杂的是你不会的时候把所有问题堆在一起看梳理清楚命令链和数据流它就真的只是一个很顺手的工具。
阅读完成 · 觉得有帮助？
