# Pytest 完整使用指南

Pytest 是 Python 最流行的测试框架，以其简洁的 API 和强大的功能被广泛应用于各种项目中。

## 目录

1. [快速开始](#1-快速开始)
2. [编写测试](#2-编写测试)
3. [Fixtures](#3-fixtures)
4. [异步测试](#4-异步测试)
5. [Mocking](#5-mocking)
6. [参数化测试](#6-参数化测试)
7. [跳过测试](#7-跳过测试)
8. [测试夹具作用域](#8-测试夹具作用域)
9. [测试组织](#9-测试组织)
10. [常用命令](#10-常用命令)
11. [配置文件](#11-配置文件)

---

## 1. 快速开始

### 安装

```bash
pip install pytest pytest-asyncio
```

### 运行测试

```bash
# 运行所有测试
pytest

# 运行指定文件
pytest tests/test_api.py

# 运行指定测试函数
pytest tests/test_api.py::test_health_check

# 显示详细输出
pytest -v

# 显示打印内容
pytest -s

# 在第一个失败处停止
pytest -x
```

---

## 2. 编写测试

### 基本结构

```python
# test_example.py
def test_basic_assertion():
    """简单的断言测试"""
    assert 1 + 1 == 2

def test_string_operations():
    """字符串操作测试"""
    text = "hello world"
    assert text.upper() == "HELLO WORLD"
    assert text.startswith("hello")
    assert len(text) == 11

def test_list_operations():
    """列表操作测试"""
    items = [1, 2, 3]
    assert len(items) == 3
    assert items.pop() == 3
    assert items == [1, 2]
```

### 测试类

```python
class TestMathOperations:
    def test_addition(self):
        assert 2 + 3 == 5
    
    def test_subtraction(self):
        assert 5 - 3 == 2
    
    def test_multiplication(self):
        assert 3 * 4 == 12


class TestStringOperations:
    def test_reverse(self):
        assert "hello"[::-1] == "olleh"
```

---

## 3. Fixtures

Fixtures 是 pytest 最强大的特性之一，用于提供测试所需的依赖和数据。

### 基本 Fixture

```python
import pytest

@pytest.fixture
def sample_data():
    """返回一个简单的数据字典"""
    return {"name": "test", "value": 100}

def test_using_fixture(sample_data):
    """使用 fixture 的测试"""
    assert sample_data["value"] > 50
```

### Fixture with Setup/Teardown

```python
import pytest
import tempfile
import shutil

@pytest.fixture
def temp_directory():
    """创建临时目录，测试后清理"""
    temp_path = tempfile.mkdtemp()
    yield temp_path  # 测试在此运行
    shutil.rmtree(temp_path, ignore_errors=True)  # 清理

def test_write_file(temp_directory):
    """使用临时目录的测试"""
    import os
    file_path = os.path.join(temp_directory, "test.txt")
    with open(file_path, "w") as f:
        f.write("hello")
    
    assert os.path.exists(file_path)
    # 测试结束后 temp_path 会被自动清理
```

### Fixture 参数化

```python
@pytest.fixture
def user_data():
    return {"username": "testuser", "email": "test@example.com"}


def test_user_creation(user_data):
    assert user_data["username"] == "testuser"
```

---

## 4. 异步测试

### 安装异步支持

```bash
pip install pytest-asyncio
```

### 配置 pytest.ini

```ini
[pytest]
asyncio_mode = auto
```

### 编写异步测试

```python
import pytest

@pytest.mark.asyncio
async def test_async_operation():
    """异步测试函数"""
    import asyncio
    
    async def fetch_data():
        await asyncio.sleep(0.1)
        return {"data": "result"}
    
    result = await fetch_data()
    assert result["data"] == "result"


@pytest.mark.asyncio
async def test_async_with_db():
    """模拟异步数据库操作"""
    import asyncio
    
    async def connect_db():
        await asyncio.sleep(0.1)
        return "database_connected"
    
    result = await connect_db()
    assert "connected" in result
```

### Fixture 返回协程

```python
import pytest
import asyncio

@pytest.fixture
async def async_database():
    """异步 fixture - 连接数据库"""
    await asyncio.sleep(0.1)  # 模拟连接
    db = {"connected": True}
    yield db
    # Teardown
    await asyncio.sleep(0.05)


@pytest.mark.asyncio
async def test_database_query(async_database):
    assert async_database["connected"] is True
```

---

## 5. Mocking

### 使用 unittest.mock

```python
from unittest.mock import Mock, patch, AsyncMock
import pytest

def test_mock_function():
    """Mock 函数调用"""
    mock = Mock(return_value=42)
    
    result = mock()
    assert result == 42
    mock.assert_called_once()


def test_patch_environment():
    """Patch 环境变量"""
    with patch("os.environ", {"TEST": "value"}):
        import os
        assert os.environ.get("TEST") == "value"


def test_mock_class():
    """Mock 类"""
    mock_class = Mock()
    mock_class.method.return_value = "mocked"
    
    result = mock_class.method()
    assert result == "mocked"


@pytest.mark.asyncio
async def test_async_mock():
    """Mock 异步函数"""
    mock_async = AsyncMock(return_value="async result")
    
    result = await mock_async()
    assert result == "async result"


@pytest.mark.asyncio
async def test_patch_async():
    """Patch 异步函数"""
    async def real_async_func():
        return "real"
    
    with patch("__main__.real_async_func", new_callable=AsyncMock) as mock_func:
        mock_func.return_value = "mocked"
        result = await mock_func()
        assert result == "mocked"
```

### Mocking 第三方库

```python
from unittest.mock import patch, MagicMock
import pytest

# Mock HTTP 请求
@pytest.mark.asyncio
async def test_api_call():
    mock_response = MagicMock()
    mock_response.status_code = 200
    mock_response.json.return_value = {"status": "ok"}
    
    with patch("httpx.AsyncClient") as mock_client:
        mock_instance = AsyncMock()
        mock_instance.get = AsyncMock(return_value=mock_response)
        mock_client.return_value = mock_instance
        
        # 实际测试代码会使用 httpx.AsyncClient
        client = mock_client.get("http://api.example.com")
        # ...
```

---

## 6. 参数化测试

一个测试函数使用不同参数多次运行。

### @pytest.mark.parametrize

```python
import pytest

@pytest.mark.parametrize("input,expected", [
    (1, 2),
    (2, 4),
    (3, 6),
])
def test_double(input, expected):
    """测试倍数函数"""
    assert input * 2 == expected


@pytest.mark.parametrize("a,b,result", [
    (1, 1, 2),
    (2, 3, 5),
    (10, 20, 30),
])
def test_addition(a, b, result):
    assert a + b == result


# 字符串参数
@pytest.mark.parametrize("text,upper", [
    ("hello", "HELLO"),
    ("World", "WORLD"),
    ("pytest", "PYTEST"),
])
def test_uppercase(text, upper):
    assert text.upper() == upper
```

### 多参数组合

```python
import pytest

@pytest.mark.parametrize("x", [1, 2, 3])
@pytest.mark.parametrize("y", [10, 20])
def test_combinations(x, y):
    """x=1,2,3 与 y=10,20 的所有组合"""
    assert x * y > 0
    # 运行 6 次: (1,10), (1,20), (2,10), (2,20), (3,10), (3,20)
```

### 使用 pytest 对象的 param

```python
import pytest

@pytest.fixture
def pytest_param_user():
    return pytest.param("user1", marks=pytest.mark.slow)


def test_user_stuff():
    pass
```

---

## 7. 跳过测试

### 跳过条件

```python
import pytest
import sys

@pytest.mark.skip(reason="功能未实现")
def test_not_implemented():
    pass


@pytest.mark.skipif(sys.version_info < (3, 8), reason="需要 Python 3.8+")
def test_new_feature():
    pass


# 动态跳过
def test_conditionally():
    if some_condition:
        pytest.skip("条件不满足")
    assert True
```

### 预期失败

```python
@pytest.mark.xfail(reason="已知 bug")
def test_known_bug():
    assert False  # 预期失败
```

---

## 8. 测试夹具作用域

Fixture 可以指定不同的作用域：

```python
# function: 每个测试函数执行一次（默认）
@pytest.fixture
def function_fixture():
    print("function scope")
    return "function"

# class: 每个测试类执行一次
@pytest.fixture(scope="class")
def class_fixture():
    print("class scope")
    return "class"

# module: 每个模块执行一次
@pytest.fixture(scope="module")
def module_fixture():
    print("module scope")
    return "module"

# session: 整个测试会话执行一次
@pytest.fixture(scope="session")
def session_fixture():
    print("session scope")
    return "session"
```

---

## 9. 测试组织

### 目录结构建议

```
project/
├── tests/
│   ├── __init__.py
│   ├── conftest.py           # 共享 fixtures
│   ├── test_api.py           # API 测试
│   ├── test_models.py        # 模型测试
│   ├── test_services/        # 服务测试
│   │   ├── __init__.py
│   │   ├── test_session.py
│   │   └── test_scheduler.py
│   └── test_integration/     # 集成测试
│       └── test_workflow.py
├── src/
│   └── your_code.py
└── pytest.ini
```

### conftest.py 共享配置

```python
# tests/conftest.py
import pytest

@pytest.fixture
def common_setup():
    """所有测试共享的设置"""
    print("Setting up test environment")
    yield
    print("Tearing down test environment")


# 自动使用某些 fixtures
@pytest.fixture(autouse=True)
def reset_state():
    """每个测试自动重置状态"""
    yield
```

---

## 10. 常用命令

```bash
# 基本运行
pytest                    # 运行所有测试
pytest tests/            # 运行指定目录
pytest test_file.py      # 运行指定文件
pytest -k "test_name"   # 按名称过滤
pytest -k "test_api"    # 运行包含 "test_api" 的测试

# 输出控制
pytest -v                # 详细输出
pytest -s                # 显示 print 输出
pytest --tb=short        # 简短 traceback
pytest --tb=long         # 详细 traceback

# 调试
pytest -x                # 第一个失败后停止
pytest --pdb             # 失败时进入 debugger
pytest -l                # 显示失败的局部变量

# 覆盖率
pytest --cov=src         # 运行并计算覆盖率
pytest --cov-report=html # 生成 HTML 报告

# 标记
pytest -m "slow"         # 运行带 slow 标记的测试
pytest -m "not slow"     # 排除 slow 标记

# 异步
pytest --asyncio-mode=auto  # 自动检测异步测试
```

---

## 11. 配置文件

### pytest.ini

```ini
[pytest]
minversion = 6.0
testpaths = tests
python_files = test_*.py
python_classes = Test*
python_functions = test_*

# 异步配置
asyncio_mode = auto

# 标记定义
markers =
    slow: 耗时较长的测试
    integration: 集成测试
    unit: 单元测试

# 忽略路径
norecursedirs = .git .tox build dist

# 自定义选项
addopts = -v --tb=short
```

### pyproject.toml

```toml
[tool.pytest.ini_options]
minversion = "6.0"
testpaths = ["tests"]
pythonpath = ["."]

[tool.pytest.markers]
slow = "marks tests as slow"
integration = "marks tests as integration tests"

[tool.coverage.run]
source = ["src"]

[tool.coverage.report]
exclude_lines = [
    "pragma: no cover",
    "def __repr__",
    "raise AssertionError",
]
```

---

## 高级技巧

### 1. 自定义标记

```python
# 在代码中使用
@pytest.mark.slow
def test_slow_operation():
    import time
    time.sleep(5)
    assert True


@pytest.mark.integration
def test_api_workflow():
    pass


# 在 pytest.ini 中注册
[pytest]
markers =
    slow: marks tests as slow (deselect with '-m "not slow"')
    integration: marks tests as integration tests
```

### 2. 条件跳过

```python
import pytest

# 基于环境变量
import os

@pytest.mark.skipif(
    os.getenv("CI") == "true",
    reason="跳过 CI 环境"
)
def test_dev_only():
    pass


# 基于平台
@pytest.mark.skipif(
    sys.platform == "win32",
    reason="不适用于 Windows"
)
def test_linux_only():
    pass
```

### 3. Fixture 依赖

```python
@pytest.fixture
def database():
    return {"connected": False}


@pytest.fixture
def db_session(database):
    """依赖另一个 fixture"""
    session = {"db": database, "active": True}
    return session


def test_database_connection(db_session):
    assert db_session["active"] is True
```

### 4. 工厂 Fixture

```python
@pytest.fixture
def user_factory():
    """工厂 fixture - 每次返回新实例"""
    created = []
    
    def _create_user(name):
        user = {"id": len(created) + 1, "name": name}
        created.append(user)
        return user
    
    return _create_user


def test_create_users(user_factory):
    user1 = user_factory("Alice")
    user2 = user_factory("Bob")
    
    assert user1["id"] == 1
    assert user2["id"] == 2
```

### 5. 临时文件

```python
import pytest
from pathlib import Path
import tempfile
import shutil


@pytest.fixture
def temp_dir():
    temp_path = Path(tempfile.mkdtemp())
    yield temp_path
    shutil.rmtree(temp_path, ignore_errors=True)


def test_file_operations(temp_dir):
    file_path = temp_dir / "test.txt"
    file_path.write_text("Hello, World!")
    assert file_path.read_text() == "Hello, World!"
```

---

## 测试最佳实践

1. **测试名称要描述性**: `test_user_can_login` 比 `test_login` 更好

2. **AAA 模式**: Arrange (准备) -> Act (执行) -> Assert (断言)

3. **每个测试一个关注点**: 保持测试简短和专注

4. **使用描述性断言消息**: 
   ```python
   assert result == expected, f"Expected {expected}, got {result}"
   ```

5. **避免测试间的依赖**: 每个测试应该独立运行

6. **保持测试快速**: 单元测试应该毫秒级完成

7. **合理使用 Mock**: 不要过度 Mock，保持测试接近真实场景

8. **定期运行测试**: 建议配置 CI/CD 自动运行

---

## 常见问题

### Q: 如何测试异常?

```python
import pytest

def test_exception():
    with pytest.raises(ValueError) as exc_info:
        raise ValueError("error message")
    
    assert str(exc_info.value) == "error message"
```

### Q: 如何测试警告?

```python
import warnings
import pytest

def test_warning():
    with warnings.catch_warnings(record=True) as w:
        warnings.warn("deprecated", DeprecationWarning)
        
        assert len(w) == 1
        assert str(w[0].message) == "deprecated"
```

### Q: 如何测试日志输出?

```python
import logging
import pytest

def test_logging(caplog):
    logger = logging.getLogger("test")
    logger.warning("test message")
    
    assert "test message" in caplog.text
```

---

## 资源链接

- 官方文档: https://docs.pytest.org/
- Pytest 插件索引: https://plugincompat.herokuapp.com/
- Awesome Pytest: https://github.com/pytest-dev/pytest

---

> 提示: 在本项目中，所有测试文件位于 `tests/` 目录，运行 `pytest` 即可执行全部测试。