企业官网建设流程全解析

简介：Allure 2.13.9自动化报告生成工具压缩包，面向软件测试工程师、自动化测试开发及质量管理团队，解决测试报告可读性差、缺陷定位困难等问题。该版本在性能与稳定性上有所提升，支持JUnit、TestNG、pytest等主流测试框架，可自动生成包含时间轴、统计图表、步骤详情与失败原因分析的HTML报告，并可通过JSON配置定制报告布局与主题。压缩包大小为16.29MB，解压后配置PATH环境变量即可通过allure命令生成或预览报告。当前已有386人学习下载。此工具还提供插件扩展能力，可接入Jira、Trello等项目管理工具，在报告中直接创建和追踪缺陷；配合测试框架注解，能进一步提升用例描述的清晰度，帮助团队更高效地管理测试结果、跟进问题并持续改进测试流程。

1. Allure 2.13.9 到底是个什么东西，为什么我还在用它

先给你一个结论：Allure 2.13.9 是自动化测试报告生成器的一个版本号，全称是 allure-commandline，解压后是一个能跑的本地命令行工具。它本身不执行测试用例，只负责把你测试框架产生的 result 文件（JSON 格式的中间结果）转换成一整套可以直接用浏览器打开的 HTML 报告——包括用例执行状态、失败截图、日志、步骤耗时、历史趋势。它解决的是「测试跑完了，结果却没人看得懂」的问题：pytest、TestNG、JUnit、Cucumber 这些框架原生报告都太简陋，要么是一堆控制台日志，要么是一张静态的 HTML，而 Allure 会把同样的数据渲染成一个带搜索、带筛选、带趋势图的可交互站点。

我之所以要在 2025 年还专门写一遍 2.13.9 这个版本，是因为它仍然是很多团队的稳定选择。Allure 2.13.9 之后主版本号跳到 2.14、2.15、2.20+，但核心用法没变，而且 2.13.9 也是我维护过的老项目里最不容易出兼容问题的一个版本。对于做接口自动化、UI 自动化的测试开发、质量保障工程师，以及要在 CI/CD 流水线里展示测试结果的 DevOps 同学，这个版本足够覆盖绝大多数需求。

2. 解压与前置环境：别急着跑 allure，先检查你的 Java

Allure 命令行工具是用 Java 写的，所以在跑任何 allure 命令之前，你的机器上必须有一个能用的 JDK。常见翻车现场是：解压完 allure 压缩包，双击 allure.bat 报错，或者敲 allure --version 提示找不到 Java。这不是 allure 的问题，是环境变量没有配好。

2.1 解压后的目录结构，我先给你拆一遍

不管你拿到的是 allure-2.13.9.rar、allure-2.13.9.zip 还是 .tgz，解压后的顶层目录都叫allure-2.13.9，里面有三个核心目录和一个可执行入口：

allure-2.13.9/ ├── bin/ # allure 命令入口（allure.bat / allure 脚本） ├── config/ # 默认的配置目录，可放 categories.json 等 ├── lib/ # Java 运行所需依赖包，不要手工动它 └── LICENSE 等文件

bin目录是命令入口：Windows 下用allure.bat，macOS/Linux 下用allure这个 shell 脚本。config目录里可以放自定义的报告分类规则，比如把某种特定异常归到「产品缺陷」而不是「测试失败」，这个后面会展开讲。lib目录是整个工具的核心依赖，如果杀毒软件或者解压工具把它当危险文件清掉了，allure 命令会出现各种看不懂的 ClassNotFoundException，所以解压时记得加白名单。

2.2 配置 JAVA_HOME 与环境变量，这步不做后面全是泪

在 Windows 上，你首先要确认装了 JDK（不是 JRE），然后配置JAVA_HOME和PATH。我之前在一台新机器上只装了 JRE，结果 allure 能启动但生成报告时报错，折腾了半天才发现是 JRE 缺少编译相关组件。检查 Java 环境的标准命令：

java -version echo %JAVA_HOME% # Windows 下 echo $JAVA_HOME # macOS / Linux 下

java -version能正常输出版本号，说明 JRE 在，但JAVA_HOME环境变量为空的话，Allure 部分功能仍然会出问题。我一般会直接在系统环境变量里新建JAVA_HOME，值指向 JDK 的安装根目录，比如C:\Program Files\Java\jdk1.8.0_202，然后在PATH里追加%JAVA_HOME%\bin。设置完要重新打开一个终端窗口，因为环境变量不会在当前窗口自动生效。

2.3 验证 allure 命令是否可用，一步到位

把 allure 的 bin 目录也加进PATH之后，打开新终端执行：

allure --version

如果输出：

2.13.9

