اگر هر بار بعد از تغییر یک تابع در پایپ‌لاین هوش مصنوعی‌تان نگران خراب شدن RAG، API یا ولیدیشن هستید، Pytest همان کمربند ایمنی است که با یک دستور همه‌چیز را چک می‌کند. به‌جای print دستی و تست‌های پراکنده، با Pytest یک فایل test_*.py می‌نویسید، assert ساده می‌گذارید و با pytest -q در چند ثانیه ۵۰ تست را سبز می‌کنید. در tooai.ir از Pytest برای تست ولیدیشن Pydantic تا FastAPI استفاده می‌کنیم؛ این مقاله همان مسیر ۶گامه را با مثال‌های قابل اجرا نشان می‌دهد.

Pytest چیست و چطور در ۳۰ ثانیه اولین تست را می‌سازد؟

Pytest فریم‌ورک تست مدرن پایتون است که تابع معمولی با assert را به تست تبدیل می‌کند؛ نیازی به کلاس و self.assertEqual ندارد، فیکسچرها را تزریق و پارامترها را خودکار می‌چرخاند. کافی است فایل test_demo.py بسازید، یک تابع test_ بنویسید و pytest بزنید. در ادامه نصب، فیکسچر، parametrize، ماک و تست API را گام‌به‌گام می‌خوانید.

فهرست مطالب

پیش‌نیازها و نصب Pytest و pytest-cov
اولین تست Pytest؛ assert ساده و اجرای pytest
فیکسچرها (Fixture) و دامنه اجرا برای تست‌های AI
پارامتری‌سازی با parametrize؛ تست ده‌ها ورودی با یک تابع
ماک کردن API و دیتابیس؛ تست بدون اینترنت و Qdrant
تست ولیدیشن Pydantic و APIهای FastAPI
مقایسه Pytest با unittest و nose2
کاربرد واقعی؛ تست پایپ‌لاین RAG فارسی
پوشش تست (Coverage) و اجرای خودکار در CI
اشتباهات رایج هنگام کار با Pytest
سوالات متداول
جمع‌بندی

پیش‌نیازها و نصب Pytest و pytest-cov

به پایتون ۳.۹+ و یک محیط مجازی تمیز نیاز دارید. Pytest سبک است و با یک دستور نصب می‌شود؛ pytest-cov برای گزارش پوشش کنار آن می‌نشیند.

python -m venv .venv
# ویندوز: .venv\Scripts\activate
source .venv/bin/activate
pip install --upgrade pytest pytest-cov httpx
pytest --version  # باید 8.x باشد
pytest --collect-only  # تست‌ها را بدون اجرا لیست می‌کند

ساختار پیشنهادی: پوشه src/ برای کد و tests/ برای تست‌ها؛ فایل‌ها با test_ شروع شوند.
پیکربندی: فایل pytest.ini یا pyproject.toml با [tool.pytest.ini_options] testpaths = ["tests"].
ویرایشگر: VS Code با افزونه Python و Test Explorer تست‌ها را تک‌کلیک اجرا می‌کند.
نکته AI: برای پروژه‌های RAG، httpx و pytest-mock را هم نصب کنید تا APIها را ماک کنید.

اگر ابزار CLI ساخته‌اید، تست همان CLI را از آموزش Typer در پایتون شروع کنید تا فرمان‌ها را خودکار وارسی کنید.

اولین تست Pytest؛ assert ساده و اجرای pytest

ساده‌ترین تست فقط یک تابع است. Pytest هر assert را هوشمند نمایش می‌دهد و مقدار واقعی/مورد انتظار را کنار هم می‌گذارد.

# src/utils.py
def normalize_text(text: str) -> str:
    return text.strip().replace("  ", " ").replace("\u200c", " ")

# tests/test_utils.py
from src.utils import normalize_text

def test_normalize_removes_extra_spaces():
    assert normalize_text("  سلام   دنیا  ") == "سلام دنیا"

def test_normalize_empty():
    assert normalize_text("") == ""

def test_normalize_half_space():
    assert "\u200c" not in normalize_text("می\u200cخواهم")

pytest -q
# ..F  (نقطه = پاس، F = شکست)
pytest -v  # نام هر تست
pytest -k "normalize"  # فقط تست‌های شامل normalize

نام‌گذاری: فایل test_*.py و تابع test_* الزامی است؛ وگرنه جمع‌آوری نمی‌شود.
assert باهوش: به‌جای self.assertEqual فقط assert a == b بنویسید؛ Pytest تفاوت لیست و دیکشنری را رنگی نشان می‌دهد.
اجرای گزینشی: pytest tests/test_utils.py::test_normalize_empty -vv فقط یک تست را با جزئیات می‌آورد.

