bughunt

bughunt은(는) 무엇을 하나요?

단위 테스트와 대부분의 UI 테스트는 작성자가 생각한 코드 경로만 확인하며, 실제 클릭과 키 입력을 생략하는 테스트 훅을 사용하는 경우가 많습니다. 사람들은 앱을 그런 방식으로 사용하지 않습니다. 그들은 훅이 없는 곳을 클릭하고, 모든 작업 후에 실행 취소를 누르고, 좁은 창에서 작업하고, 중간에 네트워크가 끊기고, 동료가 보낸 이상한 파일을 엽니다. 그들이 만나는 대부분의 버그는 이미 존재했지만, 아무도 찾지 못하고 있었습니다.

이 스킬은 찾아냅니다. 실제 입력으로 실제 앱을 구동하여 한 번에 한 영역씩 탐색하고, 확인된 모든 버그를 두 가지 형태로 기록합니다. 하나는 리포지토리에 남아 버그가 눈에 띄지 않게 재발하는 것을 방지하는 실패하는 테스트이고, 다른 하나는 누군가가 수정할 수 있도록 리포지토리의 버그 목록에 추가되는 항목입니다. 헌트는 제품 코드를 수정하지 않습니다. 발견하고, 증명하고, 기록할 뿐입니다.

모드

• Hunt (기본값): 한 영역을 선택하여 집중 탐색하고, 결과를 기록하며, 로테이션을 업데이트합니다. 한 번 실행에 하나의 영역만 탐색하여 실제 버그를 찾을 수 있을 만큼 깊이 있게 수행합니다.
• Set up: 리포지토리에 앱을 엔드투엔드로 구동할 방법이 없거나, references/boundaries.md에 경계 조건이 정의되지 않은 경우에 사용합니다. 모든 표면에서 하나의 기능을 실행할 수 있는 가장 작은 워크스루 레인(references/walkthroughs.md)을 구축한 후 헌트를 시작합니다.
• Sweep: 모든 기존 워크스루를 실행하고 마지막 실행 이후 새로 생긴 것, 변경된 것, 수정된 것을 보고합니다. 스윕은 새로운 종류의 버그가 아닌 회귀를 찾습니다. 헌트와 함께 사용하세요.
• Rules: references/invariants.md에 있는 규칙 중 하나를 레인에 추가하여 모든 워크스루의 모든 단계에서 실행되도록 합니다. 단일 규칙(예: "실행 취소는 정확히 이전 상태를 복원한다")은 아무도 스크립트로 작성하지 않을 여러 기능에서 수십 개의 버그를 드러낼 수 있습니다.

1. 먼저 기본 규칙을 숙지하세요

리포지토리의 지침 파일(CLAUDE.md, AGENTS.md, CONTRIBUTING, 모든 규칙 또는 인계 노트), 앱을 실행하는 README, 그리고 기존 엔드투엔드 테스트를 읽으십시오. 다음 사항을 확인하세요:

• 앱이 제공하는 각 표면(개발 서버, 데스크톱 빌드, 모바일 시뮬레이터)을 시작하는 방법. 표면은 하나의 호스트(웹, 데스크톱, 모바일)와 하나의 테마(라이트, 다크, 고대비), 하나의 크기(와이드, 내로우, 폰)의 조합입니다.
• 버그가 추적되는 위치(버그 파일, 할 일 목록, 이슈 트래커)와 그곳에서 사용되는 항목 형식. 해당 형식으로 작성하십시오.
• 테스트가 절대 건드려서는 안 되는 것: 실제 계정, 실제 사용자 파일, 프로덕션 데이터, 실제 이메일, 결제, 사용자의 클립보드, 프린터 및 브라우저, 설치된 앱 복사본. references/boundaries.md를 읽고 모든 적용 가능한 경계 조건을 준비한 후에만 구동하십시오. 이것은 헌트 중 실제 피해를 입힐 수 있는 부분이므로 가장 먼저 수행해야 합니다.
• 리포지토리가 다른 어떤 것(푸시, 네트워크 액세스, 유료 서비스, 에이전트 시작)을 금지하는지 여부. 해당 규칙이 이 스킬보다 우선합니다.

