Чому грамотне оформлення баг-репортів таке важливе

Правила оформлення дефектів в баг-трекері в кожної компанії свої – це залежить від політики компанії, технології розробки, використовуваного баг-трекера, типу проєкту і багато чого ще. Але в будь-якому випадку хороший баг-репорт володіє певними характеристиками. Якщо розробник або менеджер по заголовку баг-репорта не зрозуміє, в чому суть проблеми і чому її потрібно виправити, звіт може бути закритим без перегляду. 

Для того, щоб оформити баг-репорт грамотно, необхідно врахувати декілька важливих деталей. Для початку потрібно підготуватися. Якщо ви виявили баг, не варто моментально бігти до баг-трекера та писати «нічого не працює!». Розпочніть відтворення помилки. Відтворилася? Чудово. Чи не відтворилася? Отже, щось ви не врахували.

Потрібно розуміти, що хороший баг-репорт дозволяє:

1. Відтворити проблему (це не завжди можливо, але необхідно прагнути до цього).
2. Зрозуміти, у чому проблема і яка її важливість.

Знову відтворилась? Ура! А тепер мінімізуйте кількість кроків для відтворення, переконайтесь, що немає нічого зайвого. 

Якщо використовуються якісь вхідні дані, упевніться, що і вони не містять зайвого (наприклад, якщо суть помилки полягає в тому, що: «Текстовий редактор екстрено завершує свою роботу після введення тексту», то перед написанням баг-репорта необхідно перевірити, чи дійсно дефект відтворюється після введення всього тексту, а не після введення якогось певного символу).

Коли ви зрозуміли, які саме дані і які ваші дії призводять до проблеми, коротко сформулюйте її суть – придумайте заголовок баг-репорту. Опишіть проблему настільки детально та конкретно, наскільки дозволяє заголовок, при цьому не варто забувати про обмеження на кількість символів у заголовку.

 Під час опису помилки дуже важливо вказати що саме зламалось «Що?», у якому місці системи це сталось «Де?», а також за яких обставин «Коли?»

«Що?» (Що відбувається?) – це НЕ іменник, це те, що відбулось,своєрідне ДІЄСЛОВО-уточнення («Що виконується?» або «Що НЕ виконується?»).

 «Редактор зависає» – ЩО?

«Де?» – місце в системі (додатку/веб-сайті), де був знайдений баг.

 «на сторінці фотографії» – ДЕ?

«Коли?» (Після чого? Внаслідок якої дії? У період якої дії?) – дія, яка викликала собою результат, який відрізняється від очікуваного. 

 «після вставки тексту, який має в собі символ N з буферу обміну після натискання «Ctrl+V» – КОЛИ?

Розглянемо приклади правильного оформлення заголовку:

Принципу «Що? Де? Коли? » важливо дотримуватися не тільки для уніфікації та простоти опису багів, він продиктований граматичними особливостями англійської мови, яка є основною у роботі QA-фахівця. За правилами побудови речень в англійській спочатку потрібно писати підмет і присудок «Що?», після цього обставину місця «Де?» і тільки в кінці обставину часу «Коли?».

Потрібно вказувати, яка саме помилка відображається. Не варто писати «нічого не відбувається», «не працює», «ламається верстка», «nothing happens», «the layout is broken». 

Такі формулювання неточно описують баг і можуть заплутати розробника.

Краще не використовувати слова «Try to», «спробувати», потрібно чітко вказувати, які дії необхідно виконувати.

Також, як і слова, на кшталт, «можна/не можна», «можливо/неможливо», «possible/impossible», «can/can not». Вони не розкривають суть бага, з такого опису не ясно, в чому саме невідповідність.

Також не потрібно писати такі фрази, як «я клікаю на посилання», «я натискаю кнопку» і тому подібні. І заголовок, і опис кроків – це керівництво до дії для тих, хто буде виправляти проблему, тому краще формулювати як «перейти за посиланням», «натиснути на кнопку». Також не варто вживати особисті займенники або фрази «користувачу відображається» в темі, описі та результатах. Їх краще писати від третьої особи в пасивному стані.

Тепер відкрийте баг-трекер, почніть заповнювати форму баг-репорта.

Запишіть заголовок (Summary).

У деяких баг-трекерах поле «Детальний опис» (Description) присутнє, в деяких – ні. Якщо поле «Детальний опис» є, опишіть в ньому проблему більш детально – уточніть ті деталі, які довелося пропустити в заголовку. Якщо ви розумієте, в чому причина проблеми (використовується застаріла формула для розрахунків, не враховується якесь значення тощо) – це теж потрібно описувати в цьому полі. Якщо у формі запису про помилку немає окремого поля «Affect version» (версія продукту, в якому проявляється проблема), то вкажіть версію тут.

Тему баг-репорта необхідно формулювати повними реченнями з використанням підмета і присудка за принципом «Що? Де? Коли?». Це потрібно для того, щоб не порушити зміст речення та максимально точно і зрозуміло донести його зміст тій людині, яка буде читати ваш звіт про помилку. Причому, в частині «Де?» недостатньо вказати просто «на сайті» або «в браузері». Якщо тестується сайт, то само собою зрозуміло, що дефект відображається на сайті, який відкритий в певному браузері. Необхідно вказувати розділ сайту, сторінки або форму, на яких виявлено помилку.

