مستندات فنی پروژه
SCRIPTS · DOCKER TEST RUNNER

run_tests_in_docker.sh — تست‌های ایزوله در Docker

← بازگشت به فهرست اسکریپت‌ها

مسیر فایل: scripts/run_tests_in_docker.sh

راهنمای تکمیلی (انگلیسی): docs/docker-tests.md

۱. کاراییش به زبان ساده

یک استک تست جدا از استک live/production بالا می‌آورد (Postgres، Kafka، app-api)، منتظر آمادگی‌شان می‌ماند، سپس تمام سرویس‌های *-tests با پروفایل Composeی test را یکی‌یکی اجرا می‌کند، جدول خلاصهٔ PASS / FAIL / SKIPPED چاپ می‌کند، و در پایان (به‌صورت پیش‌فرض) همان استک تست را با volumeهایش پایین می‌آورد. به root .env، volumeهای live، و کانتینرهایی مثل project_postgres دست نمی‌زند.

۲. کجا در پروژه کلی استفاده می‌شود؟

  • راه استاندارد اجرای «همهٔ سوئیت‌های زیرسیستم» روی ماشین developer یا CI.
  • متصل به سرویس‌های *-tests در docker-compose.yml (پروفایل test) به‌همراه override ایزوله‌سازی در docker-compose.test.yml.
  • مکمل تست unit محلی؛ اینجا تمرکز روی شبکهٔ Compose و integration واقعی در محیط disposable است.
  • اختیاری در Ansible: با run_tests_before_deploy=true قبل از bring_up.sh روی سرور (پیش‌فرض خاموش). جزئیات: ansible/README.md.
  • نه جایگزین healthcheck استک live — آنجا bring_up.sh + check_infra.sh کافی است.

۳. ایزوله‌سازی از استک live (رویکرد جدید)

قبلاً اسکریپت همان پروژهٔ Compose و همان .env ریشه را لمس می‌کرد و می‌توانست به دادهٔ واقعی بنویسد. الان سه قطعه همیشه با هم استفاده می‌شوند:

قطعهنقش
COMPOSE_PROJECT_NAME=playpulse_test
(فلگ -p playpulse_test)		 شبکه و volume جدا (مثلاً playpulse_test_postgres_data)؛ موازی با استک live روی یک ماشین ممکن است.
.env.test جایگزین متغیرها فقط برای استک تست — نه root .env که bring_up / Ansible استفاده می‌کند. از .env.test.example کپی کنید (gitignore شده).
docker-compose.test.yml container_name ثابت‌ها (مثل project_postgres) و پورت‌های publish‌شده روی host را پاک می‌کند تا با استک live برخورد نکند؛ restart: "no".

تعریف سرویس‌ها همان docker-compose.yml است؛ کپی دوم از کل استک یا Testcontainers لازم نیست.

۴. چیکارا می‌کند؟ (جریان اجرا از اول تا آخر)

  1. پیش‌نیاز: وجود docker-compose.yml و docker-compose.test.yml. اگر .env.test نباشد، یک‌بار از .env.test.example ساخته می‌شود (هرگز overwrite نمی‌کند).
  2. دستور Compose ثابت: docker compose -p playpulse_test --env-file .env.test -f docker-compose.yml -f docker-compose.test.yml
  3. زیرساخت تست: up -d برای postgres، zookeeper، kafka، app-api؛ سپس kafka-init با --force-recreate تا topicها ساخته شوند.
  4. Wait: آمادگی Postgres، Kafka، خروج موفق kafka-init، healthy بودن app-api — همه از طریق همان پروژهٔ playpulse_test (نه نام‌های live).
  5. از این نقطه: trap روی EXIT فعال است تا در پایان (یا abort) استک تست پاک شود مگر --keep.
  6. سوئیت‌ها به‌ترتیب (شکست یکی بقیه را قطع نمی‌کند):
    • app-api-tests
    • crawler-tests و crawler-tests-live (بخش Play Store اینترنت خروجی می‌خواهد)
    • network-analyzer-tests، -live، -oracle (oracle به tshark / Dockerfile.test)
    • storage-consumer-tests و -integration
    • sentiment-tests و -integration (اگر playpulse-sentiment:latest نباشد → SKIPPED؛ cold-build نمی‌کند)
  7. هر سوئیت با compose --profile test run --rm روی همان شبکهٔ تست اجرا می‌شود؛ خروجی tee می‌شود و برچسب می‌گیرد.
  8. خلاصه PASS/FAIL/SKIPPED چاپ می‌شود.
  9. Teardown خودکار: مگر با --keep، کانتینرها و volumeهای playpulse_test حذف می‌شوند. exit code بر اساس FAIL واقعی است (SKIPPED کل run را قرمز نمی‌کند).

برچسب‌های خلاصه:

برچسبمعنا
PASSسوئیت با exit 0 تمام شد.
FAILشکست واقعی تست/اجرا.
SKIPPEDپیش‌نیاز خارجی: اینترنت برای Play Store فقط در crawler-tests-live؛ tshark برای oracle؛ یا نبود image مربوط به sentiment. network-analyzer-tests-live فقط Kafka/App API روی شبکهٔ Compose است و برای «نبود اینترنت» SKIPPED نمی‌شود.

۵. تصمیمات معماری

  • ایزوله به‌جای Testcontainers: همان Compose پروژه حفظ می‌شود؛ فقط پروژه/env/override جدا — ساده‌تر و هم‌شکل production.
  • عدم لمس دادهٔ live: integrationها فقط روی Postgres/Kafka تست می‌نویسند؛ بعد از run پیش‌فرض همه پاک می‌شود.
  • Teardown پیش‌فرض + --keep: رفتار امن برای CI و عادت روزمره؛ برای دیباگ تکراری می‌توان استک را نگه داشت و بعد با --down بست.
  • ادامه بعد از شکست: می‌خواهیم ببینیم کدام سوئیت‌ها شکستند، نه فقط اولین‌شان.
  • تفکیک SKIPPED از FAIL: نبود اینترنت یا image سنگین sentiment سیگنال «کد خراب است» را آلوده نکند.
  • پروفایل test: سرویس‌های تست با bring_up / استک روزمره بالا نمی‌آیند.
  • جدا از Ansible deploy: playbook فقط bring_up + check_infra؛ این اسکریپت عمداً در deploy نیست.

۶. دستورات

# اجرای کامل (.env.test در صورت نبود از example ساخته می‌شود؛
# در پایان استک تست خودکار down می‌شود)
./scripts/run_tests_in_docker.sh

# بدون rebuild imageها
./scripts/run_tests_in_docker.sh --no-build

# نگه داشتن استک برای تکرار سریع، سپس teardown دستی
./scripts/run_tests_in_docker.sh --keep
./scripts/run_tests_in_docker.sh --no-build --keep
./scripts/run_tests_in_docker.sh --down

./scripts/run_tests_in_docker.sh --help

# اختیاری: اگر می‌خواهید سوئیت sentiment اجرا شود (نه SKIPPED)
docker compose --profile tools build sentiment

پیش‌نیاز: Docker Engine + پلاگین Compose؛ فایل .env.test؛ برای Play Store در live: اینترنت خروجی؛ برای oracle: image با tshark؛ برای sentiment: image از قبل ساخته‌شده.

تأیید ایزوله بودن (هنگام اجرا با --keep):

docker compose -p playpulse_test ps
docker volume ls | grep playpulse_test
# نباید project_postgres مربوط به استک live را برای این run ببینید

← finalize_cycle_reports.py · فهرست اسکریپت‌ها · manual_sentiment_check.py →