گزارش باگ حرفه‌ای؛ قالب Bug Report با مثال و چک‌لیست

گزارش «صفحه پرداخت خراب است» ظاهراً یک باگ را منتقل می‌کند، اما برای تیم توسعه چند سؤال بی‌پاسخ می‌گذارد: کدام نسخه؟ با چه نوع پرداختی؟ منظور از خراب چیست؟ خطا همیشه رخ می‌دهد؟ نتیجه درست را از کجا می‌دانیم؟ یک گزارش باگ حرفه‌ای فاصله میان مشاهده تستر و اقدام توسعه‌دهنده را کوتاه می‌کند؛ بدون اغراق، سرزنش یا انبوه پیوست نامرتبط.

پاسخ کوتاه: Bug Report خوب باید مشکل را در یک عنوان دقیق خلاصه کند، محیط و بیلد را مشخص کند، پیش‌شرط و مراحل حداقلی بازتولید را بدهد، نتیجه واقعی را از نتیجه مورد انتظار جدا کند، اثر را توضیح دهد و شواهد امن و زمان‌دار ارائه کند. هدف «اثبات مقصر بودن کد» نیست؛ هدف ساختن یک مسئله قابل‌بازتولید و تصمیم‌پذیر است.

گزارش باگ چیست؟

گزارش باگ رکوردی قابل‌ردیابی از یک رفتار نامطلوب یا مغایرت احتمالی در محصول است. این رکورد باید به تیم کمک کند مشکل را بفهمد، اعتبارسنجی کند، اولویت بدهد، علت را پیدا کند، اصلاح را تحویل دهد و نتیجه را دوباره آزمایش کند. ثبت گزارش معمولاً در دل فاز اجرای تست رخ می‌دهد، اما گزارش‌های تولید، پشتیبانی و کاربران نیز می‌توانند وارد همین مسیر شوند.

Bug Report با Test Case یکسان نیست. تست‌کیس مسیر و انتظار آزمایش را پیش از اجرا تعریف می‌کند؛ گزارش باگ یک مشاهده مشخص از مغایرت را در نسخه و شرایط معین ثبت می‌کند. همچنین با Incident فرق دارد: Incident یک اختلال مشاهده‌شده در خدمت است و ممکن است بعد از بررسی به یک یا چند باگ، مشکل زیرساخت یا خطای عملیاتی مرتبط شود.

پیش از ثبت باگ چه چیزهایی را بررسی کنیم؟

هر Fail لزوماً نقص محصول نیست. پیش از ساختن رکورد جدید، یک بررسی کوتاه انجام دهید:

• نسخه درست است؟ مطمئن شوید روی بیلد موردنظر آزمایش می‌کنید و قابلیت پشت Feature Flag خاموش نیست.
• پیش‌شرط و داده معتبرند؟ نقش کاربر، وضعیت سفارش، تاریخ، موجودی و تنظیمات را کنترل کنید.
• انتظار منبع دارد؟ معیار پذیرش، قانون کسب‌وکار، طراحی تاییدشده یا قرارداد API را ببینید.
• قابل‌بازتولید است؟ حداقل یک بار با داده تازه یا نشست تمیز تکرار کنید؛ تکرار بی‌نهایت برای «قطعی کردن» لازم نیست.
• مشکل محیط نیست؟ سلامت سرویس‌های وابسته، شبکه، لاگ استقرار و تنظیمات محیط را بررسی کنید.
• قبلاً گزارش نشده؟ با نشانه، پیام خطا، مؤلفه و کلیدواژه جست‌وجو کنید. اگر Duplicate است، شاهد تازه را به رکورد اصلی اضافه کنید.

این بررسی نباید بهانه‌ای برای ثبت نکردن خطای ناپایدار باشد. اگر رخداد اثر جدی دارد اما نرخ بازتولید پایین است، همان عدم قطعیت را همراه زمان، شناسه درخواست و شرایط ثبت کنید.

اجزای یک Bug Report حرفه‌ای

۱. عنوان دقیق و قابل جست‌وجو

عنوان باید بدون باز کردن گزارش، مؤلفه، شرط و نشانه اصلی را منتقل کند. از واژه‌های مبهم مثل «کار نمی‌کند»، «مشکل در سایت» یا «فوری» دوری کنید.

عنوان ضعیف	عنوان بهتر
پرداخت خراب است	[پرداخت] پس از Callback موفق، سفارش همچنان «ناموفق» نمایش داده می‌شود
فیلتر مشکل دارد	[جست‌وجو][موبایل] انتخاب هم‌زمان برند و محدوده قیمت، فهرست کالا را خالی می‌کند
عدد اشتباه	[سبد] تخفیف درصدی از سقف ۱۰۰ هزار تومان عبور می‌کند

