canina/test-coverage-map.md

نقشه جامع پوشش تست‌های سرتاسری (E2E Test Coverage Map) — پروژه Canina

این سند شامل استخراج و فهرست کامل تمامی قابلیت‌های کاربرمحور، فرم‌ها، جریان‌های خرید و احراز هویت، عملیات CRUD پنل مدیریت و حالت‌های مرزی (Edge Cases) در پلتفرم Canina است.

---

۱. معماری و نقش‌های کاربری (User Roles)

1. مهمان / کاربر عمومی (Guest / Public User):

   • مشاهده لندینگ اصلی و بنرها
   • جستجو و فیلتر محصولات در آرشیو فروشگاه (/shop)
   • مشاهده صفحه جزئیات محصول (PDP)، دوزبندی و مشخصات مکمل
   • افزودن به سبد خرید و مدیریت مقادیر در Drawer سبد خرید
   • جریان تسویه‌حساب (Checkout Flow) با ثبت آدرس و اطلاعات تماس
   • ثبت درخواست همکاری تجاری / داروخانه‌ای (/b2b)
   • ثبت فرم تماس و استعلام مشاوره دارویی (/contact)
   • پیگیری وضعیت سفارش با کد پیگیری (/track)
   • مطالعه وبلاگ (/blog) و مقالات دانشنامه دارویی (/wiki/[slug])
   • مشاهده صفحه ویدیوهای آموزشی (/videos)
   • جستجوی سراسری محصولات و مقالات (/search)

2. کاربر ثبت‌نام‌شده / صاحب پت (Authenticated User / Pet Owner):

   • ورود/ثبت‌نام با شماره موبایل و کد تایید OTP (/profile یا مودال ورود)
   • مدیریت پروفایل کاربری و آدرس‌ها
   • مدیریت پروفایل پت‌ها (سگ/گربه، نژاد، وزن، سن، بیماری‌های زمینه‌ای)
   • داشبورد سوابق سفارشات و نسخه‌ها (/dashboard)
   • ثبت تیکت پشتیبانی و استعلام دارویی

3. مدیر ارشد و کادر مدیریت (Admin / Store Manager):

   • احراز هویت با ایمیل/رمز عبور یا OTP در پنل مدیریت (/login)
   • مدیریت محصولات (ایجاد، ویرایش، حذف، قیمت‌گذاری، کنترل موجودی، گالری، فیلدهای پیشرفته سئو SERP)
   • مدیریت دسته‌بندی‌ها و ویژگی‌های درمانی
   • مدیریت مقالات وبلاگ و دانشنامه تخصصی (Wiki)
   • مدیریت و تغییر وضعیت سفارشات (Orders)
   • بررسی و تایید درخواست‌های همکاری تجاری B2B و فرم‌های تماس
   • تنظیمات عمومی سایت، درگاه‌های پرداخت، پیامک و سئو

---

۲. ماتریس جریان‌ها و قابلیت‌های کاربرمحور (Feature & Flow Matrix)

