# فصل ۰۴ — تست: چرا کدِ داده هم تست می‌خواهد

<div dir="rtl">

# فصل ۰۴ — تست: چرا کدِ داده هم تست می‌خواهد

## در این فصل چه یاد می‌گیری

تا اینجا درستیِ کدت را با **نگاه کردن به خروجی** می‌سنجیدی. این روش تا وقتی جواب می‌دهد که پروژه کوچک باشد و تو تنها کسی باشی که تغییرش می‌دهد. در این فصل همان سنجش را **خودکار** می‌کنی: `assert`، `pytest`، و مهم‌تر از هر دو — چیزی که مخصوصِ پروژه‌های داده است و در آموزش‌های عمومیِ تست‌نویسی نمی‌بینی: **تستِ خودِ داده، و تستِ مدل به شکلی که فردا هم معنا داشته باشد.**

![یک ابزارِ اندازه‌گیریِ چند-شکافه که قطعه‌ها را قبل از عبور می‌سنجد](/lesson-assets/t5-s04-test/prompt/01-image-gauge.png)

آخر این فصل می‌توانی:

- با `assert` انتظارت از یک تابع را ثبت کنی
- چند تست را با `pytest` سازمان بدهی و یک‌جا اجرا کنی
- برای دادهٔ ورودی یک دروازهٔ اعتبارسنجی بنویسی
- بگویی از یک مدل چه چیزی را باید تست کرد و چه چیزی را نباید

## قبل از شروع

**از فصل ۲:** پوشهٔ پروژه، ماژول، و `import`.

**از ترمِ ۲ فصل ۵:** پاک‌سازیِ قیمتِ متنی — همان کار را اینجا در یک تابع می‌بندیم و تستش می‌کنیم.

> 📓 **نوت‌بوک:** [نوت‌بوک این فصل را در Colab باز کن](/notebooks/sarnakh/term-5-shipping/session-04-test.ipynb) — همهٔ کدهای این فصل آماده و به‌ترتیب داخلش هست.

## ۱. `assert`: ثبت کردنِ انتظار

</div>

```python
from pathlib import Path

import pandas as pd

CLEAN_PY = '''import pandas as pd


def clean_price(series):
    """قیمتِ متنی را به عدد تبدیل می‌کند: جداکنندهٔ هزارگان و فاصله را برمی‌دارد."""
    return pd.to_numeric(
        series.astype(str).str.replace(",", "", regex=False).str.strip(),
        errors="coerce",
    )
'''
Path("clean.py").write_text(CLEAN_PY, encoding="utf-8")

import sys
if "" not in sys.path:
    sys.path.insert(0, "")
from clean import clean_price

sample = pd.Series(["12,500,000", " 9800000 ", "نامشخص", "7,000,000"])
result = clean_price(sample)

print(result.tolist())
assert result[0] == 12500000
assert pd.isna(result[2])
print("هر دو assert رد شد بدون خطا")
```

<div dir="rtl">

</div>

```text
[12500000.0, 9800000.0, nan, 7000000.0]
هر دو assert رد شد بدون خطا
```

<div dir="rtl">

`assert` می‌گوید «این باید درست باشد». اگر باشد، هیچ اتفاقی نمی‌افتد و **همان سکوت یعنی موفقیت**. اگر نباشد، `AssertionError`:

</div>

```python
try:
    assert clean_price(pd.Series(["1,000"]))[0] == 999, "قیمت باید ۹۹۹ باشد"
except AssertionError as error:
    print("AssertionError:", error)
```

<div dir="rtl">

</div>

```text
AssertionError: قیمت باید ۹۹۹ باشد
```

<div dir="rtl">

آن متنِ بعد از ویرگول **پیامِ خطاست و اختیاری نیست، لازم است**. بدونِ آن، شش ماه بعد فقط می‌بینی «تستِ خطِ ۴۷ رد شد» و باید کد را بخوانی تا بفهمی چه انتظاری داشتی.

## ۲. `pytest`: وقتی تست‌ها چند تا می‌شوند

سه `assert` در نوت‌بوک قابلِ تحمل است. سی‌تا نه. `pytest` تست‌ها را در فایلِ جدا نگه می‌دارد، همه را با یک دستور اجرا می‌کند، و **مهم‌تر: با اولین خطا نمی‌ایستد** — همه را اجرا می‌کند و گزارشِ کامل می‌دهد.

</div>

