Bug report yazma rehberi: geliştiricinin soru sormadan işe başladığı hata kaydı

Hata raporu kimin işini kolaylaştırır

Hata raporunu okuyan kişi çoğunlukla sizi tanımaz, ekranınızı görmez ve sizinle hemen konuşamaz. Rapor, geliştiricinin hatayı kendi makinesinde yeniden üretip nedenini bulabilmesi için elindeki tek araçtır. İyi bir rapor, geliştiricinin soru sormadan işe başlamasını sağlar. Kötü bir rapor ise "yeniden üretemedim" yanıtıyla geri döner ve zaman kaybettirir.

Raporu ayrıca ürün sahibi ya da ekip lideri okur; bu kişi hatanın önceliğini ve yayın kararına etkisini değerlendirir. Bir de aylar sonra aynı belirtiyi arayan biri vardır. Başlık ve açıklama, arama yapılabilecek terimleri taşımalıdır. Bu yüzden hata raporu bir şikâyet değil, bir mühendislik belgesidir: olgu yazar, yorumu ayırır, kanıt ekler.

Bir hata raporunun bileşenleri

Takip aracınız Jira, Azure DevOps ya da başka bir sistem olsun, iyi bir raporda şu bileşenler bulunur:

• Başlık: Belirtiyi ve konumu söyler. "Hata var" yerine "Sepette kupon kaldırıldığında toplam tutar güncellenmiyor".
• Ortam: Uygulama sürümü, tarayıcı ve sürümü ya da cihaz modeli ve işletim sistemi, test ortamı (geliştirme, test, ön üretim, üretim).
• Ön koşullar: Hatayı görmek için gereken veri ve durum: kullanıcı rolü, sepet içeriği, aktif kupon.
• Yeniden üretme adımları: Numaralı, kısa ve sıralı. Her adım tek eylem.
• Beklenen sonuç: Gereksinimin ya da belgenin söylediği davranış.
• Gerçek sonuç: Gözlemlediğiniz davranış.
• Kanıt: Ekran görüntüsü, ekran kaydı, günlük (log) çıktısı, ağ isteği ve yanıtı, hata mesajının tam metni.
• Sıklık: Her seferinde mi oluyor, ara sıra mı? Ara sıra ise hangi koşulda?
• Önem derecesi ve öncelik: Sistemin etkilenme düzeyi ve düzeltme sırası.

Beklenen ve gerçek sonucu ayrı yazmak, raporun en güçlü alışkanlıklarından biridir. Okuyan kişi aradaki farkı hemen görür ve gereksinimle karşılaştırır.

Yeniden üretme adımları nasıl yazılır

Adımlar, hatayı hiç görmemiş birinin onları sırayla izleyerek aynı sonuca ulaşabileceği kadar açık olmalıdır. Pratik kurallar:

• Başlangıç noktasını belirtin. "Uygulamayı aç" yeterli değildir; hangi hesapla, hangi sayfada başladığınızı yazın.
• Her adımda tek eylem olsun. "Kuponu gir ve onayla" yerine kuponu girmek ve onaylamak ayrı adımlar olarak yazılır.
• Gerçek değerleri yazın. "Bir kod gir" yerine kullandığınız kodu yazın (hassas değilse).
• Bekleme ya da zamanlama gerekiyorsa belirtin.
• Adımları kendiniz bir kez baştan izleyerek doğrulayın. Hatayı raporladıktan sonra yeniden üretemiyorsanız, önce eksik ön koşulu arayın.

Örneğin bir mobil uygulama testinde şöyle bir rapor yazılabilir:

Başlık: Siparişi iptal ettikten sonra sipariş listesi eski durumu gösteriyor Ortam: Test ortamı, mobil uygulamanın son sürümü, güncel bir işletim sistemi Adımlar: Hesapla giriş yap. Siparişlerim sayfasını aç. Hazırlanıyor durumundaki siparişi seç. İptal et düğmesine bas, onayla. Siparişlerim listesine geri dön. Beklenen: Sipariş "İptal edildi" durumunda görünür. Gerçek: Sipariş hâlâ "Hazırlanıyor" görünür; sayfa elle yenilenince doğru duruma geçer. Not: Aynı davranış web arayüzünde görülmüyor.

Son satırdaki not, geliştiriciyi doğrudan mobil istemcinin önbelleğine ya da güncelleme mantığına yönlendirir.

Önem derecesi ile öncelik aynı şey değildir