فیکسچرها (Fixture) و دامنه اجرا برای تست‌های AI

فیکسچر داده یا سرویس مشترک را یک بار می‌سازد و به هر تست تزریق می‌کند؛ برای لود مدل امبدینگ یا اتصال Qdrant عالی است.

import pytest

@pytest.fixture(scope="module")
def sample_docs():
    return [
        {"id": "doc1", "text": "پایتون زبان هوش مصنوعی است"},
        {"id": "doc2", "text": "Pytest تست خودکار را ساده می‌کند"},
    ]

@pytest.fixture
def tmp_env(monkeypatch):
    monkeypatch.setenv("OPENAI_API_KEY", "sk-test")
    return True

def test_docs_count(sample_docs):
    assert len(sample_docs) == 2

def test_env_is_set(tmp_env, monkeypatch):
    import os
    assert os.getenv("OPENAI_API_KEY") == "sk-test"

scope: function (پیش‌فرض، هر تست)، module (هر فایل)، session (کل اجرا) — برای مدل سنگین scope="session" بگذارید تا یک بار لود شود.
monkeypatch: فیکسچر داخلی برای ست کردن env و ماک تابع بدون کتابخانه اضافی.
yield fixture: با yield می‌توانید بعد از تست، فایل موقتی یا کانکشن را ببندید.

پارامتری‌سازی با parametrize؛ تست ده‌ها ورودی با یک تابع

به‌جای کپی ۱۰ تابع، یک تابع را با ۱۰ ورودی می‌چرخانید؛ برای تست ولیدیشن ایمیل، سن یا طول متن فارسی ایده‌آل است.

import pytest

@pytest.mark.parametrize("raw,expected", [
    ("  سلام ", "سلام"),
    ("", ""),
    ("a  b  c", "a b c"),
    ("می\u200cخواهم", "می خواهم"),
])
def test_normalize_params(raw, expected):
    from src.utils import normalize_text
    assert normalize_text(raw) == expected

@pytest.mark.parametrize("age,should_pass", [(25, True), (-1, False), (200, False), (0, False)])
def test_age_validation(age, should_pass):
    from pydantic import BaseModel, Field, ValidationError
    class User(BaseModel):
        age: int = Field(ge=0, le=120)
    try:
        User(age=age)
        assert should_pass is True
    except ValidationError:
        assert should_pass is False

خوانایی: هر سطر یک کیس؛ Pytest نام کیس را test_normalize_params[سلام-سلام] نشان می‌دهد.
ترکیب با fixture: می‌توانید همزمان fixture و parametrize داشته باشید.
ids سفارشی: با ids=["trim", "empty", ...] نام فارسی بگذارید تا گزارش CI خواناتر شود.

ماک کردن API و دیتابیس؛ تست بدون اینترنت و Qdrant

تست واقعی نباید به اینترنت یا Qdrant واقعی وصل شود؛ با unittest.mock یا pytest-mock پاسخ را جعلی می‌دهید و سرعت ۱۰ برابر می‌شود.

# src/search.py
def search_qdrant(client, query: str, limit: int = 3):
    vec = [0.1, 0.2, 0.3]  # در واقع embed(query)
    return client.search(collection_name="kb", query_vector=vec, limit=limit)

# tests/test_search.py
from unittest.mock import MagicMock

def test_search_calls_qdrant():
    mock_client = MagicMock()
    mock_client.search.return_value = [{"id": "doc1", "score": 0.92}]
    from src.search import search_qdrant
    hits = search_qdrant(mock_client, "سلام", limit=2)
    assert hits[0]["id"] == "doc1"
    mock_client.search.assert_called_once()
    _, kwargs = mock_client.search.call_args
    assert kwargs["limit"] == 2

def test_search_empty(monkeypatch):
    import src.search
    monkeypatch.setattr(src.search, "search_qdrant", lambda c, q, limit=3: [])
    assert src.search.search_qdrant(None, "x") == []

MagicMock: هر متدی را می‌سازد؛ return_value و side_effect برای خطا.
monkeypatch.setattr: تابع واقعی را در زمان تست عوض می‌کند؛ بعد از تست خودکار برمی‌گردد.
چرا مهم: تست RAG با Qdrant واقعی کند و ناپایدار است؛ ماک حافظه را سبک و CI را پایدار می‌کند. جزئیات ذخیره برداری را در آموزش Qdrant ببینید.

تست ولیدیشن Pydantic و APIهای FastAPI

قلب هر سرویس AI، ولیدیشن ورودی با Pydantic و سرویس‌دهی با FastAPI است؛ هر دو را با Pytest و TestClient در یک فایل تست می‌کنید.