```python
TEST_PY = '''import pandas as pd

from clean import clean_price


def test_removes_thousand_separator():
    assert clean_price(pd.Series(["12,500,000"]))[0] == 12500000


def test_strips_spaces():
    assert clean_price(pd.Series([" 9800000 "]))[0] == 9800000


def test_unparsable_becomes_nan():
    assert pd.isna(clean_price(pd.Series(["نامشخص"]))[0])


def test_keeps_length():
    values = pd.Series(["1,000", "bad", "2,000"])
    assert len(clean_price(values)) == len(values)
'''
Path("test_clean.py").write_text(TEST_PY, encoding="utf-8")
print("نوشته شد: test_clean.py")
```

<div dir="rtl">

</div>

```text
نوشته شد: test_clean.py
```

<div dir="rtl">

دو قرارداد که `pytest` بر اساسشان تست‌ها را **خودش پیدا می‌کند** — و رعایت نکردنشان یعنی تستت اجرا نمی‌شود و تو فکر می‌کنی همه‌چیز سبز است:

- نامِ فایل با `test_` شروع شود.
- نامِ تابع با `test_` شروع شود.

و یک قاعدهٔ سوم: تابع هیچ ورودی‌ای نگیرد و چیزی برنگرداند. این یکی بی‌صدا نیست. تابعی که ورودی بگیرد با `ERROR` گزارش می‌شود، و تابعی که به‌جای `assert` مقداری برگرداند می‌گذرد و فقط یک هشدار می‌گیرد، پس چیزی را نسنجیده است.

و **نامِ تست، توضیحِ آن است**: `test_unparsable_becomes_nan` بدونِ خواندنِ بدنه‌اش می‌گوید چه چیزی را تضمین می‌کند.

</div>

```python
import subprocess

run = subprocess.run(
    [sys.executable, "-m", "pytest", "-q", "test_clean.py"],
    capture_output=True, text=True,
)
print("کد خروج pytest:", run.returncode)
print("همه گذشتند:", "failed" not in run.stdout)
```

<div dir="rtl">

</div>

```text
کد خروج pytest: 0
همه گذشتند: True
```

<div dir="rtl">

**کدِ خروجِ صفر یعنی همه‌چیز سبز.** همین عدد است که بعداً یک سامانهٔ خودکار می‌تواند بخواند و جلوی انتشارِ یک نسخهٔ خراب را بگیرد.

> 💡 **نکته:** در Colab معمولاً `!pytest -q` را می‌زنی و گزارشِ رنگی را می‌بینی. اینجا از `subprocess` استفاده کردیم تا همین سلول در یک فایلِ `.py` هم کار کند — همان اصلِ فصلِ ۲.

## ۳. تستِ داده: چیزی که مخصوصِ کارِ ماست

در یک برنامهٔ معمولی، ورودی را برنامه‌نویس تعیین می‌کند. در پروژهٔ داده، **ورودی از دنیای بیرون می‌آید و بی‌خبر عوض می‌شود**: کسی ستونی را تغییرِ نام می‌دهد، یک سامانهٔ دیگر قیمت را به‌صورتِ متن می‌فرستد، یک ردیفِ خراب وارد می‌شود.

**کدت هیچ خطایی نمی‌دهد. فقط نتیجه‌اش غلط می‌شود.**

</div>

```python
from pandas.api.types import is_numeric_dtype

REQUIRED = ["year", "ram_gb", "brand", "city", "price"]
NUMERIC = ["year", "ram_gb", "price"]


def check_data(frame):
    """فهرستِ مشکلاتِ داده. فهرستِ خالی یعنی سالم."""
    problems = [f"ستون {c} نیست" for c in REQUIRED if c not in frame.columns]
    if problems:
        return problems                      # بدونِ ستون، سنجشِ مقدارها بی‌معناست

    problems = [f"ستون {c} عددی نیست" for c in NUMERIC if not is_numeric_dtype(frame[c])]
    if problems:
        return problems                      # با نوعِ غلط، مقایسه‌ها خطا می‌دهند

    if frame["price"].min() <= 0:
        problems.append("قیمت غیرمثبت دارد")
    if not frame["year"].between(2015, 2026).all():
        problems.append("سال خارج از بازهٔ منطقی")
    if frame["price"].isna().any():
        problems.append("قیمت خالی دارد")
    if frame.duplicated().any():
        problems.append("ردیف تکراری دارد")
    return problems


clean = pd.read_csv("laptops_clean.csv")
raw = pd.read_csv("laptops.csv")
broken = clean.copy()
broken.loc[5, "price"] = -1
broken.loc[9, "year"] = 1999

print("دادهٔ پاک‌شده    :", check_data(clean))
print("دادهٔ خام        :", check_data(raw))
print("دادهٔ دستکاری‌شده:", check_data(broken))
```