پیام خطای کامل را فقط وقتی در عنوان بیاورید که کوتاه و متمایزکننده است. شناسه کاربر، شماره تلفن، توکن یا داده حساس نباید وارد عنوان قابل‌مشاهده برای همه شود.

۲. خلاصه و اثر

در دو یا سه جمله بگویید چه اتفاقی می‌افتد، چه کسی متاثر است و چرا اهمیت دارد. واقعیت مشاهده‌شده را از حدس علت جدا کنید. «بعد از بازگشت درگاه، سفارش ناموفق می‌ماند و کاربر دوباره پرداخت می‌کند» مشاهده و اثر است؛ «به‌خاطر Race Condition در سرویس پرداخت» تا زمان داشتن شاهد، فرضیه است.

۳. محیط، نسخه و بیلد

• نام محیط: Test، Staging، Production یا محیط محلی
• نسخه برنامه، Build Number، commit یا تاریخ استقرار
• دستگاه، سیستم‌عامل، مرورگر یا نسخه اپ در صورت ارتباط
• نسخه API، Feature Flag، منطقه یا نوع شبکه در صورت اثرگذاری
• زمان رخداد با منطقه زمانی؛ برای مثال «۱۴:۳۲ به وقت ایران»

عبارت «آخرین نسخه» بعد از انتشار بعدی بی‌معنا می‌شود. همیشه یک شناسه پایدار ثبت کنید.

۴. پیش‌شرط و داده تست

وضعیت لازم پیش از گام اول را بنویسید: نقش کاربر، موجودی کالا، نوع حساب، سفارش قبلی، فعال بودن تخفیف یا زبان رابط. داده را به‌اندازه‌ای مشخص کنید که بازتولید ممکن باشد، اما اطلاعات شخصی را ماسک کنید. برای نمونه به‌جای شماره واقعی بنویسید «کاربر تست با شناسه داخلی QA-۱۷».

۵. مراحل بازتولید حداقلی

مراحل باید شماره‌دار، مستقل و عملی باشند. هر گام یک اقدام روشن داشته باشد و از شرح کارهای بی‌اثر پرهیز شود:

1. با کاربر دارای نقش مشخص وارد شوید.
2. کالای مشخص را به سبد اضافه کنید.
3. کد تخفیف تعریف‌شده را اعمال کنید.
4. مبلغ نمایش‌داده‌شده را با قانون مورد انتظار مقایسه کنید.

اگر مشکل فقط بعد از ده‌ها اقدام رخ می‌دهد، با حذف مرحله‌های غیرضروری سناریو را کوچک کنید. این کاهش (reduction) هم بازتولید را سریع‌تر می‌کند و هم سرنخ علت را افزایش می‌دهد.

۶. نتیجه واقعی و نتیجه مورد انتظار

Actual Result فقط آنچه مشاهده شد را بیان می‌کند؛ با عدد، متن پیام، وضعیت HTTP یا تغییر داده. Expected Result رفتار درست را همراه منبعش توضیح می‌دهد. انتظار را از سلیقه شخصی نسازید. اگر نیازمندی مبهم است، سؤال محصول یا اختلاف سند را ثبت کنید؛ گزارش باگ جای تصمیم پنهانی درباره رفتار محصول نیست.

اگر نوشتن نتیجه مورد انتظار دشوار است، ابتدا معیار پذیرش یا تست‌کیس را بازبینی کنید. راهنمای نوشتن تست‌کیس و Expected Result در این بخش کمک می‌کند.

۷. نرخ و دامنه بازتولید

به‌جای «گاهی رخ می‌دهد» بنویسید «۲ بار از ۱۰ اجرا روی شبکه موبایل؛ روی Wi‑Fi در ۱۰ اجرا دیده نشد». اگر تفاوت داده، دستگاه یا زمان مهم است، آن را ثبت کنید. این عدد احتمال را اثبات نمی‌کند، اما به تیم در طراحی آزمایش بعدی کمک می‌کند.

۸. Severity و Priority

Severity اثر نقص بر سیستم و کاربر را توصیف می‌کند؛ Priority زمان و ترتیب رفع را با توجه به اثر تجاری، انتشار، تعهد و هزینه تعیین می‌کند. تستر می‌تواند Severity را با دلیل پیشنهاد دهد، اما Priority معمولاً در triage با مشارکت محصول و فنی نهایی می‌شود.