from pydantic import BaseModel, Field, ValidationError
import pytest
from fastapi import FastAPI
from fastapi.testclient import TestClient

class AskIn(BaseModel):
    question: str = Field(min_length=10, max_length=500)
    top_k: int = Field(default=3, ge=1, le=10)

app = FastAPI()

@app.post("/ask")
def ask(payload: AskIn):
    return {"answer": f"پاسخ به: {payload.question[:20]}", "sources": []}

client = TestClient(app)

def test_ask_valid():
    resp = client.post("/ask", json={"question": "Pytest چیست و چطور کار می‌کند؟", "top_k": 3})
    assert resp.status_code == 200
    assert "answer" in resp.json()

def test_ask_short_question_fails():
    resp = client.post("/ask", json={"question": "سلام", "top_k": 3})
    assert resp.status_code == 422

def test_pydantic_direct():
    with pytest.raises(ValidationError):
        AskIn(question="کوتاه", top_k=20)

TestClient: بدون اجرای سرور، درخواست HTTP شبیه‌سازی می‌کند؛ httpx نیاز نیست.
422: کد استاندارد FastAPI برای خطای ولیدیشن؛ تست آن جلوی باگ فرانت را می‌گیرد.
pytest.raises: مطمئن می‌شوید مسیر خطا واقعاً ValidationError می‌دهد.

برای ساخت همین API از صفر، آموزش FastAPI در پایتون را گام‌به‌گام دنبال کنید.

مقایسه Pytest با unittest و nose2

معیار	Pytest	unittest (استاندارد)	nose2
نوشتار تست	تابع + assert ساده	کلاس + self.assert*	تابع اما افزونه‌محور
فیکسچر	دکوراتور تزریقی، scope متنوع	setUp/tearDown دستی	setup/teardown محدود
پارامتری‌سازی	@pytest.mark.parametrize داخلی	حلقه دستی یا subTest	افزونه پارامتری
گزارش خطا	رنگی و تفاضلی دقیق	ساده	متوسط
اکوسیستم AI	سازگار با FastAPI، Pydantic، Qdrant	عمومی	قدیمی‌تر
سرعت کشف	بالا، کش هوشمند	متوسط	متوسط

برای پروژه جدید AI، Pytest به‌خاطر فیکسچر و parametrize انتخاب اول است؛ unittest فقط وقتی منطقی است که به وابستگی صفر نیاز دارید.

کاربرد واقعی؛ تست پایپ‌لاین RAG فارسی

سناریوی کامل: نرمال‌سازی سؤال → ولیدیشن Pydantic → جستجو در Qdrant (ماک) → چک خروجی LLM. هر لایه یک تست جدا دارد.

# tests/test_rag_pipeline.py
import pytest
from unittest.mock import MagicMock

def normalize(q: str) -> str:
    return q.strip().replace("  ", " ")

def rag_answer(question: str, mock_client):
    q = normalize(question)
    if len(q) < 10:
        raise ValueError("سؤال کوتاه است")
    hits = mock_client.search(collection_name="kb", query_vector=[0.1]*3, limit=2)
    return {"answer": f"یافته {len(hits)} مدرک", "sources": [h["id"] for h in hits]}

@pytest.fixture
def qdrant_mock():
    m = MagicMock()
    m.search.return_value = [{"id": "doc1"}, {"id": "doc2"}]
    return m

def test_rag_success(qdrant_mock):
    out = rag_answer("آموزش Pytest چیست؟", qdrant_mock)
    assert out["sources"] == ["doc1", "doc2"]
    assert "یافته" in out["answer"]

def test_rag_short_question(qdrant_mock):
    with pytest.raises(ValueError):
        rag_answer("سلام", qdrant_mock)

@pytest.mark.parametrize("q", ["", "   ", "کوتاه"])
def test_rag_invalid_parametrize(q, qdrant_mock):
    with pytest.raises(ValueError):
        rag_answer(q, qdrant_mock)

لایه‌بندی: هر تابع یک مسئولیت؛ تست‌ها هم همان لایه‌ها را جدا چک می‌کنند.
ماک Qdrant: بدون Docker، پایپ‌لاین در ۰.۰۲ ثانیه تست می‌شود.
آماده CI: همین فایل با pytest -q در گیت‌هاب اکشن سبز می‌شود.

پوشش تست (Coverage) و اجرای خودکار در CI

برای رسیدن به پوشش پایدار این ۳ گام را به ترتیب انجام دهید:

گزارش محلی: pytest --cov=src --cov-report=term-missing بزنید و خط‌های قرمز را ببینید.
افزودن تست‌های جاافتاده: برای هر خط قرمز یک کیس parametrize یا pytest.raises اضافه کنید.
قفل CI: در گیت‌هاب اکشن --cov-fail-under=80 بگذارید تا پوشش افت کند PR قرمز شود.

