۲۲ — API Integration Tests

هدف این لایه تست، پوشش فلوهای واقعی API با PostgreSQL و Redis واقعی است؛ فقط سرویس‌های خارجی مثل Zarinpal mock می‌شوند و SMS با SMS_DEV_MODE=true در DB به‌عنوان notification ثبت می‌شود.

---

لایه‌های تست

لایه	دستور	کاربرد
Unit/API mock/Component	npm test	سریع، بدون DB واقعی
API integration	npm run test:integration	route handlerها با DB/Redis واقعی
کامل CI	npm run test:ci یا npm run test:all	هر دو لایه پشت سر هم
UI E2E	npm run test:e2e	Playwright برای UI

---

پیش‌نیاز لوکال

docker compose up -d
copy .env.test.example .env.test
npm run db:test:setup
npm run test:integration

در Windows هم npm run db:test:setup قابل اجراست؛ اسکریپت scripts/setup-test-db.ts از docker compose exec استفاده می‌کند و migrationها را روی takeeat_test اجرا می‌کند.

---

ساختار

src/tests/
  helpers/
    request.ts       # NextRequest + cookie jar
    auth.ts          # OTP login, admin login, JWT shortcut
    factories.ts     # DB fixtures with real UUIDs
    assertions.ts    # order/payment/SMS assertions
    testDb.ts        # migrate/reset Prisma
    testRedis.ts     # Redis flush
    mocks/zarinpal.ts
  integration/
    setup.ts
    flows/
      01-auth.test.ts
      02-boxes-and-me.test.ts
      03-order-pay-at-pickup.test.ts
      04-order-gateway.test.ts
      05-vendor-lifecycle.test.ts
      06-vendor-orders.test.ts
      07-admin-vendors.test.ts
      08-admin-catalog.test.ts
      09-admin-orders.test.ts
      10-order-cancel-discount.test.ts
      11-cron.test.ts
      12-auth-guards.test.ts

---

Coverage Map

فایل	پوشش
01-auth	OTP send/verify، vendor login، admin login، refresh، logout
02-boxes-and-me	public boxes، box detail، profile GET/PATCH
03-order-pay-at-pickup	سفارش پرداخت در محل تا pickup
04-order-gateway	create payment، callback موفق/لغوشده
05-vendor-lifecycle	register، admin approve، box create/publish/today، me/stats
06-vendor-orders	vendor orders list/confirm/cancel/pickup، stubهای فعلی
07-admin-vendors	list/approve/reject/suspend vendor
08-admin-catalog	packages و discount codes
09-admin-orders	admin orders و refund
10-order-cancel-discount	cancel و apply-discount
11-cron	cron secret، reminder، no_show، expire
12-auth-guards	role guard و ownership

---

Mock Policy

• SMS: واقعی ارسال نمی‌شود. SMS_DEV_MODE=true باعث ثبت notification با providerRef=dev-mode می‌شود.
• Zarinpal: در تست gateway با src/tests/helpers/mocks/zarinpal.ts mock می‌شود.
• DB/Redis: mock نمی‌شوند؛ تست‌ها state واقعی را reset می‌کنند.

---

نوشتن فلو جدید

1. از factories.ts fixture بسازید.
2. با cookieJar() یا loginViaOtp() auth بسازید.
3. route را dynamic import کنید.
4. با callRoute() handler را صدا بزنید.
5. state نهایی را از DB assert کنید.

همیشه برای UUID از randomUUID() یا factoryها استفاده کنید؛ مقدارهایی مثل box-1 با zod uuid() fail می‌شوند.

---

Troubleshooting

مشکل	راه‌حل
DB تست وجود ندارد	npm run db:test:setup
Redis state قدیمی	integration setup بعد از هر تست flushdb می‌کند؛ اگر بیرون تست مشکل بود Redis DB 1 را flush کنید
Prisma DLL lock در Windows	همه processهای node/dev server را ببندید و دوباره migration را اجرا کنید
تست gateway به اینترنت وصل می‌شود	مطمئن شوید route قبل از import شدن، mock Zarinpal را در test file دارد

---

Known Stubs

این دو endpoint فعلاً فقط existence test دارند و باید در آینده پیاده‌سازی شوند:

• GET /api/vendor/orders/[id]/mark-paid
• GET /api/vendor/boxes/[id]/cancel