Viết báo cáo lỗi thế nào để được nhận: cấu trúc, các bước và những sai lầm thường gặp
Báo cáo lỗi không phải thủ tục giấy tờ. Nó được đọc bởi một người phải tái hiện lỗi trên máy mình, hiểu mức độ tệ đến đâu và quyết định sửa ngay hay để sau bản phát hành. Báo cáo không cho họ những thứ đó sẽ bị trả lại kèm câu hỏi, và cả hai bên cùng mất thời gian.
Một báo cáo gồm những gì
Bộ tối thiểu gần như giống nhau ở mọi nơi: tiêu đề, môi trường, các bước tái hiện, kết quả mong đợi, kết quả thực tế. Mức nghiêm trọng, tệp đính kèm và log là phần thêm — nhưng thiếu năm mục kia thì chưa có báo cáo.
Có một cách tự kiểm tra dễ: đưa báo cáo cho người không biết gì về nhiệm vụ. Nếu họ tái hiện được lỗi mà không hỏi câu nào, báo cáo đã xong.
Tiêu đề: hỏng cái gì và ở đâu
Tiêu đề được đọc trong một danh sách cả trăm dòng, và người ta dựa vào đó để quyết định có mở ra hay không. Vậy nên nó cần hai dữ kiện: chính xác chuyện gì xảy ra và ở chỗ nào. «Giỏ hàng bị hỏng» không có cái nào cả.
Tiêu đề tốt vẫn hiểu được khi bị cắt còn một dòng trong danh sách. Tiêu đề dở thì phải mở ra mới biết nó nói về cái gì.
✕
Lỗi trong đơn hàng
✓
POST /orders tạo đơn khi giỏ hàng trống và trả về 201
Các bước tái hiện: dữ liệu chính xác, không phải kể lại
Một bước là hành động có thể lặp lại y nguyên. «Gửi một giá trị không hợp lệ» thì không lặp lại được: giá trị không hợp lệ là vô số, và một nửa trong đó chạy đúng. Cái cần là đúng giá trị đã làm nó hỏng.
Với API, điều đó nghĩa là phương thức, địa chỉ đầy đủ kèm tham số, phần thân yêu cầu và các tiêu đề nếu chúng có ảnh hưởng. Với giao diện thì là đã bấm gì và gõ gì, đúng từng chữ. Thứ tự cũng quan trọng: lỗi chỉ tái hiện sau khi đăng nhập thì thiếu bước đó sẽ không tái hiện.
✕
1. Mở danh mục 2. Đặt một bộ lọc kỳ lạ 3. Không lọc được gì
✓
1. GET /products?min_price=-500 2. Xem mã phản hồi và số phần tử trong data
Kết quả mong đợi lấy từ yêu cầu
Điểm yếu hay gặp nhất là kết quả mong đợi được nghĩ ra tại chỗ. «Đáng lẽ không nên như vậy» là ý kiến, không phải yêu cầu, và tranh luận về nó có thể kéo dài mãi.
Kết quả mong đợi là một trích dẫn: một dòng trong yêu cầu, một tiêu chí nghiệm thu, một mục tài liệu, hay cách hành xử của phương thức bên cạnh vốn được làm đúng. Nếu chẳng có gì để trích, thì đây chưa phải lỗi mà là câu hỏi cho người phân tích — và nên mở nó đúng như vậy.
Ngược lại, kết quả thực tế được viết không kèm diễn giải: mã phản hồi, phần thân, một con số cụ thể. Không phải «tổng tiền tính sai» mà «trong phản hồi total = 1380 với hai món giá 690 và mã giảm 10%».
Năm sai lầm khiến báo cáo bị trả lại
- Hai lỗi trong một báo cáo. Sửa một cái rồi đóng cả phiếu, cái còn lại đi thẳng ra bản phát hành.
- Các bước viết theo trí nhớ. Viết một đằng, gửi một nẻo, không tái hiện được.
- Nhận xét thay cho sự kiện: «hỏng hết rồi», «chạy tệ lắm». Không rõ phải sửa cái gì.
- Thiếu môi trường. Trên máy chủ nào, với người dùng nào, quyền ra sao.
- Trùng lặp. Trước khi mở phiếu nên tìm thử — trên bảng thường đã có sẵn một cái.
Ví dụ API bug report hoàn chỉnh
Đây là ví dụ làm việc, không phải form bắt buộc. Nó nối observation với contract và giữ nguyên request chính xác thay vì kể lại theo trí nhớ.
Title: POST /orders tạo order cho cart rỗng và trả 201\nEnvironment: QA, build 2026.09.21-3, user qa-buyer-17\nPrecondition: cart của user rỗng\n\nSteps:\n1. Gửi POST /api/v1/orders với Bearer token hợp lệ\n2. Request body: {}\n3. Gửi GET /api/v1/orders\n\nExpected: 422; không tạo order (AC-ORD-04)\nActual: 201; tạo order_id=8412, total=0\nReproducibility: 3/3\nEvidence: request/response HAR, correlation_id=7af2…
Không dán token thật, password, personal data hoặc full production dump. Hãy che secret, dùng synthetic data và chia sẻ log nhạy cảm qua security process đã thống nhất.
Checklist trước khi gửi và retest
Severity mô tả impact, priority mô tả thứ tự business muốn sửa. Thang điểm và owner tùy team nên lý do quan trọng nhất. Sau trạng thái Fixed, QA lặp lại step gốc trên build được nêu và kiểm regression gần nhất thay vì đóng theo comment của developer.
- Title có action, kết quả sai và khu vực bị ảnh hưởng.
- Có build, environment, role, precondition và test data chính xác.
- Expected dẫn tới criterion, contract hoặc quyết định đã ghi.
- Actual có fact quan sát được: status, value, time, id và frequency.
- Attachment mở được, secret đã che và một report chỉ chứa một defect.
- Retest bao phủ scenario gốc, fixed build và regression gần đó.
Câu hỏi thường gặp về bug report
Có nên report defect chỉ xảy ra một lần?
Có nếu impact đáng kể và có evidence. Ghi frequency, thời gian, data và log mà không khẳng định tái hiện ổn định. Lỗi payment hiếm vẫn quan trọng hơn margin lệch ổn định.
Ai đặt severity và priority?
Không có quy tắc chung. QA thường đề xuất severity, product hoặc triage đặt priority, nhưng mỗi team có thể khác. Định nghĩa chung và lý do được ghi lại mới là điều quan trọng.
Làm gì khi không có requirement?
Ghi behaviour và risk thành câu hỏi hoặc discovery item, lấy quyết định của product rồi mới xác định expected. Sở thích cá nhân không tự động là defect.
Báo cáo là một tài liệu làm việc, và cách duy nhất để học viết nó là viết vài chục cái: trên lỗi thật, chứ không phải ví dụ bịa ra.