Mac에서 단계별 스크린샷으로 버그를 문서화하는 방법

이 가이드에서는 다른 사람이 재현할 수 있는 소프트웨어 버그의 스크린샷 증거를 모으는 방법을 설명합니다. 실행 환경을 기록하고, 예상 결과와 실제 결과를 정리한 뒤, 필요한 동작을 캡처하세요. 증거를 정돈하고 전송 전에 보고서를 한 번 테스트하면 됩니다.

핵심 요약: 유용한 버그 보고서에는 분명한 시작 상태, 정확한 재현 단계, 예상 결과와 실제 결과, 발생 빈도, 실행 환경, 처음으로 오류가 보이는 화면이 모두 들어갑니다.

먼저 실행 환경을 기록합니다

실행 환경을 적으면 검토자가 버그가 발생한 조건을 알 수 있습니다. 앱 버전, macOS 버전, 기기 종류, 계정이나 권한 상태, 동작을 바꾸는 설정을 기록하세요.

나중에도 조건을 다시 만들 수 있을 만큼 구체적으로 적어야 합니다. "최신 버전"은 다음 업데이트 뒤에는 의미가 모호해지지만, "macOS 15.5에서 실행한 Shotomatic 1.8.2"는 이후에도 유용합니다.

해당하는 항목을 포함하세요.

• 앱 및 빌드 버전
• macOS 버전
• Mac 모델 또는 프로세서 아키텍처
• 계정 유형 또는 플랜
• 브라우저와 브라우저 버전
• 연결된 디스플레이 또는 입력 기기
• 관련 권한과 기능 설정
• 네트워크 상태

예상 결과와 실제 결과를 적습니다

두 결과를 먼저 적어 두면 검토자가 단계를 읽기 전에 문제를 이해할 수 있습니다. 어떤 결과가 나와야 하는지 한 문장으로, 실제로는 어떻게 되는지 한 문장으로 쓰세요.

원인을 추측하지 말고 눈으로 확인한 결과를 적습니다. "PDF 내보내기 버튼을 눌러도 아무 일도 일어나지 않음"은 증거입니다. "내보내기 서비스가 고장 났음"은 확인되지 않은 원인을 단정합니다.

예를 들면 다음과 같습니다.

예상 결과: Export PDF를 선택하면 저장 대화상자가 열립니다.

실제 결과: Export PDF를 선택하면 메뉴는 닫히지만 저장 대화상자가 나타나지 않고 파일도 생성되지 않습니다.

결과 옆에 발생 빈도도 적으세요. 매번 발생하는지, 간헐적인지, 특정 선행 작업 뒤에만 나타나는지 설명합니다.

알려진 시작 상태에서 재현합니다

시작 상태를 정하면 보고서에 보이지 않는 설정을 줄일 수 있습니다. 앱을 닫았다 다시 열거나, 새 테스트 데이터를 만들거나, 관련 설정을 초기화한 뒤 순서를 캡처하세요.

문서화하기 전에 그 상태에서 버그가 한 번 재현되는지 확인합니다. 문제가 다시 나타나지 않는다면 기억에 의존해 자신 있게 단계를 쓰지 말고, 무엇이 달라졌는지 기록하세요.

필요한 동작마다 스크린샷 한 장을 캡처합니다

각 스크린샷은 검토자가 다음 동작을 반복하거나 오류를 알아보는 데 도움이 되어야 합니다. 시작 상태, 필요한 클릭이나 입력, 처음 잘못된 상태가 보인 화면, 진단에 영향을 주는 오류 메시지를 캡처하세요.

결과에 영향을 주지 않는 동작은 빼도 됩니다. 창을 옆으로 옮기거나 관련 없는 패널을 여는 동작은 문제를 일으키는 조건이 아닌 한 잡음만 늘립니다.

Action Capture를 사용한다면 정돈된 시작 상태에서 평소 속도로 문제를 재현하세요. Shotomatic은 허용한 클릭 직전의 대상 상태를 저장하고 클릭 위치를 표시하므로, 캡처 순서가 재현 단계의 초안이 됩니다. Free 세션에는 저장 단계가 5개까지 포함되며, Pro에서는 세션 단계 제한이 없어집니다.

상태 변화를 설명하는 글을 덧붙입니다

짧은 글은 스크린샷만으로 알 수 없는 내용을 설명해야 합니다. 사용할 컨트롤과 입력할 값을 적고, 동작 뒤에 어떤 상태로 바뀌어야 하는지 알려 주세요.

다음과 같은 형식으로 단계를 쓰세요.

1. 동작: Export PDF를 선택합니다.
2. 예상 확인 지점: 저장 대화상자가 열립니다.
3. 관찰한 결과: 메뉴가 닫히지만 대화상자가 나타나지 않습니다.

"여기를 클릭"처럼 화면에 보이는 표시만 되풀이하는 글은 피하세요. 클릭 표시는 이미 위치를 보여 줍니다. 문장에는 컨트롤의 이름과 다음에 확인할 내용을 담으세요.

개인정보를 보호합니다

버그 보고서를 테스트 환경 밖으로 보내기 전에 개인정보를 제거해야 합니다. 가능하면 예시 계정과 테스트 데이터를 사용하세요. 나중에 가리는 것보다 처음부터 원본 데이터를 바꾸는 편이 안전합니다.

실제 데이터를 피할 수 없다면 관련 없는 영역을 자르고 이름, 이메일 주소, 메시지, 토큰, 라이선스 정보, 고객 기록, 알림 미리보기를 흐리게 처리하세요. 검토자가 어느 화면인지 알 수 있도록 주변 인터페이스는 충분히 남깁니다.

자르기, 흐리게 처리하기, 예시 데이터 사용 중 무엇을 선택할지는 별도의 가림 처리 가이드에서 확인하세요.

이 버그 보고서 구조를 사용합니다

다음 구조를 사용하면 보고서가 지나치게 길어지지 않으면서 필요한 내용을 모두 담을 수 있습니다.

제목:

실행 환경:
- 앱/빌드 버전:
- macOS/기기:
- 계정 또는 권한 상태:
- 관련 설정:

예상 결과:

실제 결과:

발생 빈도:

준비 사항:

재현 단계:
1.
2.
3.

증거:
- 필요한 동작별 스크린샷
- 처음 오류가 보이는 화면
- 관련 오류 메시지 또는 로그

우회 방법:

추가 메모:

이는 글의 구조일 뿐 Shotomatic으로 가져올 수 있는 템플릿은 아닙니다. 팀에서 이미 사용하는 이슈 추적 도구나 지원 시스템에 복사해 쓰세요.

전송 전에 보고서를 테스트합니다

마지막 재현 과정에서 빠진 전제 조건을 찾을 수 있습니다. 보고서에 적은 실행 환경에서 시작하고, 기억에 의존하지 말고 작성한 단계만 따라가세요.

같은 순서로 적어 둔 결과에 도달하고, 필요한 값이 모두 들어 있으며, 스크린샷이 올바른 화면을 순서대로 보여 주면 보고서를 보낼 수 있습니다. 타이밍이나 움직임이 중요한 단계라면 글로 적은 순서를 기본 자료로 유지하면서 짧은 녹화를 보조 증거로 첨부하세요.

Action Capture로 클릭 순서를 모을 수 있지만, 보고서에는 실행 환경, 예상 결과, 실제 결과, 발생 빈도도 적어야 합니다. 일반적인 캡처와 편집 과정은 Mac에서 클릭을 캡처해 단계별 가이드를 만드는 방법을 참고하세요.