1. 写在前面Allure2 到底解决了什么问题做测试的人尤其是做接口自动化、UI 自动化的朋友肯定被测试报告折磨过。以前用 JUnit 或者 TestNG 跑完用例看结果得去翻 HTML 文件样式老旧不说失败原因还不直观。要是用例一多光看哪些用例挂了、挂在哪一步就得花不少时间。后来我接触到 Allure2第一感受就是这玩意儿出来的报告终于像给领导汇报的样子了。Allure2 是一个开源的测试报告框架它本身不跑测试用例而是把测试执行过程中产生的数据拿过来重新组织、渲染生成一份结构清晰、分类明确的 HTML 报告。它能展示功能覆盖率、失败用例分类、执行时间趋势、每个用例的步骤日志、参数化数据、截图附件等等。说白了它就是把“测试结果”这个原始材料加工成一份“测试产出”。这篇内容我打算从环境准备、安装细节、适配不同测试框架、生成报告、以及我在实际项目中踩过的坑这几个方向完整走一遍。不管你是刚入门自动化测试的新手还是已经在项目里用 Allure 但没来得及深入研究的同学按照这份操作走下来都能在本地把报告跑起来。我用的是最常用的 pytest Allure 组合来演示但思路同样适用于 Java 系和 JavaScript 系的测试框架。2. 环境准备装 Allure2 之前先把基础环境理清楚2.1 JDK 是躲不开的前提Allure2 是基于 Java 的命令行工具所以第一步不是下载 Allure 包而是确认你机器上有 JDK。很多人在这里会卡一下因为单纯跑 pytest 的机器未必装了 JDK或者只装了 JRE但 Allure 需要 JDK 8 以上的环境建议直接用 JDK 11 或者 JDK 17这两个 LTS 版本在 Allure 上表现都很稳定。验证 JDK 是否安装直接在终端执行java -version如果提示找不到命令那就得先去装 JDK。Windows 用户可以去 Oracle 官网下载安装包或者用 OpenJDKmacOS 用户我比较推荐用 Homebrew 装brew install openjdk17装完之后最好确认一下JAVA_HOME环境变量是否配置好了。特别是在 Windows 上很多人装完 JDK 直接进下一步结果 Allure 命令能识别但生成报告时报一堆类加载错误最后发现就是JAVA_HOME没配对。2.2 选择 Allure2 的安装方式Allure2 的安装方式有几种我分别说一下适用场景。Windows 上最省事的是用包管理器 Scoopscoop install allure这个命令会自动装好 Allure 并把依赖的 JDK 也一并解决连环境变量都不用手动配属于“一条命令走天下”的方案。但前提是你机器上装了 Scoop没装的话先去装一下。不想引入包管理器的话就去 GitHub 的 allure-framework 官方仓库下载allure-commandline的 zip 包。下载后解压到某个固定目录然后把解压目录下的bin路径加进系统PATH环境变量。这一步要注意加的是bin的路径不是解压根目录。macOS 用户用 Homebrew 是最流畅的brew install allureLinux 用户可以用 apt 或者直接下载 zip 包。我个人建议如果你只是偶尔生成报告用 zip 包就够了如果会经常更新版本建议用包管理器升级方便。2.3 验证安装结果的正确姿势装完之后别急着去跑项目先验证一下 Allure 能不能正常运行allure --version正常情况下会输出类似2.24.1这样的版本号。如果你执行命令后看到的是“不是内部或外部命令”先别慌大概率是PATH配置的问题去环境变量里检查一遍然后重新打开一个终端窗口。这里多说一句很多人改了环境变量后在旧的终端窗口里继续测试发现环境变量没生效就以为配置失败了。实际上环境变量的读取是在终端启动时完成的改完之后必须新开窗口才生效。我在 Windows 上就因为这个习惯多花了不少时间。2.4 如果下载速度让人崩溃怎么办Allure 的 GitHub 仓库在国内访问时下载 zip 包经常慢得让人怀疑人生。我的经验是两个替代方案一是用包管理器Scoop 和 Homebrew 一般都有自己的镜像机制速度要快不少二是用开源的迅雷下载 GitHub 文件走 P2P 加速。如果网络条件实在不行也可以找公司内部网络代理这条路在大多数公司是通行的。另外提醒一下不要随便去第三方网站下载所谓的“绿色版”Allure这类渠道的安全性很难保证官方 zip 包虽然下载慢点但至少干净。3. Allure2 的原理认知结果文件、报告和测试用例的关系3.1 搞懂“临时结果”和“最终报告”的区别Allure2 的工作流程简单来说分两步第一步是在测试执行过程中生成一堆 JSON 文件这些文件记录了每个测试用例的详细情况叫做“结果文件”第二步是执行 Allure 命令把这些 JSON 文件渲染成一份静态 HTML 报告。这个设计我觉得特别值得说道说道。很多测试框架的错误在于报告是在测试进程里直接生成 HTML 的一旦执行中断报告就生成不了。而 Allure2 把结果和展示解耦了即使测试中途崩溃只要 JSON 文件留下来了后面随时可以用命令行重新生成报告甚至可以拿到另一台机器上去生成。结果文件默认是放在一个名为allure-results的目录下这个目录是可以通过配置修改的。最终报告默认输出到allure-report目录这个目录也可以指定。明白了这个原理你就能理解为什么我们跑完测试后会看到一堆.json文件里面内容长得像“天书”。这些文件不是垃圾它们是后续生成报告的数据源。3.2 一个测试用例对应多少份 JSON 文件很多新手第一次跑完 pytest Allure 后看allure-results目录会有点懵为什么一个测试用例会生成好几个文件我来拆一下*-result.json这是每个测试用例的核心结果文件记录了用例名称、状态、步骤、参数、附件等。*-container.json这是容器文件记录了 fixture如 setup/teardown、测试类、测试套件等维度信息。*-attachment.*附件文件比如截图、日志等它们由 result 文件中的引用指向。三者的关系是result 文件指向 attachment 文件container 文件聚合多个 result 文件。理解了这一步你在排查“为什么报告里有些用例的步骤是空的”这类问题时就能直接去检查 result 文件的完整性。3.3 报告只是“展示层”别把业务逻辑塞进去使用 Allure2 有个很容易跑偏的误区想在报告上做太多文章试图把报告变成项目管理工具。Allure 的定位非常明确它就是测试结果的展示层它可以帮你按模块、按优先级、按严重程度筛选用例但它不负责管理你的测试计划、不追踪缺陷状态。我在实际项目里见过有人给用例添加大量标签想用 Allure 做版本对比分析结果报告越来越臃肿加载越来越慢。合理的做法是Allure 报告用来展示“当前这次回归的质量状况”趋势分析和缺陷跟进交给 CMDB 或者缺陷管理平台去做。4. 把 Allure2 接入 pytest真实步骤与踩坑记录4.1 安装 pytest 和 allure-pytest 插件如果项目里已经跑过 pytest那这一步就很简单直接安装适配插件pip install pytest allure-pytest如果你是从零开始那就先创建一个虚拟环境再装。这一点在团队协作中特别重要因为虚拟环境能避免不同项目的依赖冲突。创建虚拟环境并安装依赖python -m venv venv source venv/bin/activate # Windows 上用 venv\Scripts\activate pip install pytest allure-pytest安装完成后执行pytest --help如果输出信息里能看到--alluredir选项说明插件已经成功注册了。4.2 编写一个最简单的测试用例用一个极简的例子跑通全流程。新建一个测试文件test_demo.pyimport allure import pytest allure.feature(用户模块) class TestUser: allure.story(登录功能) allure.title(测试用户名和密码正确时能否登录成功) def test_login_success(self): with allure.step(输入用户名): print(输入admin) with allure.step(输入密码): print(输入123456) with allure.step(点击登录): assert True allure.story(登录功能) allure.title(测试密码错误时登录是否失败) def test_login_wrong_password(self): with allure.step(输入用户名): print(输入admin) with allure.step(输入错误密码): print(输入000000) with allure.step(点击登录): assert False这里用了allure.feature、allure.story和allure.title三个装饰器。它们的作用是给用例做分类和重命名。不写这些装饰器也能跑但报告里的用例名称会变成函数名阅读体验会差不少不建议省。4.3 执行测试并生成结果文件执行命令pytest test_demo.py --alluredir./allure-results执行完成后allure-results目录里会多出刚才提到的那几类文件。这里有一个很常见的坑如果不加--clean-alluredir参数第二次执行时旧的结果文件会和新文件混在一起。因为 Allure 每次执行生成的文件名是随机的无法覆盖旧文件。我建议在运行命令中加上pytest test_demo.py --alluredir./allure-results --clean-alluredir这样每次执行前会清空整个allure-results目录避免旧数据污染新报告。4.4 生成并打开 HTML 报告结果文件有了接下来就是 Allure 命令登场的时刻allure serve ./allure-results这条命令会启动一个本地 Web 服务自动打开默认浏览器呈现报告。执行过程中终端会显示类似Generating report to temp directory...的日志看到Report successfully generated就说明成功了。如果不想启动 Web 服务而是想生成一个静态 HTML 目录用于发送给别人或者集成到 CI用allure generate ./allure-results -o ./allure-report --clean allure open ./allure-report第一行命令把结果文件渲染到allure-report目录--clean表示如果该目录已存在则先清空。第二行命令打开已生成的报告。注意allure open本质上也是启动了一个 Web 服务来预览静态文件。想直接以文件方式发送给别人也行直接把allure-report目录打包即可但对方打开 index.html 时最好也是通过本地服务方式浏览器直接双击 html 文件可能因资源跨域加载而显示空白。4.5 中文乱码问题排查我最早跑 Allure 报告时遇到过中文乱码测试步骤描述在报告里显示成乱码。这个问题的来源通常有两个一个是终端在输出日志时用了 GBK 编码写进 JSON 后读取时错乱另一个是 Allure 报告页面本身的字符编码配置问题。首先打开报告页面确认浏览器加载的是 UTF-8 编码一般现代浏览器默认都能正确处理。其次确保 pytest 执行时日志输出用 UTF-8pytest -o log_clitrue --alluredir./allure-results如果还出现乱码就检查一下系统默认编码Windows 系统可以在终端中执行chcp 65001再跑一次用例结果基本就正常了。这里少踩一个坑就能省下好多时间。5. 不只 pytestAllure2 在 Java、JavaScript 生态里的接入思路5.1 Java 生态JUnit5 Allure 的接入流程虽然我这篇内容以 pytest 演示为主但 Allure2 在 Java 生态里的地位同样很高。很多 Java 后端团队的接口测试、单元测试就是用 JUnit5 加上 Allure。接入过程大致是在 Maven 或 Gradle 中引入io.qameta.allure:allure-junit5依赖然后在测试类中用Epic、Feature、Story、Severity等注解来组织用例。运行完测试后构建工具会自动把结果数据写到allure-results目录。之后就是一样地执行allure generate命令。这里有一个容易忽略的点Allure 和 JUnit5 的版本兼容性。allure-junit5 的版本号要和 Allure 命令行版本匹配不然可能出现字段解析错误。我在项目里遇到过 allure-junit5 2.13 配合 allure 2.24 命令行的场景部分用例的步骤显示异常给依赖升到对应版本后问题就好了。建议去官方文档查一下版本兼容矩阵或者直接用最新稳定版。5.2 JavaScript 生态Jest 和 Mocha 的适配如果前端团队想在组件测试上接入 Allure也有现成的适配方案。allure-jasmine和allure-mocha这两个插件分别对应 Jasmine 和 Mocha 测试框架。Jest 的话可以借助jest-allure这个三方库来接入。前端项目的接入稍微复杂一点因为 Allure 的适配器在 Node 环境中依赖文件系统路径不同平台的处理方式略有差异。通常的做法是在 Jest 的 setupFiles 里引入 Allure 的 reporter然后在测试文件中使用allure.feature等方法添加原数据。数据最终写入 result 目录的方式与 pytest 一致。说实话前端测试报告中截图和日志的利用比后端接口测试丰富得多比如组件快照、DOM 状态截图能够直观展示 UI 问题。如果你正在做前端自动化测试这块值得投入时间研究。5.3 其他入口JMeter 和手动测试能否接入在热搜词里我看到了 jmeter 能出测试报告吗 这个问题顺便说一下JMeter 自带的 HTML 报告模板功能可以做基本的性能测试报告但如果你想统一用 Allure 管理接口测试、性能测试的展示可以借助 JMeter 的 JUnit 请求取样器把 JMeter 测试逻辑嵌入 JUnit 用例里再由 Allure 生成报告。这种方式主要适用于接口类测试压测类的 TPS、响应时间等指标还是 JMeter 自身的报告更专业。手动测试用例也可以通过 Allure 的allure.attachment方式手动上传测试结果。不过这个场景相对少见一般用于某些验收测试环节需要手动记录一部分结果再和自动化结果合并。如果你有这个需求建议研究一下 Allure TestOps 生态它对手工测试和自动化测试的统一管理做得更完善。6. 报告里那些关键指标怎么看才不算白看6.1 Overview 页面的指标解读打开 Allure 报告后最直观的就是 Overview 页面它把测试的五维信息浓缩在一起Environment显示运行环境信息比如 Java 版本、操作系统、测试环境地址等。要显示这些信息需要在allure-results目录下放一个environment.properties文件。Categories用聚合视图把用例按“已知缺陷”“产品缺陷”“测试缺陷”“环境缺陷”等类别划分。这个分类是根据用例失败时的异常类型自动匹配的也可以在categories.json里自定义规则。Suites按测试套件维度展示执行情况相当于一个用例执行清单。Graphs把用例状态、严重程度、持续时间等指标按照图表形式展示适合快速发现异常分布。Timeline展示用例执行的并行关系和时间顺序帮助定位执行效率问题。一般人拿到报告第一件事就是看通过率这个没问题。但我想强调通过率只是一个结果指标真正有价值的是 Categories 页面里的失败原因归类。如果所有失败都归类为“测试缺陷”说明是脚本本身的问题如果都是“环境缺陷”那要反思是不是测试环境不稳定。6.2 功能覆盖率怎么在报告里体现Allure 报告中的 Behaviors 页面可以按照allure.feature的维度统计功能覆盖情况。比如一个登录模块有 10 个测试场景实际写了 8 个用例在报告里就能看到该 Feature 下的用例数量和执行通过率。这里有一个我的个人习惯给每个功能模块制定测试用例时先定好需要的用例数量再拿 Allure 报告的 Behaviors 页面来核对覆盖率。这样在回归测试时一眼就能看出哪些功能分支没有被覆盖到。如果项目使用了 BDD 模式allure.story可以对应史诗和用户故事和需求管理工具里的故事卡一一对应。某种程度上这能让测试报告直接服务项目管理人员减少沟通成本。6.3 截图、日志和附件的正确使用方式Allure 报告最具优势的一点是附件机制。在 pytest 中你可以非常轻松地把上下文数据附加到用例报告里allure.step(请求接口 /user/info) def call_user_info_api(): response requests.get(https://api.example.com/user/info) allure.attach(response.text, 响应内容, allure.attachment_type.TEXT) return response如果测试失败响应内容会作为附件显示在失败步骤的详情里不需要去翻日志文件。在 UI 测试中截图更是刚需。使用 Selenium 时可以在异常处理中自动截图import allure from selenium import webdriver def test_login_page(): driver webdriver.Chrome() try: driver.get(https://example.com/login) # 执行操作 assert driver.title 登录 except Exception as e: allure.attach(driver.get_screenshot_as_png(), 失败截图, allure.attachment_type.PNG) raise e finally: driver.quit()一句建议截图加不加是一回事加得好不好是另一回事。失败时截图往往是最有价值的信息但成功用例也可以在关键步骤加截图这样在评审报告时可以直观看到每一步的 UI 变化特别适合给需求方演示。7. 参数化、重试机制与高级玩法7.1 参数化测试在报告中的表现pytest 的参数化功能非常强大结合 Allure 后能让报告更清晰。比如import allure import pytest allure.title(登录测试-{username}-{password}) pytest.mark.parametrize(username,password, [ (admin, 123456), (user1, password), (admin, wrong_password) ]) def test_login(username, password): assert login(username, password)注意allure.title里使用了占位符{username}和{password}这样每个参数组合生成的用例名都是独立的。如果不加这行的话报告里会看到三个同名用例无法直观区分参数差异。参数化数据在详情页中还有专门的展示区域能够清晰看到当前用例执行的具体参数值。这在排查前后参数变化导致的问题时非常好用。7.2 失败重跑对报告的影响pytest 中有pytest-rerunfailures插件可以让失败的用例自动重跑。这个功能和 Allure 搭配时有一个容易混淆的点重试后的用例在 Allure 报告中默认只显示最后一次结果但用例里会保留重试的历史记录。如果你希望重试逻辑不影响报告的纯净性比如某条用例第一次跑网络超时重试成功了报告里最终显示通过即可那默认行为就够用了。但如果你想把每次重试的日志都留档可以加上 retry 参数并且在上报结果时做一些自定义处理。我的经验是不要把 flaky 用例的重试次数设置得太大。一般 1-2 次足够超过 3 次反而掩盖了真实问题。重试应该用于解决环境抖动带来的偶发失败而不是逃避稳定性问题。7.3 使用 environment.properties 记录测试环境信息Allure 报告默认展示的全局信息里有一项是 Environment很多人会忽略它。通过一个简单的 properties 文件可以把本次测试的环境信息都展示出来BrowserChrome Browser.Version120.0 OSWindows 11 Test.EnvironmentStaging Base.URLhttps://staging-api.example.com把这个文件放到allure-results目录下然后重新生成报告就能在 Overview 页面的 Environment 区域看到这些信息。如果报告和缺陷管理工具联动这些环境信息能帮开发快速定位问题特别是有多个测试环境时。另外在 CI 中跑测试时还可以通过 CI 的环境变量动态生成这个 properties 文件让报告里的环境信息始终是当前流水线的构建信息。这个技巧在项目推动质量建设时非常加分。7.4 自定义分类规则Allure 默认的 categories 可能不符合你的项目语境比如把“超时”类失败归为“环境缺陷”把“断言失败”归为“产品缺陷”。但你也可以创建自己的categories.json[ { name: 数据库连接失败, matchedStatuses: [broken], messageRegex: .*connection.*failed.* }, { name: 断言不一致, matchedStatuses: [failed], messageRegex: .*AssertionError.* } ]文件同样放在allure-results目录下重新生成报告后Categories 页面就会按照这套规则分类。这个高级用法在大型项目里能省下很多人工分析时间。8. 实操过程中常见的七个坑与排查方法问题现象可能原因解决方案allure命令无法识别PATH 未配置或未新开终端检查 PATH 并新开终端窗口报告中用例重复显示旧 result 文件未清理执行时加--clean-alluredir中文乱码编码配置不一致终端chcp 65001或检查输出编码报告打开空白浏览器直接双击 HTML 文件跨域资源被拦使用allure open或本地 Web 服务预览步骤日志不显示allure-pytest 版本过低或装饰器未生效升级插件检查allure.step使用位置用例分类在 Behaviors 页面为空忘记加allure.feature在类或函数上补充 feature 装饰器执行中断导致报告数据不完整结果文件未完全落盘添加 try-finally 逻辑确保 always 上报第一个坑在 Windows 系统上出现概率极高特别是在用户安装了多个 Python 版本或者用 Anaconda 管理环境时PATH 里经常出现覆盖问题。建议把 scoop 的 bin 路径放在 PATH 的前面。第二个坑我几乎每次切换分支跑测试都会踩到因为同事可能在同一个项目目录下跑过测试。所以我现在习惯在命令里固定加--clean-alluredir不管是本地还是 CI。第三个坑在 Windows 10 以下的系统更容易出现新版 Windows 终端默认编码已经是 UTF-8 了。遇到中文乱码先检查是不是终端输出编码导致 JSON 内容错误而不是急着改报告模板。第五个坑的典型场景是函数里用了with allure.step()但函数被pytest.fixture修饰了导致 Allure 收集不到 step 信息。解决办法是确认with allure.step()逻辑是写在测试函数内部而不是 fixture 的隐式调用里。我在定位这个问题时花了半小时最后发现是 fixture 与 step 混用导致的报错信息根本不会提示这一层。9. 在 CI 里接入 AllureJekins 和 GitLab CI 的配置要点9.1 Jenkins 上如何配置 Allure本地跑通了接下来自然是把 Allure 接入 CI让每次构建后自动生成测试报告。先讲 Jenkins。在 Jenkins 中最简单的集成方式是使用 Allure 官方插件。插件安装后需要在“系统设置”里配置 Allure 安装路径或者指定由插件自动从 GitHub 下载指定版本。然后在“构建后操作”中选择Allure Report填入allure-results目录路径。有个细节要注意如果执行机上有多个项目共用同一个 Jenkins 工作目录务必将allure-results放到当前构建的工作目录中避免多个项目的结果文件互相覆盖。我的习惯是在 Jenkins 项目的构建命令里把--alluredir./allure-results写死同时加上--clean-alluredir。9.2 GitLab CI 中的 Docker 化执行方案GitLab CI 的玩法更“容器化”。一般来说你需要在仓库里内置一个 Dockerfile里面装好 Python、JDK、Allure 命令行然后在.gitlab-ci.yml中定义测试 jobtest: stage: test script: - pip install pytest allure-pytest - pytest --alluredir./allure-results --clean-alluredir artifacts: paths: - allure-results/ expire_in: 1 week这里的关键点是 Artifacts 的配置。因为 GitLab CI 在 job 执行完成后会产生一个 artifact而后续如果需要看报告要么用专门的 Allure 报告插件要么把allure-report目录作为 artifact 上传。前者我建议优先考虑因为它在 MR 页面上展示得很优雅开发直接在 merge request 里就能看到测试趋势。9.3 容器里面 Allure 命令编码与时区的小坑容器环境中跑 Allure 报告有两个小坑我印象很深。第一个是时区问题很多基础镜像默认是 UTC 时区导致报告里的执行时间比本地时间晚了 8 小时。解决办法是在 Dockerfile 里设置时区例如ENV TZAsia/Shanghai RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime echo $TZ /etc/timezone第二个是字体问题如果容器里跑的是 UI 测试需要生成截图或 PDF系统没有中文字体时截图里的中文会变成方框。解决办法是安装中文字体包这个坑可能在 UI 自动化中特别常见。10. 让我再看一眼报告质量审查清单最后我习惯在每次发布测试报告前对一个“报告质量清单”逐项检查。这份清单是从项目实践中总结出来的分享给你作为参考报告中用例名称是否有可读性还是只是函数签名每个失败用例是否有关键日志和截图环境信息是否记录完整能否从报告上分辨执行环境分类是否合理失败用例能否一眼定位到原因是否有与本次范围无关的历史结果数据是否已清理报告打开速度是否可接受如果太慢考虑减少附件大小或按模块拆分报告。检查完毕再把这封报告发出去质量会大不一样。11. 一些个人的使用体会用 Allure2 这几年我最大的体会是测试报告不是给测试自己看的它同时也是项目质量状态的呈现载体。一个测试框架好不好用不只看它能跑多少用例还要看它在团队协作中的可读性、可维护性和可追溯性。Allure2 在这些方面做得相当平衡。如果非要说它在学习曲线上有什么门槛那就是一开始要把“结果文件”和“报告文件”这两个概念搞清楚。理解了这个后面什么 CI 集成、分布式执行、报告合并都会顺理成章。最后再分享一个小技巧如果你在不同分支上跑测试想对比两次测试报告的数据可以借助allure generate生成到不同目录然后本地起一个简单的 HTTP 服务就能在两份报告之间来回切换对比了。这个功能我没见多少人用过但效果真的很好。