Debug laporan bug yang bukan Anda tulis: alur kerja praktis

Apa yang membuat laporan bug ini sulit (dan apa yang bisa Anda kendalikan)

Mendiagnosis bug yang dilaporkan oleh orang lain lebih sulit karena Anda tidak punya peta mental pembuat aslinya. Anda tidak tahu apa yang rentan, apa yang "normal", atau jalan pintas apa yang diambil. Gejala kecil (tombol, salah ketik, layar lambat) bisa berasal dari masalah yang lebih dalam di API, database, atau job background.

Laporan bug yang berguna memberi Anda empat hal:

• aksi yang tepat
• data yang tepat
• hasil yang diharapkan
• hasil aktual

Kebanyakan laporan hanya memberi yang terakhir: "Simpan tidak bekerja," "rusak," "error acak." Yang hilang adalah konteks yang membuatnya dapat diulang: peran pengguna, record spesifik, environment (prod vs staging), dan apakah ini mulai setelah sebuah perubahan.

Tujuannya adalah mengubah gejala samar menjadi reproduksi yang dapat diandalkan. Setelah Anda bisa membuatnya terjadi sesuai permintaan, itu bukan misteri lagi. Itu adalah rangkaian pemeriksaan.

Yang bisa Anda kendalikan segera:

• set langkah terkecil yang memicu masalah
• data uji yang tepat (ID, email, payload, filter)
• environment dan versi (build, feature flag, browser/perangkat)
• bukti bahwa itu terjadi (timestamp, screenshot, teks error, potongan log)
• hasil pass/fail yang jelas yang bisa Anda jalankan ulang

"Selesai" bukanlah "Saya kira saya sudah memperbaikinya." Selesai adalah: langkah reproduksi Anda lulus setelah perubahan kecil, dan Anda dengan cepat menguji ulang perilaku sekitar yang mungkin terpengaruh.

Siapkan baseline stabil sebelum Anda mengubah apa pun

Cara tercepat membuang waktu adalah mengubah banyak hal sekaligus. Bekukan titik awal Anda sehingga setiap hasil uji berarti sesuatu.

Pilih satu environment dan tetap di situ sampai Anda bisa mereproduksi masalah. Jika laporan datang dari produksi, konfirmasi di sana dulu. Jika itu berisiko, gunakan staging. Lokal juga bisa jika Anda bisa menyesuaikan data dan pengaturan dengan dekat.

Lalu tetapkan kode yang sebenarnya berjalan: versi, tanggal build, dan feature flag atau konfigurasi yang memengaruhi alur. Perbedaan kecil (integrasi dimatikan, base URL API berbeda, job background hilang) bisa mengubah bug nyata menjadi hantu.

Buat setup uji yang bersih dan dapat diulang. Gunakan akun baru dan data yang diketahui. Jika bisa, reset state sebelum tiap percobaan (logout, bersihkan cache, mulai dari record yang sama).

Tulis asumsi saat Anda berjalan. Ini bukan kerja sia-sia; ini menghentikan Anda berdebat dengan diri sendiri nanti.

Contoh catatan baseline:

• Environment: produksi, staging, atau lokal
• Versi/build: commit, tag, atau timestamp build
• Konfigurasi: feature flag, integrasi, kunci uji
• Identitas uji: email/role akun, permission
• Data: ID record, item seeded, keadaan awal yang diharapkan

Jika reproduksi gagal, catatan ini memberi tahu apa yang harus Anda variasi selanjutnya, satu kenop (knob) pada satu waktu.

Terjemahkan laporan menjadi langkah dan input yang dapat diuji

Kemenangan tercepat adalah mengubah keluhan samar menjadi sesuatu yang bisa Anda jalankan seperti skrip.

Mulai dengan menulis ulang laporan sebagai user story singkat: siapa melakukan apa, di mana, dan apa yang mereka harapkan. Lalu tambahkan hasil yang diamati.

Contoh penulisan ulang:

"Sebagai admin billing, ketika saya mengubah status invoice menjadi Paid dan klik Simpan di halaman invoice, status seharusnya tetap. Sebaliknya, halaman tetap sama dan status tidak berubah setelah refresh."

