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

재현 가능한 버그 보고서는 읽는 사람이 질문하지 않아도 버그를 재현할 수 있어야 합니다. 단계별 스크린샷은 개발자가 보았던 화면을 순서대로 모두 보여 주므로 추측할 여지를 대부분 없앱니다.

이 글은 재현 가능한 보고서에 필요한 내용과 Temposhot Action Capture로 Mac에서 단계를 캡처하는 방법을 다룹니다.

아래 예시는 하나의 사례를 처음부터 끝까지 따라갑니다. 웹 앱에 프로젝트 목록이 있고, 프로젝트 이름을 바꿔도 페이지를 새로 고치기 전까지 목록이 갱신되지 않습니다. 이 사례는 테스트 계정을 사용하며, 재현에 필요한 작업이 7개이고 5회 시도 중 3회 실패합니다.

환경을 먼저 기록

많은 버그는 특정 버전, 특정 브라우저, 특정 계정 유형에서만 나타납니다. 재현하기 전에 설정을 기억하는 동안 환경을 적어 둡니다.

항목	예시
앱 또는 사이트 버전	정보 창이나 바닥글의 빌드 번호
macOS 버전	About This Mac 창에서 확인
Mac 모델과 칩	About This Mac 창에서 확인
브라우저와 버전	웹 앱은 브라우저의 About 페이지에서 확인
계정 유형 또는 역할	무료, 유료, 관리자, 뷰어
언어와 지역	버그가 텍스트, 날짜, 통화와 관련된 경우
날짜와 시간	로그를 맞춰 볼 수 있도록 시간대와 함께 기록

값은 텍스트로 복사합니다. About 창의 스크린샷도 증거가 되지만, 개발자는 이미지 안의 글자를 검색할 수 없습니다.

결과를 바꾸는 값 수집

모든 항목이 모든 버그에 중요하지는 않습니다. 기록할 값은 다르면 결과가 바뀔 수 있는 값입니다. 이름 변경 버그에서는 목록 화면이 뷰어와 편집자에게 다르게 캐시되므로 브라우저 버전과 계정 역할이 중요합니다.

값이 결과에 영향을 주는지는 간단한 테스트로 확인합니다. 브라우저처럼 값 하나를 바꾸고 다시 시도합니다. 버그가 사라지면 "데스크톱 브라우저에서 재현됨, 모바일 앱에서는 재현되지 않음"처럼 발견 사항으로 기록합니다.

환경 정보를 첫 페이지에 두기

환경 정보 블록은 보고서 맨 위, 단계보다 앞에 둡니다. 개발자는 트래커에서 제목과 첫 몇 줄을 읽고 첨부 파일을 열지 결정합니다. 환경 정보가 PDF 6페이지에 묻혀 있으면 개발자는 다른 브라우저로 시도한 뒤 "재현되지 않음"이라고 보고할 수 있습니다.

로그와 콘솔 출력을 텍스트로 첨부

웹 앱에서는 실패 시점에 브라우저 콘솔이 오류를 표시하는 경우가 많습니다. 오류 줄을 텍스트로 복사해 환경 정보 블록 아래에 붙여 넣습니다. 콘솔 스크린샷도 유용하지만, 개발자가 코드베이스에서 메시지를 검색하려면 텍스트가 필요합니다.

실패 근처의 줄만 남깁니다. 관련 오류가 하나뿐인 400줄짜리 콘솔 덤프는 독자가 오류를 직접 찾아야 합니다. 오류 발생 시각을 함께 적어 시도 로그와 맞출 수 있게 합니다.

Mac 앱에서는 충돌 리포트나 오류 대화 상자가 같은 역할을 합니다. 대화 상자의 텍스트를 오류 코드를 포함해 그대로 복사하고, 실행 중에 수동 단축키로 대화 상자를 캡처합니다.

기대 결과와 실제 결과 기술

보고서의 틀은 짧은 문장 두 개로 잡습니다.

• 기대 결과: "Save를 선택하면 새 이름이 목록에 표시됩니다."
• 실제 결과: "Save를 선택한 뒤에도 목록에 이전 이름이 표시됩니다. 페이지를 새로 고치면 새 이름이 표시됩니다."

원인에 대한 생각이 아니라 관찰한 내용을 적습니다. "목록이 갱신되지 않음"은 관찰이고, "캐시가 깨졌음"은 추측입니다.

