Как писать баг-репорт, который починят с первого раза
Хороший репорт экономит два часа переписки. Плохой возвращается с комментарием «не воспроизводится» и живёт неделю. Разница почти всегда в одних и тех же четырёх местах.
Зачем вообще нужен баг-репорт
У репорта одна задача: чтобы другой человек, не присутствовавший при находке, воспроизвёл проблему и понял, почему это проблема. Всё остальное — оформление вокруг этой задачи.
Отсюда критерий качества: репорт хорош, если разработчик открыл его и сразу пошёл чинить, не задав ни одного вопроса.
Заголовок: по нему решают, брать ли задачу
Заголовок читают в списке из сотни строк, не открывая. Рабочая формула: [где] что происходит [при каком условии].
| Плохо | Хорошо |
|---|---|
| Не работает корзина | Корзина: после перезагрузки страницы остаётся только последний товар |
| Ошибка 500 | Оформление заказа: POST /api/order отдаёт 500 при пустом поле «Комментарий» |
| Криво отображается | Каталог: описание выходит за границы карточки при названии длиннее 40 символов |
Заметьте, что в правой колонке видно место, симптом и условие. Этого достаточно, чтобы оценить важность без открытия задачи.
Шаги: пишите для человека, который видит продукт впервые
Главная ошибка — писать шаги для себя. «Добавить товар» понятно вам, но не тому, кто будет воспроизводить через неделю. Нужны конкретные данные.
- Одно действие на шаг, нумерация обязательна.
- Конкретные значения: не «ввести длинное название», а «ввести название из 41 символа».
- Начальное состояние вынесено в предусловия: какой пользователь, что уже в корзине, какой стенд.
- Никаких «и т.д.» — воспроизводить будут буквально.
Ожидаемый и фактический результат
Здесь ломается больше всего репортов. Ожидаемый результат должен быть со ссылкой на источник: требование, макет, поведение прошлой версии. Иначе обсуждение уходит в «а почему ты решил, что должно быть так», и дефект превращается в спор о вкусах.
Фактический результат — только то, что наблюдается. Не «валидация не работает на бэкенде» (это гипотеза), а «сервер вернул 500». Гипотезе место в комментарии, и она полезна, но отделяйте её от факта.
Если в задаче два дефекта, починят один, второй потеряется вместе с закрытой задачей. Это самая частая причина, по которой «мы же это чинили» превращается в «оно опять сломано».
Что приложить, чтобы не переспрашивали
- Скриншот целиком, а не вырезанный фрагмент: часто важны адрес страницы и время.
- Видео для плавающих и многошаговых дефектов — двадцать секунд убеждают лучше трёх абзацев.
- Запрос и ответ из вкладки Network: метод, адрес, тело, код. Удобно кнопкой «Copy as cURL» — только уберите токены перед вставкой в задачу.
- Ошибку консоли целиком, со стеком.
- Идентификаторы: номер заказа, почта, точное время, traceId — по ним найдут запись в логах сервера.
Как выглядит репорт целиком
Собранный по всем правилам дефект занимает меньше экрана и не требует ни одного уточняющего вопроса:
| Поле | Значение |
|---|---|
| Заголовок | Корзина: после перезагрузки страницы остаётся только последний добавленный товар |
| Окружение | Стенд test, сборка 2.15.0, Chrome 126 / Windows 11, пользователь test@shop.ru, роль «клиент» |
| Предусловия | В корзине три разных товара, пользователь авторизован |
| Шаги | 1. Открыть /cart2. Убедиться, что видно три позиции 3. Нажать F5 |
| Ожидаемый результат | Все три товара на месте, счётчик в шапке показывает 3 (требование REQ-14 «Корзина сохраняется между сессиями») |
| Фактический результат | Остаётся один товар — последний добавленный. Счётчик при этом показывает 3, данные расходятся |
| Воспроизводимость | Всегда, 5 из 5 попыток |
| Серьёзность | Critical — обхода нет, сценарий покупки прерывается |
| Вложения | Видео, HAR-файл, запрос GET /api/cart как cURL, traceId 8f1c-44a2 |
Обратите внимание на две детали. В фактическом результате отмечено расхождение счётчика и содержимого — это подсказка разработчику, где искать. А в ожидаемом стоит номер требования, поэтому обсуждать «а должно ли быть так» не придётся.
Пять проверок перед отправкой
- Воспроизводится повторно? Хотя бы дважды.
- Воспроизводится в другом браузере или в инкогнито? Это отделяет дефект от кэша и расширений.
- Нет ли уже такого репорта? Поиск по трекеру — тридцать секунд.
- Это точно расхождение с требованием, а не ваше ожидание?
- Актуальна ли ваша сборка? Возможно, уже починили.
Готовую структуру со всеми полями можно забрать в шаблоне баг-репорта, а как выставлять важность — в разборе Severity и Priority.
Заводить ли дефект, если он мелкий?
Да, но с честной серьёзностью. Незаведённый мелкий дефект накапливается в «мы про это знаем» и однажды всплывает как претензия от клиента. Заведённый и отложенный — это осознанное решение команды, а не забытая проблема.
Насколько подробным должен быть репорт?
Ровно настолько, чтобы воспроизвёл человек без вашего контекста. Обычно это 5–8 строк шагов. Пересказ логики продукта туда не нужен.
Что делать, если дефект плавающий?
Указать частоту («3 из 10 попыток»), приложить видео и логи, описать, при каких условиях чаще. Плавающий дефект — не повод не заводить задачу.
Можно ли писать репорт скриншотом?
Текст ошибки нужен текстом: по картинке нельзя искать в трекере и нельзя скопировать в поиск по логам. Скриншот — дополнение, а не замена.
Написать хороший репорт с первого раза не выходит почти ни у кого — это навык, который ставится повторением. В курсе для этого есть тренажёр: вы разбираете дефект, пишете текст, и он проверяется по семи критериям с показом эталона. 14 900 ₽ один раз, а сам тренажёр открыт бесплатно — попробуйте прямо сейчас в конструкторе баг-репорта.