保姆级教程：Pytest + Allure 接口自动化测试从 0 到 1 完整指南（含环境搭建、用例编写、报告生成、报错排坑全流程）

一、前言

在接口自动化测试中，一份清晰、美观的测试报告是项目交付和问题定位的关键。本文将带你从零开始，搭建 Pytest + Allure 自动化测试环境，从基础用例编写到专业可视化报告生成，再到常见报错解决方案，全程保姆级讲解，新手也能直接上手！

---

二、环境搭建（Windows 系统）

1. 安装 Python 环境

• 下载地址：https://www.python.org/downloads/
• 安装步骤：勾选 Add Python to PATH，默认安装即可
• 验证安装：打开 CMD 终端，输入 python --version，输出版本号即成功

2. 安装 Pytest 与 Allure 依赖

打开项目虚拟环境终端，执行以下命令安装依赖包：

# 安装 pytest 测试框架
pip install pytest==9.0.3

# 安装 allure 相关依赖
pip install allure-pytest==2.13.5
pip install allure-python-commons==2.13.5

验证安装：执行 pip list，能看到上述包即安装成功。

3. 安装 Allure 命令行工具

1. 下载 Allure 压缩包：https://github.com/allure-framework/allure2/releases/download/2.30.0/allure-2.30.0.zip
2. 解压到本地目录，例如 D:\dev_tools\allure-2.30.0
3. 配置系统环境变量：
   • 打开「系统环境变量」→ 找到 Path → 编辑
   • 新增路径：D:\dev_tools\allure-2.30.0\bin（必须以 \bin 结尾）
   • 一路点击「确定」保存配置
4. 验证安装：重启 CMD 终端 ，输入 allure --version，输出版本号 2.30.0 即配置成功

---

三、项目结构与基础用例编写

1. 推荐项目结构

api_test/
├── .venv/                # 虚拟环境目录
├── report/               # 报告存放目录
│   ├── allure-results/   # Allure 结果数据目录
│   └── html-report/      # 静态HTML报告目录（用generate命令生成）
├── tests/                # 测试用例目录
├── my_logging.py         # 日志工具类（可选）
├── pytest.ini            # pytest 配置文件（可选）
├── test_allure01.py      # 基础测试用例文件
└── test_allure02.py      # 带 Allure 注解的测试用例文件

2. 编写基础测试用例

（1）test_allure01.py（无注解基础版）

# 基础测试用例，无 Allure 注解
def test_aaa():
    assert "aaa" == "aaa"

def test_bbb():
    assert "bbb" == "bbb"

（2）test_allure02.py（带 Allure 注解美化版）

加入装饰器，让报告分类更清晰、可读性更强：

import allure

# 定义功能模块（报告中的一级分类）
@allure.feature("示例功能模块")
class TestDemo:
    # 定义测试场景（报告中的二级分类）
    @allure.story("aaa 场景测试")
    # 自定义用例标题（报告中展示的用例名称）
    @allure.title("验证 aaa 字符串相等")
    def test_aaa(self):
        assert "aaa" == "aaa"

    @allure.story("bbb 场景测试")
    @allure.title("验证 bbb 字符串相等")
    def test_bbb(self):
        assert "bbb" == "bbb"

---

四、生成并查看 Allure 测试报告

Allure 提供了两种生成报告的方式，分别适合不同场景：

方式一：动态服务方式（适合本地调试，推荐）

1. 执行测试，生成报告数据在项目终端执行以下命令，运行指定用例并生成 Allure 结果文件：

   cmd

   pytest test_allure01.py test_allure02.py --alluredir=./report/allure-results

   执行成功后，./report/allure-results 目录下会生成多个 .json 格式的结果文件。

2. 启动 Allure 服务，打开可视化报告

   方式 1：使用环境变量（推荐）

   cmd

   allure serve ./report/allure-results

   方式 2：使用完整路径（环境变量不生效时）

   cmd

   D:\dev_tools\allure-2.30.0\bin\allure.bat serve ./report/allure-results

   执行成功后，终端会输出本地访问地址（如 http://127.0.0.1:63452），复制到浏览器即可查看专业的 Allure 测试报告。

---

方式二：静态文件生成方式（适合部署分享，必看）

除了 serve 命令，Allure 还支持通过 generate 命令生成静态 HTML 报告文件，可以直接保存、分享或部署到服务器。

1. 核心命令说明

   cmd

   allure generate [options] <allure-results> -o <reports>

   • <allure-results>：必填，测试结果数据文件夹（即 --alluredir 生成的目录）
   • -o <reports>：必填，指定生成的 HTML 报告存放目录
   • [options]：可选参数，如 --clean（生成前清空目标目录）

