GitHub의 커버리지 업로드 수정: 녹색 체크가 검증되었다는 의미는 아니다

모든 '녹색 체크'에 의존하지 말고, 실제로 실행된 것과 그 증명 결과를 확인하세요

당신의 AI 코딩 도구는 테스트가 통과했다고 알려줍니다. GitHub에는 녹색 체크 표시가 나타납니다. 앱은 당신의 노트북에서 열립니다.

하지만 이것만으로 사람이 사용하도록 초대할 수 있는지 여부는 알 수 없습니다.

어쩌면 그럴 수도 있습니다. 하지만 이 세 가지 사실이 저장 기능이 작동하는지, 다른 계정이 비공개 기록을 읽을 수 있는지, 또는 테스트가 곧 게시하려는 버전과 같은 버전을 대상으로 실행되었는지를 알려주지는 않습니다.

저는 초보자들이 "모든 것이 녹색인가요?"보다 더 유용한 질문을 하기를 바랍니다.

실제로 무엇이 실행되었으며, 그 결과는 무엇을 증명하는가?

10월 1일, GitHub는 Code Quality coverage-upload action에 대한 변경 사항을 발표했습니다. 이제 열려 있는 풀 리퀘스트(pull request)가 없는 비기본 브랜치에 푸시할 경우, 풀 리퀘스트 번호가 누락되어 실패하는 대신 업로드를 건너뜁니다. 스킵된 이유와 단계 요약이 알림으로 설명됩니다. 지원되는 풀 리퀘스트 이벤트 및 기본 브랜치 업로드의 기존 동작은 유지됩니다.

여기에는 타이밍에 대한 세부 사항이 있습니다. 푸시(push)만으로 트리거되는 워크플로우는 단순히 풀 리퀘스트를 열었다고 해서 업로드되지 않습니다. 추가적인 푸시 또는 적절한 풀 리퀘스트 트리거가 필요합니다. 이 특정 기능은 GitHub Team 및 Enterprise Cloud용이며, Enterprise Server에는 해당하지 않습니다.

이는 오해의 소지가 있는 실패에 대한 합리적인 수정입니다. 제가 전달하려는 더 큰 교훈은 녹색 체크 자체가 나쁘다는 것이 아닙니다. 성공적으로 완료된 작업(job completing successfully)과 특정 증거가 수집되었다는 사실(a particular piece of evidence being collected)은 서로 다른 사실이라는 것입니다.

네 가지 정직한 결과로 시작하세요

저는 모든 중요한 검사에 다음 네 가지 레이블 중 하나를 부여할 것입니다.

• Passed (통과): 검사가 실행되었고, 명시된 기대치(expectation)가 충족되었습니다.
• Failed (실패): 검사가 실행되었으나, 기대치가 충족되지 않았습니다.
• Skipped (건너뜀): 검사가 의도적으로 실행되지 않았으며, 그 이유가 기록되어 있습니다.
• Unknown (알 수 없음): 신뢰할 수 있는 결과가 없거나, 이 빌드와 일치하는 결과를 매칭할 수 없습니다.

스킵된 커버리지 업로드(skipped coverage upload)는 테스트가 실패했다는 것을 의미하지 않습니다. 또한 커버리지가 업로드되었다는 것도 의미하지 않습니다. 이 두 진술은 어떤 모순 없이 모두 사실일 수 있습니다.

위험한 움직임은 건너뛰거나 알 수 없는(unknown) 경우를 통과(passed)로 처리하는 것입니다. 왜냐하면 전체 페이지가 안심시키는 것처럼 보이기 때문입니다.

가상의 예약 앱을 상상해 보세요. 자동 빌드가 성공했지만, 테스트 데이터베이스가 필요한 검사는 해당 데이터베이스를 사용할 수 없어서 건너뛰어졌습니다. 이 앱은 여전히 올바르게 패키징될 수 있습니다. 하지만 여러분이 예약 기능을 저장할 수 있다는 것은 입증하지 못했습니다.

만약 이제 막 시작하는 단계라면, $1 AI App Builder Starter Prompts 가 아이디어를 작동하는 첫 빌드로 안내할 것입니다. 이 네 가지 결과 규칙을 프롬프트 옆에 기억하세요: 어시스턴트는 누락된 검사를 자신감 있는 요약 뒤에 숨기지 않고, 무엇을 검증할 수 있는지 설명해야 합니다.