답변이 작업 가능 대상을 변경하는 경우에만 질문하십시오. 그렇지 않으면 직접 결정하고, 해당 가정을 헌트 보고서에 기록하십시오.

2. 영역을 선택하고 기능을 나열하세요

사용자가 지정한 영역을 사용하십시오. 그렇지 않은 경우 bughunt/areas.md를 읽고(첫 실행 시 templates/areas.md에서 생성), 다음 순서로 선택하십시오: 한 번도 헌트되지 않은 영역, 그 다음으로 마지막 헌트 이후 변경된 영역(git log로 해당 경로 확인), 그 다음으로 가장 오래된 영역. 영역은 사용자가 함께 사용하는 기능 집합입니다: 문서 편집기, 파일 브라우저, 로그인 및 계정, 설정, 공유, 결제 등.

리포지토리에 있는 모든 정보(기능 레지스트리, 메뉴 및 명령 목록, 라우트, 도움말 페이지, 코드의 진입점)를 통해 해당 영역의 기능을 나열하십시오. 각 기능은 모든 표면에서 최소 한 번 이상 테스트되어야 합니다.

3. 헌트 수행

각 기능에 대해, 먼저 실제 사람이 하는 방식으로 처음부터 끝까지 현실적인 합성 파일로 작업하십시오. 그런 다음 references/checklist.md를 참조하여 작업하십시오. 여기에는 앱을 반복해서 깨뜨리는 적대적 사용자 동작 목록이 포함되어 있습니다: 모든 단계 후 실행 취소, 키보드 전용, 좁은 창, 다크 모드, 중간에 오프라인, 가장 크고 가장 손상된 파일, 다른 포맷으로의 왕복, 두 개의 탭에서 동일한 작업, 의도적인 실패 유발.

실제 입력 이벤트(클릭, 키 입력, 드래그, 타이핑)를 사용하여 사람의 속도로 앱을 구동하십시오. 스크립트는 사람보다 빠르게 실행되므로, 각 클릭 후 다음 동작 전에 약간의 간격을 두고, 별도로 실행 취소할 것으로 예상되는 두 변경 사이에 0.5초의 간격을 두십시오. 그렇지 않으면 타이밍 아티팩트를 버그로 잘못 기록할 수 있습니다.

각 단계에서 다음 사항을 관찰하십시오:

• 잘못된 결과, 또는 지속되지 않는 올바른 결과(다시 로드, 저장, 실행 취소 또는 탭 전환 후 사라짐)
• 작업 손실: 편집 내용, 설정, 선택 영역, 스크롤 위치
• 너무 많이, 너무 적게 또는 전혀 실행 취소되지 않는 경우
• 아무 작업도 수행하지 않거나, 진입점 중 하나에서만 작동하거나, 실행할 수 없을 때 비활성화되지 않는 명령
• 원시 오류 텍스트: 스택 추적, 오류 코드, 내부 경로
• 콘솔 오류, 충돌, 빈 창, 멈춤
• 너무 희미하거나, 잘리거나, 겹치거나, 단어 중간이 끊긴 텍스트(references/invariants.md의 스크린샷 검사가 대부분 자동으로 감지)
• 다른 표면에서 동일한 단계가 다르게 동작하는 경우

후보를 발견하면 표면, 단계 및 예상 결과와 함께 즉시 기록하십시오. 그런 다음 계속 진행하고, 기능 테스트가 끝날 때 확인하십시오.

4. 기록하기 전에 확인하세요

헌트의 가치는 발견 결과의 정확성에 달려 있습니다. 각 후보에 대해 다음을 수행하십시오:

1. 깨끗한 상태에서 사람의 속도로 두 번 재현하십시오. 수동으로 또는 최소한의 스크립트를 사용하십시오. 재현되지 않으면 폐기하거나, 본 내용과 위치를 "확인되지 않음:"으로 기록하십시오.
2. 테스트 자체의 문제를 배제하십시오. 타이밍(위 참조), 잘못된 요소와 일치한 선택자, 테스트 자체의 스텁, 포커스되지 않은 창, 호버 상태가 있는 요소 위에 위치한 포인터 등. 포인터 위치에 따라 결과가 달라지는 발견은 실제 버그이지만, 테스트에서 포인터 위치를 고정해야 합니다.
3. 비용이 적게 들 때 원인을 찾으십시오. 의심되는 지점의 코드를 읽고 파일과 함수 이름을 지정하십시오. 너무 오래 시간을 보내지 마십시오; 수정자는 직접 찾을 것입니다.
4. 트래커를 확인하십시오. 이미 등록된 항목이 있는 경우, 새 항목 대신 해당 항목에 새 표면 또는 세부 정보를 추가하십시오.
5. 원인별로 그룹화하십시오. 여러 증상이 하나의 원인을 공유하는 경우가 많습니다(예: 하나의 누락된 키 바인딩이 한 호스트의 다섯 편집기에서 실행 취소를 깨뜨릴 수 있음). 이를 명시하여 수정이 한 번에 이루어지도록 하십시오.

5. 확인된 각 버그를 기록하세요

• 먼저 실패하는 테스트를 작성하십시오. 기능의 워크스루(또는 새 워크스루)에 예상 결과를 명시하는 단계를 추가하십시오. 실행하여 테스트가 실패하는지, 그리고 버그의 원인으로 인해 실패하는지 확인하십시오(다른 이유가 아닌). 버그가 수정되면 테스트가 통과합니다. 실행을 통과시키기 위해 기존 예상 결과나 스크린샷 검사를 약화시키지 마십시오. 검사가 잘못된 경우 보고서에 이유를 명시하고 사람이 처리하도록 남겨두십시오.
• 그런 다음 버그 항목을 작성하십시오. 리포지토리의 버그 목록 끝에, 해당 형식으로 templates/bug-entry.md를 사용하여 작성하십시오: 사용자 관점의 증상, 발생 상황과 예상 상황, 측정된 수치, 코드 위치, 이를 보호하는 테스트, 그리고 나타나는 표면.
• 헌트 중에는 제품 코드를 변경하지 마십시오.(사용자가 수정을 요청한 경우 제외) 수정하면서 진행하면 발견 사실이 가려지고 두 종류의 검토가 혼합됩니다.
• 리포지토리 규칙이 허용하는 경우, 새 테스트와 버그 항목을 파일별로 스테이징하여 커밋하십시오. 사용자가 허락하지 않는 한 푸시하지 마십시오.

6. 보고 및 로테이션

templates/hunt-report.md를 사용하여 헌트 보고서를 작성하십시오: 영역, 표면, 각 발견과 해당 테스트 및 항목, 폐기된 후보와 그 이유, 테스트할 수 없었던 사항, 원인별 제안된 수정 그룹. bughunt/areas.md의 해당 영역 행을 업데이트하십시오(날짜, 커밋, 발견 사항).

마지막으로 사용자에게 일반 언어로 알리십시오: 확인된 버그 수, 최악의 버그 세 가지, 수정 그룹, 그리고 로테이션이 다음에 선택할 영역.

계속 찾으세요

완료된 헌트는 동일한 버그가 재발하는 것을 잡는 테스트를 남깁니다. 새로운 버그는 새로운 탐색이 필요합니다:

• 로테이션에 따라 다시 헌트하십시오. 큰 변경이 있는 영역은 다시 헌트하십시오.
• 새로운 곳에서 계속 나타나는 버그를 규칙(references/invariants.md)으로 전환하여 모든 단계에서 검사하도록 하십시오.
• 사용자가 보고하는 모든 버그는 수정되기 전에 워크스루 단계가 되어야 합니다.
• 모든 릴리스 전에 전체 레인을 실행하고, 리포지토리가 스케줄러를 허용한다면 매일 밤 실행하십시오. 새로운 실패와 변경된 실패만 보고하여 알려진 버그가 새로운 버그를 묻지 않도록 하십시오.

작업이 큰 경우

작업을 여러 모델 또는 세션에 분할할 수 있다면, 가장 강력한 모델로 헌트하고, 새 세션에서 다른 모델로 확인하십시오. 두 번째 패스는 깨끗한 상태에서 각 실패하는 테스트를 다시 실행하고 각 항목을 처음부터 읽습니다. 이렇게 하면 한 번의 패스만으로 유지되기 쉬운 확신에 찬 거짓 양성을 잡을 수 있습니다.