진단이 아닌 관찰을 기록

보고서에 진단을 쓰면 개발자가 엉뚱한 곳을 봅니다. 실제 원인이 캐시가 아니라 누락된 이벤트라면 "캐시가 깨졌음"이라는 문장은 시간을 낭비하게 합니다. 관찰은 누구나 화면에서 확인할 수 있는 내용입니다.

우회 방법은 심각도 판단이 아니라 사실로 적습니다. 보고서를 분류하는 팀이 심각도를 정합니다.

알려진 시작 상태에서 재현

"앱을 엽니다"로 시작하는 보고서는 이미 세션 깊숙이 들어가 있던 상태를 숨깁니다. 누구나 도달할 수 있는 상태에서 시작합니다. 새로 로그인하거나, 새 프로젝트를 만들거나, 특정 URL을 엽니다.

기록하기 전에 버그를 두 번 이상 재현합니다. 가끔만 나타나면 빈도를 적습니다. 예: "5회 중 3회".

시작 상태 만들기

이름 변경 버그의 시작 상태는 로그아웃된 브라우저 창의 로그인 페이지입니다. 먼저 로그아웃하면 이전 세션이 지워지므로, 개발자가 보고자와 같은 지점에서 시작합니다.

시도 기록

간헐적인 버그에는 짧은 시도 기록이 필요합니다. 각 시도의 시각과 실패 여부를 적어 개발자가 서버 로그와 맞춰 볼 수 있게 합니다. 빈도를 파악하는 데는 보통 5회의 시도면 충분합니다.

경로를 최소로 줄이기

버그가 처음 나타난 경로가 가장 짧은 경우는 드뭅니다. 기록하기 전에 작업을 하나씩 제거하고 버그가 계속 나타나는지 확인합니다. 예시에서는 이름을 바꾸기 전에 프로젝트 상세 정보를 여는 작업이 필요하지 않다는 것을 확인해, 경로를 작업 9개에서 7개로 줄였습니다.

경로가 짧으면 두 가지 이점이 있습니다. 개발자가 재현 한 번에 쓰는 시간이 줄고, 독자가 다른 길로 빠질 지점도 줄어듭니다. 남은 작업을 하나 제거했을 때 버그가 사라지면 줄이기를 멈춥니다.

기록한 실행에서 버그가 나타나지 않으면 기록은 그대로 둡니다. 마지막 몇 작업을 반복하고, 실패가 나타나면 수동 단축키를 누릅니다. 실패하지 않은 실행의 기록도 정확한 경로를 보여 주므로 유용합니다.

필수 작업마다 스크린샷 하나 캡처

1. Action Capture 열기

   Command+3를 누르고 Start Action Capture를 선택합니다. 한 앱만 대상으로 하면 Specific Window를, 단계가 여러 앱에 걸치면 Active Window를 선택합니다.

2. 단계 수행

   클릭이 기록될 때마다 클릭 직전의 창을 저장하므로, 모든 페이지에 조작할 컨트롤이 먼저 보입니다.

3. 실패 캡처

   잘못된 결과가 나타나면 Shift+Command+2를 누르거나 플로팅 툴바에서 Capture now를 선택합니다. 실패 화면은 클릭 없이 나타나는 경우가 많습니다.

4. 캡처 완료

   Finish capture를 선택합니다. 단계마다 한 페이지씩 담긴 문서가 편집기에서 열립니다.

Parse clicked elements를 켜면 페이지 제목이 Click "[[element-name]]"으로 시작합니다. Visual Annotations 아래에서 Show cursor on click captures와 Mark clicked area를 켜면 각 페이지에 클릭한 위치가 표시됩니다. 버그가 Temposhot 자체에 있으면 Include toolbar in captures를 켜서 단계에 플로팅 툴바가 보이게 합니다.

실행 설정을 한 번만 구성

Configure Action Capture의 설정은 Mac에 저장되어 이후 실행에서도 다시 사용됩니다. 버그 보고용으로 구성한 설정은 다음 보고서에도 그대로 남습니다.

한 브라우저 창 안의 버그에는 Specific Window를 선택합니다. 이 설정에서는 Capture outside clicks를 켜지 않는 한 대상 창 밖의 클릭이 무시됩니다. 재현 과정이 앱 사이를 오가면, 예를 들어 이메일 링크에서 브라우저로 이동하는 경우에는 Active Window를 선택합니다.

