pytest 完整指南 2026：fixture、parametrize 與平行化實測

uv venv .venv
uv pip install --python .venv/bin/python pytest pytest-cov pytest-xdist pytest-asyncio
.venv/bin/python -m pytest --version

demo/
├── app/
│   ├── __init__.py
│   └── pricing.py          # 被測邏輯：折扣、運費、稅
├── tests/
│   ├── conftest.py         # 共用 fixture
│   ├── test_pricing.py     # 17 個測試（含 parametrize 展開）
│   ├── test_scope.py       # fixture 作用域驗證
│   ├── test_async.py       # 非同步測試
│   └── test_slow.py        # 12 個慢速測試，用來量平行化
└── pytest.ini

[pytest]
testpaths = tests
addopts = -ra --strict-markers
asyncio_mode = auto
asyncio_default_fixture_loop_scope = function
markers =
    slow: 慢速測試，可用 -m "not slow" 跳過

from dataclasses import dataclass
from decimal import ROUND_HALF_UP, Decimal

TW_VAT_RATE = Decimal("0.05")


class InvalidCoupon(ValueError):
    """折扣碼不合法時丟出。"""


@dataclass(frozen=True)
class Coupon:
    code: str
    kind: str                      # "percent" 或 "fixed"
    value: Decimal
    min_subtotal: Decimal = Decimal("0")


def apply_coupon(subtotal: Decimal, coupon: Coupon | None) -> Decimal:
    if coupon is None:
        return subtotal
    if coupon.min_subtotal and subtotal < coupon.min_subtotal:
        raise InvalidCoupon(f"{coupon.code} 需滿 {coupon.min_subtotal} 元")
    if coupon.kind == "percent":
        if not (0 < coupon.value <= 100):
            raise InvalidCoupon("百分比折扣需介於 1-100")
        return (subtotal * (1 - coupon.value / 100)).quantize(Decimal("1"), rounding=ROUND_HALF_UP)
    if coupon.kind == "fixed":
        if coupon.value <= 0:
            raise InvalidCoupon("固定折扣需大於 0")
        return max(Decimal("0"), subtotal - coupon.value)
    raise InvalidCoupon(f"未知折扣類型：{coupon.kind}")

@pytest.mark.parametrize(
    "subtotal,coupon,expected",
    [
        (Decimal("1000"), None, Decimal("1000")),
        (Decimal("1000"), Coupon("TEN", "percent", Decimal("10")), Decimal("900")),
        (Decimal("999"), Coupon("TEN", "percent", Decimal("10")), Decimal("899")),
        (Decimal("1000"), Coupon("MINUS100", "fixed", Decimal("100")), Decimal("900")),
        (Decimal("50"), Coupon("MINUS100", "fixed", Decimal("100")), Decimal("0")),
        (Decimal("100"), Coupon("BIG", "fixed", Decimal("100")), Decimal("0")),
    ],
)
def test_apply_coupon(subtotal, coupon, expected):
    assert apply_coupon(subtotal, coupon) == expected

@pytest.mark.parametrize("bad", [
    Coupon("P200", "percent", Decimal("200")),
    Coupon("P0", "percent", Decimal("0")),
    Coupon("ZERO", "fixed", Decimal("0")),
    Coupon("WTF", "bogus", Decimal("5")),
])
def test_invalid_coupon_raises(bad):
    with pytest.raises(InvalidCoupon):
        apply_coupon(Decimal("1000"), bad)


def test_min_subtotal_not_reached():
    c = Coupon("VIP500", "fixed", Decimal("500"), min_subtotal=Decimal("5000"))
    with pytest.raises(InvalidCoupon, match="需滿 5000"):
        apply_coupon(Decimal("1000"), c)

# tests/conftest.py
import pytest


class CallCounter:
    def __init__(self) -> None:
        self.counts = {"function": 0, "module": 0, "session": 0}

    def bump(self, name: str) -> int:
        self.counts[name] += 1
        return self.counts[name]


@pytest.fixture(scope="session")
def counter() -> CallCounter:
    return CallCounter()


@pytest.fixture
def fn_fixture(counter):
    return counter.bump("function")


@pytest.fixture(scope="module")
def module_fixture(counter):
    return counter.bump("module")


@pytest.fixture(scope="session")
def session_fixture(counter):
    return counter.bump("session")

def test_a(session_fixture, module_fixture, fn_fixture):
    assert (session_fixture, module_fixture, fn_fixture) == (1, 1, 1)

def test_b(session_fixture, module_fixture, fn_fixture):
    assert (session_fixture, module_fixture, fn_fixture) == (1, 1, 2)

def test_c(session_fixture, module_fixture, fn_fixture):
    assert (session_fixture, module_fixture, fn_fixture) == (1, 1, 3)

def test_zz_final_counters(counter):
    assert counter.counts == {"function": 3, "module": 1, "session": 1}

@pytest.fixture
def catalog(tmp_path):
    p = tmp_path / "catalog.json"
    p.write_text(json.dumps([
        {"sku": "A001", "name": "機械鍵盤", "price": 3290},
        {"sku": "A002", "name": "滑鼠墊", "price": 390, "qty": 2},
    ], ensure_ascii=False), encoding="utf-8")
    return load_catalog(p)


def test_shipping_threshold_from_env(monkeypatch):
    monkeypatch.setenv("FREE_SHIPPING_THRESHOLD", "2000")
    assert shipping_fee(Decimal("1500")) == Decimal("80")
    assert shipping_fee(Decimal("2000")) == Decimal("0")

class FakeRateClient:
    def __init__(self, rate: str):
        self.rate = Decimal(rate)
        self.calls = 0

    async def get_discount_rate(self, code: str) -> Decimal:
        self.calls += 1
        await asyncio.sleep(0.01)
        return self.rate if code == "TEN" else Decimal("0")


async def test_async_coupon_flow():
    client = FakeRateClient("10")
    rate = await client.get_discount_rate("TEN")
    assert apply_coupon(Decimal("1000"), Coupon("TEN", "percent", rate)) == Decimal("900")
    assert client.calls == 1

.venv/bin/python -m pytest -m "not slow" --cov=app --cov-report=term-missing

Name              Stmts   Miss  Cover   Missing
-----------------------------------------------
app/__init__.py       0      0   100%
app/pricing.py       50      0   100%
-----------------------------------------------
TOTAL                50      0   100%
23 passed, 12 deselected in 0.12s

@pytest.mark.slow
@pytest.mark.parametrize("i", range(12))
def test_sleepy(i):
    time.sleep(0.5)
    assert i >= 0

name: tests
on: [push, pull_request]
jobs:
  pytest:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install -e ".[dev]"
      - run: pytest -m "not slow" --cov=app --cov-report=xml -n auto
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: coverage
          path: coverage.xml