اگر تست‌های پایتون شما فقط چند حالت دستی را بررسی می‌کنند، Hypothesis می‌تواند جای خالی را پر کند: به‌جای نوشتن ده‌ها assert تکراری، یک ویژگی عمومی تعریف می‌کنید و کتابخانه صدها ورودی تصادفی، شامل حالت‌های مرزی، را می‌آزماید. در این آموزش از نصب و اولین تست شروع می‌کنیم، استراتژی‌ها، shrinking، تنظیمات Pytest و تست آرایه‌های NumPy را می‌بینیم و در پایان یک چک‌لیست عملی برای وارد کردن Hypothesis به پروژه‌های داده و هوش مصنوعی دارید.

آموزش Hypothesis در پایتون چیست و چه کاری انجام می‌دهد؟

Hypothesis یک کتابخانه تست مبتنی بر ویژگی (property-based testing) برای پایتون است: شما دامنه ورودی را با استراتژی تعریف می‌کنید و کتابخانه نمونه‌های تصادفی و مرزی می‌سازد، خطا را کوچک می‌کند و ساده‌ترین ورودی شکست را نشان می‌دهد. برای پروژه‌های داده و AI که ورودی‌های متنوع دارند، مکمل خوبی برای Pytest است. در ادامه، نصب و اولین تست را قدم‌به‌قدم می‌بینید.

فهرست مطالب

Hypothesis چیست و چرا تست معمولی کافی نیست؟
نصب و اولین تست مبتنی بر ویژگی
استراتژی‌های پرکاربرد Hypothesis
ساخت استراتژی سفارشی با composite
تست داده‌های NumPy در پروژه‌های AI
تنظیمات، Shrinking و بازتولید خطا
اجرا در CI و کنار Pytest
اشتباهات رایج در استفاده از Hypothesis
سوالات متداول
جمع‌بندی و چک‌لیست

Hypothesis چیست و چرا تست معمولی کافی نیست؟

در تست معمولی، شما یک ورودی مشخص می‌دهید و یک خروجی مشخص انتظار دارید؛ مثلاً «جمع ۲ و ۳ برابر ۵ است». این روش برای مستند کردن رفتار و جلوگیری از بازگشت باگ ضروری است، اما فقط همان حالت‌هایی را پوشش می‌دهد که به ذهن شما رسیده است. Hypothesis سؤال را عوض می‌کند: «برای هر عدد صحیح a و b، آیا a + b با b + a برابر است؟» سپس خودش ورودی‌های مختلف را می‌سازد و به دنبال نقض ویژگی می‌گردد.

مزیت اصلی، ترکیب تولید تصادفی با shrinking است. وقتی تست شکست می‌خورد، Hypothesis فقط یک ورودی بزرگ و شلوغ نشان نمی‌دهد؛ آن را مرحله‌به‌مرحله کوچک‌تر می‌کند تا به کمترین ورودی ممکن برسد که همان باگ را تکرار می‌کند. این کار تشخیص علت را بسیار ساده‌تر می‌کند. به‌طور پیش‌فرض، هر تست حدود ۱۰۰ نمونه اجرا می‌شود، اما این عدد با تنظیمات قابل تغییر است.

Hypothesis جایگزین تست‌های نمونه‌محور نیست. بهترین نتیجه وقتی می‌آید که تست‌های ساده و خوانا را برای حالت‌های مشخص نگه دارید و برای قوانین عمومی، داده‌های حجیم و ورودی‌های نامرتب از تست مبتنی بر ویژگی استفاده کنید.

نصب و اولین تست مبتنی بر ویژگی

پیش‌نیاز این آموزش پایتون ۳.۱۱ یا بالاتر و آشنایی مقدماتی با Pytest است. نسخه پایدار فعلی Hypothesis (6.170) نیز همین حداقل نسخه پایتون را اعلام می‌کند. نصب ساده است:

python -m pip install hypothesis
# اگر می‌خواهید از استراتژی‌های NumPy استفاده کنید:
python -m pip install "hypothesis[numpy]"

یک فایل به نام test_properties.py بسازید و اولین تست را بنویسید:

from hypothesis import given, strategies as st


def reverse_twice(items):
    return list(reversed(list(reversed(items))))


@given(st.lists(st.integers()))
def test_reverse_twice_is_identity(items):
    assert reverse_twice(items) == items

با اجرای pytest -q این تست باید سبز شود. نکته مهم این است که خودتان تابع تست را با ورودی صدا نمی‌زنید؛ decorator @given این کار را انجام می‌دهد. st.lists(st.integers()) می‌گوید «لیستی از اعداد صحیح، با هر طولی» و Hypothesis نمونه‌های متنوعی از جمله لیست خالی، لیست تک‌عضوی و لیست‌های بزرگ‌تر می‌سازد.