Selanjutnya, tangkap kondisi yang membuat laporan menjadi benar. Bug sering bergantung pada satu detail yang hilang: peran, keadaan record, locale, atau environment.

Input kunci yang harus dicatat sebelum Anda klik di sekitar:

• Peran pengguna dan tipe akun (admin vs standar, trial vs berbayar)
• Keadaan data (ID record, status, data terkait yang dibutuhkan)
• Detail klien (OS, versi browser/aplikasi)
• Pengaturan lokal dan waktu (bahasa, zona waktu, rentang tanggal)
• Environment dan build (prod vs staging, versi rilis, feature flag)

Kumpulkan bukti saat Anda masih melihat perilaku asli. Screenshot membantu, tapi rekaman singkat lebih baik karena menangkap timing dan klik tepat. Selalu catat timestamp (termasuk zona waktu) agar Anda bisa mencocokkannya dengan log nanti.

Tiga pertanyaan klarifikasi yang menghilangkan tebakan terbanyak:

• Pada akun pengguna dan peran mana tepatnya ini terjadi, dan bisakah Anda memberi satu contoh ID record?
• Apa yang Anda harapkan segera setelah aksi, dan apa yang benar-benar Anda lihat?
• Apakah ini terjadi setiap kali dengan langkah yang sama, atau hanya pada data tertentu (status, rentang tanggal, locale, input besar)?

Reproduksi masalah secara andal

Jangan mulai dengan menebak penyebab. Buat masalah itu terjadi dengan sengaja, dengan cara yang sama, lebih dari sekali.

Pertama, jalankan langkah pelapor persis seperti tertulis. Jangan "memperbaiki" langkahnya. Catat tempat pertama pengalaman Anda berbeda, bahkan jika tampak sepele (label tombol berbeda, field hilang, teks error sedikit berbeda). Ketidaksesuaian pertama itu sering petunjuk.

Alur sederhana yang bekerja di kebanyakan aplikasi:

• Reset ke keadaan awal yang diketahui (muat ulang bersih, akun yang sama, permission yang sama, flag yang sama).
• Ikuti langkah satu per satu dan catat input tepat yang Anda gunakan (ID, tanggal, filter).
• Tulis expected vs actual di langkah yang gagal.
• Ulangi sekali untuk memastikan bisa diulang.
• Perkecil ke set langkah terkecil yang masih memicunya.

Setelah bisa diulang, variasikan satu hal pada satu waktu. Tes satu-variabel yang biasanya memberi hasil:

• langkah yang sama, role berbeda
• langkah yang sama, record berbeda (baru vs legacy)
• langkah yang sama, browser/perangkat berbeda
• langkah yang sama, sesi bersih (incognito, cache dibersihkan)
• langkah yang sama, jaringan berbeda

Akhiri dengan skrip repro singkat yang orang lain bisa jalankan dalam 2 menit: keadaan awal, langkah, input, dan pengamatan gagal pertama.

Isolasi lapisan yang gagal: UI, API, atau DB

Sebelum Anda membaca seluruh codebase, putuskan lapisan mana yang gagal.

Tanya: apakah gejala hanya di UI, atau juga di data dan respons API?

Contoh: "Nama profil saya tidak terupdate." Jika API mengembalikan nama baru tetapi UI masih menampilkan yang lama, curigai state/caching UI. Jika API tidak pernah menyimpannya, kemungkinan besar di API atau DB.

Pertanyaan triase cepat yang bisa Anda jawab dalam beberapa menit:

• Bisakah Anda mereproduksinya di lebih dari satu browser/perangkat?
• Apakah refresh keras (hard refresh) mengubah apa pun?
• Apakah request jaringan muncul saat Anda klik tombol?
• Apakah respons API sudah terlihat salah?
• Apakah database menunjukkan baris yang diharapkan setelah aksi?

Pemeriksaan UI berkaitan dengan visibilitas: error di console, tab Network, dan state usang (UI tidak re-fetch setelah save, atau membaca dari cache lama).

Pemeriksaan API berkaitan dengan kontrak: payload (field, tipe, ID), status code, dan body error. 200 dengan body yang mengejutkan bisa sama pentingnya dengan 400.