کد	بخش / صفحه	قابلیت / سناریو	Happy Path	ورودی نامعتبر / منفی	حالت مرزی / Edge Case	وضعیت فعلی تست
ST-01	صفحه اصلی (/)	بارگذاری هدر، منوها، بنر اسلایدر، محصولات برگزیده	✅	❌	لود در شبکه کند	✅ تست ضمنی
ST-02	فروشگاه (/shop)	فیلتر دسته‌بندی، مرتب‌سازی، جستجو و صفحه‌بندی	✅	جستجوی بدون نتیجه	فیلتر هم‌زمان چندگانه	⚠️ ناقص
ST-03	جزئیات محصول (/shop/[slug])	تغییر وزن/دوز، ماشین‌حساب مصرف پت، افزودن به سبد	✅	محصول ناموجود	گالری تصاویر چندگانه	⚠️ ناقص
ST-04	سبد خرید (Cart Drawer)	افزایش/کاهش تعداد، حذف آیتم، محاسبه جمع کل	✅	سبد خرید خالی	کوپن تخفیف نامعتبر	⚠️ ناقص
ST-05	تسویه حساب (/checkout)	ثبت اطلاعات گیرنده، انتخاب روش ارسال و پرداخت	✅	اعتبارسنجی فیلدهای ضروری	لغو پرداخت و بازگشت	✅ پوشش داده شد
ST-06	همکاری تجاری (/b2b)	ارسال فرم همکاری کلینیک/پت‌شاپ با مدارک	✅	فیلدهای ناقص/موبایل اشتباه	ارسال فرم تکراری	✅ پوشش داده شد
ST-07	تماس با ما (/contact)	ارسال پیام مشاوره و استعلام دارویی	✅	ایمیل/موبایل نامعتبر	فیلد پیام خالی	✅ پوشش داده شد
ST-08	وبلاگ و دانشنامه (/blog, /wiki)	مشاهده مقالات، جستجو، جدول ترکیبات دارویی	✅	اسلاگ ناموجود (404)	لینک‌های بین‌مقالات	✅ پوشش داده شد
ST-09	پیگیری سفارش (/track)	استعلام وضعیت سفارش با شماره موبایل و کد سفارش	✅	کد پیگیری نامعتبر	سفارش یافت نشد	❌ بدون تست
ST-10	جستجوی سراسری (/search)	سرچ زنده محصولات، پیشنهادات هوشمند	✅	کلمه کلیدی بدون نتیجه	عبارات خاص فارسی/انگلیسی	❌ بدون تست
ST-11	احراز هویت و ثبت‌نام (AuthModal)	لاگین/ثبت‌نام با OTP، فرم ورود با پسورد	✅	کد OTP اشتباه یا منقضی	خروج از حساب (Logout)	⚠️ نیازمند تست اختصاصی
ST-12	بازیابی و فراموشی رمز عبور	درخواست ریست پسورد با پیامک OTP و تغییر رمز	✅	شماره اشتباه / کد نامعتبر	تلاش‌های بیش از حد (Rate limit)	⚠️ نیازمند تست اختصاصی
ST-13	صفحات خطا و روت‌های نامعتبر	رندر صفحه ۴۰۴ سفارشی، خطای ۵۰۰ و بازگشت به خانه	✅	ورود به آدرس‌های ناموجود	خطای کرش سرور یا کامپوننت	⚠️ نیازمند تست اختصاصی
SEC-01	امنیت و اعتبارسنجی ورودی‌ها	جلوگیری از XSS و SQLi در جستجو و فرم‌های تماس	✅	ارسال اسکریپت <script>	مقادیر غیرمجاز طولانی	⚠️ نیازمند تست اختصاصی
SEC-02	کنترل هجوم و Rate Limiting	اعمال Cooldown در ارسال پیامک OTP (۶۰ ثانیه‌ای)	✅	درخواست مکرر OTP در بازه کوتاه	خطای 429 Too Many Requests	⚠️ نیازمند تست اختصاصی
CONC-01	مدیریت هم‌زمانی و موجودی انبار	رقابت هم‌زمان دو کاربر برای خرید آخرین موجودی کالا	✅	اتمام موجودی حین پرداخت	ثبت همزمان بیش از موجودی	⚠️ نیازمند تست بار
AD-01	لاگین ادمین (/login)	ورود با رمز عبور و سشن توکن JWT	✅	رمز اشتباه / دسترسی غیرمجاز	سشن منقضی‌شده	✅ پوشش داده شد
AD-02	سطوح دسترسی و رول‌های ادمین	دسترسی SUPER_ADMIN در برابر محدودیت‌های روت	✅	تلاش کاربر عادی برای ورود به ادمین	دسترسی به صفحات بدون مجوز	⚠️ نیازمند تست اختصاصی
AD-03	مدیریت محصولات (/products)	ساخت، ویرایش، تب سئو، آپلود تصویر و حذف	✅	نام خالی / فرمت اشتباه	مقادیر طولانی سئو	✅ پوشش داده شد
AD-04	مدیریت سفارشات (/orders)	فیلتر وضعیت، مشاهده جزئیات، تغییر وضعیت به ارسال‌شده	✅	تغییر غیرمجاز وضعیت	لیست سفارش خالی	✅ پوشش داده شد
AD-05	مدیریت B2B (/b2b)	مشاهده درخواست‌های دریافتی، تغییر وضعیت و یادداشت	✅	بدون داده	تایید نهایی همکاری	✅ پوشش داده شد
AD-06	مدیریت مقالات (/blogs)	ایجاد مقاله، ویرایش تگ‌ها، وضعیت انتشار	✅	عنوان خالی	ویرایش محتوای حجیم	✅ پوشش داده شد
AD-07	تنظیمات سئو و عمومی (/settings)	تغییر متادیتا، فعال/غیرفعال کردن حالت کاتالوگ	✅	ساختار نامعتبر JSON	ذخیره فوری تنظیمات	⚠️ نیازمند تست

---

۳. وضعیت پوشش نهایی سوئیت ۱۱گانه (Final 11 Test Suites Status)

تمام ۱۱ سوئیت تست زیر با استانداردهای بدون if-isVisible، حذف سلکتورهای فال‌بک، assertion دقیق روی مقادیر رشته‌ای و محاسبات ریاضی، و اعتبارسنجی با Mutation Testing پیاده‌سازی و در CI ادغام شدند:

1. tests/e2e/storefront/shop-filter-search.spec.ts: تست کامل جستجو، فیلتر دسته‌ها، ماشین‌حساب دوز و حالت‌های بدون نتیجه.
2. tests/e2e/storefront/order-tracking.spec.ts: تست پیگیری سفارشات با سناریوهای موفق و ناموفق.
3. tests/e2e/storefront/cart-operations.spec.ts: تست تعاملی سبد خرید، محاسبه دقیق ریاضی unitPrice * 2، تغییر تعداد، حذف و سبد خالی.
4. tests/e2e/admin/admin-orders-flow.spec.ts: تست مدیریت سفارشات، تغییر وضعیت فاکتور و فیلترها در پنل مدیریت.
5. tests/e2e/admin/admin-blogs-crud.spec.ts: تست ایجاد و ویرایش مقالات وبلاگ و دانشنامه در پنل ادمین.
6. tests/e2e/admin/admin-b2b-submissions.spec.ts: تست مشاهده و مدیریت فرم‌های ثبت شده B2B و تماس.
7. tests/e2e/storefront/auth-otp-recovery.spec.ts: تست جریان OTP و بازیابی و تنظیم رمز عبور جدید.
8. tests/e2e/admin/admin-rbac-roles.spec.ts: تفکیک سطوح دسترسی، نقش‌های کاربران و ادمین ارشد.
9. tests/e2e/storefront/error-pages-404-500.spec.ts: رندر و ناوبری صفحات خطای ۴۰۴ و ۵۰۰.
10. tests/e2e/security/xss-ratelimit.spec.ts: تست مقاومت امنیتی در برابر حملات XSS و محدودیت نرخ ارسال پیامک (Cooldown Timer).
11. tests/e2e/storefront/concurrency-stock.spec.ts: رقابت موازی همزمان (Parallel Race با Promise.all) روی آخرین موجودی کالا در دو کانتکست مجزا.

Warning

محدودیت شناخته‌شده در تست همزمانی سطح E2E (Stock Concurrency & Race Conditions): تست concurrency-stock.spec.ts رفتار لایه فرانت‌اند و کلاینت در برابر پاسخ‌های همزمان را پوشش می‌دهد. از آنجا که اجرای تست‌های مرورگری E2E به صورت ایزوله انجام شده و دیتابیس مشترک تست را مسدود نمی‌کند، برای راستی‌آزمایی دقیق تراکنش‌های ACID دیتابیس (مانند SELECT FOR UPDATE، جلوگیری از Overselling و قفل‌های ردیفی در Postgres)، قویاً توصیه می‌شود یک Integration Test اختصاصی مستقیماً روی لایه سرویس بک‌اند (orders.service.ts با یک نمونه تست واقعی PostgreSQL) اجرا گردد.

---

۴. راهنمای نگهداری و افزودن فیچرهای جدید بدون شکستن تست‌ها (Developer Maintenance Guide)

برای اینکه توسعه‌دهندگان جدید یا تغییرات آینده باعث رگرسیون یا شکست بی‌دلیل سوئیت نشوند، قوانین زیر الزامی است:

1. استفاده اجباری از data-testid:
   • برای هر المان قابل تعامل جدید (دکمه، اینپوت، کارت، فیلتر)، به جای اتکا به کلاس CSS یا متن فارسی، حتماً data-testid="..." اضافه کنید.
2. پرهیز از Assertionهای شکننده متن یا کلاس:
   • از چک کردن کلاس‌های ظاهری (مانند text-canina-blue) خودداری کنید. به جای آن، وضعیت بیزینسی (مقدار عددی، مقدار فیلد فرم با .toHaveValue(), یا URL با .toHaveURL()) را راستی‌آزمایی کنید.
3. ممنوعیت استفاده از الگوی کاذب if (await element.isVisible()):
   • اگر حضور یک المان بخشی از کارکرد صفحه است، آن را مستقیماً با await expect(locator).toBeVisible() بنویسید تا در صورت بروز باگ، تست فیل شود و بی‌صدا عبور نکند.
4. اجرای محلی قبل از Push:
   • همیشه قبل از ایجاد PR یا Push، دستور زیر را اجرا کنید:

     npx playwright test --project=chromium-desktop --project=admin-chromium
     

5. به‌روزرسانی خودکار در گیت‌هاب/گیتیا (CI Pipeline):
   • فایل .gitea/workflows/e2e.yml روی هر Push و Pull Request روی برنچ‌های main و develop تمام سوئیت‌ها را به طور خودکار اجرا می‌کند.