단계 제한에 맞추기

무료 요금제에서는 Action Capture 실행 하나당 단계 제한이 5개입니다. 이름 변경 버그는 필수 작업 7개와 실패 화면이 필요하므로, 무료 실행은 다섯 번째 단계 뒤에 일시 중지됩니다. 그때까지 저장된 단계는 실행에 남습니다.

처리 방법은 두 가지입니다. 로그인 이후처럼 자연스러운 지점에서 재현을 두 번의 실행으로 나누고, 두 번째 실행을 같은 문서에 추가합니다. 또는 Temposhot Pro를 활성화합니다. Pro에서는 제한이 없으므로 한 번의 실행으로 모든 단계를 기록합니다.

실행 중 키보드 사용

재현 중에 손을 키보드에 두면 불필요한 클릭이 빈 페이지로 기록되는 것을 막을 수 있습니다. 아래 단축키는 실행과 이후 편집에 쓰입니다.

Temposhot은 너무 가깝게 이어지는 클릭을 무시합니다. 목록 항목을 두 번 클릭하면 단계는 두 개가 아니라 하나만 생성됩니다.

클릭이 누락될 때

저장된 단계가 예상보다 적으면 원인은 몇 가지로 한정됩니다. 다시 기록하기 전에 아래 순서로 확인합니다.

• 플로팅 툴바에 Paused가 표시됨. Resume capture를 선택함. 일시 중지 중의 클릭은 저장되지 않음.
• 대상이 Specific Window이고 클릭이 다른 창에 닿음. 대상 안을 클릭하거나 Capture outside clicks를 켬.
• Mouse click capture가 특정 키를 누른 상태를 요구하거나 건너뛰는 모드로 설정됨. 버그 보고서에는 Capture every mouse click으로 되돌림.
• 손쉬운 사용(Accessibility) 권한이 없음. Permissions Required에서 화면 기록과 손쉬운 사용이 모두 Granted로 표시되어야 함.

파싱된 제목이 모두 Click here로 나오면 대상 앱이 컨트롤에 대한 손쉬운 사용 데이터를 거의 제공하지 않는 것입니다. 단계는 저장되며, 제목만 수동으로 다시 작성하면 됩니다.

상태 변화를 설명하는 텍스트 추가

스크린샷은 화면을 보여 주지만, 화면 사이에서 무엇이 바뀌었는지는 항상 보여 주지 않습니다. 이때는 Page description을 사용합니다. 예: "여기서 카운터는 4를 표시해야 합니다. 현재 3을 표시합니다."

실패 페이지에서는 Rectangle(R)로 잘못된 값 주위에 사각형을 그리고, Text(T)로 기대 값을 적은 라벨을 추가합니다. 잘못된 클릭으로 생긴 페이지는 삭제해 순서에 필수 작업만 남깁니다. 제목은 Save를 선택합니다처럼 평이한 단계 문장으로 고칩니다. 편집기 가이드에 모든 도구와 단축키가 나와 있습니다.

예시 정리

기록된 이름 변경 실행은 페이지 9개를 만들었습니다. 한 페이지는 목록의 빈 영역을 클릭해서, 다른 한 페이지는 브라우저 주소창을 클릭해서 생성되었습니다. 두 페이지를 삭제하고 수동 단축키로 찍은 실패 페이지는 남겨서, 작업 페이지 7개와 실패 페이지 1개가 남았습니다.

파싱된 제목은 출발점일 뿐입니다. Click "Rename"은 "프로젝트 메뉴에서 Rename을 선택합니다"로 고쳐 쓰며, 이렇게 쓰면 컨트롤의 위치도 함께 알려 줍니다. 파서가 이름을 찾지 못한 페이지는 Click here로 표시되므로 항상 다시 작성해야 합니다.

상태 변화를 설명하는 페이지 설명 패턴

버그 보고서의 페이지 설명은 대부분 세 가지 짧은 패턴으로 충분합니다. "이 단계 전에 목록에는 프로젝트 12개가 표시됨"은 시작 값을 기록합니다. "타이핑 후 2초 대기"는 스크린샷으로 보이지 않는 타이밍을 기록합니다. "여기서 목록에는 Q3 Budget이 표시되어야 함"은 실패가 나타나는 페이지의 기대 상태를 기록합니다.