<div dir="rtl">

</div>

```text
دادهٔ پاک‌شده    : []
دادهٔ خام        : ['ستون price عددی نیست']
دادهٔ دستکاری‌شده: ['قیمت غیرمثبت دارد', 'سال خارج از بازهٔ منطقی']
```

<div dir="rtl">

**آن دو `return` زودهنگام، طراحیِ عمدی‌اند و همان چیزی‌اند که این تابع را از یک تابعِ شکننده جدا می‌کند.** بدونِ آن‌ها، `frame["price"].min() <= 0` روی دادهٔ خام `TypeError` می‌داد — چون قیمت هنوز متن است. **بررسی را از کلی به جزئی مرتب کن: ستون‌ها، بعد نوع‌ها، بعد مقدارها.** هر لایه فرض می‌کند لایهٔ قبل درست بوده.

> 📏 **اندازه بگیر:** این دروازه را **در ابتدای هر مسیرِ پردازشِ داده** بگذار، نه در انتها. یک ردیفِ خراب که وارد آموزش شود، نه خطا می‌دهد و نه معلوم می‌شود — فقط عددت را کمی بدتر می‌کند و تو ماه‌ها دنبالِ مقصر می‌گردی. **هزینهٔ این تابع پنج دقیقه است؛ هزینهٔ نداشتنش می‌تواند یک فصل باشد.**

## ۴. تستِ مدل: چه چیزی را باید تست کرد

اینجا رایج‌ترین اشتباه پیش می‌آید. وسوسه می‌شوی بنویسی:

</div>

```python-broken
def test_model_accuracy():
    assert model.score(X_test, y_test) == 1381886
```

<div dir="rtl">

**این تستِ بدی است**، به سه دلیل: با هر نسخهٔ تازهٔ `scikit-learn` می‌شکند، با هر تغییرِ داده می‌شکند، و مهم‌تر — **حتی وقتی می‌شکند به تو نمی‌گوید چیزی خراب شده، فقط می‌گوید چیزی عوض شده.**

تستِ خوب **قرارداد** را می‌سنجد، نه عددِ دقیق را:

</div>

```python
from sklearn.compose import ColumnTransformer
from sklearn.dummy import DummyRegressor
from sklearn.impute import SimpleImputer
from sklearn.linear_model import Ridge
from sklearn.metrics import mean_absolute_error
from sklearn.model_selection import train_test_split
from sklearn.pipeline import Pipeline
from sklearn.preprocessing import OneHotEncoder, StandardScaler

# در پروژهٔ واقعی این همان PriceModel فصل ۲ است؛ اینجا مستقیم می‌سازیمش
# تا این نوت‌بوک بدونِ هیچ فایلِ بیرونی کار کند.
model = Pipeline([
    ("prepare", ColumnTransformer([
        ("num", Pipeline([("fill", SimpleImputer(strategy="median")),
                          ("scale", StandardScaler())]), ["year", "ram_gb"]),
        ("cat", OneHotEncoder(handle_unknown="ignore"), ["brand", "city"]),
    ])),
    ("model", Ridge(alpha=0.1)),
])

X = clean[["year", "ram_gb", "brand", "city"]]
y = clean["price"]
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=0)

model.fit(X_train, y_train)
baseline = DummyRegressor(strategy="median").fit(X_train, y_train)

model_mae = mean_absolute_error(y_test, model.predict(X_test))
baseline_mae = mean_absolute_error(y_test, baseline.predict(X_test))

print("MAE مدل    :", round(model_mae))
print("MAE خط پایه:", round(baseline_mae))
print("دستِ‌کم دو برابر بهتر از خط پایه:", bool(model_mae < baseline_mae / 2))
```

<div dir="rtl">

</div>

```text
MAE مدل    : 1381886
MAE خط پایه: 7793750
دستِ‌کم دو برابر بهتر از خط پایه: True
```

<div dir="rtl">

**«دستِ‌کم دو برابر بهتر از خطِ پایه» تستی است که فردا هم معنا دارد.** عوض شدنِ نسخه یا داده آن را نمی‌شکند، ولی اگر کسی ستونِ `brand` را از `Pipeline` بیندازد، **فوراً** می‌شکند.

</div>

| تست کن | تست نکن |
|---|---|
| تابع‌های پاک‌سازیِ خودت | خودِ `scikit-learn` |
| شکل و نوعِ خروجیِ مدل | عددِ دقیقِ متریک |
| «بهتر از خطِ پایه» | «دقیقاً برابرِ فلان عدد» |
| اینکه پیش‌بینی برای ورودیِ ناشناخته خطا ندهد | کیفیتِ پیش‌بینی برای یک ردیفِ خاص |
| اینکه داده به قرارداد پایبند است | اینکه داده «خوب» است (تعریف‌ناپذیر) |