说明安装成功。如果输出不是内部或外部命令或者command not found，就检查 PATH 是否配对了。这里有个小细节：在 macOS 上如果你用的是 zsh，需要执行source ~/.zshrc或者干脆开一个新终端窗口让配置生效。

3. 先跑通最小链路：pytest 生成 result，再用 allure 出报告

很多教程上来就讲 Allure 的各种注解和装饰器，容易把新手绕晕。我建议按「先看到报告，再学花活」的顺序来：先在本地把一个最小 pytest 用例跑出 result 目录，再用 allure 命令把它变成 HTML 报告。这一步通了，后面所有高级功能都有了基础。

3.1 用 pytest 产出 Allure 需要的 result 中间文件

假设你已经有一个 pytest 项目，最简用例长这样：

import pytest def test_login_success(): assert 1 == 1 def test_login_failed(): assert 1 == 2

直接执行 pytest 不会产生 allure 认识的中间文件，你需要安装allure-pytest插件，并在运行 pytest 时指定--alluredir参数：

pip install allure-pytest pytest --alluredir=./allure-results

先说明逻辑：--alluredir指定的是 Allure 中间结果（raw result）的输出目录，不是最终报告目录。插件会把每次用例执行的状态、耗时、日志、失败原因写成一个.json文件放在这个目录里。执行完你可以看到allure-results目录下多了一堆 UUID 命名的 JSON 文件，这些文件就是后面生成报告的唯一数据源。

allure-results这个目录名不是强制的，你可以叫results或者output/allure-reports，但建议固定成allure-results，因为很多 CI 插件默认就会找这个目录。另外记得把allure-results加进.gitignore，这个目录里的文件每次跑测试都会重新生成，不该进版本库。

3.2 用 allure generate 一次性生成静态报告

拿到allure-results之后，用 generate 命令把它转成一套静态 HTML：

allure generate ./allure-results -o ./allure-report --clean

这里有三个参数必须搞清楚：

• ./allure-results：输入目录，指向刚才 pytest 生成的中间结果；
• -o ./allure-report：输出目录，即最终报告存放位置，目录不存在会自动创建；
• --clean：在生成前清空输出目录，避免上次报告残留导致数据混乱。

生成过程会在终端打印日志，结束后allure-report目录下会有一个index.html。直接双击这个文件不一定能打开——因为报告里的 JS 资源需要静态服务承载，直接 file:// 协议访问容易遇到跨域限制。所以我建议用下面这个命令来预览。

3.3 allure serve：本地临时起一个服务来预览报告

serve 是我个人使用频率最高的命令，它会自动起一个本地 Web 服务并打开默认浏览器：

allure serve ./allure-results

serve 命令的功能是：读取./allure-results，在内存里构建报告，然后启动一个临时 HTTP 服务器（默认端口随机），最后自动打开浏览器。它的优点是随手就能预览，缺点是每次都要重新构建、服务关闭后就没有了。generate 命令则是把报告落盘成文件，适合传给其他同事或者塞进 CI 制品库。

两次运行结果会合并吗？不会。如果你跑了两轮 pytest，allure-results目录里会有两批 JSON 文件。再执行 generate 时，Allure 会读取该目录下所有 result 文件并合并展示在同一个报告里——这正是 Allure 支持多次增量执行的设计意图。

3.4 三个常用命令的参数速查表

allure open是我之后才发现的用法。当你已经用 generate 生成过报告，想快速再看一眼时，allure open ./allure-report比重新 generate 或 serve 更省时间。它不对 result 文件做任何重新处理，只是把已有的报告目录挂到一个本地服务上。

4. 把 Allure 接到 pytest 工程里：注解、动态信息与报告命名的完整配置

跑通最小链路后，你要面对的真实情况是：项目里有几百条用例，每条用例有前置条件、数据依赖、截图、日志，还要在报告里能快速筛出失败用例、按模块分类、看执行趋势。这就要用到 allure-pytest 的注解机制和几种配置文件。

4.1 allure-pytest 的核心注解，用一小段代码看全

先看一个较完整的接口测试用例写法：

import allure @allure.feature("用户模块") # 用在类或函数上，定义一个功能模块 @allure.story("登录") # 用在函数上，定义用户故事或子模块 @allure.title("验证用户名密码正确时可以登录") # 自定义用例标题 @allure.severity(allure.severity_level.BLOCKER) # 严重级别 def test_login_success(): with allure.step("输入用户名"): pass with allure.step("输入密码"): pass with allure.step("点击登录"): assert True

这段代码的关键在于把用例的可读性直接拉高：报告首页会按feature分组，组内部再按story展示用例列表，title让每条用例显示为可读的中文描述而非test_login_success这种函数名。allure.step定义的步骤会展示为报告里的展开层级，点击即可看到每一步的执行情况。