Pemeriksaan DB berkaitan dengan kenyataan: baris hilang, tulis parsial, kegagalan constraint, update yang mempengaruhi nol baris karena WHERE clause tidak cocok.

Untuk tetap terarah, buatlah peta kecil: aksi UI mana memicu endpoint mana, dan tabel mana yang dibaca atau ditulis.

Ikuti request dari ujung ke ujung dengan log dan timestamp

Kejelasan sering muncul dengan mengikuti satu request nyata dari klik hingga database dan kembali.

Tangkap tiga jangkar dari laporan atau repro Anda:

• waktu tepat (dengan zona waktu)
• identifier pengguna (account/email/ID internal)
• correlation ID (request ID/trace ID/session ID)

Jika Anda tidak punya correlation ID, tambahkan satu di gateway/backend dan sertakan di header respons dan log.

Untuk menghindari kebanjiran noise, ambil hanya yang diperlukan untuk menjawab "Di mana gagal dan kenapa?":

• rentang timestamp (mis. 1 menit sebelum sampai 1 menit setelah)
• satu user ID (dan tenant/org ID jika relevan)
• correlation ID
• method, path, status code, latency
• pesan error pertama yang bermakna (bukan halaman stack trace panjang)

Sinyal yang perlu diperhatikan:

• Timeout/latensi tinggi: query lambat, panggilan eksternal, locks.
• 401/403: masalah permission atau konteks tenant.
• 400 validation error: seringkali mismatch payload UI.

Jika "bekerja kemarin" tapi tidak hari ini, curigai drift environment: flag yang berubah, secret yang diputar, migrasi yang belum dijalankan, atau job yang berhenti berjalan.

Bangun kasus reproduksi minimal (agar perbaikan tetap kecil)

Bug termudah diperbaiki adalah eksperimen kecil dan dapat diulang.

Perkecil semuanya: klik lebih sedikit, field lebih sedikit, dataset terkecil yang masih gagal. Jika hanya terjadi pada "pelanggan dengan banyak record," coba buat kasus minimal yang tetap memicunya. Jika tidak bisa, itu petunjuk bug terkait volume data.

Pisahkan "state buruk" dari "kode buruk" dengan mereset state secara sengaja: akun bersih, tenant atau dataset baru, build yang diketahui.

Salah satu cara praktis menjaga repro tetap jelas adalah tabel input ringkas:

Buat repro portable agar orang lain bisa menjalankannya cepat:

• 3 sampai 6 langkah dari start bersih
• satu record uji (atau satu body request) yang dapat digunakan ulang
• satu sinyal sukses yang jelas (pesan UI, kode HTTP, jumlah baris DB)
• detail environment tepat (build/versi, role, flag)

Perangkap umum yang membuang waktu

Jalur tercepat biasanya membosankan: ubah satu hal, amati, catat.

Kesalahan umum:

• Memperbaiki gejala permukaan (menutupi error API/DB yang nyata).
• Mengubah banyak variabel sekaligus (pembaruan dependency + tweak konfigurasi + refactor).
• Menguji pada baseline yang berbeda dari pelapor (env, data, build, browser).
• Lupa permissions dan role (admin vs pengguna biasa).
• Hilangnya feature flag atau eksperimen yang mengganti alur.
• Menyatakan kemenangan tanpa verifikasi (tidak menjalankan ulang repro, tidak memeriksa efek samping).

Contoh realistis: tiket mengatakan "Export CSV kosong." Anda menguji dengan akun admin dan melihat data. Pengguna punya role terbatas, dan API mengembalikan daftar kosong karena filter permission. Jika Anda hanya menambal UI untuk menampilkan "No rows," Anda melewatkan pertanyaan sebenarnya: apakah role itu seharusnya diizinkan mengekspor, atau produk harus menjelaskan mengapa datanya terfilter?

Setelah perbaikan apa pun, jalankan ulang langkah repro yang sama, lalu uji satu skenario terdekat yang seharusnya tetap berfungsi.

Daftar periksa cepat sebelum meminta perbaikan

Anda akan mendapat jawaban lebih baik dari rekan (atau alat) jika membawa paket yang rapat: langkah yang dapat diulang, satu lapisan yang kemungkinan gagal, dan bukti.