각 설명은 한두 문장으로 제한합니다. 설명이 길면 PDF에서 스크린샷이 아래로 밀리며, 설명을 Before image로 설정하면 독자가 텍스트를 먼저 읽습니다.

실패 페이지 표시

실패 페이지에는 정보가 가장 많으므로 주석을 가장 자세히 붙입니다. 오래된 이름 주위에 사각형 하나와 새 이름을 적은 텍스트 라벨 하나면 보통 충분합니다. 한 페이지에 주석이 3개를 넘으면 잘못된 값을 찾기 어려워집니다.

창이 큰데 목록이 작은 경우 실패 페이지에 Framing을 레벨 4(Close) 같은 수준으로 적용합니다. 원본 이미지는 바뀌지 않으며, 개발자가 전체 맥락이 필요하면 Show full image로 원본을 되돌릴 수 있습니다.

개인 정보 보호

버그 보고서는 트래커, 채팅 스레드, 벤더 티켓에 복사됩니다. 모든 스크린샷을 조직 내부에서도 공개된 것으로 취급합니다.

• 가능하면 테스트 계정과 샘플 데이터로 재현함.
• Framing(F)과 Custom으로 사이드바, 브라우저 탭, 알림을 자름.
• Blur(B, Pro)로 이름, 이메일 주소, 토큰, ID를 흐리게 처리함.
• 붙여 넣는 URL이나 로그 텍스트에서 세션 토큰과 API 키를 제거함.

내보내기 크기에서 모든 페이지 확인

캔버스에서 50퍼센트 확대 상태일 때 값을 가린 것처럼 보이는 흐림 처리도 전체 크기에서는 읽힐 수 있습니다. Object Inspector에서 Blur strength를 텍스트를 읽을 수 없는 값으로 설정합니다. 기본값은 2에서 80 사이 눈금의 12입니다. 보내기 전에 내보내기 미리 보기를 페이지마다 넘겨 확인합니다.

브라우저 주소창의 URL은 흔한 유출 경로입니다. 공유 링크나 재설정 토큰이 주소창에 보이면 브라우저 기반 재현의 모든 페이지에 노출됩니다. 페이지마다 Framing으로 주소창을 자르거나 흐리게 처리합니다.

버그 보고서 구조 사용

1. 제목: 무엇이 어디에서 실패하는지 적음. 예: "목록 보기에서 이름을 바꾼 항목이 갱신되지 않음"
2. 환경: 위 표의 값
3. 재현 단계: 번호를 붙이고 알려진 상태에서 시작
4. 기대 결과와 실제 결과
5. 빈도: 항상 발생하는지, 얼마나 자주 발생하는지
6. 증거: 내보낸 스크린샷 가이드와 로그 또는 콘솔 오류 텍스트
7. 우회 방법: 있는 경우

한 파일만 첨부하려면 문서에서 Export PDF를 선택합니다. 트래커가 이슈 본문에 인라인으로 보여 주는 PNG 페이지가 필요하면 More export formats를 선택합니다. 이미지 파일 이름은 페이지 제목을 따릅니다. 내보내기 가이드에 모든 형식이 나와 있습니다.

트래커에 맞는 내보내기 선택

트래커마다 첨부 파일을 표시하는 방식이 다릅니다. 트래커가 이슈 본문에서 이미지를 미리 보여 주면 인라인 PNG 페이지가 맞습니다. 개발자가 파일을 열지 않고도 단계를 읽을 수 있기 때문입니다. 트래커가 첨부 목록만 보여 주거나 보고서를 외부 벤더에 보내는 경우에는 PDF 한 개가 맞습니다.

ZIP package 형식은 렌더링된 PNG 페이지와 document.json 파일을 하나의 압축 파일에 담습니다. 파일 하나만 받으면서 이미지와 페이지 텍스트가 모두 필요한 벤더 티켓에 적합합니다.

작성 완료된 예시

트래커에 올라간 이름 변경 보고서의 제목은 "이름을 바꾼 프로젝트가 새로 고침 전까지 Projects 목록에 이전 이름으로 표시됨"입니다. 환경 블록에는 빌드 번호, macOS 버전, 브라우저 버전, 편집자 역할, 14:02부터 14:20까지의 시도 시각이 적혀 있습니다.