这里建议你遵守一个纪律：@allure.feature对应测试计划的模块名，@allure.story对应具体功能点，不要混用。混用的后果是报告左侧的列表会变得层级混乱，失去快速定位的价值。

4.2 动态更新用例名和附件，这是最实用的高阶参数

如果用例中某些字段是运行时才能确定的，比如订单编号、用户 ID，就需要用allure.dynamic在代码里动态修改标题或附加信息：

import allure def test_create_order_with_dynamic_data(): order_id = "SO20250101-0001" allure.dynamic.title(f"创建订单-{order_id}") allure.dynamic.description(f"校验订单号: {order_id}") with open("logs/api_response.log", "r", encoding="utf-8") as f: allure.attach(f.read(), name="接口响应日志", attachment_type=allure.attachment_type.TEXT)

allure.dynamic.title可以让报告里显示的是运行时数据，比静态注解灵活得多。allure.attach是最常用的附件接口，可以把接口返回的 JSON、日志文本甚至截图塞进报告详情页。实际做接口自动化时，我一般会在断言失败时把请求头和响应体都 attach 进去，这能让失败排查时间缩短一半以上。

4.3 environment.properties 与 categories.json：这两个配置文件决定报告的专业度

environment.properties是放在allure-results目录下一个固定名字的配置，用来展示测试环境信息：

app.version=2.13.9 env=test browser=headless-chrome base.url=https://api.example.com

这个文件内容会显示在报告首页的「Environment」区域。放置位置必须是allure-results目录下，并且要在 pytest 执行前放好，因为 generate 或 serve 时 Allure 会扫描该目录下的这个文件。另一种做法是写一个 pytest 的 fixture 在 session 开始时动态写文件：

import pytest @pytest.fixture(scope="session", autouse=True) def write_env_properties(): with open("allure-results/environment.properties", "w", encoding="utf-8") as f: f.write(f"env=test\nbase.url=https://api.example.com\n")

categories.json则是定义失败分类的配置文件。默认情况下 Allure 把用例结果只分成 passed、failed、broken 三类。但实际工作中你想区分：断言失败是「功能缺陷」，用例代码异常是「自动化脚本问题」，接口超时是「环境问题」。在allure-results目录下创建categories.json：

[ { "name": "功能缺陷", "matchedStatuses": ["failed"], "messageRegex": ".*AssertionError.*" }, { "name": "环境异常", "matchedStatuses": ["broken"], "messageRegex": ".*ConnectTimeout.*|.*Connection refused.*" }, { "name": "脚本问题", "matchedStatuses": ["broken"] } ]

这里有一个匹配逻辑需要注意：Allure 对用例的最终状态判定后，会拿状态去和 matchedStatuses 匹配，再拿 messageRegex 正则去匹配失败信息。命中「功能缺陷」的用例会显示为 product defect 分类，命中「环境异常」的则显示为环境问题，都不命中则落到默认分类。这个配置文件是让我觉得 Allure 比其他报告工具高级的重要原因——你可以完全控制失败原因的归类逻辑。

4.4 加上清理机制的完整运行命令

运行测试时，如果上一次残留了旧的 result 文件，报告里会出现已经不存在的历史用例。正确做法是每次执行前清理 result 目录：

rm -rf ./allure-results pytest --alluredir=./allure-results --clean-alluredir allure generate ./allure-results -o ./allure-report --clean

pytest 的--clean-alluredir参数会在开始收集用例前清空allure-results目录，等价于手动rm -rf。加上这一步后，每次运行生成的报告都只包含当前批次的数据，避免混淆。

5. Allure 2.13.9 常见问题与避坑记录

工具链跑久了你会发现，真正耗时间的不是功能不会用，而是环境、路径、兼容性这些看起来很小的坑。下面这几条是我在多个团队和机器上反复踩过的，按「现象 → 原因 → 解决」的顺序写给你。

5.1 现象：allure serve 提示端口被占用

某次我在 CI 机器上执行allure serve ./allure-results，终端直接报错：

Port 12345 is already in use

原因：serve 默认会找一个空闲端口，但如果上一次启动的服务没有正常关闭，端口占用会持续存在。解决：启动时显式指定一个端口，并且保证用完关闭：

allure serve ./allure-results -p 8080

-p参数指定端口后，报错信息会直接提示你需要换端口还是结束旧进程。在 Windows 上可以执行netstat -ano | findstr 8080找到占用进程 PID，再用taskkill /F /PID <pid>结束；在 Linux/macOS 上用lsof -i:8080配合kill -9处理。

5.2 现象：pip install allure-pytest 后执行 pytest 不生成 result 文件

我一度以为运行 pytest 后 Allure 自动就生效了。实际是：插件虽然安装了，但如果 pytest.ini 里没有声明alluredir，或者命令行没有传--alluredir，插件根本不会写入任何文件。

