Python测试运行器Nox

Python 测试运行器 Nox 详解
===================================

Nox 是灵活的 Python 测试运行器，通过 noxfile.py 定义多个测试会话，
自动为每个会话创建独立的虚拟环境，适用于多版本测试。

一、安装与基本概念
------------------

# 安装 Nox
# pip install nox

# 验证安装
nox --version

# Nox 的核心概念：
# · Session（会话）：一个测试任务，在独立虚拟环境中运行
# · noxfile.py：定义所有会话的配置文件
# · 每个会话可以指定不同的 Python 版本和依赖

# 列出所有可用的会话
nox --list

二、noxfile.py 基础
-------------------

# 基本的 noxfile.py 文件
"""
import nox

# 指定会话使用的 Python 版本
@nox.session(python=["3.9", "3.10", "3.11"])
def tests(session):
# 安装依赖
session.install("pytest", "pytest-cov")
# 安装项目本身
session.install(".")
# 运行命令
session.run("pytest", "tests/", "--cov=src")

@nox.session
def lint(session):
# 代码检查会话
session.install("ruff")
session.run("ruff", "check", "src/")

@nox.session
def type_check(session):
# 类型检查会话
session.install("mypy")
session.install(".")
session.run("mypy", "src/")
"""

# 运行所有会话
nox

# 运行特定会话
nox -s tests

# 运行多个会话
nox -s tests lint

三、高级会话配置
----------------

# 参数化会话与精细控制
"""
import nox

# 使用参数化标签
@nox.session(tags=["core"])
@nox.parametrize("django", ["3.2", "4.0", "4.1"])
def tests(session, django):
# 安装特定版本的 Django
session.install(f"django=={django}")
session.install("pytest", "pytest-django")
session.install(".")
session.run("pytest", "tests/")

@nox.session(python="3.11", venv_backend="conda")
def conda_tests(session):
# 使用 Conda 创建虚拟环境
session.install("numpy", "scipy")
session.run("pytest", "tests/")
"""

# 查看参数化会话
nox --list

# 按标签运行会话
nox --tags core

四、虚拟环境管理
----------------

# Nox 为每个会话自动创建和管理虚拟环境

# 配置虚拟环境后端
"""
import nox

# 可选的 venv_backend 值：
# · "virtualenv" （默认）
# · "conda"
# · "venv"

@nox.session(venv_backend="virtualenv")
def example(session):
# 默认后端，需要安装 virtualenv
session.install("pytest")

@nox.session(venv_backend="venv")
def stdlib_venv(session):
# 使用 Python 标准库 venv
session.install("pytest")
"""

# 复用虚拟环境（加快重复运行速度）
nox -s tests --reuse-existing-virtualenvs

# 强制重新创建虚拟环境
nox -s tests --force-venv

五、会话高级功能
----------------

# 更多装饰器参数和辅助方法
"""
import nox

# 不指定 Python 版本（使用当前环境）
@nox.session(python=False)
def build_docs(session):
# 不创建虚拟环境，使用系统 Python
session.run("sphinx-build", "-b", "html", "docs/", "docs/_build")

@nox.session
def coverage(session):
# 安装依赖
session.install("pytest", "pytest-cov", "coverage")
session.install(".")
# 运行测试并生成覆盖率报告
session.run(
"pytest", "tests/",
"--cov=src",
"--cov-report=html",
"--cov-report=term-missing",
)
# 多个命令连续执行
session.run("coverage", "report", "--fail-under=80")

@nox.session
def integration(session):
# 集成测试会话
session.install("-r", "requirements-dev.txt")
session.install(".")
# 设置环境变量
session.env["DATABASE_URL"] = "sqlite:///test.db"
session.env["DEBUG"] = "true"
session.run("pytest", "tests/integration/", "-v")
"""

六、reuse_venv 与缓存
---------------------

# 控制虚拟环境缓存行为
"""
import nox

# 默认情况下每次运行都会重新创建虚拟环境
# 通过命令行参数控制：
# nox -s tests --reuse-existing-virtualenvs

# 在 noxfile 中设置默认行为
nox.options.reuse_existing_virtualenvs = True

# 或通过环境变量控制
# export NOX_REUSE_VENV=1

@nox.session
def fast_tests(session):
# 安装依赖
session.install("pytest")
session.install(".")
session.run("pytest", "tests/unit/", "-x")
"""

七、与 CI/CD 集成
------------------

# GitHub Actions 配置示例
"""
name: Tests
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
strategy:
matrix:
python-version: ["3.9", "3.10", "3.11"]
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: ${{ matrix.python-version }}
- run: pip install nox
- run: nox -s tests --python ${{ matrix.python-version }}
"""

# 只运行未通过的会话
nox -s tests --error-on-missing-interpreters

# 并行运行会话
nox -s tests lint type_check --parallel

# Nox 让多版本测试变得简单可靠，每个会话的隔离性
# 确保测试环境纯净，是 CI 管道的得力助手。