Önem derecesi (severity), hatanın sistem üzerindeki teknik etkisidir. Öncelik (priority) ise düzeltmenin iş açısından ne kadar hızlı yapılması gerektiğidir. Bu kavramlar sıklıkla örtüşür ama her zaman değil.

Örnekler: • Yüksek önem, düşük öncelik: Nadir kullanılan bir yönetim ekranında veri kaybına yol açan hata, yalnızca birkaç kişinin eriştiği bir ortamda bulunuyorsa hemen düzeltme gerektirmeyebilir. • Düşük önem, yüksek öncelik: Ana sayfadaki marka adında yazım hatası teknik olarak önemsizdir ama kurumsal itibar nedeniyle hemen düzeltilmek istenebilir.

Test uzmanı genellikle önem derecesini önerir; öncelik, ürün sahibi ya da proje yönetimiyle birlikte belirlenir. Rapor yazarken ikisini ayrı alanlarda tutun ve gerekçenizi açıklayın: "ödeme tamamlanamıyor, kullanıcı alışverişi bitiremez" gibi. Etkiyi tarif etmek, tartışmayı kişisel görüşten ölçülebilir bir zemine taşır.

Kanıt toplama: ekran kaydı, günlük ve ağ isteği

Kanıt, raporun inandırıcılığını belirler. Kanıt türleri:

Ekran görüntüsü: Hata mesajının tamamı ve çevresindeki bağlam görünsün. Sorunlu alanı işaretleyin ama kırpmayın; adres çubuğu, saat ve kullanıcı bilgisi bağlam verir.

Ekran kaydı: Zamanlama ya da sıra hatalarında çok değerlidir. Kayıtta adımlarınızı gösterin.

Günlük (log): Uygulama günlüğünde ilgili zaman aralığını alın. Tüm günlüğü yapıştırmak yerine hata anının çevresini ekleyin ve zaman damgasını rapora yazın.

Tarayıcı geliştirici araçları: Ağ sekmesinde başarısız isteğin adresi, durum kodu ve yanıt gövdesi; konsol sekmesinde hata iletileri. Web testlerinde bu sekmelerden alınan bilgi çoğu zaman nedeni gösterir.

API testlerinde: İstek gövdesi, başlıklar ve yanıt. Kimlik bilgilerini ve jetonları paylaşmadan önce silin ya da maskeleyin.

Gizlilik: Gerçek müşteri verisi içeren ekran görüntülerini yaymayın. Test ortamında sentetik veri kullanın; üretimde bulunan bir hatayı raporlarken kişisel verileri karartın.

Sık yapılan hatalar

Birden çok sorunu tek raporda toplamak: Her hata ayrı bir kayıt olmalı. Aksi halde kısmen düzeltilen kayıt kapatılamaz.

Yorum karıştırmak: "Geliştirici yanlış yapmış" ya da "bu tasarım saçma" yerine gözlemi yazın. Önerileriniz için ayrı bir bölüm kullanın.

Eksik ortam bilgisi: Yalnızca belirli tarayıcıda görülen hata, ortam yazılmazsa "bende çalışıyor" yanıtıyla kapanır.

Yinelenen kayıt: Raporu açmadan önce takip aracında benzer başlıkları arayın. Aynı hata için yeni kayıt açmak yerine mevcut kayda kanıt ve ek koşul yazın.

Sıklığı yazmamak: "Bazen oluyor" ifadesini bir koşula bağlamaya çalışın: yalnızca yavaş ağda, yalnızca ilk girişte, yalnızca belirli rolde.

Kapanış sonrası ilgisizlik: Düzeltme geldiğinde aynı adımlarla yeniden test edin, sonucu kayda yazın ve ilgili regresyon testini güncelleyin. Hata yaşam döngüsünün parçası olarak, kök nedeni sonradan tartışmak gelecekte benzer hatayı önler.

Bu beceriyi nerede geliştirirsiniz

Test Otomasyonu ve QA Temelleri programının Hata Yönetimi ve Raporlama modülü; etkili hata raporu yazma, hata önceliklendirme ve önem derecesi, hata yaşam döngüsü ve iş akışı, Jira ile hata takibi ve pano yönetimi, hata eğilim analizi ile kök neden araştırması ve hata kapı metrikleri ile yayın kararı başlıklarını içerir. Bu içerik, hata raporlarını kayıt tutmaktan çıkarıp ekip kararlarını destekleyen bir veriye dönüştürmek isteyen test uzmanları, destek ekibinden teknik role geçenler ve rapor kalitesini yükseltmek isteyen ürün analistleri için uygundur.