Как написать баг-репорт, который исправят
Как написать баг-репорт, по которому баг исправят: конкретный заголовок, точные шаги, ожидаемый и фактический результат, окружение и улики.
Чтобы написать баг-репорт, с которым разработчик сможет работать, сначала воспроизведите проблему, а затем напишите конкретный заголовок в одну строку, окружение (URL, браузер и его версию, операционную систему, аккаунт), пронумерованные шаги воспроизведения от известной отправной точки, ожидаемый результат, фактический результат с точными сообщениями об ошибках и приложите улики: скриншот или запись, ошибки консоли и упавший сетевой запрос. Один баг — один репорт.
Проверка хорошего репорта простая: сможет ли разработчик, который ни разу не видел проблему, воспроизвести её на своей машине, ни о чём вас не спрашивая? Если да, баг, скорее всего, исправят быстро. Если ему придётся возвращаться с вопросами, каждый такой круг стоит дня. Если нужны поля в виде чек-листа, скопируйте наш шаблон баг-репорта.
1. Воспроизведите баг, прежде чем писать
Попробуйте вызвать баг во второй раз. Заодно обратите внимание на детали, которые могут оказаться важными:
- Под каким аккаунтом или ролью вы работали.
- Какие данные были задействованы: конкретный товар, длинное имя, пустой список, большой файл.
- Какие шаги действительно нужны. Убирайте шаги по одному, чтобы найти самый короткий путь.
- Повторяется ли баг в другом браузере или в режиме инкогнито.
Если он повторяется каждый раз, отлично. Если только иногда, посчитайте: «4 из 10 попыток». Если воспроизвести его не удаётся вообще, всё равно сообщите о нём и прямо об этом напишите.
2. Проверьте, не заведён ли он уже
Поищите в трекере сообщение об ошибке, название страницы и несколько ключевых слов. Если нашли совпадение, добавьте свои детали туда, а не открывайте новый тикет: ваше окружение, новый способ вызвать баг или то, что он всё ещё воспроизводится на последней сборке. Дубликаты раскидывают информацию по разным тикетам и отнимают время на триаже.
3. Напишите конкретный заголовок
Заголовок часто единственное, что читают при триаже. Пусть он описывает проблему, а не функцию.
| Слабый заголовок | Заголовок получше |
|---|---|
| Сломан вход | Вход через Google в Safari возвращает обратно на страницу входа |
| Баг в отчётах | В CSV-экспорте отчёта о продажах пропадают строки после 1000 |
| Страница тормозит | Страница биллинга грузится больше 10 секунд у аккаунтов с большим числом счетов |
| Ошибка при сохранении | Сохранение профиля с эмодзи в имени возвращает «Invalid input» |
Удобная схема: что сломалось, плюс когда это происходит, плюс где.
4. Опишите окружение
Многие баги проявляются только в определённой конфигурации. Укажите:
- URL страницы, где это случилось.
- Браузер и версию, например Chrome, Firefox, Safari или Edge с номером версии со страницы «О браузере».
- Операционную систему и устройство.
- Размер экрана, если это проблема вёрстки.
- Версию или сборку приложения, если приложение её показывает.
- Аккаунт, роль или тестового пользователя и всё необычное в нём (пробный аккаунт, большая организация, язык интерфейса не английский).
- Время, когда это произошло, с часовым поясом, чтобы команда нашла событие в серверных логах.
5. Напишите шаги воспроизведения
Шаги — это сердце репорта. Хорошие шаги:
- Начинаются с известного состояния: «Вошёл как админ, на странице Dashboard».
- Содержат одно действие на каждый пронумерованный шаг.
- Называют точные данные: товар, файл, введённый текст. Никогда не указывайте настоящие пароли или номера карт; используйте тестовые данные.
- Используют надписи из приложения, выделенные жирным или кавычками, чтобы разработчик нашёл ту же кнопку.
- Заканчиваются в момент, когда появляется баг.
1. Войти как [email protected] (роль Admin).
2. Перейти в «Настройки», затем «Команда».
3. Нажать «Пригласить участника».
4. Ввести «[email protected]» и выбрать роль «Наблюдатель».
5. Нажать «Отправить приглашение».
6. Напишите ожидаемый и фактический результат
Поставьте их рядом:
Ожидалось: приглашение появляется в списке «Ожидают», и показывается уведомление о подтверждении.
Фактически: диалог закрывается, уведомления нет, список «Ожидают» остаётся пустым.
После перезагрузки приглашения по-прежнему нет.
Описывайте то, что наблюдали, а не то, что, по-вашему, стало причиной. «Запрос приглашения упал» — это вывод; «диалог закрылся, и в списке ничего не появилось» — наблюдение. Если вы видели сообщение об ошибке, скопируйте его текстом, дословно. Разработчики ищут в коде именно эту строку.
7. Добавьте улики
Улики превращают описание в доказательство и часто сразу указывают на причину.
- Скриншот с выделенной проблемной областью. Обрежьте посторонние персональные данные.
- Запись экрана для всего, что связано с движением, таймингом или несколькими шагами. Делайте её короткой и начинайте прямо перед проблемой.
- Ошибки консоли. В веб-приложениях красная ошибка в консоли браузера часто самая полезная подсказка. Смотрите, как сохранить логи консоли в Chrome.
- Упавший сетевой запрос. URL, код статуса и тело ответа API-вызова, который завершился ошибкой. Смотрите, как записать сетевой трафик в Chrome.
- HAR файл, если команда просит всю сетевую сессию. Следуйте инструкции как получить HAR файл и сначала очистите его через очистку HAR, потому что HAR файлы содержат cookies и токены.
8. Честно оцените влияние
Скажите, насколько всё плохо и скольких людей это затрагивает. Пользуйтесь шкалой серьёзности вашей команды, если она есть. Будьте честны: если всё помечено как критичное, критичного нет ничего. Упомяните обходной путь, если нашли его: он меняет срочность исправления и тем временем помогает поддержке.
9. Один репорт — один баг
Если вы нашли три проблемы на одной странице, напишите три репорта. Тогда каждый можно назначить, исправить, проверить и закрыть отдельно. Свяжите их, если они кажутся родственными.
10. Оставайтесь на связи
После отправки следите за тикетом и отвечайте на вопросы. Когда исправление выйдет, перепроверьте по тем же шагам и подтвердите. Если баг потом вернётся, переоткройте исходный тикет или сошлитесь на него, чтобы история осталась в одном месте.
Частые ошибки
- Расплывчатые заголовки вроде «не работает» или «проблема со страницей».
- Пропущенные шаги или шаги, которые начинаются с середины сценария.
- Скриншоты сообщений об ошибках вместо текста, по которым нельзя искать.
- Несколько багов в одном тикете.
- Настоящие секреты в репорте: пароли, API-ключи, сессионные cookies или данные клиентов на скриншотах и в логах.
- Эмоциональные формулировки. Спокойный, фактический репорт исправляют быстрее, чем гневный.
Хорошие и плохие репорты рядом — в наших примерах баг-репортов.
Пишите меньше, собирайте больше
Больше всего сил в баг-репорте уходит на технические детали, и именно о них авторы чаще всего забывают. Midge, бесплатное расширение для Chrome, записывает экран или делает скриншот и прикладывает эти детали за вас, так что вам остаётся написать только заголовок, шаги и то, чего вы ожидали. В каждой записи есть логи консоли, сетевые запросы, действия пользователя и данные об устройстве. Пароли, номера карт, токены и cookies удаляются прямо в браузере, прежде чем что-либо покинет ваше устройство. Репорт отправляется одной ссылкой, которую можно вставить в любой трекер, которым пользуется ваша команда.
Похожие гайды
Частые вопросы
Какие части баг-репорта самые важные?
Шаги воспроизведения, ожидаемый результат и фактический результат. С этими тремя частями разработчик обычно может увидеть проблему сам. Данные об окружении и улики, такие как скриншоты и ошибки консоли, ускоряют работу.
Какой длины должен быть баг-репорт?
Как можно короче, но полным. Большинство хороших репортов умещаются на одном экране: заголовок в одну строку, короткое описание, от пяти до десяти шагов, ожидаемый и фактический результат и вложения.
Что делать, если баг не воспроизводится?
Всё равно сообщите о нём и прямо об этом напишите. Опишите точно, что вы делали и когда это произошло, и приложите все улики, что у вас есть, например скриншот или ошибку консоли. В поле частоты укажите, что это случилось один раз.
Стоит ли писать своё мнение о причине?
Разделяйте наблюдения и догадки. В основных полях пишите то, что видели, а если у вас есть гипотеза, добавьте её в раздел заметок с пометкой, что это догадка.