Sebelum siapa pun mengubah kode, konfirmasi:

• Anda bisa mereproduksinya dua kali menggunakan input yang sama (user, data, environment yang sama).
• Anda bisa menyebut lapisan yang gagal (UI, API, atau DB) dan memberi satu alasan.
• Anda menangkap bukti: request, response/error, log relevan, dan timestamp yang cocok.
• Anda mengurangi repro ke kasus terkecil yang bisa Anda buat.
• Anda menulis acceptance criteria dalam satu kalimat (contoh: "Simpan memperbarui record dan menunjukkan sukses dalam 2 detik").

Lalu lakukan pemeriksaan regresi singkat: coba role berbeda, browser/window private kedua, satu fitur terdekat yang menggunakan endpoint/tabel sama, dan input edge-case (kosong, teks panjang, karakter khusus).

Contoh realistis: mempersempit bug “Tombol Simpan tidak melakukan apa-apa”

Pesan support: "Tombol Simpan tidak melakukan apa-apa di form Edit Customer." Tindak lanjut mengungkap ini hanya terjadi untuk customer yang dibuat sebelum bulan lalu, dan hanya saat Anda mengubah billing email.

Mulai dari UI dan anggap kegagalan paling sederhana dulu. Buka record, lakukan edit, dan cari tanda bahwa "tidak ada" sebenarnya sesuatu: tombol nonaktif, toast tersembunyi, pesan validasi yang tidak dirender. Buka console browser dan tab Network.

Di sini, klik Simpan memicu request, tapi UI tidak pernah menampilkan hasil karena frontend hanya menganggap 200 sebagai sukses dan mengabaikan error 400. Tab Network menunjukkan respons 400 dengan body JSON seperti: {\"error\":\"billingEmail must be unique\"}.

Sekarang verifikasi API memang gagal: ambil payload persis dari request dan replay. Jika gagal di luar UI juga, hentikan pengejaran bug state frontend.

Lalu periksa database: mengapa pengecekan unik hanya gagal untuk record lama? Anda menemukan pelanggan legacy berbagi billing_email placeholder bertahun-tahun lalu. Pengecekan unik baru kini memblokir penyimpanan siapa pun yang masih memakai placeholder itu.

Repro minimal yang bisa Anda serahkan:

• Pilih customer legacy dengan billing_email = [email protected].
• Ubah field apa saja dan klik Simpan.
• Amati API mengembalikan 400 dengan billingEmail must be unique.
• Amati UI tidak menampilkan error dan meninggalkan form tanpa perubahan.

Acceptance test: ketika API mengembalikan error validasi, UI menampilkan pesan tersebut, mempertahankan edit pengguna, dan error menyebut field yang gagal secara spesifik.

Langkah selanjutnya: minta perbaikan minimal yang bisa Anda uji

Setelah bug dapat direproduksi dan Anda mengidentifikasi lapisan yang kemungkinan, minta bantuan dengan cara yang menghasilkan patch kecil dan aman.

Kemas "file kasus" sederhana: langkah repro minimal (dengan input, environment, role), expected vs actual, mengapa Anda berpikir ini UI/API/DB, dan cuplikan log kecil yang menunjukkan kegagalan.

Lalu buat permintaan itu sempit:

• usulkan perubahan kode terkecil yang memperbaiki repro
• hindari refactor kecuali perlu
• jelaskan penyebabnya dengan kata-kata biasa
• sertakan rencana uji kecil (cara mengonfirmasi perbaikan, dan apa yang mungkin rusak di dekatnya)

Jika Anda menggunakan platform vibe-coding seperti Koder.ai (koder.ai), pendekatan file-kasus ini yang menjaga saran tetap fokus. Snapshot dan rollback-nya juga membantu menguji perubahan kecil dengan aman dan kembali ke baseline yang dikenal.

Serahkan ke developer berpengalaman ketika perbaikan menyentuh keamanan, pembayaran, migrasi data, atau apa pun yang bisa merusak data produksi. Juga serahkan jika perubahan terus berkembang melampaui patch kecil atau Anda tidak bisa menjelaskan risikonya dalam kata-kata sederhana.