각 검사에 좁은 임무를 부여하세요

'앱 테스트하기(Test the app)'는 판단하기에는 너무 광범위합니다. 저는 이를 초보자가 이해할 수 있는 주장들로 나누어 제시할 것입니다.

빌드 검사(build check)는 소스 코드가 실행 가능한 제품으로 변환될 수 있는지 여부를 묻습니다. 작은 로직 테스트(logic test)는 예약 취소가 상태를 변경하는지 물을 수 있습니다. 브라우저 테스트(browser test)는 사용자가 슬롯을 예약하고 새로고침한 후 그것이 보이는지 물을 수 있습니다.

권한 테스트(permission test)는 다른 질문을 합니다: 두 번째 사용자가 자신이 소유하지 않은 예약을 읽거나 변경할 수 있는가?

성공적인 검사 하나가 나머지 모든 것을 대체하지 못합니다. 앱은 아무것도 저장하지 않으면서 컴파일될 수 있습니다. 저작권 보호가 깨지면서도 저장은 작동할 수 있습니다. 올바른 권한 규칙이 존재하더라도 화면이 여전히 잘못된 요청을 보낼 수 있습니다.

AI에게 테스트 추가를 요청하기 전에, 평범한 영어로 보호하고자 하는 동작(behavior)을 작성하세요:

"로그인한 고객은 사용 가능한 슬롯을 예약하고 페이지를 새로고침하여 예약을 볼 수 있다. 다른 고객은 해당 예약을 보거나 취소할 수 없다."

이제 여러분의 어시스턴트는 인상적인 출력을 생성하라는 모호한 요청 대신, 테스트해야 할 구체적인 약속을 갖게 됩니다.

백분율보다 분모를 읽으세요

코드 커버리지(Code coverage)는 테스트 실행 중에 어떤 부분의 코드가 사용되었는지 설명합니다. 이는 제품이 좋은지에 대한 판결이라기보다는 유용한 증거입니다.

예를 들어, Vitest의 문서는 기본 보고서가 테스트 실행 중에 가져와진 파일들을 보여준다고 설명합니다. 커버되지 않은 파일들까지 포함하려면 적절한 포함 패턴이 필요합니다.

그것이 분모를 중요하게 만듭니다. 프로젝트의 작은 선택된 부분에 걸쳐 높은 비율을 보이는 것이, 평가하고자 했던 전체 애플리케이션에 걸쳐 높은 비율을 보인다는 주장과 같지 않습니다.

AI에게 보고서가 어떤 소스 파일을 포함하고 제외하는지 물어보세요. 중요한 저장(save), 권한(permission), 복구(recovery) 경로들이 대표되는지 물어보세요. 무엇을 측정하는지 이해하기 전에 임의의 비율을 요구하지 마세요.

완전히 실행된 코드라 할지라도 약한 단언(weak assertions)을 포함할 수 있습니다. 저장 버튼을 클릭하고 그저 버튼이 존재하는지만 확인하는 테스트는, 재로드하여 저장된 예약을 확인하는 테스트보다 훨씬 적은 증거가 됩니다.

정확한 빌드에서 증거를 요구하라

어제 성공했던 테스트 실행 기록은 유용한 이력 항목입니다. 그것이 오늘 수정된 버전에 자동으로 대한 증거는 아닙니다.

저는 AI에게 각 후보 릴리스마다 작은 검증 노트를 유지하도록 요청할 것입니다:

• 버전: 커밋 식별자 또는 다른 정확한 빌드 식별자.
• 환경: 로컬 개발, 테스트 배포, 또는 프로덕션과 유사한 스테이징 환경.
• 점검 사항(Checks): 건너뛴 항목의 이름, 결과, 그리고 이유.
• 증거(Evidence): 보고서, 스크린샷 또는 관련 로그 파일의 경로.
• 누락된 부분(Gaps): 여전히 테스트되지 않았거나 검증할 수 없었던 동작.
• 결정(Decision): 진행될 수 있는 것과 기다려야 하는 것.

자격 증명(credentials), 개인 고객 기록, 접근 토큰은 그 노트에 포함하지 마세요. 가능한 경우 합성 기록으로 테스트하세요.

