مستندات تست زیرساخت پروژه
پیش از شروع پیاده‌سازی هر بخش از منطق برنامه (Django، Crawler و …)، لازم بود از سلامت و آماده‌به‌کار بودن زیرساخت پایه‌ی پروژه (PostgreSQL و Kafka) اطمینان حاصل شود. برای این منظور، به‌جای بررسی دستی و پراکنده، یک اسکریپت Smoke Test خودکار در مسیر scripts/infra/check_infra.sh نوشته شده است که این بررسی را به‌صورت یکپارچه و تکرارپذیر انجام می‌دهد.
پیش‌نیازها
پیش از اجرای اسکریپت باید موارد زیر انجام شده باشد:
-
فایل
.envبر اساس نمونه‌ی موجود ساخته و مقادیر آن تنظیم شده باشد. - سرویس‌های زیرساختی با دستور زیر بالا آمده باشند:
cp .env.example .env
# edit the .env values
docker compose up -d postgres zookeeper kafkaنحوه‌ی اجرای اسکریپت
chmod +x scripts/infra/check_infra.sh
./scripts/infra/check_infra.shروند بررسی اسکریپت
اسکریپت به‌ترتیب دو بخش زیرساخت را بررسی می‌کند و در پایان یک گزارش خلاصه ارائه می‌دهد.
بخش اول: PostgreSQL
| مرحله | هدف از انجام آن |
|---|---|
| بررسی اجرا بودن کانتینر | اطمینان از این‌که کانتینر Postgres اصلاً بالا آمده و متوقف یا Crash نشده است. |
| بررسی آماده‌به‌کار بودن (pg_isready) | تشخیص لحظه‌ای که Postgres کاملاً برای پذیرش اتصال آماده شده؛ چون بین «بالا آمدن کانتینر» و «آماده شدن دیتابیس» معمولاً چند ثانیه فاصله وجود دارد. |
| تست واقعی نوشتن و خواندن | ساخت یک جدول موقت، درج یک ردیف، خواندن آن، و حذف جدول. این تست فراتر از یک Ping ساده است و اطمینان می‌دهد کاربر و پایگاه‌داده تعریف‌شده در .env واقعاً قابل استفاده‌اند. |
بخش دوم: Kafka
| مرحله | هدف از انجام آن |
|---|---|
| بررسی اجرا بودن کانتینر | اطمینان از بالا بودن کانتینر Kafka. |
| بررسی در دسترس بودن بروکر | تایید این‌که بروکر Kafka به درخواست‌های API پاسخ می‌دهد (نشانه‌ی اتصال موفق به Zookeeper و آماده بودن کامل بروکر). |
| ساخت Topic تستی | بررسی این‌که عملیات مدیریتی (ساخت Topic) که بعداً Crawler و Storage Consumer به آن نیاز دارند، بدون خطا انجام می‌شود. |
| ارسال پیام (Produce) | شبیه‌سازی رفتار واقعی Crawler که قرار است داده در Kafka بنویسد. |
| خواندن پیام (Consume) و تطبیق محتوا | شبیه‌سازی رفتار Storage Consumer؛ همچنین اطمینان از این‌که پیام دریافتی دقیقاً با پیام ارسالی یکسان است (نه صرفاً وجود دارد). |
| پاکسازی (حذف Topic تستی) | جلوگیری از باقی ماندن داده‌ی تستی در Kafka که ممکن است بعداً با Topic های واقعی پروژه اشتباه گرفته شود. |
خروجی و نحوه‌ی تفسیر آن
اسکریپت برای هر مرحله یکی از سه وضعیت زیر را نمایش می‌دهد:
- [OK] — مرحله با موفقیت انجام شده است.
- [FAIL] — مرحله ناموفق بوده و جزئیات خطا (در صورت وجود) بلافاصله زیر آن چاپ می‌شود.
- [..] — مرحله در حال انجام است (وضعیت میانی، صرفاً برای اطلاع‌رسانی).
در پایان اجرا، یک خط جمع‌بندی نمایش داده می‌شود:
-
اگر همه‌ی بررسی‌ها موفق باشند: پیام موفقیت نمایش داده شده و اسکریپت با
exit code 0خارج می‌شود. -
اگر حداقل یک بررسی ناموفق باشد: تعداد بررسی‌های ناموفق نمایش داده شده و اسکریپت با
exit code 1خارج می‌شود.
Exit Code معنادار به‌طور خاص برای این در نظر گرفته شده که این اسکریپت بعداً در مراحل توسعه‌ی بعدی پروژه (مثلاً یک اسکریپت بزرگ‌تر نصب end-to-end) بتواند به‌عنوان یک پیش‌شرط (Precondition) فراخوانی شود؛ یعنی مراحل بعدی نصب تنها زمانی اجرا شوند که زیرساخت واقعاً سالم باشد.
نکات و ملاحظات طراحی
- مقاوم در برابر خطای جزئی: اسکریپت با اولین خطا متوقف نمی‌شود؛ بلکه تمام بررسی‌ها را تا انتها اجرا کرده و در پایان یک گزارش کامل ارائه می‌دهد. این باعث می‌شود در صورت بروز مشکل، به‌جای یک خطای مبهم، دقیقاً مشخص باشد کدام سرویس و کدام مرحله دچار مشکل شده است.
- مکانیزم Retry: برای هر دو سرویس، اسکریپت چند بار (با فاصله‌ی زمانی) تلاش می‌کند پیش از اعلام شکست؛ چون معمول است که سرویس‌هایی مثل Kafka چند ثانیه پس از بالا آمدن کانتینر، زمان نیاز داشته باشند تا کاملاً آماده‌ی پاسخ‌گویی شوند.
- عدم وابستگی به کد پایتون پروژه: این اسکریپت عمداً فقط از ابزارهای موجود در خودِ Image ها (psql، ابزارهای CLI کافکا) استفاده می‌کند و به هیچ کتابخانه یا کد اپلیکیشنی وابسته نیست؛ بنابراین می‌تواند مستقل و پیش از نوشتن هر خط کد پایتون اجرا و اعتبارسنجی شود.
- پاکسازی خودکار داده‌ی تستی: هم جدول موقت در Postgres و هم Topic تستی در Kafka، در پایان اجرا حذف می‌شوند تا زیرساخت پس از تست دقیقاً در همان وضعیت اولیه (بدون داده‌ی اضافی) باقی بماند.