From 5b26a487c1dbebed5d113c87c853e0dd9af6fb28 Mon Sep 17 00:00:00 2001 From: Amirhossein Khalili Date: Sat, 5 Sep 2026 22:20:23 +0800 Subject: [PATCH] feat: add chapter 09-testing-and-debugging specs --- .../00-lesson-chapter-goals/spec.md | 81 +++++++++++ .../spec.md | 104 ++++++++++++++ .../spec.md | 111 +++++++++++++++ .../spec.md | 114 ++++++++++++++++ .../04-lesson-ai-debugging-techniques/spec.md | 127 ++++++++++++++++++ .../05-lesson-resolving-common-errors/spec.md | 124 +++++++++++++++++ 6 files changed, 661 insertions(+) create mode 100644 chapters/09-testing-and-debugging/00-lesson-chapter-goals/spec.md create mode 100644 chapters/09-testing-and-debugging/01-lesson-why-agents-make-mistakes/spec.md create mode 100644 chapters/09-testing-and-debugging/02-lesson-testing-types-and-importance/spec.md create mode 100644 chapters/09-testing-and-debugging/03-lesson-manual-testing-and-qa-checklist/spec.md create mode 100644 chapters/09-testing-and-debugging/04-lesson-ai-debugging-techniques/spec.md create mode 100644 chapters/09-testing-and-debugging/05-lesson-resolving-common-errors/spec.md diff --git a/chapters/09-testing-and-debugging/00-lesson-chapter-goals/spec.md b/chapters/09-testing-and-debugging/00-lesson-chapter-goals/spec.md new file mode 100644 index 0000000..d1e5b3b --- /dev/null +++ b/chapters/09-testing-and-debugging/00-lesson-chapter-goals/spec.md @@ -0,0 +1,81 @@ +# مشخصات درس‌نامه: اهداف فصل نهم (Chapter Goals) +- **شناسه در سیلابس:** `L9.1` +- **فصل:** فصل ۹: تست و Debugging (Ch 9) +- **نوع محتوا:** 📘 درس‌نامه متنی +- **زمان تقریبی مطالعه:** ۵ دقیقه +- **پیش‌نیازهای مستقیم:** `L7.8` (امنیت پایگاه داده با RLS) + +--- + +## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy) +دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند: +- [ ] **درک کند (Understand):** چرا مهارت تست و دیباگ سیستماتیک، مرز تعیین‌کننده میان یک وایب کدر آماتور که با اولین باگ تسلیم می‌شود با یک معمار حرفه‌ای و خونسرد است. +- [ ] **درک کند (Understand):** نقشه راه ۶ درس‌نامه تخصصی این فصل (از چرایی خطای ایجنت‌ها، انواع تست‌های نرم‌افزاری، چک‌لیست تضمین کیفیت QA، تکنیک‌های پیشرفته دیباگ با هوش مصنوعی تا کالبدشکافی خطاهای متداول) چگونه چیده شده است. +- [ ] **تحلیل/ارزیابی کند (Evaluate):** رویکرد ترکیبی «تست‌های خودکار با ایجنت‌ها (Agentic Testing) به همراه راستی‌آزمایی دستی انسان (Human QA)» را به عنوان استراتژی استاندارد ارزیابی کند. +- [ ] **به‌کار ببندد (Apply):** پروژه محوری دوره (پورتفولیوی پویا با پنل ادمین و سئو) را تحت آزمون‌های جامع تاب‌آوری و اعتبارسنجی کیفیت قرار دهد. + +--- + +## ۲. محدوده و مرزهای محتوا (Scope & Boundaries) + +### آنچه باید پوشش داده شود (In-Scope): +1. **ورود به فاز ارتقای کیفیت و پایداری محصول:** + * نوشتن کد آسان است؛ تضمین اینکه کد در سناریوهای واقعی زیر بار کاربران خرد نشود، هنر واقعی مهندسی است. +2. **مرور سرفصل‌های فصل ۹:** + * درس ۹.۲: چرا ایجنت‌های هوش مصنوعی اشتباه می‌کنند؟ (کالبدشکافی توهم، حافظه فرسوده و فراموشی ناخواسته فایل‌های مرتبط). + * درس ۹.۳: انواع تست نرم‌افزاری (Unit، Integration و E2E) و تولید خودکار تست‌ها توسط ایجنت با ابزارهایی نظیر Vitest و Playwright. + * درس ۹.۴: تست دستی و چک‌لیست طلایی تضمین کیفیت (QA Checklist) برای ارزیابی فرم‌ها، موبایل و وضعیت‌های استثنایی. + * درس ۹.۵: تکنیک‌های پیشرفته دیباگ با AI (شکار ریشه خطا با ایزوله‌سازی، استفاده از لاگ‌های سرور و کامپوزر Cursor). + * درس ۹.۶: کالبدشکافی و حل خطاهای متداول (خطاهای Next.js، خطاهای اتصال دیتابیس و خطاهای دور باطل ایجنت). +3. **پروژه محوری (پورتفولیوی پویا):** + * آزمایش تمام فیچرها: ویترین، دیتابیس Supabase، لاگین ادمین، فرم‌های سئو و واکنش‌گرایی بدون کوچک‌ترین باگ پنهان. +4. **دستورات چندسکویی:** + * ارائه دستورات اجرای تست‌ها در قالب منوهای کشویی اختصاصی برای Windows، macOS و Linux. +5. **کال‌اوت نکته کوئرا (`
`):** تغییر نگرش نسبت به باگ‌ها؛ باگ‌ها دشمن نیستند، بلکه نشانه‌هایی شفاف برای هدایت دقیق‌تر ایجنت هستند. + +### آنچه نباید وارد آن شویم (Out-of-Scope): +- مباحث تست نفوذ امنیتی پیشرفته و هک اخلاقی (فصل ۱۱). +- تست‌های بار سرور و مانیتورینگ آنلاین لاگ‌ها در محیط ابری (فصل ۱۳). + +--- + +## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms) + +| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده | +| :--- | :--- | :--- | +| Quality Assurance (QA) | تضمین کیفیت نرم‌افزار | فرآیند سیستماتیک اطمینان از عملکرد صحیح، بدون نقص و پایدار محصول پیش از انتشار | +| Systematic Debugging | دیباگ سیستماتیک | روش گام‌به‌گام و علمی برای کشف ریشه اصلی خطا به جای حدس‌های تصادفی | +| Agentic Testing | تست‌نویسی مبتنی بر ایجنت | استفاده از هوش مصنوعی برای تولید، اجرا و تحلیل نتایج تست‌های خودکار نرم‌افزار | +| Regression Bug | باگ پس‌رفتی | خطایی که بر اثر ایجاد یک تغییر جدید، باعث خراب شدن بخش‌های قبلاً سالم برنامه می‌شود | + +--- + +## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders) +> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` قرار گرفته و در قالب جدول تک‌خانه‌ای وسط‌چین با کپشن تفصیلی درج شوند: + +1. **تصویر کاور درس:** `images/cover.png` + * **موضوع:** کاور مدرن با تم تیره که یک رادار دیجیتال اسکن‌کننده نئونی را در حال ردیابی و نشانه‌گذاری حشرات و باگ‌های نرم‌افزاری در کدهای پروژه نشان می‌دهد. +2. **نقشه راه فصل ۹:** `images/chapter-9-roadmap.png` + * **موضوع:** اینفوگرافیک گام‌به‌گام از چرایی اشتباه ایجنت $\rightarrow$ انواع تست‌ها $\rightarrow$ چک‌لیست QA $\rightarrow$ تکنیک‌های دیباگ $\rightarrow$ حل خطاهای متداول $\rightarrow$ محصول ضدضربه. +3. **چرخه آزمون دوگانه (هوش مصنوعی + ناظر انسان):** `images/dual-testing-loop.png` + * **موضوع:** دیاگرام تعاملی: ایجنت تست‌های خودکار را اجرا می‌کند $\rightarrow$ انسان چک‌لیست سناریوهای کاربری را در مرورگر راستی‌آزمایی می‌نماید. + +--- + +## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`) + +1. **تیتر اصلی:** `# اهداف فصل نهم: تست و Debugging؛ تبدیل نرم‌افزار به محصولی ضدضربه` +2. **مقدمه کوتاه:** چرا آرامش یک توسعه‌دهنده در مواجهه با خطاهای قرمز، بزرگ‌ترین سلاح اوست؟ +3. **جدول کاور درس** +4. **سرفصل‌های کلیدی فصل در یک نگاه:** مرور ۶ ایستگاه سنجش کیفیت و دیباگ. +5. **جدول نقشه راه یادگیری فصل** +6. **رویکرد دوگانه دوره: تست‌های خودکار ایجنت در کنار نگاه تیزبین انسان:** تقسیم وظایف در دنیای وایب کدینگ. +7. **پورتفولیوی پویا در اتاق آزمایش:** آماده‌سازی پروژه برای عبور از سخت‌ترین سناریوهای شکست. +8. **کال‌اوت آرامش‌بخش Quera (`
`):** ثبت دکمه «خواندم» و آغاز فرایند شکار باگ‌ها. + +--- + +## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer) +- [ ] اهداف کلان فصل ۹ و اهمیت دیباگ سیستماتیک با زبان رسا و حرفه‌ای تبیین شده باشد. +- [ ] سرفصل‌های ۶ درس‌نامه بعدی با ترتیب منطقی معرفی گردند. +- [ ] استراتژی ترکیبی تست خودکار با ایجنت و چک‌لیست دستی انسان صریحاً تشریح شود. diff --git a/chapters/09-testing-and-debugging/01-lesson-why-agents-make-mistakes/spec.md b/chapters/09-testing-and-debugging/01-lesson-why-agents-make-mistakes/spec.md new file mode 100644 index 0000000..8be9579 --- /dev/null +++ b/chapters/09-testing-and-debugging/01-lesson-why-agents-make-mistakes/spec.md @@ -0,0 +1,104 @@ +# مشخصات درس‌نامه: چرا Agent اشتباه می‌کند؟ (Why AI Coding Agents Make Mistakes) +- **شناسه در سیلابس:** `L9.2` +- **فصل:** فصل ۹: تست و Debugging (Ch 9) +- **نوع محتوا:** 📘 درس‌نامه متنی +- **زمان تقریبی مطالعه:** ۱۲ دقیقه +- **پیش‌نیازهای مستقیم:** `L9.1` (اهداف فصل نهم) + +--- + +## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy) +دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند: +- [ ] **درک کند (Understand):** چرا ایجنت‌های هوش مصنوعی مهندس واقعی نیستند، بلکه سیستم‌های پیش‌بینی احتمالاتی هستند و خطاهای آن‌ها ریشه‌های علمی و ساختاری مشخصی دارد. +- [ ] **تحلیل/ارزیابی کند (Evaluate):** پنج ریشه بنیادین خطاهای هوش مصنوعی شامل: **فرسودگی کانتکست (Context Bloat)، توهم توابع و پکیج‌ها (Hallucination)، نابینایی نسبت به اثرات جانبی (Cascade Effects)، ابهام در پرامپت کاربر، و چاپلوسی مدل (Sycophancy)** را شناسایی و تحلیل کند. +- [ ] **تحلیل/ارزیابی کند (Evaluate):** خطای اختلاط نسخه‌های قدیمی (مانند کدهای منسوخ Next.js 12) با نسخه‌های مدرن (Next.js App Router) توسط ایجنت را تشخیص دهد. +- [ ] **به‌کار ببندد (Apply):** راهکارهای دفاعی پیشگیرانه (بهداشت سشن، مشخص کردن دقیق شماره نسخه استک در پرامپت، و ارجاع صریح به فایل‌ها با `@filename`) را اجرا کند. +- [ ] **به‌کار ببندد (Apply):** اصل طلایی عدم اعتماد کلامی به ادعای ایجنت («من مشکل را حل کردم!») و راستی‌آزمایی مستقل در ترمینال و مرورگر را نهادینه سازد. + +--- + +## ۲. محدوده و مرزهای محتوا (Scope & Boundaries) + +### آنچه باید پوشش داده شود (In-Scope): +1. **رمزگشایی از ذهن ایجنت‌های کدنویسی:** + * هوش مصنوعی با شما دشمنی ندارد و خنگ نیست؛ مدل‌ها تابع فیزیک محاسباتی و توزیع احتمالات هستند. شناخت این نقاط ضعف، شما را به یک راهنمای مقتدر تبدیل می‌کند. +2. **کالبدشکافی ۵ ریشه اصلی خطاهای ایجنت:** + * **ریشه ۱: فرسودگی پنجره بافت و پدیده گم‌شدگی در میانه (Lost in the Middle):** + * در چت‌های طولانی، توجه مدل به پیام‌های میانی به شدت افت می‌کند و شروط اولیه (مثل «از تایپ‌اسکریپت استفاده کن») را از یاد می‌برد. + * **ریشه ۲: توهم و استفاده از کدهای منسوخ (Hallucinated & Outdated APIs):** + * مدل‌های زبانی روی داده‌های گذشته اینترنت آموزش دیده‌اند؛ بنابراین ممکن است ناخودآگاه کدهای قدیمی Next.js Pages Router (مانند `getServerSideProps`) را وارد پروژه App Router مدرن شما کنند یا متدهایی خیالی در Supabase بسازند. + * **ریشه ۳: نابینایی نسبت به اثرات جانبی (Scope Blindness & Cascade Bugs):** + * ایجنت یک باگ را در کامپوننت `ProjectCard.tsx` درست می‌کند، اما نمی‌بیند که این تغییر باعث شکسته شدن ورودی‌ها در `ProjectsGrid.tsx` شده است. + * **ریشه ۴: پرامپت‌های مبهم و کلی کاربر:** + * گفتن «دکمه لاگین کار نمی‌کند» به جای ارسال متن دقیق خطای قرمز کنسول. + * **ریشه ۵: پدیده چاپلوسی و اعتمادبه‌نفس کاذب (AI Sycophancy):** + * مدل‌ها به گونه‌ای آموزش دیده‌اند که شما را خوشحال کنند؛ به همین دلیل با لحنی کاملاً شاداب می‌گویند: *«مشکل با موفقیت حل شد!»* حتی اگر کد اصلاً کامپایل نشود! +3. **پادزهرهای عملی برای مهار لغزش ایجنت‌ها:** + * **قانون سه شکست:** اگر ایجنت در ۳ پرامپت متوالی نتوانست باگ را حل کند، ادامه دادن چت فایده‌ای ندارد؛ پنجره را ببندید و در یک سشن تازه مسئله را به صورت ایزوله شرح دهید. + * **تزریق صریح نسخه در پرامپت:** قید کردن عبارت «استفاده از Next.js 15 App Router و Supabase v2». + * **ارجاع متمرکز:** استفاده از نشانه `@` در ادیتور Cursor برای اضافه کردن فقط فایل‌های درگیر به بافت چت. +4. **کال‌اوت‌های Quera:** + * `
`: پدیده چاپلوسی هوش مصنوعی؛ چرا تأییدیه کلامی مدل ارزش فنی ندارد و تنها سند معتبر، خروجی بدون خطای کامپایلر است؟ + * `
`: تله اصرار در چت آلوده؛ هرگز وقت و توکن‌های خود را با جدال بی‌پایان در یک پنجره پر از خطا تلف نکنید. + +### آنچه نباید وارد آن شویم (Out-of-Scope): +- آموزش انواع تست‌های خودکار (درس بعدی ۹.۳). +- ابزارهای گرافیکی مانیتورینگ کارایی سرور (فصل ۱۳). + +--- + +## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms) + +| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده | +| :--- | :--- | :--- | +| Lost in the Middle | گم‌شدگی در میانه | پدیده کاهش تمرکز مدل‌های زبانی بر اطلاعات واقع در میانه مکالمات طولانی | +| AI Sycophancy | چاپلوسی / تاییدطلبی مدل | تمایل هوش مصنوعی به تایید مثبت فرضیات کاربر حتی در صورت نادرست بودن کدها | +| Cascade Failure | شکست زنجیره‌ای | خطایی که در اثر اصلاح یک بخش، به طور دومینووار سایر بخش‌های سالم برنامه را تخریب می‌کند | +| Deprecated Syntax | سینتکس منسوخ | دستورات و کدهای قدیمی فریم‌ورک‌ها که در نسخه‌های جدید پشتیبانی نمی‌شوند | +| Context Cleansing | پاکسازی و تصفیه بافت | بستن چت‌های شلوغ و باز کردن یک سشن تمیز با ارجاع به فایل‌های ضروری | + +--- + +## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders) +> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` قرار گرفته و در قالب جدول تک‌خانه‌ای وسط‌چین با کپشن تفصیلی درج شوند: + +1. **تصویر کاور درس:** `images/cover.png` + * **موضوع:** کاور مدرن با تم تیره که مغز شیشه‌ای هوش مصنوعی را با مدارهای جرقه‌زننده و چراغ‌های هشدار زرد نئونی در حال تحلیل خطا نشان می‌دهد. +2. **پنج ریشه بنیادین خطاهای ایجنت:** `images/ai-failure-modes-diagram.png` + * **موضوع:** اینفوگرافیک ۵ پرچم قرمز: فرسودگی کانتکست، توهم کد، نابینایی اثرات جانبی، پرامپت گنگ، و تایید کاذب. +3. **نمودار پدیده Lost in the Middle:** `images/lost-in-the-middle-curve.png` + * **موضوع:** نمودار U شکل که نشان می‌دهد توجه مدل در ابتدا و انتهای چت ۱۰۰٪ است اما در وسط مکالمه به شدت افت می‌کند. +4. **مقایسه کدهای منسوخ با کدهای مدرن:** `images/deprecated-vs-modern-code.png` + * **موضوع:** تصویر مقایسه‌ای: کدهای قدیمی Pages Router در برابر کدهای استاندارد App Router با علامت ضربدر قرمز و تیک سبز. +5. **قانون سه‌گانه ریست سشن:** `images/three-strikes-reset-rule.png` + * **موضوع:** فلوچارت تصمیم‌گیری: تلاش ۱ $\rightarrow$ تلاش ۲ $\rightarrow$ تلاش ۳ $\rightarrow$ توقف فوری و باز کردن چت تمیز جدید. + +--- + +## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`) + +1. **تیتر اصلی:** `# چرا Agent اشتباه می‌کند؟ رمزگشایی از نقاط کور هوش مصنوعی` +2. **مقدمه:** چرا خونسردترین توسعه‌دهندگان، آن‌هایی هستند که طرز کار و اشتباهات هوش مصنوعی را پیش‌بینی می‌کنند؟ +3. **جدول کاور درس** +4. **هوش مصنوعی مهندس نیست؛ ماشین احتمالات است:** درک واقعیت پردازش توکن‌ها. +5. **پنج دلیل اصلی که ایجنت‌ها را به بیراهه می‌برد:** + * فرسودگی بافت و پدیده فراموشی در میانه (Lost in the Middle). + * توهم و استفاده تصادفی از کدهای دوره‌افتاده و منسوخ. + * نابینایی نسبت به اثرات زنجیره‌ای در سایر فایل‌ها. + * ابهام در ورودی‌های ما (Garbage In, Garbage Out). + * چاپلوسی مدل: چرا AI همیشه می‌گوید همه چیز عالی است؟! +6. **باکس نکته Quera (`
`):** روان‌شناسی ایجنت‌ها؛ چرا نباید به جملات امیدوارکننده مدل بدون تست در مرورگر اعتماد کرد؟ +7. **استراتژی‌های دفاعی برای وایب کدرهای برنده:** + * قانون طلایی سه شکست (Three Strikes Rule). + * تزریق قیدهای صریح نسخه فریم‌ورک در پرامپت. + * ارجاع لیزری به فایل‌ها با استفاده از کاراکتر `@`. +8. **باکس هشدار Quera (`
`):** هرگز در چت‌های پر از خطا نجنگید؛ سشن تمیز معجزه می‌کند. +9. **جمع‌بندی درس‌نامه:** تسلط بر روان‌شناسی خطاهای ایجنت و آماده‌سازی برای آشنایی با انواع تست‌های نرم‌افزاری در درس بعد. + +--- + +## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer) +- [ ] ریشه‌های ۵ گانه خطاهای ایجنت‌های هوش مصنوعی با استدلال‌های فنی و روان تحلیل شده باشند. +- [ ] پدیده‌های Lost in the Middle و کدهای منسوخ با مثال‌های واقعی Next.js توضیح داده شوند. +- [ ] راهکارهای عملی (قانون سه شکست و پاکسازی بافت) به عنوان مهارت‌های محوری ارائه گردند. +- [ ] اهمیت اعتبارسنجی مستقل انسان در برابر چاپلوسی مدل مورد تاکید صریح قرار گیرد. diff --git a/chapters/09-testing-and-debugging/02-lesson-testing-types-and-importance/spec.md b/chapters/09-testing-and-debugging/02-lesson-testing-types-and-importance/spec.md new file mode 100644 index 0000000..e945e3a --- /dev/null +++ b/chapters/09-testing-and-debugging/02-lesson-testing-types-and-importance/spec.md @@ -0,0 +1,111 @@ +# مشخصات درس‌نامه: انواع تست و اهمیت آن‌ها (Software Testing Types & Agentic Testing) +- **شناسه در سیلابس:** `L9.3` +- **فصل:** فصل ۹: تست و Debugging (Ch 9) +- **نوع محتوا:** 📘 درس‌نامه متنی +- **زمان تقریبی مطالعه:** ۱۵ دقیقه +- **پیش‌نیازهای مستقیم:** `L9.2` (چرا Agent اشتباه می‌کند؟) + +--- + +## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy) +دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند: +- [ ] **درک کند (Understand):** هرم استاندارد تست‌های نرم‌افزاری و تمایز میان سه لایه اصلی: **تست‌های واحد (Unit Tests)، تست‌های یکپارچگی (Integration Tests)، و تست‌های سرتاسری (End-to-End / E2E Tests)** را توضیح دهد. +- [ ] **تحلیل/ارزیابی کند (Evaluate):** چرا تست‌های خودکار بهترین بیمه‌نامه در برابر «باگ‌های پس‌رفتی (Regression Bugs)» در هنگام توسعه سریع با هوش مصنوعی هستند. +- [ ] **درک کند (Understand):** ابزارهای مدرن اجرای تست در وب به ویژه **Vitest** (برای تست‌های سریع یونیت) و **Playwright** (برای شبیه‌سازی مرورگر واقعی در تست‌های E2E) چگونه کار می‌کنند. +- [ ] **به‌کار ببندد (Apply):** از ایجنت‌های هوش مصنوعی (Cursor / Claude Code) برای تولید خودکار و اجرای کدهای تست کامپوننت‌های پورتفولیو (مانند کارت پروژه‌ها و فرم ورود) بهره‌برداری کند. +- [ ] **به‌کار ببندد (Apply):** فرامین اجرای آزمون‌ها را با استفاده از منوهای کشویی سیستم‌عامل‌ها در ترمینال اجرا و گزارش قبولی تیک‌های سبز را تحلیل نماید. + +--- + +## ۲. محدوده و مرزهای محتوا (Scope & Boundaries) + +### آنچه باید پوشش داده شود (In-Scope): +1. **هرم تست‌های نرم‌افزاری (The Testing Pyramid):** + * **لایه ۱: تست‌های واحد (Unit Tests - قاعده هرم):** + * آزمایش کوچک‌ترین قطعات کد به صورت ایزوله. + * مثال: آیا تابع کوتاه کردن توضیحات، متن‌های بالای ۱۰۰ کاراکتر را با `...` کوتاه می‌کند؟ آیا کامپوننت `ProjectCard` عنوان و بج‌ها را درست رندر می‌کند؟ + * **لایه ۲: تست‌های یکپارچگی (Integration Tests - میانه هرم):** + * آزمایش هماهنگی و گفتگوی چند جزء با یکدیگر. + * مثال: آیا فرم افزودن پروژه پس از فشردن دکمه ثبت، اطلاعات را به درستی به کلاینت سوپابیس فرستاده و پیام موفقیت توست را فعال می‌کند؟ + * **لایه ۳: تست‌های سرتاسری (E2E Tests - نوک هرم):** + * شبیه‌سازی دقیق رفتار کاربر در مرورگر واقعی بدون دخالت دست. + * مثال: یک ربات مرورگر باز شود $\rightarrow$ به `/login` برود $\rightarrow$ ایمیل و پسورد را تایپ کند $\rightarrow$ وارد `/admin` شود $\rightarrow$ پروژه جدید بسازد $\rightarrow$ به صفحه اصلی برود و وجود پروژه را تایید کند! +2. **ابزارهای پیشتاز وب: معرفی Vitest و Playwright:** + * **Vitest:** موتور اجرای تست سبک و برق‌آسا برای فریم‌ورک‌های مدرن وب. + * **Playwright:** ابزار قدرتمند شرکت مایکروسافت برای اتوماسیون و تست در مرورگرهای کروم، فایرفاکس و سافاری. +3. **تولید خودکار تست با ایجنت‌های هوش مصنوعی (Agentic Testing):** + * نیازی به حفظ کردن سینتکس پیچیده `expect` و `assert` نیست! + * پرامپت استاندارد ساخت تست: + *«کدهای کامپوننت `src/components/ProjectCard.tsx` را بخوان و یک مجموعه تست کامل با Vitest بنویس که موارد زیر را راستی‌آزمایی کند: ۱. رندر درست تایتل و تگ‌ها، ۲. باز شدن پنجره مودال با کلیک کاربر، ۳. وضعیت بدون تصویر.»* +4. **دستورات چندسکویی اجرای تست‌ها در ۳ منوی کشویی:** + * دستور اجرای تست‌های یونیت: `npx vitest run` + * دستور اجرای تست‌های مرورگر: `npx playwright test` + * منوهای کشویی اختصاصی برای Windows، macOS و Linux. +5. **توازن طلایی: تست خودکار در کنار تست دستی انسان:** + * تست خودکار مطمئن می‌شود کدهای دیروز خراب نشده‌اند؛ تست انسانی مطمئن می‌شود که ظاهر و حس کاربری دلنشین و زیباست. +6. **کال‌اوت‌های Quera:** + * `
`: تولید خودکار تست با AI؛ چگونه یکی از خسته‌کننده‌ترین وظایف مهندسی به یک پرامپت ۱۰ ثانیه‌ای تبدیل شده است؟ + * `
`: تله توهم تست‌های سبز؛ چرا داشتن ۱۰۰٪ تست سبز به معنای بی‌نقص بودن تجربه کاربر نیست اگر دکمه زیر یک لایه بصری پنهان شده باشد. + +### آنچه نباید وارد آن شویم (Out-of-Scope): +- کانفیگ‌های پیشرفته پایپ‌لاین‌های CI/CD در گیت‌هاب اکشنز (فصل ۱۲). +- آموزش تخصصی ماک کردن عمیق سوکت‌های شبکه برای سیستم‌های پیچیده. + +--- + +## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms) + +| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده | +| :--- | :--- | :--- | +| Testing Pyramid | هرم آزمون نرم‌افزار | مدل ساختاری توزیع بهینه تست‌ها: تعداد زیاد تست واحد، تست‌های یکپارچگی متوسط و تست‌های E2E متمرکز | +| Unit Test | تست واحد | آزمودن یک تابع، کامپوننت یا بخش کوچک و مستقل از برنامه در شرایط ایزوله | +| Integration Test | تست یکپارچگی | سنجش درستی عملکرد و تبادل داده میان دو یا چند بخش متصل به یکدیگر در سیستم | +| End-to-End (E2E) Test | تست سرتاسری | آزمایش کامل فرآیند کاربر از ابتدا تا انتها با شبیه‌سازی مرورگر واقعی | +| Vitest | ویتست | فریم‌ورک سریع و مدرن اجرای تست‌های جاوااسکریپت و تایپ‌اسکریپت بر پایه ابزار Vite | +| Playwright | پلی‌رایت | ابزار اتوماسیون تست مرورگرها برای شبیه‌سازی دقیق کلیک‌ها، فرم‌ها و روتینگ | + +--- + +## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders) +> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` قرار گرفته و در قالب جدول تک‌خانه‌ای وسط‌چین با کپشن تفصیلی درج شوند: + +1. **تصویر کاور درس:** `images/cover.png` + * **موضوع:** کاور مدرن با تم تیره که هرم نئونی سه‌بعدی تست‌های نرم‌افزاری را با نمادهای تیک سبز درخشان در فضای دیجیتال نمایش می‌دهد. +2. **دیاگرام هرم استاندارد تست‌های نرم‌افزاری:** `images/testing-pyramid-diagram.png` + * **موضوع:** اینفوگرافیک هرمی: قاعده بزرگ تست‌های Unit $\rightarrow$ میانه تست‌های Integration $\rightarrow$ قله تست‌های E2E با مقایسه سرعت و هزینه هر لایه. +3. **تولید خودکار تست با پرامپت در کامپوزر:** `images/agentic-test-prompt-demo.png` + * **موضوع:** اسکرین‌شات از پنجره چت Cursor که با ارسال یک کامپوننت، فایل کامل `ProjectCard.test.tsx` را تحویل می‌دهد. +4. **ترمینال خروجی تیک‌های سبز Vitest:** `images/vitest-terminal-passed.png` + * **موضوع:** اسکرین‌شات از پنجره سیاه ترمینال با نمایش پیام پیروزمندانه `✓ 8 tests passed in 450ms` به رنگ سبز روشن. +5. **شبیه‌سازی مرورگر با Playwright:** `images/playwright-browser-simulation.png` + * **موضوع:** نمایش تصویری پنجره خودکار مرورگر که فرم لاگین را بدون دخالت دست پر کرده و به پنل ادمین می‌رود. + +--- + +## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`) + +1. **تیتر اصلی:** `# انواع تست و اهمیت آن‌ها: هرم ایمنی نرم‌افزار در عصر هوش مصنوعی` +2. **مقدمه:** چرا اضافه کردن یک فیچر جدید نباید باعث لرزیدن تن توسعه‌دهنده از خراب شدن کدهای قبلی شود؟ +3. **جدول کاور درس** +4. **هرم تست‌های نرم‌افزاری: سه لایه دفاعی مستحکم:** + * تست‌های واحد (Unit Tests) در خط مقدم. + * تست‌های یکپارچگی (Integration Tests) در نقطه اتصال. + * تست‌های سرتاسری (E2E Tests) در نقش کاربر نهایی. +5. **معرفی دو سلاح مدرن: Vitest و Playwright:** + * چرا این ابزارها جایگزین Jest و Selenium شدند؟ +6. **وایب تستینگ: سپردن نوشتن تست‌ها به ایجنت‌های هوش مصنوعی:** + * تکنیک پرامپت‌نویسی برای تولید فایل‌های `.test.tsx`. + * دستورات چندسکویی اجرای تست‌ها در ویندوز، مک و لینوکس. +7. **باکس نکته Quera (`
`):** تغییر بازی؛ پایان کابوس تست‌نویسی دستی با هدایت هوشمند ایجنت. +8. **توازن طلایی: تست‌های خودکار در کنار نگاه موشکافانه انسان:** + * کارهایی که ربات‌ها می‌توانند و کارهایی که فقط انسان می‌فهمد. +9. **باکس هشدار Quera (`
`):** تله توهم تست‌های سبز؛ همیشه کارایی واقعی را در مرورگر با چشمان خود بسنجید. +10. **جمع‌بندی درس‌نامه:** مجهز شدن به سیستم تست‌های خودکار و ورود به چک‌لیست طلایی تست دستی (Manual QA) در درس بعد. + +--- + +## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer) +- [ ] سه لایه هرم تست (Unit, Integration, E2E) با مثال‌های ملموس از پورتفولیو شرح داده شوند. +- [ ] ابزارهای مدرن Vitest و Playwright به همراه دلایل برتری آن‌ها معرفی گردند. +- [ ] پرامپت استخراج خودکار تست از ایجنت‌های هوش مصنوعی در متن گنجانده شود. +- [ ] دستورات ترمینالی اجرای تست‌ها با منوهای کشویی سیستم‌عامل‌ها پیاده‌سازی شوند. diff --git a/chapters/09-testing-and-debugging/03-lesson-manual-testing-and-qa-checklist/spec.md b/chapters/09-testing-and-debugging/03-lesson-manual-testing-and-qa-checklist/spec.md new file mode 100644 index 0000000..da63571 --- /dev/null +++ b/chapters/09-testing-and-debugging/03-lesson-manual-testing-and-qa-checklist/spec.md @@ -0,0 +1,114 @@ +# مشخصات درس‌نامه: بررسی خروجی، تست دستی و چک‌لیست تضمین کیفیت (QA Checklist) +- **شناسه در سیلابس:** `L9.4` +- **فصل:** فصل ۹: تست و Debugging (Ch 9) +- **نوع محتوا:** 📘 درس‌نامه متنی +- **زمان تقریبی مطالعه:** ۱۵ دقیقه +- **پیش‌نیازهای مستقیم:** `L9.3` (انواع تست و اهمیت آن‌ها) + +--- + +## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy) +دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند: +- [ ] **درک کند (Understand):** چرا تست‌های خودکار سبز (Automated Tests) هرگز کافی نیستند و چرا بررسی چشمی، تست دستی اکتشافی (Exploratory Testing) و بازبینی خط‌به‌خط تغییرات (Diff Review) آخرین سنگر دفاعی محصول هستند. +- [ ] **تحلیل/ارزیابی کند (Evaluate):** تغییرات کدی که ایجنت در فایل‌های پروژه ایجاد کرده است را با مهارت Code Review غیربرنامه‌نویسی (بررسی کدهای اضافه، پکیج‌های مخفی، کلیدهای هاردکد شده و کامپوننت‌های دست‌نخورده) ارزیابی کند. +- [ ] **به‌کار ببندد (Apply):** چک‌لیست جامع تضمین کیفیت (QA Checklist) ۱۰ مرحله‌ای شامل: اعتبارسنجی فرم‌ها، سناریوهای مرزی (Edge Cases)، وضعیت‌های خطا، رفتار در صفحات کوچک موبایل، وضعیت بدون اینترنت و رندر فونت‌های فارسی را روی پورتفولیوی شخصی اجرا کند. +- [ ] **ایجاد کند (Create):** یک پرامپت استاندارد گزارش تست دستی به همراه اسکرین‌شات و شرح گام‌به‌گام بازتولید باگ (Reproduction Steps) تدوین کند تا ایجنت مشکل را در اولین تلاش رفع کند. + +--- + +## ۲. محدوده و مرزهای محتوا (Scope & Boundaries) + +### آنچه باید پوشش داده شود (In-Scope): +1. **تفاوت تست خودکار و احساس کاربر واقعی:** + * کامپیوترها منطق شرط‌ها را می‌سنجند، اما چشم انسان ناهماهنگی چیدمان، شکستن خط متن، دکمه‌های ناخوانا و حس بد کاربر را درک می‌کند. +2. **هنر Code Review بدون نیاز به تسلط بر نحو برنامه‌نویسی:** + * خواندن Git Diff در Cursor و VS Code: آیا فقط فایل‌های مرتبط تغییر کرده‌اند؟ + * شناسایی «کدهای سرگردان و فراموش‌شده» (Ghost Code / Hallucinated Imports). + * کشف کلیدهای محرمانه و توکن‌هایی که ممکن است ناخواسته داخل کامپوننت‌ها نوشته شده باشند. +3. **چک‌لیست ۱۰ گانه QA برای وایب کدرها:** + * ۱. تست مسیرهای بحرانی (Happy Path): لاگین ادمین، ثبت پروژه، ذخیره تنظیمات سئو. + * ۲. تست ورودی‌های مخرب و غیرمعمول (Edge Cases): فیلدهای بسیار طولانی، کاراکترهای ایموجی، متن خالی و لینک‌های نامعتبر. + * ۳. تست نمایش در موبایل واقعی و صفحات باریک (۳۲۰ تا ۳۹۰ پیکسل). + * ۴. بررسی تایپوگرافی فارسی و راست‌چین (RTL) در تمام فرم‌ها و خطاها. + * ۵. تست وضعیت‌های شبکه: قطع اتصال، اینترنت کند و خطاهای سرور. + * ۶. چک کردن مسیرهای ناموجود (صفحه ۴۰۴ اختصاصی). + * ۷. تست دسترسی‌پذیری سریع (فوکوس با کلید Tab روی دکمه‌ها و فرم‌ها). + * ۸. تست خروج از سیستم (Logout) و پاک شدن سشن‌ها. + * ۹. بازبینی کنسول مرورگر برای نبود هشدارهای زرد و خطاهای قرمز (Hydration Errors). + * ۱۰. تست کش مرورگر و رفرش سخت (Hard Reload). +4. **جعبه پرامپت طلایی گزارش باگ به ایجنت:** + * فرمول گزارش باگ: «رفتار مورد انتظار (Expected) + رفتار واقعی رخ داده (Actual) + گام‌های بازتولید (Steps) + اسکرین‌شات یا خطای کنسول». +5. **دستورات چندسکویی برای بررسی پروژه و ساخت Build تست:** + * اجرای تست ساخت کامل (`npm run build`) برای کشف خطاهای زمان کامپایل قبل از تست دستی. +6. **کال‌اوت‌های آموزشی و هشدار کوئرا:** + * کال‌اوت بنفش (`
`): مفهوم تست اکتشافی (Monkey Testing / Exploratory Testing). + * کال‌اوت سبز (`
`): توصیه به تست با گوشی واقعی به جای شبیه‌ساز مرورگر. + * کال‌اوت قرمز (`
`): تله «تأیید کورکورانه تغییرات ایجنت» (Accept All بدون دیدن Diff). + +### آنچه نباید وارد آن شویم (Out-of-Scope): +- مباحث تکنیکال تست نفوذ امنیتی SQL Injection و XSS پیشرفته (فصل ۱۱). +- ابزارهای تحلیل رفتار کاربر مانند Hotjar و مانیتورینگ آنلاین لاگ‌های سرور بعد از دیپلوی (فصل ۱۳). + +--- + +## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms) + +| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده | +| :--- | :--- | :--- | +| Code Review | بازبینی کد | بررسی دقیق تغییرات پیش از اعمال در شاخه اصلی پروژه برای کشف باگ و خطای ناخواسته | +| Git Diff | نمایش تفاوت کدها | ابزار بصری مقایسه نسخه قبلی و تغییرات جدید با رنگ سبز (اضافه) و قرمز (حذف) | +| Exploratory Testing | تست اکتشافی | آزمودن آزادانه نرم‌افزار توسط انسان برای پیدا کردن رفتارهای غیرمنتظره و عجیب | +| Edge Case | حالت حدی و نامتعارف | شرایط استثنایی یا ورودی‌های غیرمعمول که معمولاً در سناریوهای عادی تست از قلم می‌افتند | +| Reproduction Steps | گام‌های بازتولید خطا | مراحل ترتیبی و گام‌به‌گامی که هر فرد برای تکرار دقیق باگ در سیستم باید طی کند | +| Blind Acceptance | پذیرش کورکورانه | خطای رایج زدن دکمه «قبول همه تغییرات» ایجنت بدون خواندن فایل‌های دستکاری‌شده | + +--- + +## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders) +> **راهنمای ایجنت نویسنده:** تصاویر باید در پوشهٔ `images/` ذخیره شده و در جدول تک‌خانه‌ای قرار گیرند: + +1. **تصویر کاور درس:** `images/cover.png` + * **موضوع:** کاربری با ذره‌بین دیجیتال در حال بررسی کدهای پروژه روی یک تبلت و تیک زدن چک‌لیست تضمین کیفیت. +2. **پنجره بازبینی Diff در ادیتور:** `images/git-diff-inspection.png` + * **موضوع:** نمایش خطوط قرمز (حذف‌شده) و سبز (اضافه‌شده) در ابزار کامپوزر Cursor با نشانه‌گذاری کدهای خطرناک یا اضافه. +3. **اینفوگرافیک چک‌لیست ۱۰ مرحله‌ای QA:** `images/qa-checklist-infographic.png` + * **موضوع:** طراحی بصری ۱۰ گام بازرسی طلایی با آیکون‌های فرم، موبایل، شبکه، کنسول و سشن ادمین. +4. **گزارش باگ سیستماتیک در گفتگو با ایجنت:** `images/structured-bug-report-prompt.png` + * **موضوع:** چت‌باکس ادیتور که گزارش منظم خطا با فرمت ۴ مرحله‌ای به ایجنت ارائه شده و ایجنت در حال اصلاح دقیق است. + +--- + +## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`) + +1. **تیتر اصلی:** `# بررسی خروجی، تست دستی و چک‌لیست تضمین کیفیت (QA Checklist)` +2. **مقدمه:** ایجنت می‌گوید «کار تمام شد و تست‌ها سبز است!»؛ اما آیا پروژه واقعاً در دستان کاربر کار می‌کند؟ +3. **جدول کاور درس** +4. **استعاره بازرس ساختمان در برابر کارگران ساختمانی:** + * بناها آجرها را می‌چینند، اما بازرس با چک‌لیست لوله‌کشی، برق، فشار آب و ارگونومی درها را بررسی می‌کند. شما بازرس کل پروژه خود هستید. +5. **مهارت بازبینی کد (Code Review) برای افراد غیربرنامه‌نویس:** + * سه سؤالی که هنگام دیدن Git Diff باید بپرسید: + 1. آیا فایلی که ربطی به این تسک ندارد تغییر کرده است؟ + 2. آیا پکیج عجیب یا خط کدی با کامنت‌های عجیب اضافه شده؟ + 3. آیا کد کارآمد قبلی تصادفاً پاک یا ساده‌سازی نشده است؟ +6. **چک‌لیست ۱۰ گانه QA برای وایب کدرها (با تمرکز روی پروژه پورتفولیو):** + * شرح گام‌به‌گام تست هر بخش: فرم لاگین ادمین، ثبت مشخصات، اعتبارسنجی ارقام، وضعیت بدون نت، و رسپانسیو بودن. +7. **باکس نکته Quera (`
`):** تست اکتشافی و تکنیک «میمون بازیگوش» (تایپ کاراکترهای عجیب و غریب و کلیک‌های پشت‌سرهم سریع روی دکمه‌ها). +8. **دستورات چندسکویی ساخت تست پروداکشن قبل از QA:** + * اجرای Build پروژه برای اطمینان از عدم وجود خطای تایپ یا ایمپورت ناقص. + * منوی کشویی سه‌گانه برای ویندوز، مک و لینوکس: + - Windows (PowerShell): `npm run build` + - macOS (Terminal): `npm run build` + - Linux (Bash): `npm run build` +9. **جعبه پرامپت طلایی: انتقال گزارش باگ به ایجنت بدون افتادن در سردرگمی:** + * ساختار قالب گزارش باگ برای ایجنت. +10. **باکس هشدار Quera (`
`):** خطای پذیرش کورکورانه (Blind Accept)؛ هرگز بدون بازبینی سریع تغییرات فایل‌ها، کد را تحویل نگیرید. +11. **باکس رضایت‌بخش Quera (`
`):** تست روی موبایل واقعی از طریق هات‌اسپات و آی‌پی لوکال؛ تجربه‌ای که هیچ شبیه‌سازی جای آن را نمی‌گیرد. +12. **جمع‌بندی درس‌نامه:** تثبیت چک‌لیست بازبینی و آماده‌سازی برای ورود به جهان دیباگ تخصصی و خواندن پیام‌های خطا در درس بعد. + +--- + +## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer) +- [ ] روش بازبینی Git Diff به صورت کاربردی برای افراد غیر فنی تشریح شده باشد. +- [ ] چک‌لیست ۱۰ مرحله‌ای QA با مثال‌های مستقیم از پروژه پورتفولیو ارائه گردد. +- [ ] ساختار ۴ مرحله‌ای گزارش باگ به ایجنت به همراه پرامپت نمونه آماده کپی گنجانده شود. +- [ ] دستورات اجرای بیلد چندسکویی در تب‌های کشویی ویندوز، مک و لینوکس درج شده باشد. diff --git a/chapters/09-testing-and-debugging/04-lesson-ai-debugging-techniques/spec.md b/chapters/09-testing-and-debugging/04-lesson-ai-debugging-techniques/spec.md new file mode 100644 index 0000000..528330e --- /dev/null +++ b/chapters/09-testing-and-debugging/04-lesson-ai-debugging-techniques/spec.md @@ -0,0 +1,127 @@ +# مشخصات درس‌نامه: اصول دیباگ کردن خطاها و خواندن لاگ‌ها با کمک هوش مصنوعی +- **شناسه در سیلابس:** `L9.5` +- **فصل:** فصل ۹: تست و Debugging (Ch 9) +- **نوع محتوا:** 📘 درس‌نامه متنی +- **زمان تقریبی مطالعه:** ۱۵ دقیقه +- **پیش‌نیازهای مستقیم:** `L9.4` (بررسی خروجی، تست دستی و چک‌لیست QA) + +--- + +## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy) +دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند: +- [ ] **درک کند (Understand):** چرا مواجهه با صفحه قرمز خطا (Error Overlay) یا لاگ‌های ترمینال نباید ترسناک باشد و چگونه پیام‌های خطا به عنوان راهنمای مستقیم و گره‌گشای سیستم عمل می‌کنند. +- [ ] **تحلیل/ارزیابی کند (Evaluate):** ساختار یک پیام خطا و ردپای اجرا (Stack Trace) را تفکیک کرده و تفاوت خطاهای فرانت‌اند (کنسول مرورگر / Hydration) را با خطاهای سرور و پایگاه داده (ترمینال / Supabase / 500 / RLS) ارزیابی کند. +- [ ] **به‌کار ببندد (Apply):** روش سیستماتیک ۴ مرحله‌ای دیباگ (مشاهده دقیق $\rightarrow$ ایزوله‌سازی $\rightarrow$ کشف ریشه با فرضیه‌سازی $\rightarrow$ اصلاح از طریق ایجنت) را روی باگ‌های شبیه‌سازی‌شده در پروژه پورتفولیو پیاده کند. +- [ ] **ایجاد کند (Create):** پرامپت طلایی «کالبدشکافی و کشف ریشه قبل از نوشتن کد» (Root Cause Analysis Prompt) را تنظیم کند تا از افتادن ایجنت در چرخه وصله‌پینه‌های بی‌اثر جلوگیری نماید. + +--- + +## ۲. محدوده و مرزهای محتوا (Scope & Boundaries) + +### آنچه باید پوشش داده شود (In-Scope): +1. **شکستن طلسم ترس از خطاهای سرخ:** + * کامپیوترها دروغ نمی‌گویند؛ وقتی خطایی چاپ می‌شود، دقیقاً نام فایل، شماره خط و علت رخ دادن را فریاد می‌زنند. +2. **کالبدشکافی پیام خطا و استک‌تریس (Anatomy of a Stack Trace):** + * خط اصلی پیام خطا (Error Message): مشکل چیست؟ (مانند `TypeError: Cannot read properties of undefined`). + * شماره خط و فایل مبدأ (File and Line Number): مشکل کجاست؟ (مانند `components/ProjectCard.tsx:42:15`). + * ردپای توابع فراخواننده (Call Stack): چطور به این نقطه رسیدیم؟ +3. **تفکیک جغرافیای خطاهای مدرن وب:** + * خطاهای مرورگر (Client-side): بررسی در تب Console در Chrome DevTools. + * خطاهای سرور (Server-side): بررسی در پنجره ترمینال ران‌کننده Next.js (`npm run dev`). + * خطاهای پایگاه داده و شبکه: بررسی در تب Network و خطاهای HTTP (400 Bad Request, 401 Unauthorized, 403 Forbidden, 500 Internal Server Error). +4. **تکنیک «حل اولین خطا اول» (First Error First):** + * در بسیاری از مواقع، یک خطای پایه‌ای باعث ایجاد ۲۰ خطای آبشاری بعدی می‌شود. تمرکز فقط بر روی بالاترین خطای رخ داده. +5. **روش ۴ مرحله‌ای دیباگ سیستماتیک با ایجنت:** + * گام ۱: متوقف کردن سردرگمی و خواندن آرام پیام. + * گام ۲: تفکیک کد از لاگ؛ کپی کردن فقط خطوط مفید لاگ (نه ۵۰۰ خط بی‌ربط). + * گام ۳: ارسال متن خطا + فایل مرتبط با کلید `@` به چت ایجنت. + * گام ۴: الزام ایجنت به توضیح علت ریشه‌ای (Root Cause) پیش از ارائه پچ و کد جدید. +6. **دستورات چندسکویی برای تمیز کردن کش و ری‌استارت محیط:** + * دستورات پاک کردن فولدر `.next` و ری‌استارت سرور توسعه در سه سیستم‌عامل. +7. **کال‌اوت‌های آموزشی و هشدار کوئرا:** + * کال‌اوت بنفش (`
`): مفهوم Hydration Mismatch در Next.js و دلیل تفاوت محتوای سرور و کلاینت. + * کال‌اوت سبز (`
`): قانون طلایی «قانون ۵ دقیقه»؛ اگر ایجنت در دو تلاش باگ را رفع نکرد، کش را پاک کنید و سرور را ری‌استارت کنید. + * کال‌اوت قرمز (`
`): هشدار کپی کردن کامل خروجی‌های غول‌پیکر ترمینال بدون انتخاب پیام خطای هدف. + +### آنچه نباید وارد آن شویم (Out-of-Scope): +- ابزارهای مانیتورینگ آنلاین لاگ‌ها نظیر Sentry یا Datadog (فصل ۱۳). +- تست‌های نفوذ و دیباگ حملات امنیتی (فصل ۱۱). + +--- + +## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms) + +| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده | +| :--- | :--- | :--- | +| Stack Trace | ردپای اجرا / استک‌تریس | فهرست ترتیبی توابعی که در حافظه اجرا شدند تا در نهایت به نقطه بروز خطا رسیدند | +| Root Cause Analysis | تحلیل ریشه‌ای خطا | فرآیند کشف سرچشمه واقعی مشکل، به جای دستکاری یا وصله‌پینه کردن علائم ظاهری | +| Hydration Mismatch | ناهمخوانی هایدریشن | خطای فرانت‌اند ناشی از تفاوت محتوای ساخته‌شده توسط سرور با محتوای رندر شده مرورگر | +| Error Overlay | پرده نمایش خطای زنده | صفحه گرافیکی قرمزرنگی که فریمورک‌هایی مثل Next.js هنگام بروز باگ روی صفحه باز می‌کنند | +| Cascading Errors | خطاهای آبشاری | خطاهای زنجیره‌ای پرشماری که تنها در اثر یک اشتباه منفرد در ابتدای برنامه پدیدار می‌شوند | +| Server Action Error | خطای اکشن‌های سرور | باگ‌های مربوط به عملیات سمت سرور در Next.js هنگام برقراری ارتباط با دیتابیس یا فایل‌ها | + +--- + +## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders) +> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` ذخیره شده و در جدول تک‌خانه‌ای درج شوند: + +1. **تصویر کاور درس:** `images/cover.png` + * **موضوع:** نمایش دیجیتال کاربری که شبیه کارآگاه، سرنخ‌های پیام خطای قرمز در کنسول را دنبال کرده و به قطعه کد معیوب می‌رسد. +2. **کالبدشکافی پیام خطا و استک‌تریس:** `images/stack-trace-anatomy.png` + * **موضوع:** اسکرین‌شات از پنجره قرمز خطای Next.js با فلش‌های توضیحی روی پیام خطا، فایل، شماره خط و کال استک. +3. **دیاگرام جغرافیای خطاها در وب مدرن:** `images/error-geography-diagram.png` + * **موضوع:** تفکیک سه‌گانه خطاها: کلاینت (کنسول DevTools)، سرور (ترمینال Next.js)، دیتابیس (شبکه و هدرهای Supabase). +4. **چرخه ۴ مرحله‌ای دیباگ سیستماتیک:** `images/four-step-debugging-flow.png` + * **موضوع:** فلوچارت تعاملی: مشاهده آرام $\rightarrow$ استخراج لاگ تمیز $\rightarrow$ تحلیل علت با ایجنت $\rightarrow$ تست اصلاحیه. + +--- + +## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`) + +1. **تیتر اصلی:** `# اصول دیباگ کردن خطاها و خواندن لاگ‌ها با کمک هوش مصنوعی` +2. **مقدمه:** چرا مواجهه با صفحه تماماً قرمز Next.js نشانه شکست نیست، بلکه دقیق‌ترین قطب‌نمای شما برای حل مشکل است؟ +3. **جدول کاور درس** +4. **استعاره پزشک اورژانس و آزمایش خون:** + * بیمار داد می‌زند «دلم درد می‌کند» (ظاهر باگ)، اما پزشک به آزمایش خون و برگه علائم حیاتی نگاه می‌کند (لاگ و استک‌تریس). +5. **کالبدشکافی یک استک‌تریس واقعی در پروژه پورتفولیو:** + * بررسی عمیق یک خطای متداول: + `TypeError: Cannot read properties of null (reading 'title')` در صفحه جزئیات پروژه. + * چگونه شماره خط و نام فایل را بخوانیم و فایل هدف را باز کنیم. +6. **جغرافیای خطاها: باگ من دقیقاً کجاست؟** + * خطاهای مرورگر (تب Console در DevTools). + * خطاهای سرور (صفحه مشکی ترمینال ادیتور). + * خطاهای ارتباطی و شبکه (تب Network و کدهای وضعیت 401 و 404). +7. **باکس نکته Quera (`
`):** خطای مشهور Hydration Error در React/Next.js و چرایی وقوع آن هنگام استفاده از افزونه‌های مرورگر یا توابع زمان. +8. **روش ۴ مرحله‌ای دیباگ سیستماتیک در وایب کدینگ:** + * گام‌به‌گام از کپی کردن بخش مرتبط تا پرامپت‌نویسی بدون ایجاد سردرگمی برای ایجنت. +9. **دستورات چندسکویی پاک‌سازی کش در زمان هنگ کردن یا باگ‌های مرموز:** + * منوی کشویی سه‌گانه برای ویندوز، مک و لینوکس: + - Windows (PowerShell): + ```powershell + Remove-Item -Recurse -Force .next + npm run dev + ``` + - macOS (Terminal): + ```bash + rm -rf .next + npm run dev + ``` + - Linux (Bash): + ```bash + rm -rf .next + npm run dev + ``` +10. **جعبه پرامپت طلایی: تحلیل ریشه‌ای خطا قبل از دستکاری کد:** + * نمونه پرامپت رسمی: + > «من با خطای زیر مواجه شدم. پیش از اینکه هیچ تغییری در فایل‌ها اعمال کنی، ۱) به زبان بسیار ساده علت ریشه‌ای بروز این خطا را توضیح بده، ۲) دقیقاً مشخص کن کدام بخش از جریان داده مشکل دارد، ۳) سپس کد اصلاح‌شده پیشنهادی را ارائه بده.» +11. **باکس هشدار Quera (`
`):** پرهیز از بمباران ایجنت با کل متن ترمینال؛ نویز کمتر، دقت بالاتر هوش مصنوعی. +12. **باکس نکته اطمینان‌بخش Quera (`
`):** قانون اولویت اولین خطا (First Error First)؛ حل اولین خطا اغلب ۱۹ خطای بعدی را مانند دومینو ناپدید می‌کند. +13. **جمع‌بندی درس‌نامه:** تسلط بر مهارت خواندن پیام خطا و آمادگی برای تکنیک‌های دیباگ تعاملی و ابزارهای حاشیه‌نویسی (Annotation) در درس پایانی فصل. + +--- + +## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer) +- [ ] ساختار استک‌تریس به همراه مثال کاربردی و ملموس از پورتفولیو توضیح داده شود. +- [ ] تفکیک شفاف بین خطاهای کلاینت، سرور و دیتابیس با ارجاع به ابزارهای بازرسی انجام گیرد. +- [ ] پرامپت تحلیل ریشه‌ای (Root Cause Prompt) به همراه استراتژی ۴ مرحله‌ای گنجانده شود. +- [ ] دستورات ترمینالی پاک‌سازی کش در تب‌های سه‌گانه ویندوز، مک و لینوکس آورده شود. diff --git a/chapters/09-testing-and-debugging/05-lesson-resolving-common-errors/spec.md b/chapters/09-testing-and-debugging/05-lesson-resolving-common-errors/spec.md new file mode 100644 index 0000000..6e05e9c --- /dev/null +++ b/chapters/09-testing-and-debugging/05-lesson-resolving-common-errors/spec.md @@ -0,0 +1,124 @@ +# مشخصات درس‌نامه: دیباگ تعاملی با Agent، ابزارهای حاشیه‌نویسی و حل خطاهای متداول +- **شناسه در سیلابس:** `L9.6` +- **فصل:** فصل ۹: تست و Debugging (Ch 9) +- **نوع محتوا:** 📘 درس‌نامه متنی +- **زمان تقریبی مطالعه:** ۱۸ دقیقه +- **پیش‌نیازهای مستقیم:** `L9.5` (اصول دیباگ کردن خطاها و خواندن لاگ‌ها) + +--- + +## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy) +دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند: +- [ ] **درک کند (Understand):** تفاوت دیباگ مکانیکی سنتی با «دیباگ تعاملی با ایجنت» (Interactive Agentic Debugging) چیست و چگونه می‌توان از قابلیت‌های نوین ابزارهای Cursor، Claude Code و Antigravity (نظیر ارجاع مستقیم به ترمینال و اسکرین‌شات) بیشترین بهره را برد. +- [ ] **تحلیل/ارزیابی کند (Evaluate):** پدیده مخرب «چرخه باطل عذرخواهی و وصله‌پینه» (Apology & Patching Loop) را در ایجنت‌ها شناسایی کند و بداند چه زمانی باید گفتگو را متوقف کرده و با Git Rollback از ابتدا شروع نماید. +- [ ] **به‌کار ببندد (Apply):** ۴ خطای پرتکرار و مرگبار در دنیای وایب کدینگ (سیاست‌های RLS سوپابیس، کلیدهای مخفی تعریف‌نشده در `.env`، تداخل کلاینت/سرور کامپوننت و تغییرات Dynamic Params در نکست‌جی‌اس) را با الگوهای تضمینی حل کند. +- [ ] **ایجاد کند (Create):** یک پرامپت ایزوله‌سازی با تزریق لاگ‌های موقت (`console.log`) ایجاد کند تا ایجنت بتواند نقطه دقیق قطع جریان داده را بدون تغییرات غیرضروری در سایر فایل‌ها شناسایی کند. + +--- + +## ۲. محدوده و مرزهای محتوا (Scope & Boundaries) + +### آنچه باید پوشش داده شود (In-Scope): +1. **انقلاب در روش دیباگ: دیباگ تعاملی به جای سردرگمی در کد:** + * چگونه بدون خواندن هزار خط کد، مستقیماً با ایجنت دیالوگ مهندسی برقرار کنیم؟ +2. **ابزارهای پیشرفته حاشیه‌نویسی بصری و اتصال به محیط (Visual Annotation & Context):** + * استفاده از قابلیت بازرسی مرورگر داخلی و گرفتن اسکرین‌شات از المان معیوب. + * ویژگی ارجاع مستقیم به خروجی ترمینال در ابزارهای مدرن (کلید `@terminal` در Cursor یا خواندن خودکار در Claude Code). +3. **شکستن چرخه باطل «عذرخواهی می‌کنم، الان درستش می‌کنم!» (The Apology Loop):** + * وقتی ایجنت به بن‌بست می‌رسد و شروع به تکرار کدهای اشتباه یا خراب کردن بخش‌های سالم می‌کند: + - قانون طلایی سه تلاش (Three-Strikes Rule): بعد از دو بار ناموفق بودن، فوراً `git checkout` یا `git stash` بزنید. + - پاک کردن Context چت و شروع یک گفتگوی تازه با پرامپت دقیق‌تر و کانتکست ایزوله. +4. **کالبدشکافی ۴ تله فوق‌العاده رایج و راه‌حل قطعی آن‌ها:** + * تله ۱: خطای ۴۰۳ یا خالی بودن لیست پروژه‌ها در Supabase $\leftarrow$ فراموشی یا نقص در تعریف سیاست RLS. + * تله ۲: مقدار `undefined` برای متغیرهای محیطی $\leftarrow$ پیشوند اشتباه `NEXT_PUBLIC_` یا فراموشی ری‌استارت سرور. + * تله ۳: خطای React در هوک‌ها (`useState` / `useEffect`) $\leftarrow$ نبود دایرکتیو `'use client'` در بالای فایل. + * تله ۴: خطای تایپ یا اجرای Dynamic Routes در Next.js مدرن $\leftarrow$ ناهمگام بودن دسترسی به `params`. +5. **تکنیک لاگ‌گذاری موقت (Minimal Instrumentation):** + * درخواست از ایجنت برای افزودن ۳ خط `console.log` برای دیدن خروجی متغیرها در ترمینال، قبل از هرگونه بازنویسی کد. +6. **دستورات چندسکویی برای بازگشت سریع به آخرین وضعیت پایدار گیت (Rollback):** + * دستورات پاک کردن تغییرات تست و بازگشت به کامیت قبلی در سه سیستم‌عامل. +7. **کال‌اوت‌های آموزشی و هشدار کوئرا:** + * کال‌اوت بنفش (`
`): قابلیت‌های ویژه اپلیکیشن‌های دسکتاپ هوش مصنوعی در درک باگ‌های بصری. + * کال‌اوت سبز (`
`): آرامش خاطر با کامیت‌های متوالی و کوچک؛ بیمه بدنه کدهای شما. + * کال‌اوت قرمز (`
`): خطر تایید تغییرات در فایل‌های کانفیگ اصلی (`next.config.js`, `tsconfig.json`) توسط ایجنت در حالت سردرگمی. + +### آنچه نباید وارد آن شویم (Out-of-Scope): +- تنظیمات CI/CD ابری و اکشن‌های گیت‌هاب (فصل ۱۲ و ۱۳). +- تست‌های نفوذ و دیباگ باگ‌های امنیتی پیشرفته (فصل ۱۱). + +--- + +## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms) + +| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده | +| :--- | :--- | :--- | +| Interactive Debugging | دیباگ تعاملی | فرآیند گفتگوی پیوسته و هوشمند با ایجنت برای رفع پله‌پله خطاها بر اساس شواهد | +| Visual Annotation | حاشیه‌نویسی بصری | مشخص کردن المان معیوب رابط کاربری با کادر یا اسکرین‌شات و ارجاع مستقیم آن به ایجنت | +| Apology Loop | چرخه باطل عذرخواهی | وضعیتی که مدل به طور پیوسته عذرخواهی کرده و راه‌حل‌های بی‌اثر را تکرار می‌کند | +| Three-Strikes Rule | قانون سه ضربه | توقف گفتگو با ایجنت پس از دو تلاش ناموفق برای جلوگیری از خرابکاری‌های بیشتر در کد | +| Clean Context Window | پنجره کانتکست پاک | شروع یک چت کاملاً جدید برای زدودن خطاهای قبلی و تمرکز مجدد ایجنت روی مسئله | +| Git Rollback | بازگشت به نسخه پایدار گیت | لغو تغییرات معیوب اخیر و بازگرداندن فایل‌ها به آخرین کامیت سالم | + +--- + +## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders) +> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` ذخیره شده و در جدول تک‌خانه‌ای درج شوند: + +1. **تصویر کاور درس:** `images/cover.png` + * **موضوع:** تقابل یک حلقه باطل تو در تو با یک مسیر مستقیم خروج اضطراری و دیباگ موفق با ایجنت. +2. **قابلیت حاشیه‌نویسی المان در ادیتور:** `images/visual-element-annotation.png` + * **موضوع:** تصویر ابزار انتخاب المان در مرورگر یا ادیتور مدرن که کاربر دور دکمه به‌هم‌ریخته کادر کشیده و ایجنت به کد آن متصل شده است. +3. **چرخه شکستن تله عذرخواهی ایجنت:** `images/breaking-apology-loop.png` + * **موضوع:** اینفوگرافیک گام‌به‌گام: خطای تکراری $\rightarrow$ توقف $\rightarrow$ بازگشت به آخرین کامیت (`git checkout`) $\rightarrow$ چت جدید با کانتکست خلوت. +4. **جدول راهنمای ۴ خطای طلایی و راه‌حل:** `images/common-errors-matrix.png` + * **موضوع:** ماتریس گرافیکی ۴ خطای مشهور (RLS، Environment Variables، 'use client'، Dynamic Params) با تصویر خطای قرمز و کد حل مشکل. + +--- + +## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`) + +1. **تیتر اصلی:** `# دیباگ تعاملی با Agent، ابزارهای حاشیه‌نویسی و حل خطاهای متداول` +2. **مقدمه:** وقتی ایجنت ۵ بار پشت سر هم می‌گوید «عذرخواهی می‌کنم، این بار مطمئناً درست شد!» و پروژه خراب‌تر می‌شود، چطور ترمز دستی را بکشیم؟ +3. **جدول کاور درس** +4. **تکنیک حاشیه‌نویسی بصری (Visual Annotation):** + * عکس بفرستید، نه هزار کلمه توضیح! چطور اسکرین‌شات یا المان خراب را مستقیم به خورد مدل بدهیم؟ + * اتصال مستقیم لاگ‌های ترمینال با `@terminal`. +5. **روان‌شناسی مدل‌های زبانی: چرا ایجنت در چرخه باطل وصله‌پینه می‌افتد؟** + * پدیده «لج‌بازی توکنی» وقتی تاریخچه چت پر از کدهای اشتباه قبلی است. + * قانون سه ضربه (Three-Strikes Rule): بعد از تلاش دوم، کلید Reset را بزنید. +6. **جعبه ابزار خروج اضطراری: بازگشت به نقطه امن با Git:** + * نحوه استفاده از دکمه Discard در VS Code یا کامندهای پاک‌سازی ترمینال. +7. **کالبدشکافی ۴ خطای پرتکرار در پروژه پورتفولیو و نسخه شفابخش آن‌ها:** + * خطای شماره ۱: دیتابیس Supabase پاسخ نمی‌دهد و لیست خالی برمی‌گرداند (سیاست RLS عمومی). + * خطای شماره ۲: کلیدهای محیطی `process.env` مقدار `undefined` دارند. + * خطای شماره ۳: خطای کامپوننت‌های کلاینت در استفاده از هوک‌های React. + * خطای شماره ۴: خطای تغییرات Next.js 15+ در دریافت پارامترهای آدرس داینامیک. +8. **باکس نکته Quera (`
`):** استفاده از پرامپت «فقط ۳ خط لاگ موقت اضافه کن» برای فهمیدن اینکه داده تا کدام خط می‌آید و کجا قطع می‌شود. +9. **دستورات چندسکویی بازگشت به وضعیت سالم قبلی در Git:** + * منوی کشویی سه‌گانه برای ویندوز، مک و لینوکس: + - Windows (PowerShell): + ```powershell + git restore . + git clean -fd + ``` + - macOS (Terminal): + ```bash + git restore . + git clean -fd + ``` + - Linux (Bash): + ```bash + git restore . + git clean -fd + ``` +10. **باکس هشدار Quera (`
`):** هرگز اجازه ندهید ایجنت فایل‌های `package.json` یا کانفیگ‌های اصلی فریم‌ورک را برای حل یک خطای ساده کامپوننت زیر و رو کند! +11. **باکس انرژی‌بخش Quera (`
`):** اکنون شما یک محصول ضدضربه و پایدار ساخته‌اید و آماده اتصال آن به شاهراه‌های دنیای واقعی در فصل ۱۰ هستید. +12. **جمع‌بندی فصل نهم و پیش‌نمایش فصل دهم:** پایان فصل تست و دیباگ؛ ورود به فصل جذاب دهم: اتصال سرویس‌های خارجی (پیامک، ایمیل، درگاه پرداخت و هوش مصنوعی). + +--- + +## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer) +- [ ] تکنیک‌های دیباگ بصری و استفاده از لاگ ترمینال به شکل عملی شرح داده شود. +- [ ] پدیده چرخه باطل عذرخواهی و قانون سه ضربه (Three-Strikes Rule) تبیین گردد. +- [ ] ۴ خطای فوق‌متداول توسعه وب مدرن به همراه سناریوهای پروژه پورتفولیو تشریح شود. +- [ ] دستورات ترمینالی بازگشت به وضعیت سالم در گیت برای هر سه سیستم‌عامل ارائه گردد.