解决：检查 pytest 插件是否被正确加载：

pytest --help | grep alluredir

如果能看到--alluredir=ALLUREDIR这一行，说明插件加载成功；如果看不到，说明 pytest 的插件加载路径有问题。此时需要确认你用的 pytest 和 allure-pytest 是否装在同一个环境下，比如在虚拟环境里 pip list 看两个包是否同时存在。

5.3 现象：报告所有用例都显示为 broken 而不是 failed

当你看到报告中用例状态大量是 broken，但你的断言明明只是assert 1 == 2，第一反应通常是怀疑报告有问题。节奏是：broken 表示用例执行过程中发生了异常或错误，failed 表示断言未通过。如果你的测试代码在断言之前抛了异常（比如空指针、key 不存在、网络超时），Allure 就把它归为 broken。

排查方向：打开具体的用例详情页，看异常堆栈出现在哪个步骤。如果是 setup 里的 fixture 报错，整条用例会全挂；如果是请求超时，说明是环境问题而不是功能问题。想让这种情况自动分类，就用前面说的 categories.json 按 messageRegex 把超时归到环境异常。

5.4 现象：报告打开后浏览器一片空白

我先说一个最容易被忽略的场景：报告是用allure generate生成后，直接双击index.html打开的。这和前面讲的跨域限制有关系。解决：用allure open ./allure-report或者把报告目录扔到 Nginx/静态服务器里。如果你一定要双击打开，可以用 Chrome 的--allow-file-access-from-files参数启动，但这个方法不推荐日常使用，因为只会产生新的树木障碍。

zsh 或 bash 提示找不到 allure 命令时，先查 PATH；还要注意 Windows 下用allure命令需要调allure.bat。如果你解压的是 rar 包，解压工具版本太老还可能把文件权限弄丢，导致 bin 下的 shell 脚本没有执行权限。此时需要 chmod +x 手动补权限：

chmod +x ./allure-2.13.9/bin/allure

5.5 现象：历史执行趋势图不显示

新生成的报告里，首页的 History 和 Trends 区域经常是空的。数据来源是上一次报告中的history目录。Allure generate 在生成新报告时不会自动带上历史数据，除非你指定了--clean之外的参数组合。

解决：在同一个工作目录下执行 generate 时，Allure 会自动从allure-report/history读取历史数据：

allure generate ./allure-results -o ./allure-report --clean

注意了，这里有个边界条件：上一次的allure-report目录必须存在，且没有被--clean删除。如果你每次都在 CI 全新的工作空间里跑命令，历史趋势肯定为空。我一般会把allure-report目录作为 CI 的缓存目录保留下来，这样趋势图才会连续。

6. 把报告做进日常习惯：一次完整的验证与几个进阶技巧

当你把上面的内容都跑通后，Allure 2.13.9 已经在本地稳定工作了。最后分享几个我日常在用的技巧，这些能明显提升报告的使用率。

第一个技巧是「每半天自检一次报告链路」。我会用一个最小测试文件检查环境是否还正常：

pytest --alluredir=./allure-results --clean-alluredir -q allure generate ./allure-results -o ./allure-report --clean

如果这个过程没有报错，说明 JDK、Allure、pytest 插件三条链路都健康。这步动作只需要十秒钟，但能帮你提前发现杀毒软件把 lib 目录删了、Gradle 或 Maven 把 PATH 顶掉了这类奇怪问题。

第二个技巧是尽量让报告中展示的环境信息完整。我在最初使用 Allure 时，根本不知道environment.properties的存在，导致报告给到开发时对方总问环境信息。后来我在 conftest.py 里写了一个自动写环境配置的 fixture，之后每次生成的报告都会带着分支名、版本号、测试环境来源。这一个小改动，让报告从「一份测试结果」升级成「一份可直接归档的版本证据」。

第三个技巧是重跑失败用例后，用allure serve对比前后的 result 数量。如果重跑 10 条失败用例后生成了 10 个新的 JSON 文件，而报告里仍然能看到旧失败记录，说明 result 目录没有清理。定期清理allure-results目录是保持报告可信度很低成本的投入。

最后提醒一点：Allure 2.13.9 的配置文件路径是相对 result 目录的，所以categories.json和environment.properties必须和 result 文件放在同一级。我们团队最常出问题的地方，就是有人把这两个文件放在项目根目录下，生成报告后发现配置完全不生效。保持这个习惯后，我基本没有再因为报告问题加过班——Allure 2.13.9 让我从反复解释测试结果的状态中解脱出来了。希望这些经验对你有帮助，在你把 Allure 接入自己的项目时能少走几趟弯路。

本文还有配套的精品资源，点击获取