Viết Bug Report chuẩn: Cách mô tả, mức độ nghiêm trọng và bước tái hiện để Dev hiểu ngay
2 tháng trước · 11 phút đọc
Tại sao Bug Report quan trọng hơn bạn nghĩ
Mình nhớ hồi mới đi làm, viết bug xong gửi cho dev một dòng: "Trang login bị lỗi, không đăng nhập được". Dev hỏi lại: "Lỗi gì? Ở đâu? Làm thế nào để thấy lỗi?". Mình mất thêm 30 phút giải thích qua chat. Bug đó đáng lẽ fix trong 1 tiếng nhưng kéo dài cả buổi chiều.
Bug Report tệ không phải chuyện nhỏ. Khi dev không hiểu lỗi, họ phải hỏi lại - bạn mất thời gian giải thích, dev mất thời gian chờ, deadline bị đẩy lùi. Tệ hơn, nếu dev không reproduce được bug, họ có thể đóng ticket với lý do "Cannot reproduce" - bug vẫn còn đó nhưng không ai biết.
Một Bug Report tệ có thể khiến ticket đi vòng vòng mà không được fix
Bug Report chuẩn giải quyết điều này: dev đọc một lần, hiểu ngay vấn đề, reproduce được ngay, và fix đúng chỗ. Bài này mình hướng dẫn từng phần của Bug Report, lý do tại sao từng phần quan trọng, và những lỗi fresher hay mắc nhất.
Cấu trúc Bug Report chuẩn gồm những gì?
Mỗi Bug Report cần có 7 phần chính. Không phải để đủ form cho đẹp, mà mỗi phần giải quyết một câu hỏi cụ thể mà dev cần biết.
1. Title (Tiêu đề) - Trả lời: "Bug này nói về cái gì?"
Title phải đủ để đọc một dòng là hiểu ngay lỗi ở đâu, xảy ra khi nào. Format mình hay dùng: [Module/Tính năng] + Hành động + Kết quả sai.
- ❌ Tệ: "Lỗi đăng nhập"
- ✅ Tốt: "[Login] Nhập đúng email/password vẫn hiển thị thông báo 'Sai mật khẩu'"
2. Description (Mô tả tổng quan) - Trả lời: "Bug này là gì, xảy ra ở đâu?"
Tóm tắt 2-3 câu. Không cần dài, chỉ cần đủ context để dev biết mình đang đọc bug về phần nào của hệ thống.
3. Steps to Reproduce (Bước tái hiện) - Trả lời: "Làm thế nào để thấy lỗi?"
Đây là phần quan trọng nhất. Dev cần làm theo đúng từng bước để thấy bug. Nếu thiếu phần này, dev không reproduce được = không fix được.
4. Expected Result (Kết quả mong đợi) - Trả lời: "Lẽ ra phải xảy ra gì?"
Mô tả hành vi đúng theo spec hoặc logic thông thường. Đây là căn cứ để dev biết họ cần fix về đâu.
5. Actual Result (Kết quả thực tế) - Trả lời: "Thực tế đang xảy ra gì?"
Mô tả chính xác những gì bạn thấy: thông báo lỗi cụ thể, màn hình trắng, nút không phản hồi, v.v.
6. Severity & Priority - Trả lời: "Bug này nguy hiểm đến mức nào?"
Phần này mình sẽ giải thích kỹ ở mục sau vì nhiều fresher hay nhầm lẫn.
7. Attachment (Đính kèm) - Trả lời: "Có bằng chứng gì không?"
Screenshot, video record, log file. Đây là thứ giúp dev tin bạn 100% và không mất công hỏi lại.
7 phần này là xương sống của mọi Bug Report - thiếu 1 phần là dev phải hỏi lại
Cách viết Steps to Reproduce đủ để Dev không cần hỏi lại
Bước tái hiện là phần mình thấy fresher viết tệ nhất. Không phải vì họ lười, mà vì họ không nghĩ đến việc người đọc không biết gì về context lúc đó.
Quy tắc đơn giản: viết từng bước như đang hướng dẫn người chưa từng dùng app này bao giờ. Mỗi bước là một hành động, không gộp hai việc vào một dòng.
Ví dụ bug tính năng tìm kiếm trên Shopee (giả lập):
Steps to Reproduce:
1. Mở trình duyệt, truy cập trang chủ Shopee (https://shopee.vn)
2. Đăng nhập bằng tài khoản test: [email protected] / Test@1234
3. Click vào ô tìm kiếm ở thanh header
4. Nhập từ khóa: "áo thun trắng" (có dấu tiếng Việt)
5. Nhấn Enter hoặc click icon kính lúp
6. Quan sát kết quả trả về
Mỗi bước là một hành động đơn - đừng gộp 2 việc vào 1 dòng
Một vài điều cần thêm vào Steps mà nhiều người bỏ qua:
- Môi trường test: Trình duyệt gì (Chrome 120, Firefox 119), hệ điều hành gì (Windows 11, macOS 14), thiết bị gì (desktop hay mobile)
- Tài khoản test cụ thể: Nếu bug chỉ xảy ra với một loại tài khoản (tài khoản mới, tài khoản VIP, tài khoản chưa verify email)
- Dữ liệu test: Nếu bug xảy ra với input cụ thể, ghi rõ luôn
Tại sao cần kỹ đến vậy? Mình từng báo bug "Tìm kiếm không ra kết quả" nhưng quên ghi là chỉ xảy ra khi nhập từ có dấu tiếng Việt. Dev test bằng "ao thun trang" (không dấu) - thấy bình thường - đóng ticket "Cannot reproduce". Bug nằm im 2 tuần đến lúc khách hàng phàn nàn mới phát hiện lại.
Severity vs Priority: Hai khái niệm hay bị nhầm nhất
Bạn nghĩ Severity (mức độ nghiêm trọng) và Priority (mức độ ưu tiên) là một? Mình cũng nghĩ vậy hồi mới đi làm. Đến khi lead hỏi "Tại sao cái lỗi typo lại Priority = High?" mình mới hiểu ra.
Severity = Bug ảnh hưởng đến hệ thống nặng đến mức nào về mặt kỹ thuật. Priority = Bug cần được fix sớm đến mức nào về mặt business.
Hai cái này độc lập với nhau. Ví dụ:
| Bug | Severity | Priority | Lý do |
|---|---|---|---|
| Trang thanh toán crash hoàn toàn | Critical | High | Mất tiền ngay, fix ngay |
| Logo công ty bị sai trên trang chủ | Low | High | Khách hàng thấy ngay, ảnh hưởng thương hiệu |
| Nút ẩn trong trang admin hiếm dùng bị lệch 2px | Low | Low | Không ảnh hưởng user |
| Tính năng export Excel bị lỗi nhưng app vẫn chạy | Medium | Medium | Gây bất tiện nhưng không crash |
Severity và Priority không phải lúc nào cũng song hành - hiểu đúng để không bị lead hỏi ngược
Các mức Severity thường dùng:
- Critical (Blocker): App crash, mất dữ liệu, không thể dùng tính năng chính. Ví dụ: thanh toán trả về lỗi 500
- Major (High): Tính năng chính bị lỗi nhưng có workaround. Ví dụ: tìm kiếm không ra kết quả nhưng vào category vẫn thấy sản phẩm
- Minor (Medium): Tính năng phụ bị lỗi, ít ảnh hưởng user flow. Ví dụ: filter giá không sort đúng thứ tự
- Trivial (Low): Lỗi UI nhỏ, typo, lệch vài pixel. Ví dụ: nút "Đăng ký" bị lệch 3px trên mobile
Thấy phức tạp không? Thật ra khi đi làm, nhiều team dùng 3 mức thay vì 4, và lead sẽ review lại với bạn. Đừng lo nếu chưa quen ngay - mình cũng cần 2-3 tháng mới cảm nhận được ranh giới giữa các mức.
Ví dụ Bug Report hoàn chỉnh: 3 tình huống thực tế
Lý thuyết xong, mình làm thẳng vào ví dụ. Ba tình huống hay gặp nhất khi đi làm: bug login, bug tìm kiếm, bug thanh toán.
Bug 1: Lỗi đăng nhập
Title: [Login] Nhập đúng email/password vẫn hiển thị "Sai mật khẩu"
Description:
Trang đăng nhập hiển thị thông báo lỗi "Email hoặc mật khẩu không đúng"
dù thông tin đăng nhập là chính xác.
Steps to Reproduce:
1. Truy cập https://demo-app.com/login
2. Nhập email: [email protected]
3. Nhập password: Test@1234 (đã verify đây là password đúng qua DB)
4. Click nút "Đăng nhập"
5. Quan sát thông báo hiển thị
Expected Result:
Chuyển hướng sang trang Dashboard (https://demo-app.com/dashboard)
Actual Result:
Hiển thị thông báo đỏ "Email hoặc mật khẩu không đúng", không chuyển trang
Severity: Critical
Priority: High
Environment:
- Browser: Chrome 120.0.6099.130 (Windows 11)
- OS: Windows 11 22H2
Attachment: [screenshot-login-error.png] [video-reproduce.mp4]
Bug 2: Lỗi thanh toán
Title: [Checkout] Nhấn "Xác nhận thanh toán" không có phản hồi trên Safari iOS
Description:
Nút "Xác nhận thanh toán" không thực hiện hành động gì khi nhấn trên
iPhone (Safari). Trên Chrome Desktop hoạt động bình thường.
Steps to Reproduce:
1. Dùng iPhone 13, Safari 17
2. Truy cập https://demo-app.com, đăng nhập
3. Thêm sản phẩm vào giỏ hàng
4. Vào Giỏ hàng > Tiến hành thanh toán
5. Điền đầy đủ thông tin giao hàng
6. Chọn phương thức thanh toán: Thẻ tín dụng
7. Nhấn nút "Xác nhận thanh toán"
8. Quan sát phản hồi
Expected Result:
Hiển thị màn hình xác nhận đơn hàng hoặc redirect sang cổng thanh toán
Actual Result:
Nút không có phản hồi, trang không thay đổi, không có thông báo lỗi
Severity: Critical
Priority: High
Environment:
- Device: iPhone 13 Pro
- Browser: Safari 17
- iOS: 17.2
Attachment: [video-safari-checkout-bug.mp4]
Bug Report đầy đủ như thế này giúp dev reproduce trong 5 phút thay vì hỏi qua lại cả buổi
Bạn thấy không? Hai bug đều ở dạng Critical nhưng Steps to Reproduce rất khác nhau. Bug login cần ghi rõ tài khoản test. Bug thanh toán cần ghi rõ device và browser vì bug chỉ xảy ra trên Safari iOS. Nếu thiếu thông tin đó, dev test trên Chrome Desktop - thấy bình thường - đóng ticket.
5 lỗi fresher hay mắc khi viết Bug Report
Mình từng mắc hết 5 lỗi này. Liệt kê ra để bạn đọc trước, tránh sau.
Lỗi 1: Title mơ hồ
"Lỗi trang chủ", "Bug thanh toán", "App bị lỗi" - những title này không nói gì cả. Dev có 20 bug trong backlog, họ không đọc được gì từ title như vậy. Fix: dùng format [Module] + Hành động + Kết quả sai.
Lỗi 2: Thiếu Steps to Reproduce
Ghi "Vào trang login và đăng nhập, thấy lỗi" là không đủ. "Vào trang login" = từ đâu vào? Gõ URL thẳng hay click từ menu? Bằng tài khoản nào? Trình duyệt gì? Thiếu chi tiết = dev không reproduce được.
Lỗi 3: Không có Expected vs Actual
Nhiều fresher chỉ mô tả "Bug X xảy ra" mà không nói lẽ ra phải là gì. Dev cần biết behavior đúng là gì để biết fix về đâu. Đặc biệt với những bug logic phức tạp, Expected Result chính là spec sống của bug đó.
Lỗi 4: Không đính kèm screenshot
Mình biết chụp ảnh thêm một bước. Nhưng một screenshot giúp dev thấy ngay bạn đang nói đến cái gì. Text mô tả "nút bị lệch" không bằng một ảnh chụp màn hình. Video record thậm chí còn tốt hơn cho bug phức tạp.
Lỗi 5: Severity tất cả đều là Critical
Mình thấy điều này nhiều ở fresher muốn bug được fix nhanh. Kết quả ngược lại: lead không tin, cả team mất chuẩn mực chung. Bug thật sự Critical sẽ không được ưu tiên vì "bug nào cũng Critical". Ghi đúng Severity = giúp team prioritize đúng.
5 lỗi này tưởng nhỏ nhưng khiến bug report của bạn bị đánh giá thấp ngay từ đầu
Thấy khó ở đây? Bình thường. Mình mất khoảng 1 tháng đầu mới viết Bug Report ổn. Cứ viết, nhờ lead review, sai đâu sửa đó - không có cách nào nhanh hơn.