حالا یک باگ واقعی را ببینید. فرض کنید میانگین یک لیست را بدون توجه به حالت خالی نوشته‌اید:

from hypothesis import given, strategies as st


def average(values):
    return sum(values) / len(values)


@given(st.lists(st.floats(allow_nan=False, allow_infinity=False)))
def test_average_is_bounded(values):
    result = average(values)
    assert min(values) <= result <= max(values)

Hypothesis خیلی زود لیست خالی را پیدا می‌کند و پس از shrinking، ورودی values=[] را نشان می‌دهد. این همان حالت مرزی است که در تست دستی معمولاً فراموش می‌شود. برای اصلاح، قرارداد تابع را روشن کنید:

def average(values):
    if not values:
        return 0.0
    return sum(values) / len(values)


@given(st.lists(st.floats(allow_nan=False, allow_infinity=False)))
def test_average_is_bounded(values):
    result = average(values)
    if not values:
        assert result == 0.0
    else:
        assert min(values) <= result <= max(values)

این مثال نشان می‌دهد که تست مبتنی بر ویژگی، «تست نوشتن» را به «تعریف قرارداد» تبدیل می‌کند. اگر قرارداد مبهم باشد، Hypothesis آن ابهام را با یک ورودی واقعی جلوی چشم شما می‌آورد.

استراتژی‌های پرکاربرد Hypothesis

استراتژی، زبان توصیف ورودی‌هاست. چند استراتژی که در بیشتر پروژه‌ها کافی است:

استراتژی	کاربرد
`st.integers(min_value=0, max_value=100)`	اعداد صحیح در یک بازه مشخص
`st.floats(allow_nan=False, allow_infinity=False)`	اعداد اعشاری بدون NaN و بی‌نهایت
`st.text(min_size=1, max_size=50)`	رشته‌های کوتاه برای نام، برچسب یا ورودی کاربر
`st.lists(st.integers(), min_size=0, max_size=100)`	لیست با طول کنترل‌شده
`st.dictionaries(keys=st.text(), values=st.integers())`	ساختارهای کلید-مقدار
`st.sampled_from(["fast", "balanced", "accurate"])`	انتخاب از میان گزینه‌های مجاز
`st.datetimes()` و `st.dates()`	ورودی‌های زمانی و تاریخ

برای ترکیب دو نوع ورودی می‌توانید از عملگر | استفاده کنید؛ مثلاً st.integers() | st.floats(). برای حذف حالت‌های نامعتبر، اول .filter() را امتحان کنید و اگر شرط پیچیده بود، در بدنه تست از assume() استفاده کنید. توجه داشته باشید که فیلتر کردن زیاد، سرعت تولید نمونه را پایین می‌آورد و ممکن است هشدار filter_too_much بدهد؛ در چنین حالتی بهتر است استراتژی را دقیق‌تر بسازید، نه اینکه فیلتر را سنگین‌تر کنید.

ساخت استراتژی سفارشی با composite

گاهی ورودی‌ها به هم وابسته‌اند؛ مثلاً تاریخ پایان نباید قبل از تاریخ شروع باشد. @st.composite اجازه می‌دهد ورودی دوم را بر اساس ورودی اول بسازید:

from datetime import date

from hypothesis import given, strategies as st


@st.composite
def date_ranges(draw):
    start = draw(st.dates(min_value=date(2020, 1, 1)))
    end = draw(st.dates(min_value=start))
    return start, end


@given(date_ranges())
def test_date_range_is_ordered(date_range):
    start, end = date_range
    assert start <= end

تابع date_ranges یک استراتژی می‌سازد، نه یک مقدار. هر بار که Hypothesis آن را صدا می‌زند، draw یک مقدار از استراتژی داخلی بیرون می‌کشد. این الگو برای ساخت ورودی‌های واقعی مثل رکوردهای کاربر، تنظیمات مدل یا بازه‌های زمانی بسیار مفید است و از تولید داده‌های نامعتبر و سپس فیلتر کردن آن‌ها جلوگیری می‌کند.

تست داده‌های NumPy در پروژه‌های AI

در پروژه‌های یادگیری ماشین، بخش زیادی از باگ‌ها در پیش‌پردازش داده، نرمال‌سازی و تبدیل شکل آرایه‌ها رخ می‌دهد؛ نه در خود مدل. ماژول hypothesis.extra.numpy می‌تواند ماتریس‌های تصادفی با dtype و شکل مشخص بسازد. مثال زیر نرمال‌سازی سطری را بررسی می‌کند:

import numpy as np
from hypothesis import given, strategies as st
from hypothesis.extra.numpy import arrays


def normalize_rows(matrix):
    norms = np.linalg.norm(matrix, axis=1, keepdims=True)
    return matrix / norms


@given(
    arrays(
        dtype=np.float64,
        shape=(4, 3),
        elements=st.floats(
            min_value=0.1,
            max_value=100,
            allow_nan=False,
            allow_infinity=False,
        ),
    )
)
def test_normalize_rows_unit_norm(matrix):
    result = normalize_rows(matrix)
    assert np.allclose(np.linalg.norm(result, axis=1), 1.0)

این تست صدها ماتریس با مقادیر متفاوت می‌سازد و مطمئن می‌شود طول هر سطر بعد از نرمال‌سازی برابر یک است. برای داده‌های جدولی نیز hypothesis.extra.pandas امکان ساخت DataFrame با ستون‌های مشخص را می‌دهد. اگر شکل آرایه ثابت نیست، می‌توانید شکل را هم به‌صورت استراتژی تعریف کنید؛ اما برای شروع، شکل ثابت خواناتر است و همان باگ‌های منطقی را پیدا می‌کند. در تست مدل‌های سنگین، Hypothesis را فقط برای توابع قطعی پیش‌پردازش و اعتبارسنجی به کار ببرید، نه برای آموزش واقعی مدل.

تنظیمات، Shrinking و بازتولید خطا

تعداد نمونه‌ها و زمان‌بندی را می‌توان با @settings کنترل کرد:

from hypothesis import given, settings, strategies as st


@settings(max_examples=300, deadline=None)
@given(st.lists(st.integers(), max_size=50))
def test_sort_is_idempotent(values):
    assert sorted(sorted(values)) == sorted(values)

max_examples تعداد نمونه‌ها را تعیین می‌کند و مقدار پیش‌فرض آن ۱۰۰ است. deadline=None محدودیت زمانی هر نمونه را غیرفعال می‌کند و برای تست‌های کند یا محیط CI پرنوسان مناسب است. Hypothesis ورودی‌های شکست‌خورده را در پوشه .hypothesis ذخیره می‌کند تا اجرای بعدی سریع‌تر همان خطا را تکرار کند. برای اینکه یک حالت خاص همیشه اجرا شود، از @example() استفاده کنید؛ مثلاً @example([]) بالای تست میانگین. اگر خروجی خطا یک decorator با نام @reproduce_failure نشان داد، آن را فقط موقتاً برای بازتولید اضافه کنید و بعد از رفع باگ حذف کنید؛ این blob بین نسخه‌ها پایدار نیست.

اجرا در CI و کنار Pytest

Hypothesis یک افزونه Pytest است و با fixtureها و @pytest.mark.parametrize کنار می‌آید. برای اجرای سریع در توسعه و اجرای عمیق‌تر در CI می‌توانید پروفایل تنظیمات بسازید:

# conftest.py
from hypothesis import settings

settings.register_profile("ci", max_examples=500, deadline=None)
settings.load_profile("ci")

سپس در CI همان pytest -q را اجرا کنید یا با pytest --hypothesis-profile ci پروفایل را انتخاب کنید. اگر تازه با Pytest شروع کرده‌اید، راهنمای آموزش Pytest در پایتون نقطه شروع خوبی است. برای مرتب نگه داشتن کد و جلوگیری از ورود خطاهای ساده، ترکیب Pytest با یک لینتر سریع مثل آموزش Ruff در پایتون منطقی است. در CI تعداد نمونه‌ها را بی‌دلیل بالا نبرید؛ زمان اجرا به‌سرعت زیاد می‌شود و ارزش افزوده‌اش کم است.

اشتباهات رایج در استفاده از Hypothesis

تعریف نکردن ویژگی روشن: اگر فقط خروجی را با یک مقدار ثابت مقایسه کنید، تست مبتنی بر ویژگی به یک تست تصادفی بی‌فایده تبدیل می‌شود. ویژگی باید برای همه ورودی‌های دامنه درست باشد.
استفاده بیش از حد از assume و filter: فیلتر سنگین باعث کندی و هشدار filter_too_much می‌شود. دامنه را دقیق‌تر توصیف کنید یا از @st.composite کمک بگیرید.
تست کدهای غیرقطعی: زمان سیستم، شبکه، فایل و random جهانی نتیجه را شکننده می‌کنند. وابستگی‌ها را تزریق یا mock کنید و برای اعداد تصادفی از استراتژی مناسب استفاده کنید.
بالا بردن max_examples به‌جای اصلاح استراتژی: اگر تست کند است، اول دامنه ورودی و deadline را بررسی کنید؛ افزایش کورکورانه نمونه‌ها فقط CI را کند می‌کند.
اتکا به دیتابیس نمونه‌ها به‌جای @example: دیتابیس برای تکرار سریع محلی است، اما ممکن است با ارتقا یا تغییر کد بی‌اعتبار شود. حالت‌های مهم را با @example ثبت کنید.

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

