Python自动化测试入门:环境搭建与第一个pytest用例编写

Miles
Miles
发布时间:2026-11-22 | 18人浏览过
原创

面向初学者的Python自动化测试入门指南,系统讲解虚拟环境隔离配置、pytest安装验证、目录结构规划、用例命名约定、assert断言机制以及首个测试用例的编写与结果解读。

自动化测试的核心目标是通过运行预设的代码脚本来自动验证程序的输入与输出是否符合预期,从而替代机械且容易遗漏的手工回归流程。在 Python 生态中,完成一次最小可行测试需要经历三个基本步骤:建立独立的虚拟运行环境、遵循框架发现契约规划目录与测试文件、使用原生断言语法编写并执行测试用例。本文将以主流且简洁的 pytest 框架为例,详细演示从零搭建测试环境到运行首个测试用例的完整实践。

一、准备工作:搭建隔离的测试虚拟环境

在安装测试框架前,首要任务是在项目根目录下建立独立的虚拟环境。很多初学者习惯直接在系统的全局 Python 环境中执行 pip install pytest,这在短期内虽然看似省事,但极易引发不同项目间依赖版本冲突。此外,某些系统级工具若被测试依赖意外覆盖或升级,排查修复成本极高。使用 Python 内置的 venv 模块为每个项目分配独立的解释器和库目录,是业内推荐的标准做法。

1. 创建与激活虚拟环境

打开终端并进入存放项目的目录,执行以下命令创建名为 .venv 的虚拟环境:

# Linux / macOS 创建虚拟环境
python3 -m venv .venv

# Windows 创建虚拟环境
python -m venv .venv

创建完成后,当前目录会生成一个名为 .venv 的文件夹,内部包含了独立的 Python 解释器、pip 包管理器以及标准库副本。接下来需要激活该环境:

# Linux / macOS 激活虚拟环境
source .venv/bin/activate

# Windows CMD 激活虚拟环境
.venv\Scripts\activate.bat

# Windows PowerShell 激活虚拟环境
.venv\Scripts\Activate.ps1

激活成功后,命令行提示符前方会出现括号包围的环境名称,例如 (.venv) $,这表明后续执行的 python 与 pip 命令均直接作用于此独立环境。

2. 安装 pytest 并核对版本

在激活的环境中,直接使用 pip 安装 pytest:

pip install pytest

pip 会自动解析并安装 pytest 及其核心底层依赖(如 pluggy、iniconfig、packaging 等)。安装结束后,通过查看版本号确认 pytest 可执行文件已正确就绪:

pytest --version

如果终端返回类似以下示例内容,则说明测试环境已经完整搭建完成:

# 示例输出
pytest 8.3.3
Python自动化测试入门:环境搭建与第一个pytest用例编写
图 1:pytest 测试环境搭建与可用性验证的四步操作流程

二、规范先行:目录结构与 pytest 自动发现契约

很多新手在初次使用 pytest 时,最常遇到的问题是执行命令后终端提示“collected 0 items”(未收集到任何测试用例)。这通常并非代码报错,而是测试文件或函数命名未遵守 pytest 的“约定优于配置”发现规则。

当我们在命令行中输入 pytest 时,框架会从当前目录开始递归扫描子目录,并依据默认命名模式识别测试目标:

  • 测试文件名:必须以 test_ 开头或以 _test.py 结尾。例如 test_calculator.py 或 account_test.py 会被自动收集,而 calc_tests.py 或 helper.py 则会被静默忽略。
  • 测试函数名:在测试文件中,待执行的测试函数必须以 test_ 开头。例如 test_add() 会被执行,而 check_add() 或 verify_result() 则不会被当成独立测试项。
  • 测试类与类方法:若采用面向对象形式组织用例,类名必须以 Test 开头,且该类不能包含 __init__ 构造方法;类内部的测试方法同样需以 test_ 开头。

为了让业务代码与测试代码职责清晰,推荐采用源码目录与测试目录分离的标准布局:

my_project/
├── .venv/                  # 虚拟环境目录(不提交至代码仓库)
├── src/                    # 业务源码目录
│   ├── __init__.py
│   └── calculator.py       # 被测模块
└── tests/                  # 测试用例目录
    ├── __init__.py
    └── test_calculator.py  # 测试脚本
Python自动化测试入门:环境搭建与第一个pytest用例编写
图 2:pytest 自动扫描发现测试文件与测试用例的命名匹配规则

三、实战编写:业务实现与首个 pytest 测试用例

为了完整展示测试过程,我们先编写一个包含正常计算与异常处理的简单计算器业务模块,随后针对该模块编写对应的测试用例。

1. 编写被测业务代码

在 src/calculator.py 中编写加法与除法函数:

# src/calculator.py

def add(a: float, b: float) -> float:
    """计算两数相加之和"""
    return a + b

def divide(a: float, b: float) -> float:
    """计算两数相除,除数为0时抛出 ValueError"""
    if b == 0:
        raise ValueError("除数不能为零")
    return a / b

2. 编写第一个 pytest 测试用例

在 tests/test_calculator.py 中引入被测函数,并使用 pytest 编写对应的测试函数:

# tests/test_calculator.py
import pytest
from src.calculator import add, divide

def test_add_integers():
    """验证整数相加的正确性"""
    result = add(10, 20)
    assert result == 30

def test_add_floats():
    """验证浮点数相加的近似相等"""
    result = add(0.1, 0.2)
    # 浮点数计算存在精度误差,使用 pytest.approx 进行近似比较
    assert result == pytest.approx(0.3)

def test_divide_normal():
    """验证正常除法计算"""
    assert divide(10, 2) == 5.0

def test_divide_by_zero():
    """验证除数为零时是否正确抛出指定异常"""
    with pytest.raises(ValueError) as exc_info:
        divide(10, 0)
    # 进一步核对异常携带的信息文本
    assert "除数不能为零" in str(exc_info.value)

3. 理解原生 assert 语法与 unittest 的区别

初学者如果接触过 Python 内置的 unittest 或其他面向对象语言的单元测试框架,通常习惯写类似 self.assertEqual(a, b) 或 self.assertTrue(x) 这样的方法。在 pytest 中,我们无需继承任何类,直接使用 Python 原生的 assert 关键字即可完成绝大部分判断。

有人可能会产生疑问:“Python 原生 assert 语句如果失败,默认只抛出一个简陋的 AssertionError,难道不需要额外的断言方法来辅助诊断吗?”这正是 pytest 的精妙之处。pytest 在执行测试代码前,会利用 Python 的 AST(抽象语法树)重写机制对测试文件中的 assert 语句进行动态内省。当 assert add(10, 20) == 35 失败时,pytest 能自动提取等式左边与右边的求值中间过程,直观输出 assert 30 == 35 以及各个局部变量的当前取值,彻底免去了记忆几十种专门断言 API 的心智负担。

Python自动化测试入门:环境搭建与第一个pytest用例编写
图 3:unittest 与 pytest 断言机制及心智负担对比

四、执行测试:命令参数与终端输出解读

编写完成用例后,在项目根目录打开终端执行测试。推荐使用 python -m pytest 命令,相比直接输入 pytest,该命令能确保当前项目根目录被自动加入到 Python 的模块检索路径 sys.path 中,有效避免 ModuleNotFoundError: No module named 'src' 的导入错误。

1. 常用执行指令

# 1. 基础运行:运行全部测试用例
python -m pytest

# 2. 详细模式 (-v):展示每一个用例函数的名称及执行状态
python -m pytest -v

# 3. 指定文件:仅执行指定测试文件中的用例
python -m pytest tests/test_calculator.py

# 4. 指定用例:精准执行特定文件下的某一个测试函数
python -m pytest tests/test_calculator.py::test_add_integers

# 5. 关键词过滤 (-k):根据函数名模式筛选执行
python -m pytest -k "divide"

2. 解读全部通过时的测试报告

执行 python -m pytest -v 后,控制台输出如下所示:

