자동 테스트 빌더
목표: 제품이 고장났을 때만 실패하고, 그 이유를 한눈에 알 수 있는 테스트.
코드를 작성하기 전에
- 기존 설정을 확인하세요:
playwright.config.*,pytest.ini/pyproject.toml,fixture, helper, 페이지 오브젝트, 테스트 데이터. 기존 것을 확장하세요. 두 번째 프레임워크를 추가하지 마세요. - 소스 케이스를 선택하세요. 없다면 먼저 케이스(단계 및 예상 결과)를 테스트 설명에 작성한 후 코드를 작성하세요.
- 레이어를 결정하세요. 버그를 잡을 수 있는 가장 저렴한 레이어를 사용하세요:
| 증명하려는 것 | 레이어 |
|---|---|
| 비즈니스 규칙, 유효성 검사, 권한 | API 테스트 |
| 실제 UI에서 사용자가 플로우를 완료할 수 있음 | 플로우당 하나의 E2E 테스트 |
| 여러 상태의 한 컴포넌트 렌더링 | 컴포넌트 테스트 (프로젝트에 있는 경우) |
| 데이터가 실제로 변경됨 | UI 단계 후 API 또는 DB 확인 |
프로젝트에 프레임워크가 아직 없다면, 웹 및 API용 Playwright Test와 Python 서비스용 pytest + requests로 시작하세요. 첫 번째 커밋은 작게 유지하세요: 설정, 하나의 fixture, 하나의 통과 테스트, 하나의 CI 작업.
로케이터
다음 순서로 선호하세요:
getByRole(role, { name })- 접근성 검사도 겸합니다.- 정적 텍스트의 경우
getByLabel,getByPlaceholder,getByText. - 마크업이 의미론적이지 않은 경우
getByTestId. CSS 경로보다data-testid를 추가하도록 개발자에게 요청하세요.
인덱스로 XPath, 자동 생성된 클래스 이름, 또는 주석에 이유 없이 nth()를 절대 사용하지 마세요.
대기
waitForTimeout또는sleep을 사용하지 마세요. 상태를 기다리세요:await expect(locator).toBeVisible(),page.waitForResponse(url), 또는 API 폴링(expect.poll).- Playwright의 단언문은 재시도됩니다. 텍스트를 읽고 비교하는 대신
expect(locator)를 사용하세요. - 이메일, 큐 등 설계상 느린 것은 타임아웃과 명확한 메시지와 함께 폴링하세요.
테스트 데이터 및 상태
- fixture에서 API를 통해 테스트에 필요한 것을 생성하고, 이후 정리하세요.
- 실행마다 고유한 데이터: 타임스탬프 또는
test.info().workerIndex로 접미사를 붙이세요. - 역할당 한 번씩
storageState로 로그인하고, 모든 테스트에서 UI를 통해 로그인하지 마세요. - 테스트 간 순서에 의존하지 마세요. 모든 테스트는
--grep으로 단독 실행 시 통과해야 합니다.
구조
tests/
api/ 규칙 및 권한의 빠른 검사
e2e/ 사용자 플로우, 적고 중요
fixtures/ 인증, 데이터 빌더, API 클라이언트
pages/ 3개 이상의 테스트에서 페이지를 사용할 때만 페이지 오브젝트
테스트 이름은 동작으로 지정하세요: test_delete_3 대신 viewer cannot delete a project.
테스트당 하나의 동작. 하나의 동작을 설명한다면 여러 expect 줄도 괜찮습니다.
examples/에 예제: API 설정이 포함된 UI 플로우, API 권한 테스트, pytest 버전.
서드파티 및 부작용
통합 자체를 테스트하는 경우가 아니라면, 결제 제공자, 이메일, 분석, 지도를 page.route 또는 테스트 더블로 스터빙하세요. 실제 통합 테스트는 태그(@integration)를 달아 CI에서 별도로 실행할 수 있게 하세요.
테스트 불안정 해결
- 재현:
npx playwright test <file> --repeat-each=20 --workers=4. - 실패한 실행의 트레이스(
--trace on)를 열고 통과한 실행과 다른 첫 번째 단계를 찾으세요. - 일반적인 원인: 고정 대기, 두 요소와 일치하는 로케이터, 워커 간 공유 데이터, 애니메이션, 단언문 이후에 완료되는 요청.
- 원인을 수정하세요. CI의 재시도는 안전망이지 해결책이 아닙니다. 스킵 이유에 티켓 링크 없이 테스트를 건너뛰지 마세요.
완료 조건
- 테스트가 단독으로 그리고 전체 스위트에서 연속 세 번 통과합니다.
- 실패를 직접 확인하세요: 단언문 또는 앱 상태를 한 번 깨뜨리고 실패 메시지가 의미 있는지 확인하세요.
- 코드에 비밀이 없습니다. 자격 증명은 환경 변수에서 가져옵니다.
- 테스트 이름, 케이스 ID(주석 또는 태그로), 예상 결과가 리포트에서 읽을 수 있어야 합니다.
다음과 함께 보고하세요: 변경된 파일, 실행 방법, 테스트가 다루는 내용, 자동화할 수 없었던 것과 그 이유.