سطح نمونه	تعریف مبتنی بر اثر	مثال
بحرانی	زیان داده، نقض امنیت جدی یا توقف مسیر حیاتی بدون راه‌حل	نمایش سفارش کاربر دیگر
بالا	قابلیت اصلی مختل و راه‌حل جایگزین بسیار دشوار	عدم امکان پرداخت برای گروه بزرگی از کاربران
متوسط	اثر محدود با راه‌حل جایگزین قابل‌قبول	یک فیلتر ترکیبی نتیجه نادرست می‌دهد
پایین	اثر جزئی و بدون مانع جدی برای هدف کاربر	ناهم‌ترازی آیکن در یک اندازه صفحه

این جدول فقط نقطه شروع است. تیم باید تعریف خودش را با مثال‌های محصول مستند کند. یک غلط املایی در صفحه کم‌استفاده ممکن است Severity پایین باشد، اما اگر نام برند در روز کمپین اشتباه است Priority بالایی بگیرد.

۹. شواهد مفید و امن

شاهد خوب مسئله را روشن می‌کند، نه اینکه جای توضیح را بگیرد. بسته به نوع مشکل می‌توانید اضافه کنید:

• اسکرین‌شات با علامت‌گذاری ناحیه مشکل
• ویدئوی کوتاه از لحظه رخداد
• Network Trace یا درخواست/پاسخ مرتبط
• لاگ محدود به بازه زمانی و Correlation ID
• خروجی Console، Crash Report یا Stack Trace
• مقایسه قبل و بعد یا دستگاه سالم و ناسالم

پیش از پیوست، رمز، توکن، کوکی نشست، شماره کارت، تلفن، ایمیل و اطلاعات کاربران را حذف یا ماسک کنید. یک فایل لاگ چندصد مگابایتی بدون زمان و نشانه، معمولاً از چند خط مرتبط کم‌ارزش‌تر است.

۱۰. راه‌حل موقت و ارتباط‌ها

اگر راه‌حل موقت امنی وجود دارد، آن را ثبت کنید؛ مثلاً «کاربر با بازگشت به سبد و محاسبه مجدد می‌تواند ادامه دهد». همچنین لینک تست‌کیس، نیازمندی، رخداد تولید، گزارش مشابه و Release را اضافه کنید. این ارتباط‌ها در چرخه عمر و مدیریت باگ برای تصمیم و ردیابی ضروری‌اند.

قالب آماده گزارش باگ

این قالب را با فیلدهای ابزار تیم خود هماهنگ کنید:

عنوان:
[بخش/پلتفرم] + [شرط] + [رفتار نادرست یا اثر]

خلاصه و اثر:
چه اتفاقی می‌افتد؟ چه کسی یا چه مسیری متاثر است؟

محیط و بیلد:
محیط:
نسخه/Build/Commit:
دستگاه/سیستم‌عامل/مرورگر:
Feature Flag یا تنظیم مرتبط:
زمان رخداد و منطقه زمانی:

پیش‌شرط:
- نقش و وضعیت کاربر
- وضعیت داده یا قابلیت
- وابستگی لازم

داده تست:
شناسه‌های غیرحساس یا ماسک‌شده

مراحل بازتولید:
1.
2.
3.

نتیجه واقعی:
آنچه دقیقاً مشاهده شد

نتیجه مورد انتظار:
رفتار درست + لینک منبع انتظار

نرخ بازتولید:
مثلاً 3/5 و شرایط مشترک

Severity پیشنهادی:
سطح + دلیل اثر

شواهد:
اسکرین‌شات/ویدئو/لاگ/Request ID

راه‌حل موقت:
در صورت وجود

موارد مرتبط:
Test Case / Requirement / Incident / Duplicate

مثال کامل گزارش باگ فروشگاه ایرانی

عنوان: [سبد خرید] تخفیف ۲۰٪ از سقف ۱۰۰ هزار تومان عبور می‌کند و مبلغ درگاه با سفارش مغایر است

خلاصه و اثر: برای سفارش ۸۰۰ هزار تومانی، سبد ۱۶۰ هزار تومان تخفیف اعمال می‌کند؛ قانون کمپین سقف ۱۰۰ هزار تومان است. مبلغ ارسالی به درگاه با مبلغ ذخیره‌شده سفارش متفاوت می‌شود و ریسک پرداخت/تسویه نادرست وجود دارد.

محیط و بیلد: Staging؛ Build ۴۳۰؛ وب موبایل؛ زمان رخداد ۱۴:۳۲ به وقت ایران؛ فلگ کمپین نوروز فعال.