2. 完整操作步骤① 先执行测试，生成结果数据：

   cmd

   pytest test_allure01.py test_allure02.py --alluredir=./report/allure-results

   ② 执行 generate 命令生成静态报告：

   cmd

   # 推荐写法（自动清空旧报告，避免文件冲突）
   allure generate ./report/allure-results -o ./report/html-report --clean

   ③ 查看报告：进入 ./report/html-report 目录，双击打开 index.html 文件即可查看完整报告。

3. 两种方式对比

   表格

   方式	特点	适用场景
   allure serve	启动本地服务，实时刷新，需要保持终端运行	本地开发调试、快速查看报告
   allure generate	生成静态 HTML 文件，可直接保存 / 分享 / 部署	持续集成（Jenkins）、报告归档、跨环境分享

---

五、Allure 报告常用注解说明

表格

注解	作用	使用场景
@allure.feature("模块名")	一级功能模块分类	按业务模块划分测试用例，如「登录模块」「订单模块」
@allure.story("场景名")	二级测试场景分类	模块下的子场景，如「密码登录」「短信登录」
@allure.title("用例标题")	自定义用例标题	替代函数名，让报告中的用例名称更直观
@allure.description("用例描述")	用例详细描述	补充用例的前置条件、预期结果等信息
@allure.severity("级别")	用例优先级标记	标记用例重要程度，可选值：blocker/critical/normal/minor/trivial

---

六、常见报错与解决方案

1. 报错：'allure' 不是内部或外部命令，也不是可运行的程序

原因：

• Allure 环境变量配置错误
• 配置后未重启终端 / IDE
• PyCharm 虚拟环境终端未继承系统环境变量

解决方案：

1. 检查系统 Path 变量中，Allure 路径是否为 D:\dev_tools\allure-2.30.0\bin（必须以 \bin 结尾）
2. 关闭所有终端 / IDE，重新打开 CMD 验证 allure --version
3. PyCharm 终端使用完整路径执行：D:\dev_tools\allure-2.30.0\bin\allure.bat serve ./report/allure-results
4. 把 PyCharm 终端的 Shell 路径改为 C:\WINDOWS\system32\cmd.exe

2. 报错：ModuleNotFoundError: No module named 'allure_pytest'

原因 ：未安装 allure-pytest 依赖包

解决方案：执行命令安装依赖：

cmd

pip install allure-pytest

3. 报错：pytest: error: unrecognized arguments: --alluredir

原因 ：未安装 allure-pytest 或安装版本不兼容

解决方案：重新安装对应版本的依赖：

cmd

pip install allure-pytest==2.13.5

4. 报错：Allure serve 打开报告空白/报错

原因：

• 报告数据目录为空（用例未执行成功）
• Allure 版本与 allure-pytest 版本不兼容

解决方案：

1. 先执行 pytest 命令，确保 ./report/allure-results 目录下有结果文件
2. 统一版本：Allure 2.30.0 搭配 allure-pytest==2.13.5

5. 报错：PyCharm 终端无法识别 allure 命令（CMD 正常）

原因：PyCharm 虚拟环境终端未继承系统环境变量

解决方案：

1. 在 PyCharm 终端手动添加临时环境变量： powershell

   $env:Path += ";D:\dev_tools\allure-2.30.0\bin"

2. 改用完整路径执行命令，绕过环境变量问题

---

七、进阶：接口自动化测试用例示例

以下是一个带接口请求、日志记录和 Allure 注解的真实接口测试用例，可直接替换项目中的示例用例：

import allure
import requests
from my_logging import logger

@allure.feature("用户模块")
class TestUserAPI:
    @allure.story("用户登录接口")
    @allure.title("验证手机号+密码登录成功")
    @allure.severity("critical")
    def test_user_login(self):
        # 接口请求参数
        url = "https://api.example.com/user/login"
        data = {
            "phone": "13800138000",
            "password": "123456"
        }
        
        # 发送请求并记录日志
        logger.info(f"请求地址：{url}，请求参数：{data}")
        response = requests.post(url, json=data)
        logger.info(f"响应状态码：{response.status_code}，响应内容：{response.text}")
        
        # 断言验证
        assert response.status_code == 200
        assert response.json()["code"] == 0
        assert "token" in response.json()["data"]

---

八、总结

本文从环境搭建、用例编写、两种报告生成方式到常见报错排坑，完整覆盖了 Pytest + Allure 自动化测试的核心流程。通过 serve 命令可以快速调试，通过 generate 命令可以生成可分享的静态报告，搭配 Allure 注解能让测试报告更清晰、更专业，是接口自动化测试项目中不可或缺的一环。

后续可以在此基础上扩展：

• 加入配置文件管理接口地址、环境变量
• 封装请求工具类，统一处理请求头、响应断言
• 结合 Jenkins 实现持续集成，自动生成并推送测试报告