# 示例输出
============================= test session starts ==============================
platform darwin -- Python 3.11.8, pytest-8.3.3, pluggy-1.5.0 -- /path/to/.venv/bin/python
rootdir: /path/to/my_project
collected 4 items

tests/test_calculator.py::test_add_integers PASSED                       [ 25%]
tests/test_calculator.py::test_add_floats PASSED                         [ 50%]
tests/test_calculator.py::test_divide_normal PASSED                      [ 75%]
tests/test_calculator.py::test_divide_by_zero PASSED                     [100%]

============================== 4 passed in 0.02s ===============================

输出报告中各部分含义如下:

  • rootdir:测试根目录位置。
  • collected 4 items:表示框架按规则共成功发现了 4 个测试函数。
  • PASSED:绿色的 PASSED 状态代表该测试函数中的所有 assert 均顺利成立且无未捕获异常。
  • [100%]:表示用例执行进度。
  • 4 passed in 0.02s:汇总本次测试耗时与成功统计。

3. 解读测试失败时的排错信息

为了直观观察失败场景,假设我们刻意在 tests/test_calculator.py 中加入一个预期不符的断言:

def test_add_intentional_failure():
    assert add(2, 2) == 5

再次运行 python -m pytest,终端将清晰展示出错原因:

# 示例输出
=================================== FAILURES ===================================
_________________________ test_add_intentional_failure _________________________

    def test_add_intentional_failure():
>       assert add(2, 2) == 5
E       assert 4 == 5
E        +  where 4 = add(2, 2)

tests/test_calculator.py:24: AssertionError
=========================== short test summary info ============================
FAILED tests/test_calculator.py::test_add_intentional_failure - assert 4 == 5
========================= 1 failed, 4 passed in 0.03s =========================

从输出中可以看到,> 符号直接指出了发生断言失败的代码行号,E 标记展示了表达式的左侧求值结果 add(2, 2) -> 4 与右侧期望值 5,使开发者能瞬间定位是业务逻辑缺陷还是测试用例的期望值设定有误。

五、避坑指南:初学者高频错误辨析

辨析 1:assert (condition, "message") 与 assert condition, "message" 的元组陷阱

在 Python 中,如果给断言附加失败提示信息,标准的写法是逗号分隔:assert a == b, "数据不匹配"。如果误加括号写成 assert (a == b, "数据不匹配"),Python 会将括号内的内容解释为一个双元素元组。在 Python 布尔上下文中,非空元组的布尔值恒为 True。即使 a == b 结果为 False,该断言也永远不会触发失败,造成测试用例假通过的严重隐患。

辨析 2:ModuleNotFoundError: No module named 'src'

当测试文件存放在独立的 tests/ 目录时,直接在子目录运行脚本或直接键入 pytest 有时会因为 Python 未将当前工作根目录注入模块搜索路径而报错。除了坚持使用 python -m pytest 之外,更为规范的做法是在项目根目录下创建 pyproject.toml 文件明确指定源码根路径:

[tool.pytest.ini_options]
pythonpath = ["."]
testpaths = ["tests"]

配置完成后,无论从何处调用 pytest,它都会自动以项目根目录为基准定位导入模块。

Python自动化测试入门:环境搭建与第一个pytest用例编写
图 4:pytest 自动化测试入门全景知识与排查自检清单

六、总结

搭建 Python 自动化测试体系并不复杂。只要牢记虚拟环境隔离保证依赖纯净、遵循命名契约确保框架正常发现、运用简单直观的原生 assert 提升编写与调试效率这三项基本准则,就能快速在实际开发流程中建立起稳固的第一道质量防线。随着业务代码复杂度的提升,后续还可以进一步引入 pytest 的参数化测试(@pytest.mark.parametrize)与夹具机制(fixture),实现更具复用性与可维护性的自动化测试工程。

本站声明

本文内容仅供参考,不代表本站观点。转载或引用请注明出处。如发现内容问题,请通过联系我们页面反馈。

Python 相关产品和应用

全部下载

专题列表