پیش‌شرط: کاربر تست QA-۱۷ وارد شده، کالا موجود و کد NOWRUZ20 معتبر است.

مراحل: ۱) کالای ۸۰۰ هزار تومانی را به سبد اضافه کنید. ۲) کد NOWRUZ20 را اعمال کنید. ۳) مبلغ سبد را یادداشت کنید. ۴) وارد درگاه آزمایشی شوید و مبلغ را مقایسه کنید.

نتیجه واقعی: تخفیف ۱۶۰ هزار تومان؛ مبلغ سبد ۶۴۰ هزار تومان؛ مبلغ ارسال‌شده به درگاه ۷۰۰ هزار تومان.

نتیجه مورد انتظار: طبق معیار پذیرش AC-۱۲، تخفیف حداکثر ۱۰۰ هزار تومان و مبلغ نهایی در سبد، سفارش و درخواست درگاه ۷۰۰ هزار تومان باشد.

نرخ بازتولید: ۵ از ۵ بار با کد درصدی؛ با کد مبلغ ثابت مشاهده نشد.

Severity پیشنهادی: بالا؛ اثر مالی و مغایرت مبلغ در مسیر اصلی خرید.

شواهد: ویدئوی ۲۵ ثانیه‌ای، Request ID ماسک‌شده و سه خط لاگ مرتبط.

راه‌حل موقت: غیرفعال کردن کد درصدی تا اصلاح؛ نیازمند تصمیم محصول.

این مثال هم بازتولید را ممکن می‌کند و هم اثر تصمیم را نشان می‌دهد، بدون اینکه علت فنیِ اثبات‌نشده یا اطلاعات حساس را وارد گزارش کند. برای سناریوهای تخصصی‌تر پرداخت، راهنمای تست درگاه پرداخت و سندباکس را ببینید.

گزارش باگ در وضعیت‌های دشوار

باگ Cannot Reproduce

«قابل‌بازتولید نیست» به معنی «وجود ندارد» نیست. زمان دقیق، حساب یا دسته کاربر، Correlation ID، وضعیت شبکه، نسخه و داده مرتبط را نگه دارید. تیم می‌تواند موقتاً وضعیت Needs Info یا Cannot Reproduce بدهد، ابزار مشاهده‌پذیری اضافه کند و شرط بازبینی تعیین کند. بستن فوری یک رخداد امنیتی یا مالی فقط به‌دلیل بازتولید نشدن، تصمیم پرریسکی است.

باگ متناوب

نرخ بازتولید، الگوی مشترک و تعداد تلاش‌ها را ثبت کنید. ویدئو به‌تنهایی کافی نیست؛ زمان و شناسه درخواست کمک می‌کند لاگ سمت سرور با رخداد تطبیق داده شود. اگر اجرای موازی، تأخیر یا قطع شبکه شرط محتمل است، آن را به‌عنوان فرضیه برچسب بزنید، نه نتیجه قطعی.

باگ تولید

ابتدا حفاظت از کاربر و پایداری سرویس طبق فرآیند Incident اهمیت دارد. از آزمایش مخرب یا دست‌کاری داده واقعی برای بازتولید بدون مجوز خودداری کنید. پس از کنترل رخداد، اطلاعات لازم را به یک گزارش قابل‌پیگیری تبدیل کنید و ارتباط Incident، تغییر کد و Regression را نگه دارید.

باگ API و اپ موبایل

برای API، method، endpoint، headerهای غیرحساس، payload ماسک‌شده، status code، response و Correlation ID را اضافه کنید. برای موبایل، مدل دستگاه، نسخه سیستم‌عامل و اپ، مجوزها، وضعیت foreground/background، نوع شبکه و مراحل نصب یا ارتقا ممکن است حیاتی باشند. همه این فیلدها را اجباری نکنید؛ فقط زمینه مرتبط را ثبت کنید.

اشتباهات رایج در Bug Reporting

• چند مشکل در یک گزارش: رفع و تایید مستقل را دشوار می‌کند؛ مگر اینکه همه نشانه‌های یک علت مشترک باشند.
• عنوان هیجانی: «فاجعه»، «افتضاح» یا علامت تعجب اطلاعات عملی اضافه نمی‌کند.
• انتظار بدون منبع: سلیقه تستر جای تصمیم محصول را می‌گیرد.
• اسکرین‌شات بدون متن: جست‌وجو، دسترس‌پذیری و فهم زمینه را ضعیف می‌کند.
• حدس علت در عنوان: تیم را روی مسیر اشتباه قفل می‌کند.
• فیلدهای اجباری بیش‌ازحد: گزارش‌دهنده برای عبور از فرم، داده کم‌کیفیت وارد می‌کند.
• بحث شخصی در کامنت‌ها: مسئله کیفیت را به تعارض تبدیل می‌کند. برای همکاری سازنده، راهنمای ارتباط مؤثر تستر و توسعه‌دهنده مفید است.
• انتشار اطلاعات حساس: دامنه یک نقص را به رخداد امنیتی تازه تبدیل می‌کند.

