버그 리포트를 재현 가능하게 쓰는 법: 개발자가 다시 확인할 수 있는 기록 만들기

저는 처음 버그 리포트를 작성할 때 문제가 발생했다는 사실만 전달하면 충분하다고 생각했습니다. 그래서 제목에는 화면 이름과 오류 내용을 짧게 적고, 본문에는 재현이 잘 되지 않는다는 문장만 남기곤 했습니다. 하지만 개발자가 같은 현상을 확인하지 못하면 수정 작업은 멈추고, 결국 저에게 추가 질문이 돌아왔습니다. 그때부터 버그 리포트는 불편함을 알리는 메모가 아니라, 다른 사람이 같은 상황에 들어갈 수 있도록 길을 안내하는 기록이라는 생각으로 작성하기 시작했습니다.

재현 가능성이 리포트의 품질을 좌우한다

제가 생각하는 재현 가능한 리포트의 핵심은 읽는 사람이 작성자의 기억이나 추측에 의존하지 않아도 되는 상태입니다. 어떤 메뉴를 열었는지, 어떤 값을 입력했는지, 버튼을 몇 번 눌렀는지, 그 직후 무엇이 보였는지를 순서대로 적어야 합니다. 특히 발생 시각만 적는 것보다 사용한 기기, 운영체제, 애플리케이션 버전, 계정 권한, 네트워크 상태를 함께 남기는 편이 훨씬 유용했습니다. 같은 화면이라도 버전에 따라 동작이 달라지는 경우가 생각보다 많았기 때문입니다.

한 번은 주문 수정 화면에서 저장 버튼을 누르면 화면이 멈춘다는 리포트를 받은 적이 있습니다. 처음에는 단순한 오류처럼 보였지만, 실제로는 특정 브라우저에서만 발생했고 상품 수량이 999개일 때 재현됐습니다. 제가 보고서에 브라우저 종류와 수량 조건을 추가하자 담당자는 몇 분 안에 같은 문제를 확인했습니다. 반대로 조건을 적지 않았던 초기 보고서는 여러 사람이 낮은 수량으로 반복 확인하면서 문제가 없는 것으로 결론 날 뻔했습니다.

제가 실패했던 버그 리포트 작성 경험

가장 아쉬웠던 사례는 로그인 직후 화면이 비어 보인다는 내용을 제목으로만 전달했던 일입니다. 저는 당시 휴대전화에서 잠깐 화면을 본 뒤 내용을 작성했기 때문에, 문제가 발생한 계정의 권한이나 로그인 방식, 인터넷 연결 상태를 기록하지 않았습니다. 담당자는 일반 계정과 관리자 계정으로 각각 다섯 번씩 확인했지만 아무 문제가 나타나지 않았고, 저도 정확한 재현 절차를 다시 떠올리지 못했습니다. 결국 다음 날 같은 현상이 나타날 때까지 원인을 좁히지 못했습니다.

이후 다시 발생했을 때 저는 순서를 종이에 먼저 적었습니다. 오전 9시 40분에 모바일 브라우저에서 로그아웃 상태로 접속했고, 저장된 비밀번호를 이용해 로그인한 뒤 알림 팝업을 닫고 뒤로 가기 버튼을 눌렀습니다. 그다음 대시보드로 이동하자 목록 영역만 흰색으로 남았습니다. 화면 녹화와 함께 계정 유형, 브라우저 버전, 발생 횟수 3회 중 3회라는 정보를 첨부하니 원인은 특정 이동 순서에서 상태가 갱신되지 않는 문제로 좁혀졌습니다. 모호한 표현 하나를 구체적인 행동 목록으로 바꾸는 것만으로 조사 시간이 크게 줄었습니다.

한 번에 확인할 수 있도록 구조를 나누기

저는 지금 버그 리포트를 작성할 때 제목, 환경, 사전 조건, 재현 절차, 실제 결과, 기대 결과, 발생 빈도 순서로 나눕니다. 제목은 문제가 나타나는 위치와 핵심 현상을 함께 넣습니다. 예를 들어 저장이 안 된다는 제목보다 결제 내역 수정 후 저장 버튼을 눌러도 성공 안내가 표시되지 않는다는 제목이 낫습니다. 사전 조건에는 로그인 여부나 특정 데이터의 존재처럼 재현 전에 미리 준비해야 할 내용을 적고, 절차에는 한 줄에 한 행동만 기록합니다.

실제 결과와 기대 결과를 섞지 않는 것도 중요합니다. 실제 결과에는 화면에 표시된 문구, 이동 여부, 입력값의 보존 여부처럼 관찰한 사실만 씁니다. 기대 결과에는 정상이라면 어떤 변화가 있어야 하는지를 별도로 적습니다. 제가 과거에 발생한 것으로 추정된다는 표현을 자주 사용했는데, 그 문장은 담당자가 현상과 의견을 구분하기 어렵게 만들었습니다. 지금은 오류가 발생했다는 판단보다 저장 버튼을 누른 뒤 10초 동안 화면 변화가 없고 새로 고침 후에도 이전 값이 보인다는 식으로 기록합니다.

리포트를 제출하기 전에는 다른 사람이 그대로 읽고 따라 할 수 있는지 제가 한 번 더 점검합니다. 특정 고객의 개인정보나 내부 계정 비밀번호는 첨부하지 않고, 필요한 경우 테스트용 값으로 바꿉니다. 화면 캡처도 전체 화면을 무작정 올리기보다 문제가 보이는 부분에 표시를 넣고, 캡처만으로 부족한 경우에는 재현 영상을 짧게 남깁니다. 저는 최근에 30초짜리 영상과 6단계 절차를 함께 제공했는데, 담당자가 첫 시도에서 문제를 재현했습니다. 리포트의 목적은 많이 쓰는 것이 아니라 같은 결과에 도달하게 하는 데 있습니다.

실전에서 겪은 시행착오

저는 주문 수정 화면에서 저장 버튼이 멈춘다는 내용만 적었다가 브라우저 종류와 상품 수량 999개 조건을 빠뜨렸고, 이후에는 30초 화면 녹화와 함께 수량 조건을 기록해 담당자가 몇 분 안에 문제를 재현하도록 했습니다.

저는 모바일 브라우저에서 저장된 비밀번호로 로그인한 뒤 알림 팝업을 닫고 뒤로 가기를 누르는 장면을 기록하지 않아 원인을 놓쳤지만, 다음 발생 때 오전 9시 40분의 접속 순서와 계정 유형을 적어 목록 영역이 흰색으로 남는 현상을 3회 중 3회 재현했습니다.

적용 전 꼭 확인할 주의사항

• 상품 수량 999개처럼 특정 값이 재현 조건일 수 있으므로 낮은 수량만으로 문제가 없다고 판단하지 않아야 합니다.
• 실제 결과와 기대 결과를 섞지 말고 저장 버튼을 누른 뒤 10초 동안 화면 변화가 없었다는 관찰 사실을 별도로 기록해야 합니다.
• 개인정보나 내부 계정 비밀번호를 화면 캡처와 영상에 포함하지 말고 테스트용 값으로 바꿔야 합니다.