이것은 자체를 위한 서류 작업이 아닙니다. 오래된 미리 보기의 스크린샷이나 다른 브랜치의 보고서가 현재 앱에 대한 승인으로 조용히 변질되는 것을 막아줍니다.

기계 장치뿐만 아니라 여정(journey)을 테스트하라

Testing Library의 지침 원칙(guiding principles)은 컴포넌트의 내부 구현에 의존하기보다 사람들이 인터페이스를 사용하는 방식과 유사한 검사를 선호합니다.

가상의 예약 앱을 예로 들면, 한 번의 완전한 여정으로 시작할 것입니다. 즉, 로그인하고, 슬롯을 선택하고, 예약하고, 새로고침하고, 확인하고, 취소하는 과정을 거칩니다. 그런 다음 다른 계정과 유효하지 않은 요청으로 같은 기록을 테스트합니다.

파괴적인 동작(destructive actions)에는 일회용 테스트 환경을 사용하세요. 누군가의 실제 예약을 대상으로 취소 테스트를 실행하지 마십시오.

이러한 접근 방식은 AI 작업 검토에도 도움이 됩니다. 저장소 구현의 모든 줄을 이해할 필요 없이도 '예약이 새로고침 후에도 유지되는지'를 이해할 수 있기 때문입니다.

$9 AI 앱 빌더 From Zero e-book은 이러한 단계를 아이디어 구상부터 출판까지의 더 넓은 경로(범위 설정, 디자인, 아키텍처, 구축, 테스트, 출시)와 연결합니다. 40개의 스타터 프롬프트는 PDF 및 EPUB 내에 무료 보너스로 포함되어 있습니다. 귀하가 지불하는 것은 e-book이며 추가 프롬프트 팩이 아닙니다.

베타 전에 사용할 프롬프트

현재 프로젝트를 검사하고 정확한 빌드 또는 커밋을 식별하세요. 이 버전에 실제로 실행된 검사 목록을 작성하십시오. 각 항목을 통과(passed), 실패(failed), 건너뜀(skipped), 또는 알 수 없음(unknown)으로 분류하십시오. 각 결과가 평이한 영어로 무엇을 증명하는지 설명하십시오. 보고서나 증거 경로를 보여주고, 제외된 파일, 목업 의존성(mocked dependencies), 누락된 환경, 그리고 테스트되지 않은 사용자 여정을 식별하십시오. 건너뜀을 통과로 변환하지 마십시오. 각 중요한 알 수 없음(unknown)을 해결할 가장 작고 안전한 테스트를 제안하십시오. 저에게 묻지 않고 프로덕션 데이터 변경, 비용 지출 또는 배포를 하지 마십시오.

단순히 긍정적인 언어에만 의존하지 말고 누락된 증거에 대한 답변을 읽으세요.

필수 검사(check)가 건너뛰어진 경우, 그 전제 조건(prerequisite)을 복원하거나 적절한 동등물(equivalent)을 실행하고 결과를 기록해야 합니다. 둘 다 불가능하다면, 해당 제한 사항을 보이게 유지하고 영향을 받는 릴리스 결정은 보류하십시오. 단순히 대시보드를 녹색으로 만들기 위해 검사를 제거하지 마십시오.

Review Radar가 곧 출시됩니다. 계획된 패키지는 리뷰 기반 연구, 맞춤형 화면 디자인, 그리고 빌드 프롬프트 및 승인 기준(acceptance criteria)과 함께 AI가 읽을 수 있는 프로젝트 폴더를 통합합니다. 미리보기를 확인하고 이메일 대기 목록에 가입하십시오. 체크아웃은 열리지 않았으며, 해당 패키지는 완성된 앱, 사용자 또는 수익을 보장하지 않습니다.

녹색 대시보드는 당신의 증거 검토(evidence review)의 끝이 아니라 시작이어야 합니다.

또한 다음 곳에서도 저를 찾을 수 있습니다:

Medium: https://medium.com/@marcusykim
DEV.to: https://dev.to/marcusykim
Website: https://marcusykim.com/
X: https://x.com/marcusykim
LinkedIn: https://www.linkedin.com/in/marcusykim/
Upwork: https://www.upwork.com/freelancers/marcusykim