پوشش ۸۰٪ کف حرفه‌ای است؛ با pytest-cov می‌بینید کدام خط اجرا نشده است.

pytest --cov=src --cov-report=term-missing --cov-report=html
# گزارش ترمینالی + پوشه htmlcov/index.html
pytest --cov=src --cov-fail-under=80  # اگر زیر ۸۰٪ باشد، CI را قرمز کن

term-missing: خط‌های پوشش‌نیافته را با شماره نشان می‌دهد.
html: روی هر فایل کلیک کنید؛ خط سبز = تست‌شده، قرمز = جاافتاده.
CI: در گیت‌هاب اکشن: run: pytest --cov=src --cov-fail-under=80؛ اگر افت کرد، PR مرج نمی‌شود.
نکته: پوشش ۱۰۰٪ هدف نیست؛ مسیرهای خطا و edge-case فارسی را اولویت دهید.

اشتباهات رایج هنگام کار با Pytest

نام‌گذاری اشتباه: فایل tests_utils.py یا تابع check_normalize جمع‌آوری نمی‌شود؛ حتماً test_ بگذارید.
استفاده از print به‌جای assert: print در CI دیده نمی‌شود؛ فقط assert شکست را گزارش می‌کند. با pytest -s پرینت را موقت ببینید.
فیکسچر سنگین با scope=function: لود مدل امبدینگ در هر تست ۳۰ ثانیه هدر می‌دهد؛ برای مدل‌ها scope="session" بگذارید.
ماک نکردن I/O: تست که به API واقعی می‌زند، کند و flaky است؛ حتماً monkeypatch یا MagicMock بگذارید.
نادیده گرفتن parametrize: ۱۰ تابع کپی به‌جای یک parametrize، نگهداری را سخت می‌کند.
عدم تست مسیر خطا: فقط حالت سبز را تست نکنید؛ با pytest.raises ولیدیشن منفی را هم پوشش دهید.

سوالات متداول

تفاوت Pytest با unittest چیست؟

unittest کلاس‌محور و پرکد با self.assertEqual است؛ Pytest تابع‌محور با assert ساده، گزارش رنگی و فیکسچر تزریقی است. برای AI که parametrize و ماک زیاد دارد، Pytest کوتاه‌تر و خواناتر است.

آیا برای پروژه کوچک هم Pytest لازم است؟

بله؛ حتی با ۳ تست، Pytest خطای رگرسیون بعد از هر تغییر را همان ثانیه نشان می‌دهد. هزینه نوشتن ۵ دقیقه، صرفه‌جویی ساعت‌ها دیباگ است.

چطور تست‌ها را بدون اینترنت اجرا کنم؟

با unittest.mock.MagicMock کلاینت Qdrant یا OpenAI را ماک کنید و با monkeypatch.setenv کلید را فیک بگذارید. هیچ درخواستی به بیرون نمی‌رود و تست در CI آفلاین هم سبز می‌ماند.

پوشش تست چند درصد کافی است؟

برای سرویس AI، ۸۰٪ خط و ۱۰۰٪ مسیرهای ولیدیشن (Pydantic) کف حرفه‌ای است. خط‌های باقی‌مانده معمولاً لاگ یا شرط نادر است؛ به‌جای ۱۰۰٪ مصنوعی، سناریوهای فارسی واقعی را پوشش دهید.

Pytest با FastAPI چطور کار می‌کند؟

با from fastapi.testclient import TestClient یک کلاینت درون‌حافظه بسازید و با client.post("/ask", json={...}) تست کنید؛ نیازی به اجرای uvicorn نیست و پاسخ ۲۰۰ یا ۴۲۲ را مستقیم می‌گیرید.

جمع‌بندی

Pytest را با pip install pytest pytest-cov نصب و با pytest -q اجرا کنید؛ نام فایل و تابع با test_ باشد.
هر ورودی را با assert ساده چک کنید و با @pytest.mark.parametrize ده‌ها کیس را یکجا پوشش دهید.
داده مشترک را در fixture با scope=session برای مدل‌های سنگین نگه دارید.
API و Qdrant را با MagicMock و monkeypatch ماک کنید تا تست آفلاین و سریع بماند.
ولیدیشن Pydantic و FastAPI را با TestClient و pytest.raises(ValidationError) قفل کنید.
از امروز پوشه tests/ بسازید، همین ۶ گام را پیاده کنید و --cov-fail-under=80 را به CI اضافه کنید — باگ بعدی قبل از دیپلوی لو می‌رود.

آموزش Pytest در پایتون؛ تست‌نویسی خودکار پروژه AI در ۶ گام