اگر در پروژه پایتون خودتان چند بار کد را اصلاح می‌کنید و تازه بعد از ادغام متوجه خطای قالب‌بندی، تست خراب یا وابستگی ناسازگار می‌شوید، وقت آن است که کنترل کیفیت را از حالت دستی خارج کنید. ترکیب Ruff، Pytest و GitHub Actions یک زنجیره سبک و کاربردی می‌سازد که قبل از ورود کد به شاخه اصلی، خطاهای رایج را پیدا می‌کند. در این راهنما از ساختار پوشه‌ها تا اجرای خودکار در هر Pull Request را قدم‌به‌قدم می‌بینید.

پاسخ کوتاه: بهترین روش خودکارسازی کیفیت کد پایتون چیست؟

برای شروع، Ruff را برای lint و قالب‌بندی، Pytest را برای تست و GitHub Actions را برای اجرای هر دو ابزار روی هر تغییر استفاده کنید. تنظیمات را در pyproject.toml متمرکز کنید تا تمام اعضای تیم و محیط CI از یک قانون پیروی کنند. جزئیات این زنجیره و خطاهای متداول را در ادامه می‌خوانید.

چرا باید کیفیت کد پایتون را خودکار کنیم؟

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

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

سه لایه اصلی کنترل کیفیت

Lint: مشکلات احتمالی و الگوهای بد کدنویسی را گزارش می‌کند.
Format: ظاهر فایل‌ها را یکدست می‌کند تا اختلاف‌های غیرضروری در Pull Request کمتر شود.
Test: رفتار واقعی برنامه را با مثال‌های قابل تکرار بررسی می‌کند.

انتخاب Ruff، Pytest و GitHub Actions

Ruff یک ابزار سریع و کم‌وابستگی برای lint و format پروژه‌های پایتون است و در بسیاری از پروژه‌ها می‌تواند جای چند ابزار جداگانه را بگیرد. Pytest برای نوشتن تست‌های خوانا و قابل توسعه مناسب است و با fixtureها، پارامترها و افزونه‌های مختلف رشد می‌کند. GitHub Actions نیز محیط اجرای موقت در خود مخزن فراهم می‌کند؛ بنابراین لازم نیست هر توسعه‌دهنده تنظیمات CI را جداگانه روی سیستمش نگه دارد.

ابزار	کار اصلی	زمان استفاده	خروجی مورد انتظار
Ruff check	پیدا کردن خطاهای سبک و منطقی	قبل از commit و در CI	گزارش خطا با شماره خط
Ruff format	یکدست کردن قالب کد	هنگام ذخیره یا قبل از ارسال	فایل مرتب و استاندارد
Pytest	آزمودن رفتار برنامه	پس از هر تغییر مهم	گزارش تست‌های موفق یا شکست‌خورده
GitHub Actions	اجرای خودکار زنجیره	Push و Pull Request	وضعیت سبز یا قرمز در مخزن

ساختار پیشنهادی پروژه برای اجرای تست خودکار

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

project/
├── src/app/
├── tests/
│   ├── test_users.py
│   └── conftest.py
├── pyproject.toml
├── requirements.txt
└── .github/workflows/quality.yml

اگر پکیج شما داخل src قرار دارد، نصب پروژه در حالت editable را در محیط توسعه و CI در نظر بگیرید. این کار از خطاهایی جلوگیری می‌کند که فقط به دلیل مسیر import روی یک سیستم رخ می‌دهند. فایل conftest.py را هم برای fixtureهای مشترک نگه دارید، نه برای منطق محصول.

نصب ابزارها در محیط توسعه

در یک محیط مجازی تازه، ابزارها را به وابستگی‌های توسعه اضافه کنید:

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install ruff pytest
pip freeze > requirements-dev.txt

در ویندوز به جای دستور فعال‌سازی بالا از .venv\Scripts\activate استفاده می‌شود. بهتر است نسخه ابزارها را در فایل وابستگی قفل کنید تا اجرای CI با لپ‌تاپ اعضای تیم تفاوت غیرمنتظره نداشته باشد.

تنظیم Ruff در pyproject.toml

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

[tool.ruff]
line-length = 100
target-version = "py311"

[tool.ruff.lint]
select = ["E", "F", "I", "B"]
ignore = ["E501"]

[tool.ruff.format]
quote-style = "double"
indent-style = "space"

قانون‌های F خطاهای واقعی مانند متغیر تعریف‌نشده را هدف می‌گیرند، I importها را مرتب می‌کند و B الگوهای مستعد خطا را بررسی می‌کند. مجموعه قوانین را از روز اول بیش از حد بزرگ نکنید؛ چند قانون روشن که تیم می‌فهمد، از ده‌ها هشدار نادیده‌گرفته‌شده ارزشمندتر است.

تفاوت check و format

فرمان ruff check . فقط بررسی می‌کند و در صورت وجود خطا کد خروجی ناموفق می‌دهد. فرمان ruff format . فایل‌ها را تغییر می‌دهد. در CI معمولاً از ruff format --check . استفاده کنید تا سیستم فایل مخزن را دستکاری نکند و فقط بگوید کدام فایل به قالب استاندارد نیاز دارد.

نوشتن تست‌های قابل اعتماد با Pytest

