أساسيات unittest

أساسيات unittest — unittest Basics

قبل أن يُكتب أي كود في مشروع جاد، يُكتب اختبار. هذه الفلسفة تحمي كل تغيير تجريه لاحقاً. Python تأتي بحزمة unittest في المكتبة المعيارية — لا تحتاج تثبيت أي شيء، فقط import unittest وتبدأ.

مفهوم الاختبار الآلي

الاختبار الآلي (Automated Test) هو كود يتحقق من أن كوداً آخر يتصرف بالشكل المتوقع. عوضاً عن تشغيل البرنامج يدوياً وتفحّص المخرجات بعينيك، تكتب مرة واحدة توقعاتك وتشغّل الأداة كلما احتجت.

الفائدة الحقيقية تظهر عند التعديل: عندما تُعيد كتابة دالة أو تُضيف ميزة، تشغّل الاختبارات وتعرف على الفور إذا كسرت شيئاً كان يعمل. بدون اختبارات، كل تغيير يحتمل كسر أجزاء لم تُلاحظها.

بنية اختبار unittest

نمط unittest يدور حول ثلاثة عناصر:

TestCase — كلاس ترث منه اختباراتك (unittest.TestCase)
دوال الاختبار — كل دالة تبدأ بـtest_ تُعامَل كاختبار مستقل
Assertions — دوال تتحقق من التوقعات، مثل assertEqual وassertTrue

import unittest

class TestMyFunction(unittest.TestCase):
    def test_something(self):
        result = my_function()
        self.assertEqual(result, expected_value)

أول اختبار حقيقي

main.go

import unittest

# الدالة المُختبَرة — Function under test
def add(a, b):
    return a + b

def is_even(n):
    # هل العدد زوجي؟ — Is the number even?
    return n % 2 == 0

class TestMathFunctions(unittest.TestCase):

    def test_add_positive(self):
        # جمع عددين موجبين — Add two positive numbers
        self.assertEqual(add(2, 3), 5)

    def test_add_negative(self):
        # جمع مع عدد سالب — Add with negative
        self.assertEqual(add(-1, 1), 0)

    def test_add_zeros(self):
        # الجمع مع الصفر — Add zeros
        self.assertEqual(add(0, 0), 0)

    def test_is_even_true(self):
        # عدد زوجي — Even number
        self.assertTrue(is_even(4))

    def test_is_even_false(self):
        # عدد فردي — Odd number
        self.assertFalse(is_even(7))

    def test_is_even_zero(self):
        # الصفر زوجي — Zero is even
        self.assertTrue(is_even(0))


# تشغيل الاختبارات — Run tests
# argv=['ignored'] و exit=False ضروريان داخل بيئة تفاعلية
unittest.main(argv=['ignored'], exit=False, verbosity=2)

Output:

لاحظ الناتج: كل دالة اختبار تُبلَّغ منفصلاً. OK تعني نجاح. لو فشل اختبار، يُظهر FAIL مع سبب التفصيلي.

setUp و tearDown

أحياناً تحتاج إعداداً مشتركاً قبل كل اختبار — قاعدة بيانات مؤقتة، كائن مهيّأ، ملف اختبار. setUp تُشغَّل قبل كل اختبار، وtearDown تُشغَّل بعد كل اختبار حتى لو فشل.

هذا يضمن أن كل اختبار يبدأ بحالة نظيفة ولا يتأثر بنتائج الاختبارات السابقة.

main.go

import unittest

class ShoppingCart:
    """عربة تسوق — Shopping cart"""

    def __init__(self):
        self.items = []

    def add(self, name, price):
        # إضافة منتج — Add product
        self.items.append({"name": name, "price": price})

    def total(self):
        # الإجمالي — Total price
        return sum(item["price"] for item in self.items)

    def count(self):
        # عدد المنتجات — Number of items
        return len(self.items)

    def clear(self):
        # مسح العربة — Clear cart
        self.items = []


class TestShoppingCart(unittest.TestCase):

    def setUp(self):
        # يُشغَّل قبل كل اختبار — Runs before each test
        # ننشئ عربة جديدة نظيفة في كل مرة
        self.cart = ShoppingCart()
        self.cart.add("تفاح", 5)
        self.cart.add("خبز", 3)

    def tearDown(self):
        # يُشغَّل بعد كل اختبار — Runs after each test
        # هنا نظّف أي موارد (ملفات، اتصالات...)
        self.cart.clear()

    def test_initial_count(self):
        # نتوقع اثنين لأن setUp أضاف اثنين
        self.assertEqual(self.cart.count(), 2)

    def test_total_price(self):
        # مجموع 5 + 3 = 8
        self.assertEqual(self.cart.total(), 8)

    def test_add_item(self):
        self.cart.add("حليب", 4)
        self.assertEqual(self.cart.count(), 3)
        self.assertEqual(self.cart.total(), 12)

    def test_empty_after_clear(self):
        self.cart.clear()
        self.assertEqual(self.cart.count(), 0)
        self.assertEqual(self.cart.total(), 0)


unittest.main(argv=['ignored'], exit=False, verbosity=2)

Output:

Assertions الشائعة

unittest.TestCase توفّر مجموعة واسعة من دوال التحقق. إليك الأكثر استخداماً:

الدالة	متى تستخدمها
`assertEqual(a, b)`	عندما تتوقع أن `a == b`
`assertNotEqual(a, b)`	عندما تتوقع أن `a != b`
`assertTrue(x)`	عندما تتوقع أن `x` صحيحة (truthy)
`assertFalse(x)`	عندما تتوقع أن `x` خاطئة (falsy)
`assertIsNone(x)`	عندما تتوقع `x is None`
`assertIsNotNone(x)`	عندما تتوقع `x is not None`
`assertIn(a, b)`	عندما تتوقع أن `a in b`
`assertRaises(exc)`	عندما تتوقع رفع استثناء
`assertAlmostEqual(a, b)`	للأرقام العشرية (تتجاهل الفارق الصغير)

main.go

import unittest

def divide(a, b):
    # القسمة مع حماية من القسمة على صفر
    if b == 0:
        raise ValueError("لا يمكن القسمة على صفر")
    return a / b

def find_user(users, name):
    # ابحث عن مستخدم — Find a user
    for user in users:
        if user["name"] == name:
            return user
    return None


class TestAssertions(unittest.TestCase):

    def test_divide_normal(self):
        # نتيجة القسمة — Division result
        self.assertEqual(divide(10, 2), 5.0)

    def test_divide_float(self):
        # أرقام عشرية — Floating point
        # assertAlmostEqual تتجاهل فارقاً أصغر من 7 خانات عشرية
        self.assertAlmostEqual(divide(1, 3), 0.3333, places=4)

    def test_divide_by_zero(self):
        # نتوقع رفع ValueError — Expect ValueError
        with self.assertRaises(ValueError):
            divide(10, 0)

    def test_find_user_exists(self):
        users = [{"name": "أحمد"}, {"name": "فاطمة"}]
        result = find_user(users, "أحمد")
        self.assertIsNotNone(result)
        self.assertEqual(result["name"], "أحمد")

    def test_find_user_not_found(self):
        users = [{"name": "أحمد"}]
        result = find_user(users, "خالد")
        self.assertIsNone(result)

    def test_user_in_list(self):
        names = ["أحمد", "فاطمة", "خالد"]
        self.assertIn("فاطمة", names)
        self.assertNotIn("يوسف", names)


unittest.main(argv=['ignored'], exit=False, verbosity=2)

Output:

استخدام assertRaises بشكل صحيح

assertRaises له أسلوبان: كـcontext manager (الأوضح)، أو كدالة مباشرة.

# الأسلوب الأوضح: context manager
def test_invalid_input(self):
    with self.assertRaises(ValueError) as ctx:
        divide(5, 0)
    # يمكن التحقق من رسالة الخطأ
    self.assertIn("صفر", str(ctx.exception))

# الأسلوب البديل: أقل وضوحاً
def test_invalid_input_alt(self):
    self.assertRaises(ValueError, divide, 5, 0)

الأسلوب الأول أفضل لأنه يُتيح التحقق من رسالة الاستثناء أيضاً.

تشغيل الاختبارات في مشروع حقيقي

في مشروع حقيقي، الاختبارات في ملفات منفصلة:

my_project/
├── calculator.py       # الكود الأصلي
└── test_calculator.py  # الاختبارات

ثم تشغّل من Terminal:

# شغّل اختبارات ملف واحد
python -m unittest test_calculator

# شغّل كل الاختبارات في المجلد
python -m unittest discover

# مع تفاصيل — verbose
python -m unittest -v test_calculator

الخيار -m unittest يجعل Python تشغّل الوحدة كأداة سطر أوامر.

تنظيم الاختبارات — أفضل الممارسات

اسم واضح للاختبار — test_add_two_positive_numbers أفضل من test1
اختبار واحد يختبر فكرة واحدة — لا تختبر خمسة سلوكيات في دالة واحدة
اختبر الحالات الحدية — صفر، قيمة فارغة، قيمة سالبة، قيمة أقصى
لا تعتمد ترتيب التشغيل — كل اختبار مستقل عن الآخر
رسالة خطأ واضحة — assertEqual(result, 5, "يجب أن يكون الجمع 5") يساعد عند الفشل

تحدي — Challenge

import unittest

def calculate_discount(total):
    """حساب الخصم — Calculate discount.
    الطلبات فوق 500: خصم 20%
    الطلبات فوق 200: خصم 10%
    غير ذلك: لا خصم
    """
    if total > 500:
        return total * 0.20
    elif total > 200:
        return total * 0.10
    return 0


class TestCalculateDiscount(unittest.TestCase):

    def test_discount_large_order(self):
        # طلب 600 → خصم 20% = 120
        # اكتب الاختبار هنا
        pass

    def test_discount_no_discount(self):
        # طلب 100 → لا خصم = 0
        # اكتب الاختبار هنا
        pass

    def test_discount_boundary(self):
        # طلب 200 بالضبط → لا خصم (الشرط > وليس >=)
        # اكتب الاختبار هنا
        pass


# شغّل ثم اطبع النتائج بهذا الشكل
results = unittest.TestLoader().loadTestsFromTestCase(TestCalculateDiscount)
runner = unittest.TextTestRunner(stream=__import__('io').StringIO(), verbosity=0)
test_result = runner.run(results)

tests = [
    ("test_discount_large_order", TestCalculateDiscount("test_discount_large_order")),
    ("test_discount_no_discount", TestCalculateDiscount("test_discount_no_discount")),
    ("test_discount_boundary", TestCalculateDiscount("test_discount_boundary")),
]

passed = 0
for name, t in tests:
    buf = __import__('io').StringIO()
    r = unittest.TextTestRunner(stream=buf, verbosity=0)
    res = r.run(t)
    status = "PASS" if res.wasSuccessful() else "FAIL"
    if status == "PASS":
        passed += 1
    print(f"{name} ({status})")

print(f"جميع الاختبارات نجحت: {passed}/3")