Описуючи частину «Коли?», краще писати «після» якої дії відображається дефект, не використовуючи прийменник «при». Якщо баг відтворюється в момент якоїсь дії, краще так і написати – «в момент».

Якщо для відтворення бага необхідна взаємодія з певними кнопками, посиланнями, пунктами меню – це обов'язково необхідно вказати в кроках відтворення бага. Через те, що на сайті може бути декілька елементів з однаковими назвами, потрібно поряд з назвою елемента написати його тип (кнопка, посилання, поле тощо). Для більш високого ступеня розуміння вашого повідомлення про помилку рекомендується вказувати назви кнопок, посилань тощо тією мовою, якою відбувалося тестування сайту. Це полегшує і прискорює розуміння суті вашого бага та шляхи його відтворення.

З цією ж метою завжди рекомендується вказувати назви кнопок, блоків сайту і т.ін. в лапках. Це прискорює розуміння і підвищує зручність читання вашого баг-репорта. Тільки не потрібно перекладати назви елементів сайту на мову оформлення звіту. Їх необхідно вказувати саме так, як вони відображені на сайті.

Не варто довго пояснювати той факт, що тему, кроки відтворення, фактичний і очікуваний результати потрібно писати з великої літери. Кроки повинні бути пронумеровані і написані в стовпчик, між кроками і результатами краще залишити порожній рядок (відступ) для візуального відділення основних інформаційних блоків баг-репорта.

В останньому кроці потрібно звернути увагу на блок з помилкою, але не описувати саму помилку. Не варто писати «Зверніть увагу, що помилка не відображається в полі», досить написати «Звернути увагу на поле введення».

Також важливо описувати результати відповідно до теми за принципом «Що? Де? Коли?», не застосовуючи наказових слів на кшталт «має»,«must» і тому подібних. В очікуваному результаті потрібно описати правильну поведінку системи, відповідаючи на питання «Що відбувається»?

Коли ви пишете баг-репорт певною мовою – намагайтеся використовувати терміни цією ж мовою. Якщо в україномовний звіт додавати англійські слова – швидкість і зручність читання такого бага зменшується. Ще гірше, коли додаються англомовні слова, які написані українськими літерами (транслітерацією). Також при написанні баг-репорта не варто вживати сленгові слова і вирази. Необхідно описувати суть проблеми простими, зрозумілими словами. Це робиться для того, щоб та людина, яка буде перевіряти чи відтворювати ваш баг, не витрачала багато часу на «розбір польотів», а відразу ж з першого погляду, зрозуміла у чому саме проблема і як відтворити баг.

Після того, як опис помилки було написано та відредаговано, необхідно прочитати його від початку до кінця. Можливо знайдуться помилки, випадковий повтор слова або зайвий символ.

Також потрібно дбати про чистоту письма, перевіряти граматику, пунктуацію. Деякі тестувальники забувають про це і складають баг-репорти з купою помилок, які не тільки ріжуть очі, але й іноді призводять до непорозумінь. Напевно, всі ми знаємо ще зі школи фразу «стратити не можна помилувати». І хоча початківці тестувальники рідко працюють з програмами, від яких залежить людське життя, але безграмотність може створити проблеми. Наприклад, фраза «натиснути кнопку всі слова замінити на пробіл в блоці назви» може змусити програміста або іншого тестувальника шукати в блоці «Назви» кнопку «Всі слова замінити на пробіл», хоча упорядник баг-репорта мав на увазі, що потрібно натиснути якусь єдину кнопку на формі і замінити в назві всі слова на один пробіл. Крім того, що в цьому реченні є граматичні помилки, воно ще й складене семантично неправильно.

До всього іншого, якщо відійти від теми помилок, варто зауважити, що між тестувальником та програмістом важливе розуміння і довіра. Але якщо програміст буде бачити неграмотну мову від свого колеги, то у нього може виникнути відчуття, що до нього та його продукту відносяться несерйозно або ж, що людина по інший бік екрану некомпетентна.

Ще одна часта помилка новачків – вживання слів «некоректно/коректно», «правильно/неправильно». Потрібно доступно і в повному обсязі описувати, що саме відбувається в системі, оскільки фраза «система реагує некоректно» не дозволяє зрозуміти, яка ж помилка відображається. Детальніше про це можна прочитати у статті. Це також стосується баг-репортів із негативним тестуванням, коли в кроках необхідно ввести невалідні дані. У подібних випадках потрібно обов'язково уточнювати приклади даних, які необхідно ввести.

Баг-репорт – це певна інструкція з точними вказівками на те, як саме відтворити баг. І складати цю інструкцію потрібно так, щоб людина, поглянувши на ваш звіт про помилку, з першого разу за вказаними вами кроками змогла відтворити баг. Навичка написання баг-репортів в такому стилі приходить з досвідом.