تست خوب باید یک رفتار را بررسی کند، سریع اجرا شود و در صورت شکست علت روشنی داشته باشد. به جای تست کردن جزئیات داخلی، ورودی و خروجی قابل مشاهده تابع را بررسی کنید. برای نمونه:

def normalize_email(value: str) -> str:
    return value.strip().lower()

def test_normalize_email_removes_spaces_and_lowercases():
    assert normalize_email("  User@Example.COM ") == "user@example.com"

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

import pytest

@pytest.mark.parametrize("raw, expected", [
    (" Ali ", "ali"),
    ("TEST@MAIL.COM", "test@mail.com"),
])
def test_normalize_email(raw, expected):
    assert normalize_email(raw) == expected

مدیریت تست‌های کند و وابسته به سرویس

تست‌هایی که به شبکه، پایگاه داده یا سرویس بیرونی وصل می‌شوند، نباید اجرای روزمره را غیرقابل پیش‌بینی کنند. آن‌ها را با marker جدا کنید و در تست واحد از mock یا fixture کنترل‌شده استفاده کنید. اگر یک تست به ساعت، تصادف یا فایل موقت وابسته است، همان وابستگی را صریح و قابل تزریق طراحی کنید.

ساخت workflow در GitHub Actions

حالا فایل .github/workflows/quality.yml را بسازید. این workflow با هر Push و Pull Request اجرا می‌شود:

name: Python quality

on:
  push:
  pull_request:

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements-dev.txt
      - name: Lint
        run: ruff check .
      - name: Format check
        run: ruff format --check .
      - name: Tests
        run: pytest -q

در پروژه‌های واقعی، نسخه پایتون را با نسخه‌ای که محصول پشتیبانی می‌کند هماهنگ کنید. اگر چند نسخه را پشتیبانی می‌کنید، یک matrix بسازید؛ اما ابتدا یک اجرای پایدار داشته باشید و بعد پوشش نسخه‌ها را افزایش دهید. فعال کردن cache برای pip هم در مخزن‌های پرتکرار، زمان انتظار را کم می‌کند.

ممانعت از ورود کد ناسالم به شاخه اصلی

سبز شدن workflow به تنهایی جلوی merge را نمی‌گیرد. در تنظیمات شاخه اصلی، Branch protection را فعال کنید و job کیفیت را به عنوان Required status check انتخاب کنید. همچنین بازبینی حداقل یک نفر را اجباری کنید. به این ترتیب اتوماسیون جای قضاوت انسانی را نمی‌گیرد؛ فقط یک فیلتر سریع و ثابت پیش از آن می‌سازد.

اجرای محلی و رفع خطاهای رایج

قبل از Push، همین فرمان‌ها را محلی اجرا کنید:

ruff check . برای خطاهای lint.
ruff format --check . برای بررسی قالب.
pytest -q برای اجرای تست‌ها.

اگر CI در import شکست خورد، نخست مسیر نصب پکیج و فایل requirements-dev.txt را بررسی کنید. خطای تفاوت قالب معمولاً از نسخه متفاوت Ruff می‌آید؛ نسخه را قفل و به‌صورت دوره‌ای به‌روزرسانی کنید. شکست تصادفی تست نیز نشانه‌ای برای حذف وابستگی به شبکه یا زمان سیستم است، نه دلیلی برای چند بار اجرای دوباره تا سبز شدن.

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

چک‌لیست نهایی راه‌اندازی

محیط مجازی و وابستگی‌های توسعه در مخزن تعریف شده‌اند.
تنظیمات Ruff در یک فایل مشترک قرار گرفته‌اند.
تست‌های اصلی، حالت موفق و حالت خطا را پوشش می‌دهند.
workflow روی Push و Pull Request اجرا می‌شود.
نسخه ابزارها و پایتون در CI با محیط تیم هماهنگ است.
Branch protection، بررسی lint و تست را پیش از merge اجباری کرده است.

نتیجه‌گیری

خودکارسازی کیفیت کد پایتون لازم نیست با زیرساخت پیچیده شروع شود. Ruff برای قوانین و قالب، Pytest برای رفتار و GitHub Actions برای اجرای تکرارپذیر، ترکیبی سبک اما مؤثر هستند. ابتدا یک workflow ساده و چند تست حیاتی بسازید، خطاهای واقعی تیم را ثبت کنید و سپس قوانین، پوشش تست و cache را مرحله‌به‌مرحله توسعه دهید. نتیجه، Pull Requestهای تمیزتر و اعتماد بیشتر به هر انتشار است.

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

آیا Ruff می‌تواند جای Flake8 و Black را بگیرد؟

برای بسیاری از پروژه‌ها بله؛ Ruff بخشی از قابلیت‌های lint و format این ابزارها را با سرعت بالاتر ارائه می‌کند. پیش از مهاجرت، قوانین فعلی و تفاوت خروجی را بررسی کنید.

آیا اجرای تست در هر Pull Request زمان‌بر نیست؟

تست‌های واحد معمولاً سریع هستند. تست‌های سنگین را جدا علامت‌گذاری کنید، وابستگی‌ها را cache کنید و در صورت نیاز تست‌های integration را در workflow جدا اجرا کنید.

اگر یک تست در CI شکست خورد اما محلی موفق بود چه کنیم؟

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

چطور کیفیت کد پایتون را با Ruff و Pytest خودکار کنیم؟