재현 단계는 "qa-editor 계정으로 로그인"부터 "이름 변경 대화 상자 닫기"까지 번호가 붙은 7줄입니다. 기대 결과와 실제 결과는 앞서 본 두 문장이고, 빈도는 "5회 중 3회"입니다. 증거는 8페이지 PDF이며, 우회 방법은 "페이지 새로 고침"입니다.

PDF는 기본 내보내기 설정을 사용합니다. 용지는 A4, 방향은 Landscape(가로), 표지와 단계 번호와 페이지 번호는 켜짐, 설명은 이미지 앞에 표시됨입니다. 이 설정을 바꾸려면 Temposhot Pro가 필요하지만, 기본값만으로도 버그 보고서에 적합합니다.

단계도 텍스트로 작성

PDF에 단계가 있더라도 번호가 붙은 단계를 이슈 본문에 텍스트로 붙여 넣습니다. 텍스트 단계는 검색하고, 댓글에서 인용하고, 테스트 케이스로 복사할 수 있습니다. 그러면 스크린샷은 단계의 유일한 기록이 아니라 각 단계의 증거가 됩니다.

보내기 전 보고서 테스트

보고서를 처음부터 끝까지 읽습니다. 버그를 처음 보는 사람이라고 생각하면서 읽습니다. 더 확실한 방법은 동료에게 자신의 Mac에서 따라 해 보게 하는 것입니다. 질문 없이 버그를 재현하면 보고서는 준비된 것입니다.

시험 실행에서 발견되는 누락

동료의 시험 실행에서는 보통 세 가지 누락 중 하나가 발견됩니다. 시작 상태가 빠진 경우(예: 이미 존재해야 하는 프로젝트), 클릭 없이 일어나는 단계(예: 키보드 단축키)가 페이지로 기록되지 않은 경우, 타이밍에 따라 실패하는 경우(예: 입력 후 2초 이내에 Save를 선택하는 경우)입니다.

시작 상태는 첫 단계에 추가하고, 키보드 동작은 수동 단축키로 찍은 페이지를 추가하며, 타이밍은 페이지 설명에 적습니다. 그다음 시험 실행을 다시 합니다.

원본 문서 보관

내보낸 뒤에도 문서는 편집할 수 있습니다. 개발자가 화면을 하나 더 요청하면 문서를 열고 **Capture new images…**로 페이지를 추가한 뒤 다시 내보냅니다. 이미 내보낸 파일은 자동으로 갱신되지 않습니다.

자주 묻는 질문

버그 보고서에 동영상이나 스크린샷이 필요한가요?

대부분의 버그에는 스크린샷이 적합하며, 훑어보기와 주석 달기도 쉽습니다. 동영상은 타이밍 문제와 애니메이션에 유용합니다. 단계별 스크린샷 가이드와 화면 녹화 비교를 참고합니다.

버그 보고서에는 스크린샷이 몇 장 필요한가요?

필수 작업 하나당 한 장과 실패 화면 한 장입니다. 결과를 바꾸지 않는 페이지는 제거합니다.

보고서를 보낸 뒤 스크린샷은 어디에 있나요?

문서는 Mac에 남습니다. Temposhot에는 호스팅된 링크가 없으므로 내보낸 파일을 이슈 트래커나 티켓에 첨부합니다.

무료 요금제에서 재현에 5단계를 넘는 작업이 필요하면 어떻게 하나요?

실행은 단계 제한에서 일시 중지되고, 그때까지 저장된 단계는 유지됩니다. 재현을 두 번의 실행으로 나누어 하나의 문서에 추가하거나, Temposhot Pro를 사용해 제한을 넘어 기록합니다.

클릭 없이 나타나는 버그도 캡처할 수 있나요?

가능합니다. 잘못된 상태가 나타날 때 수동 캡처 단축키를 누릅니다. 기본값은 Shift+Command+2입니다. 단계는 클릭 없이 저장되며, 클릭 표시 설정이 있으면 그 설정도 적용됩니다.

클릭을 명확한 단계별 가이드로 바꾸기

Action Capture는 재현 단계를 수행하면서 클릭 표시와 초안 제목을 함께 기록합니다. Temposhot 다운로드를 받아 다음 버그 보고서를 순서가 있는 가이드로 첨부할 수 있습니다.