<div dir="rtl">

> ✅ **چک کن:** قبل از اینکه به یک تست اعتماد کنی، **عمداً بشکنش**. یکی از ستون‌ها را از فهرست‌های `ColumnTransformer` بردار، مدل را دوباره آموزش بده، و ببین تستِ «دو برابر بهتر» واقعاً قرمز می‌شود یا نه. برداشتنِ ستون فقط از `X` این آزمایش نیست، چون `ColumnTransformer` آن ستون را می‌خواهد و با `ValueError` می‌ایستد. **تستی که هرگز شکسته نشده، ممکن است اصلاً چیزی را نسنجد** — و این رایج‌تر از چیزی است که فکر می‌کنی.

> 🔧 **اگر کار نکرد:** خطای `ModuleNotFoundError` هنگامِ اجرای `pytest` تقریباً همیشه یک علت دارد: `pytest` از پوشه‌ای اجرا می‌شود که ماژولِ تو در مسیرش نیست. **از ریشهٔ پروژه اجرایش کن**، نه از داخلِ پوشهٔ تست‌ها. و اگر تستی به فایلِ داده نیاز دارد، مسیرش را نسبت به ریشهٔ پروژه بنویس، نه نسبت به فایلِ تست.

> 🤖 **از دستیارت بپرس:** تابعِ `check_data` را به دستیارت بده و بپرس: «چه بررسی‌های دیگری برای این داده منطقی است؟» **بعد هر پیشنهاد را با یک سؤال بسنج: اگر این بررسی قرمز شود، من دقیقاً چه کاری می‌کنم؟** اگر جوابی نداری، آن بررسی فقط سروصداست و باید حذفش کنی. تستی که به آن اهمیت نمی‌دهی، بدتر از نداشتنِ تست است — چون به قرمزها عادت می‌کنی.

## واژه‌های تازهٔ این فصل

</div>

| کلمه | تلفظ به حروف فارسی | یعنی چه |
|---|---|---|
| assert | اَسِرت | «این باید درست باشد»، وگرنه خطا |
| pytest | پای‌تست | ابزارِ پیدا کردن و اجرای خودکارِ تست‌ها |
| test suite | تست سوییت | مجموعهٔ تست‌های یک پروژه |
| data validation | ولیدیشن داده | سنجشِ داده در برابرِ قرارداد، قبل از استفاده |
| regression test | ری‌گرشن تست | تستی که جلوی برگشتِ یک خطای رفع‌شده را می‌گیرد |

<div dir="rtl">

## تمرین‌ها

قبل از تمرین، بدونِ نگاه به بالا جواب بده: چرا `assert mae == 1381886` تستِ بدی است؟

**تمرینِ اجباری:** برای تابعِ `check_data` یک فایلِ `test_data.py` بنویس با دستِ‌کم پنج تست: یکی برای دادهٔ سالم، و چهارتا که هر کدام **یک** خرابیِ متفاوت را می‌سازند و انتظار دارند دقیقاً همان یکی گزارش شود. **مطمئن شو هر تست فقط یک چیز را می‌سنجد** — تستی که سه چیز را با هم چک می‌کند، وقتی قرمز شود نمی‌گوید کدامش خراب بود.

**تمرینِ ستاره‌دار ⭐:** یک تستِ «رگرسیون» بنویس: عمداً یک باگ در `clean_price` بگذار (مثلاً `str.strip()` را بردار)، ببین آیا تستی قرمز می‌شود، بعد باگ را برگردان. **حالا فکر کن اگر هیچ تستی قرمز نشد، چه چیزی دربارهٔ مجموعهٔ تستت فهمیدی؟** جوابت را بنویس — این همان سؤالی است که یک تیمِ حرفه‌ای بعد از هر رخداد از خودش می‌پرسد.

## در فصل بعد

کدت تست دارد و داده‌ات دروازه دارد. ولی هنوز فقط **تو** می‌توانی به‌کارش ببری. فصلِ بعد این را عوض می‌کند: یک رابطِ گرافیکی که هر کسی بتواند بدونِ دیدنِ یک خط کد ازش استفاده کند — با `Gradio` و در چند خط.

</div>

---
Source: https://yaadestan.com/courses/sarnakh/lessons/t5/s04-test (یادستان, Yaadestan)