ابزار ردیابی باگ را چگونه برای گزارش بهتر تنظیم کنیم؟

فرآیند از ابزار مهم‌تر است. فرم را کوتاه نگه دارید، فیلدهای زمینه‌ای را بر اساس نوع گزارش نمایش دهید، عنوان و مراحل را قابل جست‌وجو کنید و ارتباط با تست‌کیس، Pull Request و Release را نگه دارید. گردش کار، مجوز و اعلان باید به تصمیم کمک کنند، نه اینکه گزارش‌دهنده را میان ده‌ها وضعیت سردرگم کنند.

اگر تیم از Jira استفاده می‌کند، راهنمای کار با Jira برای تسترها می‌تواند تنظیم issue، فیلتر و ارتباط با اسپرینت را تکمیل کند.

چک‌لیست پیش از ارسال گزارش باگ

• عنوان، مؤلفه + شرط + رفتار نادرست را می‌گوید.
• بیلد، محیط و زمان رخداد مشخص‌اند.
• پیش‌شرط و داده لازم ثبت و داده حساس ماسک شده است.
• مراحل حداقلی و شماره‌دارند.
• Actual و Expected جدا و انتظار دارای منبع است.
• نرخ یا دامنه بازتولید معلوم است.
• Severity با اثر توضیح داده شده و Priority تحمیل نشده است.
• شواهد مرتبط، کوچک، امن و قابل‌خواندن‌اند.
• گزارش مشابه جست‌وجو شده است.
• لینک تست‌کیس، نیازمندی یا Incident در صورت وجود اضافه شده است.

سؤالات متداول گزارش باگ

مهم‌ترین بخش گزارش باگ چیست؟

یک بخش به‌تنهایی کافی نیست، اما ترکیب مراحل بازتولید، نتیجه واقعی، نتیجه مورد انتظار و نسخه/محیط حداقل هسته گزارش است. عنوان خوب کشف گزارش را سریع می‌کند و شاهد مناسب علت‌یابی را بهبود می‌دهد.

اگر Expected Result معلوم نباشد، باگ ثبت کنیم؟

مشاهده را از سؤال جدا کنید. اگر رفتار آشکارا مخرب، ناامن یا متناقض است، گزارش کنید و ابهام انتظار را ذکر کنید. در مسائل طراحی یا سلیقه‌ای، ابتدا یک Question/Clarification می‌تواند مناسب‌تر از برچسب Bug باشد.

Severity را تستر تعیین می‌کند یا مدیر محصول؟

تستر معمولاً Severity را بر اساس اثر پیشنهاد می‌دهد؛ تیم باید تعریف مشترک داشته باشد. Priority با توجه به انتشار، تعداد کاربر، تعهد و هزینه در triage نهایی می‌شود و ورودی محصول در آن پررنگ است.

برای باگ غیرقابل‌بازتولید چه شواهدی مهم‌تر است؟

زمان دقیق، بیلد، شناسه درخواست یا رخداد، حساب ماسک‌شده، وضعیت شبکه و لاگ همان بازه بیشترین ارزش را دارند. هدف ساختن امکان مشاهده دفعه بعد است، نه تکرار کورکورانه تا خطا ظاهر شود.

آیا ویدئو جای مراحل بازتولید را می‌گیرد؟

خیر. ویدئو نشانه بصری می‌دهد، اما جست‌وجو، کپی، دسترس‌پذیری و تکرار دقیق با مراحل متنی بهتر است. ویدئو و اسکرین‌شات باید مکمل متن باشند.

جمع‌بندی

گزارش باگ خوب طولانی‌ترین گزارش نیست؛ کوتاه‌ترین گزارشی است که هنوز مسئله، زمینه، بازتولید، اثر و شواهد لازم را کامل منتقل می‌کند. واقعیت را از فرضیه جدا کنید، اطلاعات حساس را حذف کنید و انتظار را به منبع وصل کنید. این کیفیت نوشتار زمان رفت‌وبرگشت را کم می‌کند، triage را دقیق‌تر می‌سازد و رابطه QA و توسعه را از «اثبات خطا» به حل مشترک مسئله می‌برد.