آیا Hypothesis جایگزین Pytest است؟

نه. Hypothesis یک افزونه و رویکرد مکمل برای Pytest است. تست‌های معمولی را برای نمونه‌های مشخص و مستندسازی رفتار نگه دارید و تست‌های مبتنی بر ویژگی را برای قوانین عمومی و ورودی‌های متنوع اضافه کنید. هر دو در یک پروژه و حتی در یک فایل کنار هم کار می‌کنند.

Shrinking در Hypothesis چه فایده‌ای دارد؟

Shrinking ورودی شکست‌خورده را به کوچک‌ترین حالت ممکن کاهش می‌دهد که هنوز باگ را نشان می‌دهد. به‌جای دیدن یک لیست ۵۰۰ عضوی، معمولاً لیست خالی یا یک عدد مرزی می‌بینید. این کار علت‌یابی را سریع‌تر و گزارش باگ را قابل‌فهم‌تر می‌کند.

آیا Hypothesis برای پروژه‌های هوش مصنوعی مناسب است؟

برای بخش‌های قطعی پروژه مثل پاکسازی داده، مهندسی ویژگی، نرمال‌سازی، اعتبارسنجی ورودی و توابع امتیازدهی بسیار مناسب است. برای آموزش مدل‌های سنگین یا فراخوانی APIهای پرهزینه، آن را در لایه‌های کوچک و با تعداد نمونه کم به کار ببرید.

چرا تست‌های Hypothesis در CI کند می‌شوند؟

هر نمونه ممکن است چند میلی‌ثانیه یا بیشتر طول بکشد و با افزایش max_examples زمان خطی بالا می‌رود. علاوه بر آن، تست‌های دارای I/O یا مدل‌های سنگین هزینه‌بر هستند. برای CI پروفایل جدا با تعداد نمونه متعادل و deadline=None تعریف کنید.

آیا می‌توان از Hypothesis برای NumPy و Pandas استفاده کرد؟

بله. ماژول‌های hypothesis.extra.numpy و hypothesis.extra.pandas برای ساخت آرایه و DataFrame طراحی شده‌اند. برای نصب وابستگی‌های سازگار، از pip install "hypothesis[numpy]" استفاده کنید و نسخه کتابخانه‌ها را در پروژه قفل نگه دارید.

آیا باید همه تست‌ها را با Hypothesis بنویسم؟

نه. تست‌های ساده و مشخص را همان‌طور که هستند نگه دارید. Hypothesis را جایی به کار ببرید که دامنه ورودی بزرگ، حالت‌های مرزی زیاد یا منطق مشترک بین بسیاری از ورودی‌ها وجود دارد. این انتخابی بودن، سرعت و خوانایی تست‌ها را حفظ می‌کند.

جمع‌بندی و چک‌لیست

Hypothesis با تولید ورودی‌های متنوع و shrinking، لایه‌ای ارزشمند به تست‌های پایتون اضافه می‌کند؛ به شرطی که ویژگی‌ها را دقیق تعریف کنید و آن را جایگزین تست‌های نمونه‌محور ندانید. برای شروع، این چک‌لیست را دنبال کنید:

Hypothesis را نصب کنید و یک تست کوچک با @given بنویسید.
برای هر تابع مهم، یک ویژگی عمومی و قابل‌اثبات تعریف کنید.
حالت‌های مرزی مثل لیست خالی، صفر، NaN و رشته خالی را با استراتژی پوشش دهید.
ورودی‌های وابسته را با @st.composite بسازید، نه با فیلتر سنگین.
خطاهای واقعی را با @example به تست دائمی تبدیل کنید.
برای CI پروفایل تنظیمات جدا و زمان اجرای متعادل داشته باشید.
تست‌های داده را با NumPy و Pandas گسترش دهید، اما مدل‌های سنگین را خارج از این حلقه نگه دارید.

با همین چند قدم، پروژه پایتون شما در برابر ورودی‌هایی که هیچ‌وقت به ذهن نمی‌رسیدند مقاوم‌تر می‌شود.

آموزش Hypothesis در پایتون؛ تست مبتنی بر ویژگی از صفر